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

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

@@ -1,12 +1,19 @@
 import fs from 'node:fs/promises';
+import { logger } from '../../shared/logging.js';
+const log = logger('workspace');
 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 { AsyncLocalStorage } from 'node:async_hooks';
+import { validateRelativePath, validateFilename, DEFAULT_BRANCH, FOLDER_PLACEHOLDER, isFolderPlaceholder, entryExistsMessage, } from '@bevel-software/platform-shared';
+import { isAbsence } from '../../shared/fs.contract.js';
+import { DestinationTakenError, inspectDestination, renameNoReplace, } from '../../shared/rename-no-replace.js';
+import { NodeGitRunner } from '../workflow/git/node-git-runner.js';
+import { assertWithinDirectory } from '../../shared/path-containment.js';
+import { assertRepoRootNameFree, normalizeWorkspacePath } from '../kb-fs/repo-path.js';
+import { assertNoGitInternalsSegment, assertNotGitInternals, hasGitInternalsSegment } from '../../shared/git-internals.js';
+import { GitInternalsError, PathNotFoundError, PathTraversalError, UnreadableArchiveError, WorkflowValidationError, } from '../../shared/domain-errors.js';
 import { workspaceIdForBranch, branchForWorkspaceId } from '../../shared/workspace-id.js';
-import { RemoteBranchGoneError, WorkflowDomainError, isMissingRemoteBranchFailure, } from '../../shared/domain-errors.js';
+import { BranchNotFoundError, RemoteBranchGoneError, WorkflowDomainError, isMissingRemoteBranchFailure, } from '../../shared/domain-errors.js';
 import { assertValidBranchName } from '../kb-fs/branch-name.js';
 import { cloneCredentialArgs, cloneCredentialConfigArgs, cloneTrackingConfigArgs, SAFE_IMPLICIT_FETCH_ARGS, } from '../kb-fs/clone-config.js';
 // Zip-bomb guardrails. The upload cap is 50 MB compressed; even a generous
@@ -33,7 +40,39 @@ export class FolderTooLargeError extends Error {
         this.name = 'FolderTooLargeError';
     }
 }
-const execFileAsync = promisify(execFile);
+/**
+ * A rename or move would land on a name something else already has. 409, like
+ * every other precondition the caller has to clear first: nothing was moved,
+ * and the entry already there is untouched.
+ *
+ * Lives here rather than in `shared/domain-errors.ts` because the sentence is
+ * built by `entryExistsMessage` and that file deliberately imports no VALUE
+ * from `@bevel-software/platform-shared`, only a type. It still extends
+ * `WorkflowDomainError`, so the routes' `sendError` maps it to 409 with
+ * `{ kind: 'entry-exists', … }` without knowing this class exists.
+ */
+export class EntryExistsError extends WorkflowDomainError {
+    entryKind;
+    destination;
+    kind = 'entry-exists';
+    constructor(entryKind, destination) {
+        super(entryExistsMessage(entryKind, destination), 409, {
+            kind: 'entry-exists',
+            entryKind,
+            destination,
+        });
+        this.entryKind = entryKind;
+        this.destination = destination;
+        this.name = 'EntryExistsError';
+    }
+}
+/**
+ * A floor under the git deadline for a clone: a first clone of a large
+ * knowledge base over a slow link legitimately takes minutes, and the port's
+ * default is sized for a running deployment's operations. A configured
+ * ceiling above this applies as configured.
+ */
+const CLONE_TIMEOUT_MS = 600_000;
 /**
  * Identity stamped on the per-branch clone's git config. Every workflow
  * commit overrides this with `--author=…` so the human shows up in
@@ -49,9 +88,61 @@ function redactError(err) {
     return token ? msg.replaceAll(token, '***') : msg;
 }
 const FETCH_CACHE_TTL_MS = 30_000;
+/**
+ * The bytes a conditional write compares against. An absent file reads as the
+ * empty string, so `expectedContent: ''` means "expect nothing there yet".
+ *
+ * A directory at the path is a client error, not a 500 with a raw OS message:
+ * `GET /file` counts EISDIR as "no file at this path", so the editor that
+ * opened empty on that 404 would otherwise be told its save failed for an
+ * unexplained internal reason. Anything else (EACCES, EIO) is a real read
+ * failure and propagates: an unreadable file must not pass for an empty one.
+ */
+async function readForConditionalWrite(absolutePath, relativePath) {
+    try {
+        return await fs.readFile(absolutePath, 'utf-8');
+    }
+    catch (err) {
+        if (isAbsence(err))
+            return '';
+        const code = err.code;
+        if (code === 'EISDIR') {
+            const notAFile = new Error(`"${relativePath}" is a directory, not a file.`);
+            notAFile.status = 400;
+            throw notAFile;
+        }
+        throw err;
+    }
+}
+/**
+ * The published library's path rule, refused as a TYPED 400.
+ *
+ * The library throws a bare `Error('Invalid path: …')` — it is shared with
+ * the frontend and cannot carry a backend domain type — and the routes used
+ * to recognise that by its message prefix. Converting it here, at the one
+ * layer that calls it, is what lets the route layer read a status off a
+ * class like it does for every other refusal.
+ */
+function assertValidPath(relativePath) {
+    const reason = validateRelativePath(relativePath);
+    if (reason)
+        throw new WorkflowValidationError(`Invalid path: ${reason}`);
+}
+/** Throw the conditional write's 409 unless the file still holds `expectedContent`. */
+async function assertConditionalWriteMatches(absolutePath, relativePath, expectedContent) {
+    const current = await readForConditionalWrite(absolutePath, relativePath);
+    if (current === expectedContent)
+        return;
+    const stale = new Error(`"${relativePath}" changed since you opened it. Reload it and apply your edit again, ` +
+        'so the other change is not overwritten.');
+    stale.status = 409;
+    throw stale;
+}
 export class WorkspaceService {
     workspacesRoot;
     kbDirName;
+    disk;
+    gitRunner;
     /** Maps branch → absolute directory path. Lazily populated. */
     branchDirs = new Map();
     /**
@@ -65,6 +156,32 @@ export class WorkspaceService {
     /** Whether the last fetch per repo SUCCEEDED — read by strict callers of `ensureRemotesFetched`. */
     lastFetchOk = new Map();
     inFlightFetches = new Map();
+    /**
+     * One mutation at a time per file, keyed by RESOLVED absolute path — so
+     * `x/a.md`, `./x/a.md` and `x//a.md` are one queue and not three. See
+     * {@link withPathTurn} for what takes a turn and why.
+     */
+    writeTurns = new Map();
+    /**
+     * The folder structure changes in flight, keyed by RESOLVED absolute folder
+     * path — see {@link withFolderTurn}.
+     */
+    folderTurns = new Map();
+    /**
+     * The turns the CURRENT async context already holds. Taking one it holds
+     * runs straight through instead of waiting for itself, which is what lets a
+     * caller wrap a whole read-decide-write sequence in a turn and still call
+     * the ordinary write inside it.
+     */
+    /**
+     * The turns the current async context holds, each with the tail of the
+     * nested mutations already launched inside it — so a re-entrant call never
+     * waits for the outer turn (that would hang) while two nested calls on the
+     * same path, launched side by side inside one turn, still run one at a
+     * time. The map is inherited by every child context; the entry object is
+     * shared, which is what makes siblings queue on one tail.
+     */
+    heldTurns = new AsyncLocalStorage();
     /**
      * Late-bound by the composition root — DiffService depends on
      * WorkspaceService for path resolution.
@@ -87,9 +204,18 @@ export class WorkspaceService {
      * dozen other services at construction, so making it live only here would
      * buy an inconsistency rather than a feature.
      */
-    kbRepoUrl, kbDirName, gitUsername = 'x-access-token') {
+    kbRepoUrl, kbDirName, disk, gitUsername = 'x-access-token', 
+    /**
+     * How git is run — see `shared/git.contract.ts`. The composition root
+     * passes the one runner carrying the deployment's deadline; the default
+     * is the same runner on its default deadline, for a directly constructed
+     * service.
+     */
+    gitRunner = new NodeGitRunner()) {
         this.workspacesRoot = workspacesRoot;
         this.kbDirName = kbDirName;
+        this.disk = disk;
+        this.gitRunner = gitRunner;
         this.kbRepoUrl = typeof kbRepoUrl === 'function' ? kbRepoUrl : () => kbRepoUrl;
         this.gitUsername = typeof gitUsername === 'function' ? gitUsername : () => gitUsername;
     }
@@ -101,6 +227,78 @@ export class WorkspaceService {
     setWorkspaceClonedListener(listener) {
         this.onWorkspaceCloned = listener;
     }
+    /**
+     * Every branch name this process has been shown to be real: named by a
+     * listing of origin's branches, or registered as a clone of ours. Together
+     * with the clones still on disk this is the whole of what the platform
+     * KNOWS about branch names — and the difference between "your link is to a
+     * branch that was deleted" (410) and "there is no branch by that name"
+     * (404).
+     *
+     * Names ACCUMULATE and are never removed, and the two halves of that are
+     * the same rule: the evidence we need is evidence about a branch that is
+     * no longer there. Replacing the set on each listing would forget a
+     * deleted branch at the moment its deletion becomes the thing we have to
+     * report; evicting an old name would silently turn a long-dead branch back
+     * into "never existed"; dropping a clone's name when its workspace is swept
+     * would do that to a branch we cloned ourselves. So nothing here is ever
+     * dropped. Growth is one short string per distinct branch name origin has
+     * ever shown this process — kilobytes for any real repository, and reset
+     * by a restart.
+     *
+     * In memory only, by the spec's decision — no new persistence. A restart
+     * forgets a deleted branch whose clone was already retired, and that name
+     * then reads as unknown, which is exactly what the platform then knows.
+     */
+    branchesEverHeardOf = new Set();
+    /**
+     * Record the branch names a listing returned. Called by the git layer after
+     * every `listBranches` (wired in the composition root), which is the one
+     * place the platform ever sees origin's set of branches.
+     */
+    noteBranchesListed(names) {
+        for (const name of names)
+            this.branchesEverHeardOf.add(name);
+    }
+    /**
+     * Register a branch's clone directory — the only writer of `branchDirs`, so
+     * that every clone this process opens (fresh, adopted off disk, or handed
+     * over by a concurrent bootstrap) also leaves its branch name in
+     * `branchesEverHeardOf`. `branchDirs` is a cache of live clones and loses the
+     * branch when its workspace is swept; the name left behind is the record
+     * that the branch was real, and outlives the clone.
+     */
+    registerBranchDir(branch, workspaceDir) {
+        this.branchDirs.set(branch, workspaceDir);
+        this.branchesEverHeardOf.add(branch);
+    }
+    /**
+     * Has the platform ever heard of this branch? A clone of it — registered in
+     * this process, remembered from one, or sitting on disk from a previous one
+     * — or a listing that named it. Only asked on the failure path, where
+     * origin has just answered that it has no such ref: a yes means the branch
+     * was deleted (410), a no means it never existed as far as the platform is
+     * concerned (404).
+     */
+    async hasHeardOfBranch(branch) {
+        if (this.branchDirs.has(branch))
+            return true;
+        if (this.branchesEverHeardOf.has(branch))
+            return true;
+        try {
+            await fs.access(path.join(this.workspacesRoot, workspaceIdForBranch(branch), this.kbDirName, '.git'));
+            return true;
+        }
+        catch (err) {
+            // Only "there is nothing there" answers the question. A permission or
+            // I/O fault means we could not look, and a storage failure of ours must
+            // not be reported to the caller as a branch that never existed: it
+            // stays the 500 the operator reads.
+            if (isAbsence(err))
+                return false;
+            throw err;
+        }
+    }
     /**
      * Build git clone args. Credentials go in as `clone --config`, which both
      * authenticates this clone and leaves the helper in the new repo's config for
@@ -218,8 +416,7 @@ export class WorkspaceService {
             entries = await fs.readdir(this.workspacesRoot, { withFileTypes: true });
         }
         catch (err) {
-            const code = err?.code;
-            if (code === 'ENOENT' || code === 'ENOTDIR')
+            if (isAbsence(err))
                 return [];
             throw err;
         }
@@ -244,8 +441,7 @@ export class WorkspaceService {
                 await fs.access(path.join(this.workspacesRoot, entry.name, this.kbDirName, '.git'));
             }
             catch (err) {
-                const code = err?.code;
-                if (code === 'ENOENT' || code === 'ENOTDIR')
+                if (isAbsence(err))
                     continue;
                 cloned.push({
                     id: entry.name,
@@ -271,22 +467,24 @@ export class WorkspaceService {
      * block a new branch from bootstrapping.
      */
     async runClone(targetDir, branch, referenceRepo) {
+        // Long enough for a first clone, whatever the configured ceiling says.
+        const timeoutMs = Math.max(this.gitRunner.defaultTimeoutMs, CLONE_TIMEOUT_MS);
         if (referenceRepo) {
             try {
-                await execFileAsync('git', this.gitCloneArgs(targetDir, branch, referenceRepo), {
-                    env: { ...process.env },
+                await this.gitRunner.run(path.dirname(targetDir), this.gitCloneArgs(targetDir, branch, referenceRepo), {
+                    timeoutMs,
                 });
                 return;
             }
             catch (err) {
-                console.warn(`[workspace] referenced clone for "${branch}" failed, retrying without reference:`, redactError(err));
+                log.warn(`referenced clone for "${branch}" failed, retrying without reference:`, {
+                    detail: 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 },
-        });
+        await this.gitRunner.run(path.dirname(targetDir), this.gitCloneArgs(targetDir, branch), { timeoutMs });
     }
     /**
      * Get-or-create the per-branch workspace. Idempotent — repeat calls for
@@ -333,7 +531,7 @@ export class WorkspaceService {
             // pulls it. Once per branch per process — the cached paths above return
             // before reaching here.
             await this.normalizeCloneConfig(repoDir, branch);
-            this.branchDirs.set(branch, workspaceDir);
+            this.registerBranchDir(branch, workspaceDir);
             return this.buildWorkspaceInfo(branch, workspaceDir);
         }
         catch {
@@ -351,7 +549,7 @@ export class WorkspaceService {
         const existingBootstrap = this.inFlightBootstraps.get(branch);
         if (existingBootstrap) {
             await existingBootstrap;
-            this.branchDirs.set(branch, workspaceDir);
+            this.registerBranchDir(branch, workspaceDir);
             return this.buildWorkspaceInfo(branch, workspaceDir);
         }
         this.inFlightBootstraps.set(branch, bootstrap);
@@ -360,7 +558,7 @@ export class WorkspaceService {
             // naturally; seeding the remote is the KB startup phase's job, at boot.
             await fs.mkdir(workspaceDir, { recursive: true });
             await this.cloneProcessMapForBranch(workspaceDir, branch);
-            this.branchDirs.set(branch, workspaceDir);
+            this.registerBranchDir(branch, workspaceDir);
             resolveBootstrap();
         }
         catch (err) {
@@ -442,13 +640,13 @@ export class WorkspaceService {
     async normalizeCloneConfig(repoDir, branch) {
         try {
             for (const args of cloneTrackingConfigArgs(branch)) {
-                await execFileAsync('git', ['-C', repoDir, ...args]);
+                await this.gitRunner.run(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 config of the "${branch}" clone:`, redactError(err));
+            log.warn(`could not normalize the config of the "${branch}" clone:`, { detail: redactError(err) });
         }
         await this.stampCredentialHelper(repoDir, branch);
     }
@@ -487,23 +685,25 @@ export class WorkspaceService {
             // re-clone that fails on the same validation — masking the real cause.
             // Contain it as a loud non-stamp instead; `normalizeCloneConfig`'s
             // never-throws contract stays true.
-            console.warn(`[workspace] refusing to stamp the credential helper of the "${branch}" clone:`, redactError(err));
+            log.warn(`refusing to stamp the credential helper of the "${branch}" clone:`, { detail: redactError(err) });
             this.stampedCredentialFingerprint.delete(branch);
             return;
         }
         let stamped = true;
         for (const args of argLists) {
             try {
-                await execFileAsync('git', ['-C', repoDir, ...args]);
+                await this.gitRunner.run(repoDir, args);
             }
             catch (err) {
                 // `--unset-all` with no matching value (exit 5) is the expected no-op
                 // for a clone that never carried an app helper; anything else is a
                 // real failure.
-                const code = err?.code;
+                const code = err?.exitCode;
                 if (!(args.includes('--unset-all') && code === 5)) {
                     stamped = false;
-                    console.warn(`[workspace] could not stamp the credential helper of the "${branch}" clone:`, redactError(err));
+                    log.warn(`could not stamp the credential helper of the "${branch}" clone:`, {
+                        detail: redactError(err),
+                    });
                 }
             }
         }
@@ -539,20 +739,23 @@ export class WorkspaceService {
         // 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;
-            }
+        //
+        // A FILE squatting the clone's name is refused outright, never wiped:
+        // the recovery below exists for a crashed bootstrap's directory shell,
+        // and a regular file here is a state a human put the deployment in — so
+        // it is named and stopped, the same stance the startup phase takes on a
+        // squatted reserved root. (Links are followed: one clone mounted
+        // elsewhere is the operator's business, as it is at the workspace root.)
+        const target = await fs.stat(targetDir).catch((err) => {
+            if (isAbsence(err))
+                return null;
+            throw err;
+        });
+        if (target !== null && !target.isDirectory()) {
+            throw new Error(`The clone path "${this.kbDirName}" in this workspace exists but is not a directory. ` +
+                'Remove or rename it — the platform requires this name to be the knowledge-base clone.');
         }
-        if (targetExists) {
+        if (target !== null) {
             // 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
@@ -570,10 +773,10 @@ export class WorkspaceService {
                 // 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') {
+                // (`targetDir` is known to be a directory here, so ENOTDIR can only
+                // mean `.git` itself vanished under us — an absence either way.)
+                if (!isAbsence(err))
                     throw err;
-                }
             }
             if (alreadyCloned) {
                 // We don't auto-pull because that could clobber another user's
@@ -593,19 +796,18 @@ export class WorkspaceService {
             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']);
+            await this.gitRunner.run(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]);
+            await this.gitRunner.run(targetDir, ['config', 'user.name', BOT_NAME]);
+            await this.gitRunner.run(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.normalizeCloneConfig(targetDir, branch);
-            console.log(`[workspace] Cloned ${this.kbDirName} for branch "${branch}"` +
-                (reference ? ' (referenced a sibling clone)' : ''));
+            log.info(`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
@@ -614,7 +816,9 @@ export class WorkspaceService {
                 this.onWorkspaceCloned?.(workspaceIdForBranch(branch));
             }
             catch (listenerErr) {
-                console.error(`[workspace] onWorkspaceCloned listener failed for branch "${branch}":`, redactError(listenerErr));
+                log.error(`onWorkspaceCloned listener failed for branch "${branch}":`, {
+                    detail: redactError(listenerErr),
+                });
             }
         }
         catch (err) {
@@ -622,15 +826,33 @@ export class WorkspaceService {
             // Roll back partial state so the next bootstrap retries cleanly.
             await fs.rm(targetDir, { recursive: true, force: true }).catch(() => { });
             // A branch origin does not have is a fact about the branch, not a
-            // failure of ours: the host deleted it (and the sync retired the
-            // clone), or the link was to a branch that never existed. Typed, so the
-            // routes answer 410 with the branch named and the browser can say "this
-            // branch no longer exists" instead of "something went wrong".
+            // failure of ours — but WHICH fact depends on whether the platform ever
+            // knew the name. A branch it cloned or listed and origin no longer has
+            // was deleted (410, "this branch no longer exists"); a name it has
+            // never seen is simply not a branch (404), and saying "no longer exists
+            // on the remote" to a typo tells the reader it once did.
             if (isMissingRemoteBranchFailure(redacted)) {
-                console.log(`[workspace] branch "${branch}" does not exist on origin — nothing to clone`);
-                throw new RemoteBranchGoneError(branch);
+                let everHeardOf;
+                try {
+                    everHeardOf = await this.hasHeardOfBranch(branch);
+                }
+                catch (probeErr) {
+                    // We could not read our own storage, so we cannot say which of the
+                    // two stories this is — and guessing either one states something
+                    // about the branch that we do not know. Our failure, so: 500.
+                    log.error(`Could not tell whether branch "${branch}" was ever known here:`, {
+                        detail: redactError(probeErr),
+                    });
+                    throw new Error(`Failed to clone process map: ${redacted}`);
+                }
+                if (everHeardOf) {
+                    log.info(`branch "${branch}" is gone from origin — nothing to clone`);
+                    throw new RemoteBranchGoneError(branch);
+                }
+                log.info(`branch "${branch}" has never existed here — nothing to clone`);
+                throw new BranchNotFoundError(branch);
             }
-            console.error(`[workspace] Failed to clone for branch "${branch}":`, redacted);
+            log.error(`Failed to clone for branch "${branch}":`, { detail: redacted });
             throw new Error(`Failed to clone process map: ${redacted}`);
         }
     }
@@ -656,20 +878,114 @@ export class WorkspaceService {
     }
     async listFiles(workspaceId, readFilter) {
         const workspaceDir = await this.resolveWorkspaceDir(workspaceId);
-        return this.buildFileTree(workspaceDir, workspaceDir, BevelIgnoreStack.empty(), readFilter);
+        return this.buildFileTree(workspaceDir, workspaceDir, readFilter);
+    }
+    /** The repository inside a workspace directory: `<workspaceDir>/<kbDirName>`. */
+    repoRoot(workspaceDir) {
+        return path.join(workspaceDir, this.kbDirName);
     }
-    async readFile(workspaceId, relativePath) {
+    /**
+     * THE resolution — the only place in this service that turns a workspace
+     * path into a location on disk.
+     *
+     * Two steps, and neither is optional. `normalizeWorkspacePath` places the
+     * path inside the repository (`KnowledgeBase/Report.md` is the page of that
+     * name in the checkout, not a stray beside it) and refuses `.`/`..`,
+     * backslashes and absolute paths outright. Then the RESOLVED path is checked
+     * against `<workspaceDir>/<kbDirName>` — after normalisation, because that
+     * is the path the operation will use, and a spelling that normalises inside
+     * and resolves outside is exactly the miss this check exists to catch.
+     *
+     * Callers use the returned `relativePath` for everything downstream — the
+     * git-internals check, the diff baseline, the lock-free path turns, their own
+     * error messages — so what is checked is what is written. Nine inline
+     * `path.resolve(workspaceDir, …)` calls used to do this, none of them
+     * checking the repository root; a drift-guard test now fails if one returns.
+     */
+    async resolveInsideRepo(workspaceId, wsPath) {
         const workspaceDir = await this.resolveWorkspaceDir(workspaceId);
+        const relativePath = normalizeWorkspacePath(wsPath, this.kbDirName);
         const absolutePath = path.resolve(workspaceDir, relativePath);
-        this.assertWithinWorkspace(absolutePath, workspaceDir);
+        assertWithinDirectory(absolutePath, this.repoRoot(workspaceDir));
+        return { workspaceDir, relativePath, absolutePath };
+    }
+    async readFile(workspaceId, wsPath) {
+        const { workspaceDir, relativePath, absolutePath } = await this.resolveInsideRepo(workspaceId, wsPath);
+        assertNoGitInternalsSegment(relativePath);
+        await assertNotGitInternals(workspaceDir, relativePath, absolutePath);
+        await this.assertNotThroughLink(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);
+    async readFileBinary(workspaceId, wsPath) {
+        const { workspaceDir, relativePath, absolutePath } = await this.resolveInsideRepo(workspaceId, wsPath);
+        assertNoGitInternalsSegment(relativePath);
+        await assertNotGitInternals(workspaceDir, relativePath, absolutePath);
+        await this.assertNotThroughLink(absolutePath, workspaceDir);
         return fs.readFile(absolutePath);
     }
+    /**
+     * Refuse a path that reaches its file through a symbolic link — as the
+     * final component, or as any directory between the workspace root and it.
+     * `resolveInsideRepo`'s containment is lexical: `knowledge-base/notes.md`
+     * passes it however the name resolves, so a link the repository carries (they only
+     * arrive by direct git push; the app's own writes never create one) would
+     * let a read hand out bytes from anywhere the server process can read, and
+     * a write replace whatever the link points at. The rule is the plugin
+     * archive's: the deepest ancestor that exists must resolve to exactly its
+     * own spelling under the workspace's resolved root — identity, not mere
+     * containment — and the entry itself, when it exists, must not be a link.
+     * The workspace root may sit behind a link of the operator's (a mounted
+     * volume): both sides are resolved, so that is allowed.
+     *
+     * The same refusal as the lexical check on purpose: this IS a traversal,
+     * reached through a link rather than through a spelling.
+     */
+    async assertNotThroughLink(absolutePath, workspaceDir) {
+        const traversal = () => new PathTraversalError();
+        const entry = await fs.lstat(absolutePath).catch((err) => {
+            if (isAbsence(err))
+                return null;
+            throw err;
+        });
+        if (entry?.isSymbolicLink())
+            throw traversal();
+        // The deepest existing ancestor: a write creates the rest, under it. Each
+        // ancestor is lstat-ed BEFORE its absence is taken as leave to climb: a
+        // dangling link resolves to nothing too, and climbing past it would let
+        // a target created in the meantime receive the write.
+        let ancestor = path.dirname(absolutePath);
+        let realAncestor = null;
+        while (realAncestor === null) {
+            const ancestorEntry = await fs.lstat(ancestor).catch((err) => {
+                if (isAbsence(err))
+                    return null;
+                throw err;
+            });
+            // The workspace directory itself may be a link of the operator's (one
+            // workspace mounted elsewhere), like the root above it; the identity
+            // check below still holds everything beneath it to its own spelling.
+            if (ancestorEntry?.isSymbolicLink() && path.resolve(ancestor) !== path.resolve(workspaceDir))
+                throw traversal();
+            realAncestor = await fs.realpath(ancestor).catch((err) => {
+                if (isAbsence(err))
+                    return null;
+                throw err;
+            });
+            if (realAncestor === null) {
+                const up = path.dirname(ancestor);
+                if (up === ancestor)
+                    throw traversal();
+                ancestor = up;
+            }
+        }
+        const realRoot = await fs.realpath(workspaceDir);
+        const expected = path.join(realRoot, path.relative(path.resolve(workspaceDir), ancestor));
+        const same = process.platform === 'win32'
+            ? realAncestor.toLowerCase() === expected.toLowerCase()
+            : realAncestor === expected;
+        if (!same)
+            throw traversal();
+    }
     /**
      * 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`)
@@ -684,26 +1000,16 @@ export class WorkspaceService {
         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());
+        await this.disk.walk(repoRoot, explorerWalk(), [
+            {
+                async onFile(dir, name) {
+                    if (!name.endsWith('.md'))
+                        return;
+                    const repoPath = dir ? `${dir}/${name}` : name;
+                    files[repoPath] = await fs.readFile(path.join(repoRoot, dir, name), 'utf-8');
+                },
+            },
+        ]);
         return files;
     }
     /**
@@ -719,10 +1025,10 @@ export class WorkspaceService {
      * 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);
+    async createFolderZip(workspaceId, wsPath) {
+        const { workspaceDir, relativePath, absolutePath: absoluteRoot } = await this.resolveInsideRepo(workspaceId, wsPath);
+        assertNoGitInternalsSegment(relativePath);
+        await assertNotGitInternals(workspaceDir, relativePath, absoluteRoot);
         const stat = await fs.stat(absoluteRoot);
         if (!stat.isDirectory()) {
             throw new Error('Not a directory');
@@ -730,48 +1036,31 @@ export class WorkspaceService {
         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());
+        await this.disk.walk(absoluteRoot, explorerWalk(), [
+            {
+                async onFile(dir, name) {
+                    const childAbs = path.join(absoluteRoot, dir, name);
+                    // 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.
+                    zip.addFile(`${zipRoot}/${dir ? `${dir}/${name}` : name}`, data);
+                },
+            },
+        ]);
         return zip.toBuffer();
     }
     /**
@@ -782,6 +1071,7 @@ export class WorkspaceService {
      */
     async readFileAtRef(workspaceId, ref, relativePath) {
         this.assertValidGitRef(ref);
+        assertNoGitInternalsSegment(relativePath);
         this.assertValidRepoRelativePath(relativePath);
         const workspaceDir = await this.resolveWorkspaceDir(workspaceId);
         const repoDir = path.join(workspaceDir, this.kbDirName);
@@ -791,7 +1081,7 @@ export class WorkspaceService {
         }
         for (const candidate of candidates) {
             try {
-                const { stdout } = await execFileAsync('git', ['-C', repoDir, 'show', `${candidate}:${relativePath}`], { encoding: 'utf-8', maxBuffer: 16 * 1024 * 1024 });
+                const { stdout } = await this.gitRunner.run(repoDir, ['show', `${candidate}:${relativePath}`]);
                 return stdout;
             }
             catch {
@@ -804,6 +1094,13 @@ export class WorkspaceService {
      * 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.
+     *
+     * `force` skips the TTL — for a caller that KNOWS the remote just moved
+     * (an event-driven `?fresh=1` read, which bypasses its own cache for the
+     * same reason) and would otherwise answer from refs older than the change
+     * it is being asked about. It keeps the in-flight join, which is the half
+     * that actually prevents storms: ten forced callers in the same tick still
+     * share one fetch.
      */
     async ensureRemotesFetched(workspaceId, opts = {}) {
         const workspaceDir = await this.resolveWorkspaceDir(workspaceId);
@@ -812,7 +1109,7 @@ export class WorkspaceService {
         // The TTL is stamped only by a SUCCESSFUL fetch, so a fresh window is
         // itself the proof a strict caller wants.
         const last = this.lastFetchAt.get(repoDir) ?? 0;
-        if (now - last < FETCH_CACHE_TTL_MS)
+        if (!opts.force && now - last < FETCH_CACHE_TTL_MS)
             return;
         const inFlight = this.inFlightFetches.get(repoDir);
         if (inFlight) {
@@ -828,14 +1125,15 @@ export class WorkspaceService {
         // 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 `kb-fs/clone-config.ts` for the full rationale.
-        const promise = execFileAsync('git', ['-C', repoDir, ...SAFE_IMPLICIT_FETCH_ARGS], { env: { ...process.env } })
+        const promise = this.gitRunner
+            .run(repoDir, [...SAFE_IMPLICIT_FETCH_ARGS])
             .then(() => {
             this.lastFetchAt.set(repoDir, Date.now());
             this.lastFetchOk.set(repoDir, true);
         })
             .catch((err) => {
             this.lastFetchOk.set(repoDir, false);
-            console.warn('[workspace] git fetch origin failed:', redactError(err));
+            log.warn('git fetch origin failed:', { detail: redactError(err) });
         })
             .finally(() => {
             if (this.inFlightFetches.get(repoDir) === promise) {
@@ -862,12 +1160,20 @@ export class WorkspaceService {
             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);
+    async deleteFile(workspaceId, wsPath) {
+        const { workspaceDir, relativePath, absolutePath } = await this.resolveInsideRepo(workspaceId, wsPath);
+        assertNoGitInternalsSegment(relativePath);
+        // Under the path's turn like every other single-file mutation: a delete
+        // landing between a conditional write's compare and its write would let
+        // that write recreate the file the delete had just removed. The diff
+        // baseline is updated inside the same turn, so two mutations of one path
+        // update it in the order they landed on disk. The resolved git check runs
+        // inside the turn too (see `withPathTurn`), so it cannot reorder callers.
+        await this.withResolvedPathTurn(absolutePath, async () => {
+            await assertNotGitInternals(workspaceDir, relativePath, absolutePath);
+            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
@@ -887,65 +1193,319 @@ export class WorkspaceService {
         }
         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);
+    /**
+     * Rename or move one entry.
+     *
+     * Deliberately NOT under {@link withPathTurn}: a move mutates two paths, and
+     * holding both turns would introduce the one shape that can deadlock here
+     * (a move waiting on a target whose holder is waiting on the move's other
+     * path). A rename onto a path being conditionally written is therefore
+     * outside that guarantee; the workflow lock on the moved path is what
+     * serializes it against the app's own editors.
+     */
+    async moveEntry(workspaceId, oldWsPath, newWsPath) {
+        const { workspaceDir, relativePath: oldRelativePath, absolutePath: oldAbsolute } = await this.resolveInsideRepo(workspaceId, oldWsPath);
+        const { relativePath: newRelativePath, absolutePath: newAbsolute } = await this.resolveInsideRepo(workspaceId, newWsPath);
+        // A move and a rename are the same call, so this is where the checkout's
+        // own name is reserved at the repository root for both.
+        assertRepoRootNameFree(newRelativePath, this.kbDirName);
+        assertNoGitInternalsSegment(oldRelativePath);
+        assertNoGitInternalsSegment(newRelativePath);
+        assertValidPath(newRelativePath);
+        await assertNotGitInternals(workspaceDir, oldRelativePath, oldAbsolute);
+        await assertNotGitInternals(workspaceDir, newRelativePath, newAbsolute);
+        // Both ends: a link on the way to either end would carry the rename
+        // outside. A link used AS the source is refused too — a committed link
+        // is not something the app moves around, any more than reads it.
+        await this.assertNotThroughLink(oldAbsolute, workspaceDir);
+        await this.assertNotThroughLink(newAbsolute, workspaceDir);
+        // Before `mkdir`, so a refused move leaves no empty folder behind — and
+        // it is the look that produces the sentence naming what is in the way.
+        await this.assertDestinationFree(oldAbsolute, newAbsolute, newRelativePath);
         await fs.mkdir(path.dirname(newAbsolute), { recursive: true });
-        await fs.rename(oldAbsolute, newAbsolute);
+        // The move itself cannot replace anything either, so a destination that
+        // appears between the look above and this line is refused rather than
+        // eaten (`shared/rename-no-replace.ts`). This path takes no lock on
+        // purpose — see the note above — so the atomicity has to come from the
+        // filesystem call.
+        try {
+            await renameNoReplace(oldAbsolute, newAbsolute, newRelativePath);
+        }
+        catch (err) {
+            if (err instanceof DestinationTakenError) {
+                throw new EntryExistsError(err.entryKind, newRelativePath);
+            }
+            throw err;
+        }
         if (this.diffService) {
             await this.diffService.markUserDeleted(workspaceId, oldRelativePath);
             await this.diffService.syncFromDisk(workspaceId, newRelativePath);
         }
     }
-    async writeFile(workspaceId, relativePath, content, options) {
-        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 });
+    /**
+     * Refuse a move onto a name that is taken. `fs.rename` REPLACES an existing
+     * file on every platform — that is how renaming a `.docx` onto an existing
+     * `.md` handed the markdown file the Word bytes — so the destination is
+     * looked at first, and a move never overwrites a file or merges into a
+     * folder.
+     *
+     * Judged by `inspectDestination`, which reads a case-only rename on a
+     * case-insensitive filesystem — where `notes.md` → `Notes.md` finds the
+     * SOURCE at the destination — as the rename that was asked for rather than a
+     * clash, and everything else as a clash. It is the same reading the move
+     * itself uses, so the sentence and the refusal cannot drift apart.
+     */
+    async assertDestinationFree(oldAbsolute, newAbsolute, newRelativePath) {
+        const verdict = await inspectDestination(oldAbsolute, newAbsolute);
+        if (verdict.state === 'taken')
+            throw new EntryExistsError(verdict.kind, newRelativePath);
+    }
+    /**
+     * Refuse a conditional write, with the same 409 {@link writeFile} throws,
+     * without writing anything. The route calls this BEFORE the creator-access
+     * plan: that plan can commit a seeded `access.md` under its own lock, and a
+     * precondition failing after it would leave an authorization grant behind
+     * for a save that never landed. The write's own compare, under its write
+     * turn, stays the authoritative one; this only keeps the refusal free of
+     * side effects.
+     */
+    async assertContentMatches(workspaceId, wsPath, expectedContent) {
+        const { workspaceDir, relativePath, absolutePath } = await this.resolveInsideRepo(workspaceId, wsPath);
+        assertNoGitInternalsSegment(relativePath);
+        assertValidPath(relativePath);
+        await assertNotGitInternals(workspaceDir, relativePath, absolutePath);
+        await assertConditionalWriteMatches(absolutePath, relativePath, expectedContent);
+    }
+    /**
+     * Run `op` as the only mutation in flight for `relativePath` in this
+     * process, so a read-then-decide-then-write sequence inside it cannot have
+     * another mutation land in the middle of it.
+     *
+     * The conditional write ({@link writeFile}'s `expectedContent`) needs that,
+     * and so does a caller whose decision spans more than one call: `PUT /file`
+     * checks the precondition, plans a creator-access grant that COMMITS, and
+     * only then writes, and a save that lands in between would leave that grant
+     * behind for a write about to be refused. Such a caller wraps the sequence
+     * in a turn and the write inside it takes the same one, re-entrantly.
+     *
+     * The route's own per-path lock does not establish this: it deliberately
+     * runs the op WITHOUT acquiring when the caller already holds the lock, so
+     * two requests from that holder would interleave.
+     *
+     * The reach of the guarantee, exactly: within this process, one mutation at
+     * a time per resolved path. ACROSS instances the workflow lock row is the
+     * coordinator, and it agrees with this queue only because `PUT /file`
+     * canonicalises the path before taking either (see `canonicalRelativePath`);
+     * a caller that reaches the service directly with an odd spelling gets the
+     * local queue and whatever lock it took itself. Case is not folded: on the
+     * Linux deployment target `Foo.md` and `foo.md` are two files, and treating
+     * them as one would be a worse bug than the race it would close.
+     */
+    async withPathTurn(workspaceId, wsPath, op) {
+        const { workspaceDir, relativePath, absolutePath } = await this.resolveInsideRepo(workspaceId, wsPath);
+        assertNoGitInternalsSegment(relativePath);
+        assertValidPath(relativePath);
+        // The resolved check reads the disk, and how long that takes depends on
+        // the spelling. Run before the queue, it let a later call overtake an
+        // earlier one for the same file; inside the turn, callers keep their order
+        // and `op` still never runs on a path that resolves into the git folder.
+        return this.withResolvedPathTurn(absolutePath, async () => {
+            await assertNotGitInternals(workspaceDir, relativePath, absolutePath);
+            return op();
+        });
+    }
+    /**
+     * One folder structure change at a time per SUBTREE: an explicit folder
+     * delete and the placeholder that keeps an emptied folder. Two turns wait
+     * for each other when one folder is, or sits inside, the other, so keeping
+     * a folder can never run in the middle of deleting it (and write the
+     * placeholder back into a folder whose delete already enumerated its
+     * files), and a delete never starts while a folder under it is being kept.
+     * Not re-entrant: take it once, and never around another folder's turn.
+     *
+     * The reach of the guarantee, like {@link withPathTurn}'s: within this
+     * process, over this process's clones. Across instances the workflow lock
+     * rows coordinate — the placeholder write takes its own path's lock, as the
+     * folder delete takes each file's — and each clone's changes meet in git,
+     * as any write into a folder another instance deletes already does.
+     */
+    async withFolderTurn(workspaceId, wsDir, op) {
+        const { relativePath: relativeDir, absolutePath: absoluteDir } = await this.resolveInsideRepo(workspaceId, wsDir);
+        assertValidPath(relativeDir);
+        const overlaps = (held) => held === absoluteDir ||
+            held.startsWith(absoluteDir + path.sep) ||
+            absoluteDir.startsWith(held + path.sep);
+        // Check-and-claim with no await in between, so two callers cannot both
+        // find the subtree free.
+        for (;;) {
+            const waiting = [...this.folderTurns].filter(([held]) => overlaps(held)).map(([, turn]) => turn);
+            if (waiting.length === 0)
+                break;
+            await Promise.all(waiting);
+        }
+        let release;
+        this.folderTurns.set(absoluteDir, new Promise((resolve) => (release = resolve)));
         try {
-            // `wx` makes create-if-absent ATOMIC at the fs level — an exists-check
-            // followed by a plain write would let two concurrent creators (or a
-            // stale client whose file list predates the file) both pass the check
-            // and silently replace each other's content.
-            await fs.writeFile(absolutePath, content, {
-                encoding: 'utf-8',
-                flag: options?.failIfExists ? 'wx' : 'w',
-            });
+            return await op();
         }
-        catch (err) {
-            if (err.code === 'EEXIST') {
-                const conflict = new Error(`"${relativePath}" already exists.`);
-                conflict.status = 409;
-                throw conflict;
-            }
-            throw err;
+        finally {
+            this.folderTurns.delete(absoluteDir);
+            release();
         }
-        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);
+    /**
+     * {@link withPathTurn} on an already-resolved path.
+     *
+     * A turn this context holds runs through: waiting for itself would hang.
+     * What is stored is the SETTLED tail, never the caller's promise, so a
+     * throwing mutation cannot wedge the queue behind it and no rejection is
+     * left unhandled; the entry is dropped once it is still the tail, so the
+     * map does not grow by an entry per file ever touched.
+     *
+     * Nesting a DIFFERENT file's turn inside one is safe here because the only
+     * caller that does it is `PUT /file`, and the grant it seeds is always an
+     * `access.md` at or above its target: two such sequences cannot each hold
+     * what the other wants, since that would need each target to sit above the
+     * other. Every other holder takes one turn and nests nothing.
+     */
+    async withResolvedPathTurn(absolutePath, op) {
+        const held = this.heldTurns.getStore();
+        const inner = held?.get(absolutePath);
+        if (inner) {
+            // Re-entrant: runs without waiting for the turn this context holds —
+            // but behind any sibling launched inside that same turn, so a held
+            // turn that fires two conditional writes at once cannot have both
+            // compare the same old content and then overwrite each other.
+            const turn = inner.tail.then(() => op());
+            inner.tail = turn.then(() => undefined, () => undefined);
+            return turn;
+        }
+        const run = () => this.heldTurns.run(new Map([...(held ?? []), [absolutePath, { tail: Promise.resolve() }]]), op);
+        const previous = this.writeTurns.get(absolutePath);
+        const turn = previous ? previous.then(run) : run();
+        const tail = turn.then(() => undefined, () => undefined);
+        this.writeTurns.set(absolutePath, tail);
+        void tail.then(() => {
+            if (this.writeTurns.get(absolutePath) === tail)
+                this.writeTurns.delete(absolutePath);
+        });
+        return turn;
+    }
+    /**
+     * Write one workspace file.
+     *
+     * - `failIfExists` is an exclusive create (see the `wx` note below).
+     * - `expectedContent` is a conditional write: the file must still hold
+     *   exactly that text, or the write is refused with a 409. It is what lets
+     *   an editor that composed its save from a snapshot (the inline agent
+     *   description merges the private comments it read minutes earlier) refuse
+     *   rather than erase whatever landed in between. An absent file reads as
+     *   the empty string, so `expectedContent: ''` means "expect nothing there
+     *   yet" and creates it.
+     *
+     * The compare and the write run inside this path's write turn, so no other
+     * write through this service can land between them, whatever locking the
+     * caller did or skipped.
+     */
+    async writeFile(workspaceId, wsPath, content, options) {
+        const { workspaceDir, relativePath, absolutePath } = await this.resolveInsideRepo(workspaceId, wsPath);
+        // A write creates the folders on the way to it, so the reserved root name
+        // is refused here too — otherwise `knowledge-base/knowledge-base/x.md`
+        // would bring the unreachable folder into existence around the file.
+        assertRepoRootNameFree(relativePath, this.kbDirName);
+        assertNoGitInternalsSegment(relativePath);
+        assertValidPath(relativePath);
+        await this.withResolvedPathTurn(absolutePath, async () => {
+            // Inside the turn, beside the link check (see `withPathTurn`).
+            await assertNotGitInternals(workspaceDir, relativePath, absolutePath);
+            await this.assertNotThroughLink(absolutePath, workspaceDir);
+            // Compare BEFORE creating anything. The parent chain used to be made
+            // first, so a refused save at `x/new-folder/note.md` left an empty
+            // `x/new-folder/` behind in everyone's tree — for a write that never
+            // happened. The compare reads the file, and an absent file reads as
+            // empty whether or not its directory exists.
+            if (options?.expectedContent !== undefined) {
+                await assertConditionalWriteMatches(absolutePath, relativePath, options.expectedContent);
+            }
+            await fs.mkdir(path.dirname(absolutePath), { recursive: true });
+            try {
+                // `wx` makes create-if-absent ATOMIC at the fs level — an exists-check
+                // followed by a plain write would let two concurrent creators (or a
+                // stale client whose file list predates the file) both pass the check
+                // and silently replace each other's content.
+                await fs.writeFile(absolutePath, content, {
+                    encoding: 'utf-8',
+                    flag: options?.failIfExists ? 'wx' : 'w',
+                });
+            }
+            catch (err) {
+                if (err.code === 'EEXIST') {
+                    const conflict = new Error(`"${relativePath}" already exists.`);
+                    conflict.status = 409;
+                    throw conflict;
+                }
+                throw err;
+            }
+            // Inside the turn, so the baseline follows the order the writes landed in.
+            await this.diffService?.syncFromDisk(workspaceId, relativePath);
+        });
+    }
+    async createDirectory(workspaceId, wsPath) {
+        const { workspaceDir, relativePath, absolutePath } = await this.resolveInsideRepo(workspaceId, wsPath);
+        assertRepoRootNameFree(relativePath, this.kbDirName);
+        assertNoGitInternalsSegment(relativePath);
+        assertValidPath(relativePath);
+        await assertNotGitInternals(workspaceDir, relativePath, absolutePath);
+        await this.assertNotThroughLink(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');
+            await fs.writeFile(path.join(absolutePath, FOLDER_PLACEHOLDER), '', '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);
+    /**
+     * Write the empty-folder placeholder into `relativeDir` when that folder
+     * exists and holds nothing; true when it wrote one. Unlike
+     * {@link createDirectory} it never creates the folder: one that is gone was
+     * deleted explicitly and stays gone. A folder reached through a link is
+     * refused like any write through one, so the placeholder cannot land
+     * outside the workspace.
+     */
+    async writeFolderPlaceholder(workspaceId, wsDir) {
+        const { workspaceDir, relativePath: relativeDir, absolutePath: absoluteDir } = await this.resolveInsideRepo(workspaceId, wsDir);
+        assertValidPath(relativeDir);
+        const placeholder = path.join(absoluteDir, FOLDER_PLACEHOLDER);
+        await this.assertNotThroughLink(placeholder, workspaceDir);
+        let entries;
+        try {
+            entries = await fs.readdir(absoluteDir);
+        }
+        catch (err) {
+            if (isAbsence(err))
+                return false;
+            throw err;
+        }
+        if (entries.length > 0)
+            return false;
+        await fs.writeFile(placeholder, '', { flag: 'wx' });
+        return true;
+    }
+    async writeFileBinary(workspaceId, wsPath, data) {
+        const { workspaceDir, relativePath, absolutePath } = await this.resolveInsideRepo(workspaceId, wsPath);
+        assertRepoRootNameFree(relativePath, this.kbDirName);
+        assertNoGitInternalsSegment(relativePath);
+        assertValidPath(relativePath);
+        // An upload over a path is a mutation of that path, so it takes the same
+        // turn as a text write: see {@link withPathTurn}. The whole of it — the
+        // parent chain too, so a folder delete serialized before this turn
+        // cannot remove the parent between its creation and the write.
+        await this.withResolvedPathTurn(absolutePath, async () => {
+            await assertNotGitInternals(workspaceDir, relativePath, absolutePath);
+            await this.assertNotThroughLink(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
@@ -953,7 +1513,7 @@ export class WorkspaceService {
      * Validation + zip-bomb guards are identical to the per-user version that
      * preceded the workspace-per-branch migration.
      */
-    async unzipFile(workspaceId, zipRelativePath, destDirRelativePath, 
+    async unzipFile(workspaceId, zipWsPath, destDirWsPath, 
     /**
      * Per-extracted-path write guard (ontology-session boundary). Called with
      * each entry's workspace-relative target before it is written; if it throws,
@@ -961,28 +1521,55 @@ export class WorkspaceService {
      * 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);
+        const { workspaceDir, relativePath: zipRelativePath, absolutePath: zipAbsolute } = await this.resolveInsideRepo(workspaceId, zipWsPath);
+        assertNoGitInternalsSegment(zipRelativePath);
+        await assertNotGitInternals(workspaceDir, zipRelativePath, zipAbsolute);
         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);
+            throw new WorkflowValidationError('Only .zip files can be extracted');
+        }
+        // Inferred from the NORMALISED archive path, so an archive named without
+        // the prefix extracts beside itself inside the repository rather than at
+        // the workspace root.
+        const inferredDest = path.posix.dirname(zipRelativePath);
+        const { relativePath: destRel, absolutePath: destAbsolute } = await this.resolveInsideRepo(workspaceId, destDirWsPath ?? inferredDest);
+        assertValidPath(destRel);
+        assertNoGitInternalsSegment(destRel);
+        await assertNotGitInternals(workspaceDir, destRel, destAbsolute);
+        // Neither the archive nor the destination may sit behind a link; each
+        // entry's own target is checked again below, once it is known.
+        await this.assertNotThroughLink(zipAbsolute, workspaceDir);
+        if (destAbsolute !== this.repoRoot(workspaceDir))
+            await this.assertNotThroughLink(destAbsolute, workspaceDir);
+        // The archive is READ ONCE, here, and the reader is handed those bytes —
+        // it is never given the path to open for itself. Two reasons, and the
+        // first is why this is not a `stat` followed by `new AdmZip(path)`:
+        //
+        //  - The zip reader cannot tell absence from corruption. On a path with
+        //    nothing at it `AdmZip` throws "ADM-ZIP: Invalid filename", which would
+        //    be dressed up as an unreadable archive (422) and blame the bytes for
+        //    a name that never existed. Only the read knows which it was.
+        //  - A separate probe answers about a DIFFERENT moment than the open. An
+        //    archive deleted in between passed the probe and then failed the open,
+        //    and the caller got the 422 the probe existed to prevent. One read is
+        //    one moment, so there is no in-between to lose.
+        //
+        // `AdmZip` from a buffer costs nothing extra: given a path it reads the
+        // whole file in anyway.
+        let zipBytes;
+        try {
+            zipBytes = await fs.readFile(zipAbsolute);
+        }
+        catch (err) {
+            if (isAbsence(err))
+                throw new PathNotFoundError(zipRelativePath);
+            throw err;
+        }
         let zip;
         try {
-            zip = new AdmZip(zipAbsolute);
+            zip = new AdmZip(zipBytes);
         }
         catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            throw new Error(`Could not read zip file: ${msg}`);
+            throw new UnreadableArchiveError(err instanceof Error ? err.message : String(err));
         }
         // The destination directory is created on demand by the first allowed entry
         // (each guarded path mkdirs its parents with `recursive: true`). Creating it
@@ -1012,6 +1599,11 @@ export class WorkspaceService {
                 skipped.push({ path: rawName || '(empty)', reason: 'Invalid path' });
                 continue;
             }
+            // An archive never writes into the git folder, whatever the entry's spelling.
+            if (hasGitInternalsSegment(rawName)) {
+                skipped.push({ path: rawName, reason: new GitInternalsError().message });
+                continue;
+            }
             const trimmed = rawName.replace(/\/+$/, '');
             const segments = trimmed.split('/').filter((s) => s.length > 0);
             let invalidReason = null;
@@ -1051,6 +1643,38 @@ export class WorkspaceService {
                     return false;
                 }
             };
+            // The symbolic-link rule, per entry: a link already on disk under the
+            // destination must not redirect this entry's bytes. Reported like the
+            // other per-entry refusals, so one such entry does not fail the rest.
+            // The checkout's own name is reserved at the repository root here too: an
+            // archive carrying it would otherwise create the one folder no workspace
+            // path can name. Reported like the other per-entry refusals — one such
+            // entry does not fail the rest — and asked on its own rather than inside
+            // the catch below, which stays the closed list of types it was.
+            const reservedName = (() => {
+                try {
+                    assertRepoRootNameFree(relForReport, this.kbDirName);
+                    return null;
+                }
+                catch (err) {
+                    return err instanceof Error ? err.message : String(err);
+                }
+            })();
+            if (reservedName !== null) {
+                skipped.push({ path: rawName, reason: reservedName });
+                continue;
+            }
+            try {
+                await assertNotGitInternals(workspaceDir, trimmed, targetAbsolute);
+                await this.assertNotThroughLink(targetAbsolute, workspaceDir);
+            }
+            catch (err) {
+                if (err instanceof PathTraversalError || err instanceof GitInternalsError) {
+                    skipped.push({ path: rawName, reason: err.message });
+                    continue;
+                }
+                throw err;
+            }
             if (entry.isDirectory) {
                 if (!(await allowEntry()))
                     continue;
@@ -1188,13 +1812,10 @@ export class WorkspaceService {
         }
         let stdout;
         try {
-            ({ stdout } = await execFileAsync('git', ['-C', repoDir, 'status', '--porcelain=v1', '-z'], {
-                encoding: 'utf-8',
-                maxBuffer: 16 * 1024 * 1024,
-            }));
+            ({ stdout } = await this.gitRunner.run(repoDir, ['status', '--porcelain=v1', '-z']));
         }
         catch (err) {
-            console.warn(`[workspace] orphan scan via git status failed for ${workspaceId}:`, err instanceof Error ? err.message : err);
+            log.warn(`orphan scan via git status failed for ${workspaceId}:`, { err });
             return [];
         }
         if (!stdout.trim())
@@ -1266,7 +1887,7 @@ export class WorkspaceService {
                 removed.push(entry.name);
             }
             catch (err) {
-                console.warn(`[workspace] sweep failed for ${entry.name}:`, err instanceof Error ? err.message : err);
+                log.warn(`sweep failed for ${entry.name}:`, { err });
             }
         }
         return { removed };
@@ -1331,7 +1952,7 @@ export class WorkspaceService {
         const workspaceDir = this.workspaceDirWithinRoot(workspaceId);
         try {
             await fs.access(path.join(workspaceDir, this.kbDirName, '.git'));
-            this.branchDirs.set(branch, workspaceDir);
+            this.registerBranchDir(branch, workspaceDir);
             return workspaceDir;
         }
         catch {
@@ -1358,71 +1979,105 @@ export class WorkspaceService {
             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 the
-        // caller can't read. A directory is kept when the caller can read it — a
-        // readable directory left empty after filtering stays visible, the folder
-        // itself is readable — OR when something readable survives beneath it: a
-        // grant below (a linked skill's folder opened to a plugin's readers, a
-        // sub-folder shared on its own) makes the folders above it the way there,
-        // shown as containers whose own contents stay filtered. So an unreadable
-        // directory is walked, not skipped, and dropped only when the walk finds
-        // nothing. Fail-closed: anything not explicitly readable is dropped. No
-        // filter → identical to the pre-feature tree (regression-safe).
-        const verdict = readFilter && candidates.length > 0 ? await readFilter(candidates.map((c) => c.rel)) : null;
-        const readable = (rel) => verdict === null || verdict.get(rel) === true;
-        const children = [];
-        for (const { entry, entryPath, rel } of candidates) {
-            if (entry.isDirectory()) {
-                const sub = await this.buildFileTree(entryPath, workspaceRoot, ignoreStack, readFilter);
-                if (readable(rel) || (sub.children?.length ?? 0) > 0)
+    async buildFileTree(root, workspaceRoot, readFilter) {
+        const relOf = (abs) => path.relative(workspaceRoot, abs).replace(/\\/g, '/');
+        const top = { name: path.basename(root), relativePath: relOf(root) || '.', readable: true, unlisted: false, children: [], withheld: 0 };
+        const nodes = new Map([['', top]]);
+        await this.disk.walk(root, explorerWalk(), [
+            {
+                async onDir(rel, entries) {
+                    const node = nodes.get(rel);
+                    const abs = path.join(root, rel);
+                    const rels = entries.map((e) => relOf(path.join(abs, e.name)));
+                    // Read-permission filter: ONE batched check per directory. Drops files the
+                    // caller can't read. A directory is kept when the caller can read it — a
+                    // readable directory left empty after filtering stays visible, the folder
+                    // itself is readable — OR when something readable survives beneath it: a
+                    // grant below (a linked skill's folder opened to a plugin's readers, a
+                    // sub-folder shared on its own) makes the folders above it the way there,
+                    // shown as containers whose own contents stay filtered. So an unreadable
+                    // directory is walked, not skipped, and dropped only when the walk finds
+                    // nothing (see `finish`). Fail-closed: anything not explicitly readable is
+                    // dropped. No filter → identical to the pre-feature tree (regression-safe).
+                    const verdict = readFilter && entries.length > 0 ? await readFilter(rels) : null;
+                    const readable = (rel) => verdict === null || verdict.get(rel) === true;
+                    const unlisted = (rel) => verdict !== null && verdict.get(rel) === 'unlisted';
+                    entries.forEach((entry, i) => {
+                        const entryRel = rels[i];
+                        if (entry.isDirectory()) {
+                            const child = {
+                                name: entry.name,
+                                relativePath: entryRel,
+                                readable: readable(entryRel),
+                                unlisted: unlisted(entryRel),
+                                children: [],
+                                withheld: 0,
+                            };
+                            nodes.set(rel ? `${rel}/${entry.name}` : entry.name, child);
+                            node.children.push(child);
+                        }
+                        else if (readable(entryRel)) {
+                            node.children.push({ name: entry.name, relativePath: entryRel, type: 'file' });
+                        }
+                        else if (!unlisted(entryRel)) {
+                            node.withheld++;
+                        }
+                    });
+                },
+            },
+        ]);
+        /**
+         * Bottom-up: drop a folder the caller may not read once nothing readable
+         * turned up beneath it; sort each level. Each folder that stays carries
+         * how many entries were withheld anywhere under it (a dropped folder
+         * counts as one, its own subtree's count included), so a tree drawn from
+         * ONE folder — the Library's, a delete's — can tell "empty" from "kept
+         * from you" for that folder rather than for the listing. Only when
+         * something was withheld, so an unfiltered — or all-readable — listing
+         * stays exactly the tree it always was.
+         */
+        const finish = (node) => {
+            const children = [];
+            let withheld = node.withheld;
+            for (const child of node.children) {
+                if ('type' in child) {
+                    children.push(child);
+                    continue;
+                }
+                const sub = finish(child);
+                withheld += sub.withheld ?? 0;
+                if (child.readable || (sub.children?.length ?? 0) > 0)
                     children.push(sub);
+                else if (!child.unlisted)
+                    withheld++;
             }
-            else if (readable(rel)) {
-                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,
+            children.sort((a, b) => {
+                if (a.type !== b.type)
+                    return a.type === 'directory' ? -1 : 1;
+                return a.name.localeCompare(b.name);
+            });
+            const entry = { name: node.name, relativePath: node.relativePath, type: 'directory', children };
+            return withheld > 0 ? { ...entry, withheld } : entry;
         };
+        return finish(top);
     }
 }
+/**
+ * The explorer's walk of a workspace: no git internals (never user content,
+ * and listing it would blow up the tree), no `.gitkeep` (the empty-folder
+ * placeholder, not worth showing), `.bevelignore` honoured on the way down —
+ * and a folder that cannot be listed is the request's error, not a tree with
+ * a silent gap. A folder download and the whole-KB read walk the same way,
+ * so they carry exactly what the explorer shows.
+ */
+function explorerWalk() {
+    return {
+        // Any spelling of the git folder (`.GIT`, `.git.`) — the same rule the path
+        // guards apply, so a download or listing never carries what they refuse —
+        // and the empty-folder placeholder, which is never content.
+        skip: (e) => hasGitInternalsSegment(e.name) || (isFolderPlaceholder(e.name) && e.isFile()),
+        ignore: true,
+        unreadable: 'throw',
+    };
+}
 //# sourceMappingURL=workspace.service.js.map