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

package/dist/modules/workspace/workspace.routes.js

@@ -1,15 +1,45 @@
 import fs from 'node:fs/promises';
+import { logger } from '../../shared/logging.js';
+const log = logger('workspace.routes');
 import path from 'node:path';
-import { IGNORE_FILENAME } from './bevel-ignore.js';
+import { IGNORE_FILENAME, isAbsence } from '../../shared/fs.contract.js';
+import { printable } from '../../shared/printable.js';
 import express from 'express';
-import { DEFAULT_BRANCH, KNOWLEDGE_DIR, reservedRootDirNames } from '@bevel-software/platform-shared';
+import { DEFAULT_BRANCH, KNOWLEDGE_DIR, canonicalRelativePath, folderPlaceholderPath, isPlatformFile, isPlatformRestoreShape, platformFileCreationRefusal, platformFileRefusal, reservedRootDirNames, } from '@bevel-software/platform-shared';
 import { FolderTooLargeError } from './workspace.service.js';
 import { branchForWorkspaceId } from '../../shared/workspace-id.js';
+import { EntryExistsError } from './workspace.service.js';
 import { canReadWorkspacePath, resolveReadableMap, toKbRelative } from '../access-model/kb-read-filter.js';
 import { isRolesYamlPath, assertRolesYamlParsable } from '../access-model/roles-yaml-guard.js';
-import { WorkflowDomainError } from '../../shared/domain-errors.js';
+import { PathTraversalError, WorkflowDomainError } from '../../shared/domain-errors.js';
+import { domainErrorBody } from '../../shared/http-errors.js';
+import { assertWithinDirectory } from '../../shared/path-containment.js';
+import { normalizeWorkspacePath } from '../kb-fs/repo-path.js';
+import { hasGitInternalsSegment } from '../../shared/git-internals.js';
+import { createGitInternalsRouteGuard } from './git-internals.middleware.js';
+import { removeEmptyDirs } from './empty-dirs.js';
 import '../auth/auth.middleware.js'; // Express Request augmentation
 const MAX_UPLOAD_BYTES = 50 * 1024 * 1024; // 50 MB
+/**
+ * One file identity from one request field, or `null` when the caller sent
+ * nothing usable.
+ *
+ * TYPED, not cast: a repeated `?path=a&path=b` arrives as an array and a JSON
+ * body can hold anything, so `as string` would hand a non-string to the
+ * canonicaliser and throw a 500 on what is a client mistake.
+ *
+ * CANONICAL, because the mutating verbs on this surface coordinate on the
+ * path: `PUT` takes an in-process write turn on it, all of them take the
+ * workflow lock row keyed by it, and the bytes live at it. A save spelled
+ * `x/a.md` and a delete spelled `./x//a.md` would otherwise take two
+ * different lock rows for one file and interleave. See
+ * `canonicalRelativePath` for what it refuses to touch.
+ */
+function requestPath(value) {
+    if (typeof value !== 'string' || value.length === 0)
+        return null;
+    return canonicalRelativePath(value);
+}
 /**
  * Workspaces are per-branch (PLAN §3). Any authenticated user can access
  * any branch's workspace; coordination of concurrent edits lives in the
@@ -25,8 +55,61 @@ const MAX_UPLOAD_BYTES = 50 * 1024 * 1024; // 50 MB
  * exactly like the lock-aware filesystem the agent writes through. There
  * is no separate "share" step; save and share are fused.
  */
-export function createWorkspaceRoutes(workspaceService, authService, workflowService, eventBus, accessControl, kbDirName, creatorAccess, adminAccess) {
+export function createWorkspaceRoutes(workspaceService, authService, workflowService, eventBus, accessControl, kbDirName, creatorAccess, adminAccess, disk, 
+/** Save-time skill check: `PUT /file` on a SKILL.md answers with `warnings` (advisory, never a refusal). */
+skillSaveCheck, 
+/**
+ * Read-before-write, asked ahead of the lock where a route puts bytes on
+ * disk BEFORE it locks them (archive extraction). Every other route's writes
+ * meet the same gate inside `acquireLock`. Optional so route harnesses that
+ * exercise other behaviour need not wire it.
+ */
+changeGate) {
     const router = express.Router();
+    const gitInternalsRouteGuard = createGitInternalsRouteGuard(workspaceService);
+    // The git folder is refused ahead of every route here by
+    // `createGitInternalsRouteGuard`, which the app mounts once for the whole
+    // `/workspace/:id` prefix (see `git-internals.middleware.ts`). Mounted here
+    // too so this router carries the rule wherever it is mounted on its own.
+    router.use("/workspace/:id", gitInternalsRouteGuard);
+    /**
+     * The REPOSITORY path a request names, or `null` once the refusal has been
+     * sent.
+     *
+     * Every handler on this surface calls this FIRST, before the access check and
+     * before the service, so one path is what is checked and what is written.
+     * That was the hole: the access helpers stripped `<kbDirName>/` when it was
+     * there and otherwise took the path as written, so an unprefixed
+     * `KnowledgeBase/Reports` was judged as a repository path and then created
+     * beside the repository — a folder, eight documents and a `Plugins/` tree on
+     * core-staging, none of it ever committed. The normaliser closes it by making
+     * the unprefixed spelling MEAN the repository path it was judged as.
+     */
+    function inRepo(res, wsPath) {
+        try {
+            return normalizeWorkspacePath(wsPath, kbDirName);
+        }
+        catch (err) {
+            sendError(res, err);
+            return null;
+        }
+    }
+    /**
+     * A repository path's absolute location, checked against the repository root.
+     *
+     * The ONE place this router resolves a workspace path — the delete fast-path,
+     * the platform-restore look and the folder-keep all used to call
+     * `path.resolve(workspaceDir, …)` for themselves, against the WORKSPACE dir,
+     * which is the containment an unprefixed path satisfied on its way to being
+     * written beside the checkout. A drift-guard test fails if a second one
+     * appears.
+     */
+    async function absoluteInRepo(workspaceId, repoRelative) {
+        const workspaceDir = await workspaceService.getWorkspacePath(workspaceId);
+        const absolute = path.resolve(workspaceDir, repoRelative);
+        assertWithinDirectory(absolute, path.join(workspaceDir, kbDirName));
+        return absolute;
+    }
     function authenticated(req, res) {
         if (!req.userId) {
             res.status(401).json({ error: 'Unauthenticated' });
@@ -59,11 +142,47 @@ export function createWorkspaceRoutes(workspaceService, authService, workflowSer
             return user;
         }
         catch (err) {
-            console.error('[workspace.routes] requireUser failed:', err);
+            log.error('requireUser failed:', { err });
             res.status(500).json({ error: 'Internal server error' });
             return null;
         }
     }
+    /**
+     * Whether a failed op is one that provably touched no bytes, so its lock
+     * may be released with the disk and the commit queue left exactly as they
+     * are (`releaseLockUntouched`) rather than reset to HEAD.
+     *
+     * This is not tidiness. A release that discards resets the PATH, not "this
+     * request's changes" — git has no notion of the latter — so when the path
+     * holds a landed save whose commit is still queued (commits run out of band
+     * in the pending-commits worker), the discard destroys that save. Two moves
+     * racing onto the same free name are exactly that situation: the winner
+     * lands and enqueues, the loser then takes the same destination lock, is
+     * refused because the name is now taken, and its unwind would throw the
+     * winner's file away. One refusal, two lost files.
+     *
+     * A destination-taken refusal qualifies because nothing it can do writes:
+     * the preflight throws before the move is attempted, and the move's own
+     * no-clobber calls (`link`, `mkdir`, `open` with `O_EXCL` — see
+     * `shared/rename-no-replace.ts`) fail without creating anything, with the
+     * folder claim rolling itself back. `LockingFilesystem.withLock` draws the
+     * same line for its `CheckRefusal`, in the same words: a refusal that wrote
+     * nothing releases untouched.
+     *
+     * Deliberately a closed list of refusal TYPES rather than a guess at what
+     * an op did. An unrecognised failure keeps the discarding release, which is
+     * the fail-closed side: at worst it throws away bytes nobody promised to
+     * keep, where the other mistake throws away bytes someone was told were
+     * saved.
+     *
+     * One type, not two: the move's lower-level `DestinationTakenError` never
+     * reaches this layer — `moveEntry` converts it into `EntryExistsError`, the
+     * refusal this surface answers 409 with — so recognising it here as well
+     * would be a branch nothing can take.
+     */
+    function wroteNothing(err) {
+        return err instanceof EntryExistsError;
+    }
     /**
      * Acquire the workflow lock for `(workspaceId, branch, targetPath)`, run
      * `op`, then release. Release commits + pushes the file as a one-file
@@ -122,23 +241,31 @@ export function createWorkspaceRoutes(workspaceService, authService, workflowSer
             eventBus.emit({ kind: 'fs-tree-changed', workspaceId, branch });
             return result;
         }
-        const acquired = await workflowService.acquireLock(workspaceId, branch, targetPath, user);
+        const acquired = await workflowService.acquireLock(workspaceId, branch, targetPath, user, {
+            platformRestore: options?.platformRestore,
+        });
         if (!acquired.acquired) {
             const holder = acquired.lock.holderName || 'another user';
             const err = new Error(`"${targetPath}" is being edited by ${holder}. Try again in a moment.`);
             err.status = 409;
             throw err;
         }
-        // Two release modes, depending on whether the op succeeded:
+        // Three release modes, the same three `LockingFilesystem.withLock` uses,
+        // depending on what the op did:
+        //
+        //   - op() FAILED having possibly WRITTEN → drop the lock WITHOUT
+        //     enqueueing a commit. The op may have written partial bytes to disk
+        //     before throwing (write that errored mid-stream, etc.). A normal
+        //     `releaseLock` would enqueue a commit for whatever's on disk and the
+        //     worker would silently persist that partial state as a real
+        //     committed change. `releaseLockNoCommit` resets the path to HEAD, so
+        //     partial bytes never become a committed change with the user's name
+        //     on it.
         //
-        //   - op() FAILED  → drop the lock WITHOUT enqueueing a commit. The
-        //     op may have written partial bytes to disk before throwing
-        //     (write that errored mid-stream, etc.). A normal `releaseLock`
-        //     would enqueue a commit for whatever's on disk and the worker
-        //     would silently persist that partial state as a real committed
-        //     change. `releaseLockNoCommit` drops the lock row only —
-        //     partial disk state stays where it is but never becomes a
-        //     committed change with the user's name on it.
+        //   - op() FAILED having written NOTHING → `releaseLockUntouched`: drop
+        //     the lock row and leave both the disk and the commit queue exactly
+        //     as they are. See `wroteNothing` for which refusals qualify and why
+        //     the distinction is load-bearing rather than tidy.
         //
         //   - op() SUCCEEDED → release. The new releaseLock enqueues a
         //     pending-commit row (the actual `commitFile + push` runs out
@@ -153,11 +280,17 @@ export function createWorkspaceRoutes(workspaceService, authService, workflowSer
             opSucceeded = true;
         }
         catch (err) {
+            const untouched = wroteNothing(err);
             try {
-                await workflowService.releaseLockNoCommit(workspaceId, branch, targetPath, user);
+                if (untouched) {
+                    await workflowService.releaseLockUntouched(workspaceId, branch, targetPath, user);
+                }
+                else {
+                    await workflowService.releaseLockNoCommit(workspaceId, branch, targetPath, user);
+                }
             }
             catch (releaseErr) {
-                console.warn(`[workspace.routes] releaseLockNoCommit failed after op error for "${targetPath}":`, releaseErr instanceof Error ? releaseErr.message : releaseErr);
+                log.warn(`${untouched ? 'releaseLockUntouched' : 'releaseLockNoCommit'} failed after op error for "${targetPath}":`, { err: releaseErr });
             }
             throw err;
         }
@@ -182,19 +315,57 @@ export function createWorkspaceRoutes(workspaceService, authService, workflowSer
         }
         return result;
     }
+    /**
+     * Keep the folder a removal just emptied. A folder exists until it is
+     * deleted explicitly, so when deleting a file (or a subfolder), or moving
+     * one out, leaves its parent empty, the parent gets the placeholder in its
+     * own lock cycle — committed like any other save, within the same request.
+     * Only folders inside the repository qualify, never the clone folder
+     * itself.
+     *
+     * It runs in the folder's turn, which an explicit folder delete also takes,
+     * and looks again inside it: a folder that is gone by then was deleted
+     * explicitly and stays gone, and one that gained an entry needs nothing.
+     * The placeholder is only ever written into a folder that exists, and never
+     * through a link (see `writeFolderPlaceholder`).
+     *
+     * A failure is the request's failure: the removal landed, but a request
+     * that answers success would leave a folder that vanishes on the next
+     * clone, which is exactly what this rule forbids. It keeps its own status
+     * (a contended placeholder lock is still a 409) and only gains the context.
+     */
+    async function keepFolderOf(workspaceId, user, removedPath) {
+        const trimmed = removedPath.replace(/\/+$/, '');
+        const dir = trimmed.includes('/') ? trimmed.slice(0, trimmed.lastIndexOf('/')) : '';
+        if (!dir.startsWith(`${kbDirName}/`))
+            return;
+        try {
+            const absolute = await absoluteInRepo(workspaceId, dir);
+            await workspaceService.withFolderTurn(workspaceId, dir, async () => {
+                if (!(await isEmptyFolder(absolute)))
+                    return;
+                // One tree refresh per request: the removal already announced it.
+                await withLock(workspaceId, user, folderPlaceholderPath(dir), () => workspaceService.writeFolderPlaceholder(workspaceId, dir), { skipFsTreeEvent: true });
+            });
+        }
+        catch (err) {
+            const reason = err instanceof Error ? err.message : String(err);
+            log.error(`could not keep the folder ${printable(dir)} after removing ${printable(removedPath)}: ${printable(reason)}`);
+            throw withKeptFolderContext(err, `"${removedPath}" was removed, but its folder "${dir}" could not be kept: ${reason}`);
+        }
+    }
     /**
      * Map any thrown error to an HTTP response. Centralises the response
      * shape so each route handler stays focused on its own logic.
-     *   - `WorkflowDomainError` → its `.status` + `.payload`
-     *   - Path traversal → 403
-     *   - Invalid path / zip → 400 (Only .zip is also 400)
-     *   - Could not read zip → 422
+     *   - `WorkflowDomainError` → its `.status` + `.payload` (a traversal is a
+     *     403, an invalid path a 400, an unreadable archive a 422 — each by
+     *     its TYPE; this surface used to recognise all three by their message)
      *   - Anything else with a `.status` → that status
      *   - Default → 500
      */
     function sendError(res, err) {
         if (err instanceof WorkflowDomainError) {
-            res.status(err.status).json({ error: err.message, ...(err.payload ?? {}) });
+            res.status(err.status).json(domainErrorBody(err));
             return;
         }
         const msg = err instanceof Error ? err.message : 'Unknown error';
@@ -203,18 +374,6 @@ export function createWorkspaceRoutes(workspaceService, authService, workflowSer
             res.status(status).json({ error: msg });
             return;
         }
-        if (msg === 'Path traversal detected') {
-            res.status(403).json({ error: msg });
-            return;
-        }
-        if (msg.startsWith('Invalid path') || msg.startsWith('Only .zip')) {
-            res.status(400).json({ error: msg });
-            return;
-        }
-        if (msg.startsWith('Could not read zip file')) {
-            res.status(422).json({ error: msg });
-            return;
-        }
         res.status(500).json({ error: msg });
     }
     // GET /api/workspace[?branch=<branch>]
@@ -254,7 +413,7 @@ export function createWorkspaceRoutes(workspaceService, authService, workflowSer
             // Log the full stack so the next 500 isn't a guessing game — the
             // bare `error.message` we returned before lost most diagnostic
             // signal (cause chain, stack frames, error class).
-            console.error(`[workspace.routes] GET /workspace failed branch=${req.query.branch ?? '(default)'}:`, error instanceof Error ? error.stack ?? error.message : error);
+            log.error(`GET /workspace failed branch=${req.query.branch ?? '(default)'}:`, { err: error });
             const msg = error instanceof Error ? error.message : 'Unknown error';
             res.status(500).json({ error: msg });
         }
@@ -347,12 +506,11 @@ export function createWorkspaceRoutes(workspaceService, authService, workflowSer
         let allowed;
         try {
             // `download` is a per-path verb in access.md, resolved via the same
-            // chain walk as `write`. Strip the kbDirName prefix so the resolver
-            // receives a repo-relative path (mirrors the lock-acquire gate's
-            // strip in workflow.service.ts's assertCanWriteAtPath).
-            const repoRelative = relativePath.startsWith(`${kbDirName}/`)
-                ? relativePath.slice(kbDirName.length + 1)
-                : relativePath;
+            // chain walk as `write`. The caller has already normalised the path into
+            // the repository, so this only takes the prefix off — where it used to
+            // pass an unprefixed path through untouched and judge a stray as if it
+            // were inside.
+            const repoRelative = toKbRelative(relativePath, kbDirName) ?? relativePath;
             allowed = await accessControl.canDownload(workspaceId, user.email, repoRelative);
         }
         catch (err) {
@@ -427,7 +585,7 @@ export function createWorkspaceRoutes(workspaceService, authService, workflowSer
             // `.bevelignore` is ADMIN-ONLY. It is the file that decides what the file
             // tree and the agent view show at all, so it is deployment configuration
             // rather than knowledge — and it sits alone in being visible: its
-            // siblings (`.gitignore`, `roles.yaml`, `access.md`, `AGENTS.md`) are
+            // siblings (`.gitignore`, `roles.yaml`, `access.md`, the agent guide) are
             // already hidden from every reader by the shipped ignore rules. Somebody
             // who cannot act on it gains a puzzle; somebody who can needs to reach it.
             //
@@ -440,10 +598,14 @@ export function createWorkspaceRoutes(workspaceService, authService, workflowSer
             // on the default branch precisely so that editing `roles.yaml` on your
             // own branch cannot promote you, and the same reasoning applies to
             // anything gated on being an admin.
+            //
+            // `'unlisted'`, not `false`: hiding it withholds no content, so a
+            // non-admin in an empty knowledge base (every one ships this file) is
+            // told it is empty, not that something is being kept from them.
             const ignoreFiles = wsRelPaths.filter((wp) => path.basename(wp) === IGNORE_FILENAME);
             if (ignoreFiles.length > 0 && !(await adminAccess.isAdmin(userEmail))) {
                 for (const wp of ignoreFiles)
-                    verdict.set(wp, false);
+                    verdict.set(wp, 'unlisted');
             }
             return verdict;
         };
@@ -457,39 +619,68 @@ export function createWorkspaceRoutes(workspaceService, authService, workflowSer
      * grant on the same new directory survives. Runs BEFORE the creation itself
      * so the explorer never shows-then-hides the new subtree; if the creation
      * subsequently fails, the leftover is an empty new folder readable only by
-     * its creator. Best-effort by contract: a failure here logs and never
-     * blocks the creation.
+     * its creator.
+     *
+     * A failure here FAILS the creation, and propagates as it is. The seed is
+     * planned only for a new folder at a root the creator cannot read — the one
+     * creation the read gate lets past an unreadable spot — so without the
+     * grant the folder would come into existence invisible to the person who
+     * made it, which is exactly what the gate exists to prevent. The seed's
+     * own lock passes that gate too: if the folder appeared under someone else
+     * between the plan and this write, the refusal is theirs to see, and
+     * nothing lands.
      */
     async function seedCreatorAccessMd(workspaceId, user, plan) {
-        try {
-            await withLock(workspaceId, user, plan.wsRelPath, async () => {
-                let current = '';
-                try {
-                    current = await workspaceService.readFile(workspaceId, plan.wsRelPath);
-                }
-                catch {
-                    // Not there yet — the normal case for a brand-new directory.
-                }
-                const next = plan.apply(current);
-                if (next !== current) {
-                    await workspaceService.writeFile(workspaceId, plan.wsRelPath, next);
-                }
-            });
-            creatorAccess.noteAccessFileWritten(workspaceId);
-        }
-        catch (err) {
-            console.warn(`[workspace.routes] creator access.md seed failed for "${plan.wsRelPath}":`, err instanceof Error ? err.message : err);
-        }
+        await withLock(workspaceId, user, plan.wsRelPath, async () => {
+            let current = '';
+            try {
+                current = await workspaceService.readFile(workspaceId, plan.wsRelPath);
+            }
+            catch {
+                // Not there yet — the normal case for a brand-new directory.
+            }
+            const next = plan.apply(current);
+            if (next !== current) {
+                await workspaceService.writeFile(workspaceId, plan.wsRelPath, next);
+            }
+        });
+        creatorAccess.noteAccessFileWritten(workspaceId);
     }
+    /**
+     * GET /workspace/:id/file/raw?path=<file>[&download=1][&v=<n>]
+     *
+     * The bytes of one workspace file: for the document renderers' fetches, the
+     * file tree's Download, and the `<img>` tags the markdown pipeline emits for
+     * `![alt](./assets/x.png)`. An `<img>` sends no Authorization header, so it
+     * is the auth middleware's `bevel_token` cookie fallback that lets a plain
+     * image tag through.
+     *
+     *   request ──▶ auth: Bearer, else the cookie
+     *           ──▶ read gate on the path             403 if the caller may not read it
+     *           ──▶ download gate, if ?download=1     403 without the download: verb
+     *           ──▶ readFileBinary                    404 missing, 403 traversal
+     *           ──▶ Content-Type from the extension, nosniff, a CSP sandbox for
+     *               inline svg, attachment disposition for a download, and
+     *               Cache-Control: private, no-cache
+     *           ──▶ res.send(buffer): Express sets a weak ETag and answers 304 to
+     *               a matching If-None-Match, so a revisited page costs a read
+     *               and a hash per image rather than the bytes on the wire
+     *
+     * `?v=` is not read here. The frontend bumps it when it learns an image
+     * changed, so the browser asks for a URL it has not cached.
+     */
     router.get('/workspace/:id/file/raw', async (req, res) => {
         const id = authenticated(req, res);
         if (id === null)
             return;
-        const filePath = req.query.path;
-        if (!filePath) {
+        const requested = req.query.path;
+        if (typeof requested !== 'string' || requested.length === 0) {
             res.status(400).json({ error: 'path query parameter is required' });
             return;
         }
+        const filePath = inRepo(res, requested);
+        if (filePath === null)
+            return;
         // `?download=1` flips this from inline-serve (used by PdfRenderer and
         // the image renderers) to "save to disk" — and the save path is gated
         // on per-path `download:` rules in access.md. The inline path stays
@@ -546,12 +737,19 @@ export function createWorkspaceRoutes(workspaceService, authService, workflowSer
                 const basename = (filePath.split('/').pop() || 'file').replace(/[\r\n]/g, '');
                 res.setHeader('Content-Disposition', `attachment; filename*=UTF-8''${encodeURIComponent(basename)}`);
             }
+            // `private`: this is one person's authenticated file, and a shared cache
+            // (a CDN, a corporate proxy) must not hand it to the next person.
+            // `no-cache`: the browser may keep it but asks before reusing it, which
+            // the ETag answers with a 304; a picture replaced under the same name is
+            // therefore never older than one revalidation.
+            res.setHeader('Cache-Control', 'private, no-cache');
             res.send(buffer);
         }
         catch (error) {
-            const msg = error instanceof Error ? error.message : 'Unknown error';
-            if (msg === 'Path traversal detected') {
-                res.status(403).json({ error: msg });
+            // A traversal is the caller's 403; every other read failure here is the
+            // route's honest 404 (the image either is not there or cannot be shown).
+            if (error instanceof PathTraversalError) {
+                sendError(res, error);
                 return;
             }
             res.status(404).json({ error: 'File not found' });
@@ -586,11 +784,14 @@ export function createWorkspaceRoutes(workspaceService, authService, workflowSer
         // Trim whitespace and strip trailing slashes — `foo/` would otherwise
         // basename to `''` and produce a misleading `.zip` filename. Done
         // before the empty check so `' / '` is also caught.
-        const folderPath = rawPath.trim().replace(/\/+$/, '');
-        if (!folderPath) {
+        const trimmedPath = rawPath.trim().replace(/\/+$/, '');
+        if (!trimmedPath) {
             res.status(400).json({ error: 'path query parameter is required' });
             return;
         }
+        const folderPath = inRepo(res, trimmedPath);
+        if (folderPath === null)
+            return;
         if (req.query.download !== '1') {
             res.status(400).json({ error: 'download=1 is required for folder zip downloads' });
             return;
@@ -615,11 +816,11 @@ export function createWorkspaceRoutes(workspaceService, authService, workflowSer
                 res.status(413).json({ error: error.message });
                 return;
             }
-            const msg = error instanceof Error ? error.message : 'Unknown error';
-            if (msg === 'Path traversal detected') {
-                res.status(403).json({ error: msg });
+            if (error instanceof PathTraversalError) {
+                sendError(res, error);
                 return;
             }
+            const msg = error instanceof Error ? error.message : 'Unknown error';
             if (msg === 'Not a directory') {
                 res.status(400).json({ error: msg });
                 return;
@@ -632,11 +833,14 @@ export function createWorkspaceRoutes(workspaceService, authService, workflowSer
         const id = authenticated(req, res);
         if (id === null)
             return;
-        const filePath = req.query.path;
-        if (!filePath) {
+        const requested = requestPath(req.query.path);
+        if (requested === null) {
             res.status(400).json({ error: 'path query parameter is required' });
             return;
         }
+        const filePath = inRepo(res, requested);
+        if (filePath === null)
+            return;
         if (!(await requireReadPermission(req, res, id, filePath)))
             return;
         try {
@@ -648,23 +852,47 @@ export function createWorkspaceRoutes(workspaceService, authService, workflowSer
             res.json({ content });
         }
         catch (error) {
-            const msg = error instanceof Error ? error.message : 'Unknown error';
-            if (msg === 'Path traversal detected') {
-                res.status(403).json({ error: msg });
+            // 404 means ONE thing here: there is no file at this path. That is
+            // ENOENT, a parent that is not a directory (ENOTDIR), and a directory
+            // asked for as a file (EISDIR). Every other read failure keeps its own
+            // status, because callers act on the difference: the inline
+            // agent-description editor opens EMPTY on a 404 (a knowledge base older
+            // than the template has no such file yet), so dressing an unreadable
+            // file up as a missing one would offer an empty editor over content the
+            // save then overwrites.
+            if (isAbsence(error) || error.code === 'EISDIR') {
+                res.status(404).json({ error: 'File not found' });
                 return;
             }
-            res.status(404).json({ error: 'File not found' });
+            // Traversal stays a 403 and a malformed workspace id its domain status:
+            // both carry messages written to be read by the caller. (A traversal IS
+            // a domain error now, so the one check covers both.)
+            if (error instanceof WorkflowDomainError) {
+                sendError(res, error);
+                return;
+            }
+            // Anything else is a real failure, and it says so WITHOUT quoting
+            // itself: an errno message carries absolute workspace paths and a
+            // bootstrap failure carries git's stderr, neither of which belongs in a
+            // response body. The distinction this route exists to make is still
+            // made — an unreadable file is not a missing one — it is just not
+            // narrated to the client.
+            log.warn(`GET /file failed for "${filePath}" in "${id}":`, { err: error });
+            res.status(500).json({ error: "Couldn't read the file." });
         }
     });
     router.delete('/workspace/:id/file', async (req, res) => {
         const id = authenticated(req, res);
         if (id === null)
             return;
-        const filePath = req.query.path;
-        if (!filePath) {
+        const requested = requestPath(req.query.path);
+        if (requested === null) {
             res.status(400).json({ error: 'path query parameter is required' });
             return;
         }
+        const filePath = inRepo(res, requested);
+        if (filePath === null)
+            return;
         const user = await requireUser(req, res);
         if (!user)
             return;
@@ -679,19 +907,12 @@ export function createWorkspaceRoutes(workspaceService, authService, workflowSer
             // emits are also coalesced into a single end-of-batch event so the
             // explorer doesn't refresh N times.
             const workspaceDir = await workspaceService.getWorkspacePath(id);
-            const absolute = path.resolve(workspaceDir, filePath);
-            // Boundary check before any `fs.*` call. The single-file path
-            // bottoms out in `workspaceService.deleteFile` (which asserts the
-            // boundary itself), but this fast-path resolves the absolute
-            // ourselves and then `fs.stat` / `fs.rm` / `enumerateFilesUnder`
-            // it. Without this guard, a `../escape` `filePath` would let the
-            // dir-delete branch operate on directories outside the workspace.
-            const workspaceRoot = path.resolve(workspaceDir);
-            if (absolute !== workspaceRoot && !absolute.startsWith(workspaceRoot + path.sep)) {
-                const err = new Error('Path traversal detected');
-                err.status = 403;
-                throw err;
-            }
+            // Boundary check before any `fs.*` call — against the REPOSITORY root,
+            // which is where `absoluteInRepo` holds it. The single-file path bottoms
+            // out in `workspaceService.deleteFile` (which resolves inside the
+            // repository itself), but this fast-path needs the absolute for
+            // `fs.stat` / `fs.rm` / `enumerateFilesUnder`.
+            const absolute = await absoluteInRepo(id, filePath);
             let stat = null;
             try {
                 stat = await fs.stat(absolute);
@@ -700,48 +921,73 @@ export function createWorkspaceRoutes(workspaceService, authService, workflowSer
                 // Not on disk — let workspaceService.deleteFile return its own 404.
             }
             if (stat?.isDirectory()) {
-                const filesInDir = await enumerateFilesUnder(absolute, workspaceDir);
                 const branch = branchForWorkspaceId(id);
-                for (const relFile of filesInDir) {
-                    await withLock(id, user, relFile, async () => {
-                        await workspaceService.deleteFile(id, relFile);
-                    }, { skipFsTreeEvent: true });
-                }
-                // No explicit push here — each per-file release enqueues a
-                // pending-commits row, and the background worker drains them
-                // (commit + push) on its own schedule. The N round-trips that
-                // the old skipPush+pushBranch pattern collapsed into one happen
-                // serially in the worker; user perception is unchanged because
-                // the disk-side delete is what other sessions see via
-                // `fs-tree-changed`.
-                // Sweep the now-empty directory subtree off disk. Git doesn't track
-                // empty folders, so there's nothing to commit; this is just disk
-                // hygiene so the file tree stops showing the empty containers.
-                //
-                // This MUST recurse: a folder that held *subfolders* still has those
-                // (now-empty) subdirectory shells on disk after the per-file deletes,
-                // so a single non-recursive `rmdir(absolute)` would see a non-empty
-                // dir and bail — leaving the folder visible in the tree and looking
-                // undeletable (BEVA-132). `removeEmptyDirs` walks bottom-up and only
-                // removes dirs that are *actually empty* at the moment it visits them,
-                // so a concurrent writer's new file (and its parent chain) is
-                // preserved — the same safety property the old non-recursive check had.
+                // In the folder's turn: keeping a folder under this one (a file delete
+                // racing this one) waits until the sweep is done, and then finds the
+                // folder gone instead of writing it back.
+                let filesInDir;
                 try {
-                    await removeEmptyDirs(absolute);
+                    filesInDir = await workspaceService.withFolderTurn(id, filePath, async () => {
+                        const files = await enumerateFilesUnder(disk, absolute, workspaceDir);
+                        for (const relFile of files) {
+                            await withLock(id, user, relFile, async () => {
+                                await workspaceService.deleteFile(id, relFile);
+                            }, { skipFsTreeEvent: true });
+                        }
+                        // No explicit push here — each per-file release enqueues a
+                        // pending-commits row, and the background worker drains them
+                        // (commit + push) on its own schedule. The N round-trips that
+                        // the old skipPush+pushBranch pattern collapsed into one happen
+                        // serially in the worker; user perception is unchanged because
+                        // the disk-side delete is what other sessions see via
+                        // `fs-tree-changed`.
+                        // This is the EXPLICIT folder delete — the one operation that removes
+                        // a folder — so the walk above deleted the placeholders too, and the
+                        // now-empty directory subtree is swept off disk. Git doesn't track
+                        // empty folders, so there's nothing more to commit; this is disk
+                        // hygiene so the file tree stops showing the deleted containers.
+                        //
+                        // This MUST recurse: a folder that held *subfolders* still has those
+                        // (now-empty) subdirectory shells on disk after the per-file deletes,
+                        // so a single non-recursive `rmdir(absolute)` would see a non-empty
+                        // dir and bail — leaving the folder visible in the tree and looking
+                        // undeletable (BEVA-132). `removeEmptyDirs` walks bottom-up and only
+                        // removes dirs that are *actually empty* at the moment it visits them,
+                        // so a concurrent writer's new file (and its parent chain) is
+                        // preserved — the same safety property the old non-recursive check had.
+                        // A folder that vanished or filled up under a concurrent writer
+                        // is passed over inside the sweep; what reaches here is a real
+                        // failure (permissions, I/O) that left the folder on disk, and
+                        // the request fails — as the agent's delete does — rather than
+                        // the response reporting gone a folder the tree still shows. The
+                        // per-file deletes have landed either way, and the next delete
+                        // of the now-empty folder either sweeps it or says why not. The
+                        // cause is logged; the answer carries no path of the host's.
+                        try {
+                            await removeEmptyDirs(absolute);
+                        }
+                        catch (rmErr) {
+                            log.warn(`dir cleanup failed for ${printable(filePath)}`, { err: rmErr });
+                            throw new Error('The files were deleted, but the empty folder could not be removed. Delete it again.');
+                        }
+                        return files;
+                    });
+                    // The folder that HELD the deleted one was not asked to go.
+                    await keepFolderOf(id, user, filePath);
                 }
-                catch (rmErr) {
-                    // Directory already gone (raced delete), or a concurrent writer
-                    // repopulated it. Either way, skip removal — the per-file deletes
-                    // are what's load-bearing.
-                    console.warn(`[workspace.routes] dir cleanup skipped for "${filePath}":`, rmErr instanceof Error ? rmErr.message : rmErr);
+                finally {
+                    // Single tree-refresh signal for the whole batch (we suppressed
+                    // the per-file ones via `skipFsTreeEvent`) — sent on failure too:
+                    // a batch that stops part way, or a parent that could not be kept,
+                    // has still changed the tree.
+                    eventBus.emit({ kind: 'fs-tree-changed', workspaceId: id, branch });
                 }
-                // Single tree-refresh signal for the whole batch (we suppressed
-                // the per-file ones via `skipFsTreeEvent`).
-                eventBus.emit({ kind: 'fs-tree-changed', workspaceId: id, branch });
                 res.json({ status: 'deleted', count: filesInDir.length });
                 return;
             }
             await withLock(id, user, filePath, () => workspaceService.deleteFile(id, filePath));
+            // Deleting content is not deleting structure: an emptied folder stays.
+            await keepFolderOf(id, user, filePath);
             res.json({ status: 'deleted' });
         }
         catch (err) {
@@ -752,15 +998,72 @@ export function createWorkspaceRoutes(workspaceService, authService, workflowSer
         const id = authenticated(req, res);
         if (id === null)
             return;
-        const { oldPath, newPath } = req.body;
-        if (!oldPath || !newPath) {
+        const body = (req.body ?? {});
+        const requestedOld = requestPath(body.oldPath);
+        const requestedNew = requestPath(body.newPath);
+        if (requestedOld === null || requestedNew === null) {
             res.status(400).json({ error: 'oldPath and newPath are required in body' });
             return;
         }
+        // Both ends inside the repository before anything is judged: the platform-file
+        // rules, the locks and the rename all read the same two paths.
+        const oldPath = inRepo(res, requestedOld);
+        if (oldPath === null)
+            return;
+        const newPath = inRepo(res, requestedNew);
+        if (newPath === null)
+            return;
+        // Two spellings of one file are now ONE path, so a move can arrive with
+        // both ends equal. `withLock` below would survive it — the inner
+        // acquisition sees the lock the outer just took, held by this same user,
+        // and runs straight through — but the move itself is a rename onto
+        // itself that commits a change and tells the diff service the path was
+        // both deleted and rewritten. It is a client mistake, so it is a 400.
+        if (oldPath === newPath) {
+            res.status(400).json({ error: 'oldPath and newPath must differ' });
+            return;
+        }
         const user = await requireUser(req, res);
         if (!user)
             return;
         try {
+            // A platform file stays in the folder the platform reads it from —
+            // rename, move and drag all arrive here, and all three are refused.
+            // Moving one out is not a choice to confirm: once the root has no
+            // `access.md`, write on the root denies everyone and the move that
+            // would undo it is the move the gate refuses.
+            //
+            // The single exception is that repair: an admin putting a misplaced
+            // copy BACK. `isPlatformRestoreShape` says whether the MOVE is that
+            // repair — it is judged on the source's name and the destination, not
+            // on the source being a platform file where it currently sits, because
+            // a stray `roles.yaml` in a folder is ordinary content there and is
+            // still the copy the root is missing. `canRestorePlatformFile` then
+            // decides who may make it, and whether the disk agrees.
+            const oldRel = toKbRelative(oldPath, kbDirName);
+            const newRel = toKbRelative(newPath, kbDirName);
+            let platformRestore = false;
+            if (oldRel !== null && newRel !== null && isPlatformRestoreShape(oldRel, newRel)) {
+                platformRestore = await accessControl.canRestorePlatformFile(id, user.email, newRel);
+            }
+            // A platform file stays where the platform reads it …
+            if (oldRel !== null && isPlatformFile(oldRel) && !platformRestore) {
+                res.status(409).json({ error: platformFileRefusal(oldRel) });
+                return;
+            }
+            // … and nothing else becomes one. `moveEntry` is a plain rename, so
+            // without this a note renamed to `access.md` would come back as the
+            // folder's rules, and a note dragged ONTO the root's `access.md` would
+            // replace the rules that are there — neither of which the rule above,
+            // which reads only the SOURCE, says anything about. The agent's move
+            // tool has refused both since it shipped; this is the same sentence,
+            // from the same place. Only the restore lands on a platform path, and
+            // only where the file is missing (`canRestorePlatformFile` checked the
+            // disk; the destination lock below checks it again, under the lock).
+            if (newRel !== null && isPlatformFile(newRel) && !platformRestore) {
+                res.status(409).json({ error: platformFileCreationRefusal(newRel) });
+                return;
+            }
             // Move = rename on disk + commit on both sides. We lock-and-release
             // the destination first (commits the new file's appearance), then
             // lock-and-release the source path (commits its deletion). Two
@@ -781,7 +1084,38 @@ export function createWorkspaceRoutes(workspaceService, authService, workflowSer
             // not a single merge-style rename commit, but git's log/blame
             // rename detection still groups them visually after the fact.
             const [firstLock, secondLock] = oldPath < newPath ? [oldPath, newPath] : [newPath, oldPath];
-            await withLock(id, user, firstLock, () => withLock(id, user, secondLock, () => workspaceService.moveEntry(id, oldPath, newPath)));
+            // Only the DESTINATION side carries the restore claim. The source is an
+            // ordinary write the caller must already hold: the exception exists so a
+            // file can land where the platform reads it, not so an admin can take
+            // one out of a folder that denies them.
+            const restoreAt = (p) => ({
+                platformRestore: platformRestore && p === newPath ? { source: oldPath } : undefined,
+            });
+            // The restore was authorised against a destination that was missing when
+            // the access module looked. Both locks are in hand by the time this runs,
+            // so nothing else can take that path from under the rename — but between
+            // the two a writer still could, and a restore that lands on a platform
+            // file replaces the rules it came to bring back. So the last thing the
+            // move does before renaming is look again, inside the window it holds.
+            const move = async () => {
+                if (platformRestore) {
+                    const absoluteNew = await absoluteInRepo(id, newPath);
+                    const taken = await fs.stat(absoluteNew).then(() => true, 
+                    // Genuine absence is the only "free": anything else is not an
+                    // answer, and an unanswered question does not clear the way onto
+                    // a platform file.
+                    (err) => !isAbsence(err));
+                    if (taken) {
+                        const err = new Error(platformFileRefusal(newPath));
+                        err.status = 409;
+                        throw err;
+                    }
+                }
+                return workspaceService.moveEntry(id, oldPath, newPath);
+            };
+            await withLock(id, user, firstLock, () => withLock(id, user, secondLock, move, restoreAt(secondLock)), restoreAt(firstLock));
+            // Moving the last entry out leaves its folder in place, like a delete.
+            await keepFolderOf(id, user, oldPath);
             res.json({ status: 'moved' });
         }
         catch (err) {
@@ -792,41 +1126,89 @@ export function createWorkspaceRoutes(workspaceService, authService, workflowSer
         const id = authenticated(req, res);
         if (id === null)
             return;
-        const filePath = req.query.path;
-        if (!filePath) {
+        // ONE spelling of the target from here down. `x/a.md`, `./x/a.md` and
+        // `x//a.md` are the same file and all pass the path validator, and this
+        // route coordinates on that path three times over: the in-process write
+        // turn, the workflow lock row, and the bytes themselves. Two clients
+        // spelling one file differently would otherwise take two different locks
+        // and both pass their own precondition.
+        const requested = requestPath(req.query.path);
+        if (requested === null) {
             res.status(400).json({ error: 'path query parameter is required' });
             return;
         }
-        const { content, ifAbsent } = req.body;
+        const filePath = inRepo(res, requested);
+        if (filePath === null)
+            return;
+        const { content, ifAbsent, ifMatch } = req.body;
         if (content === undefined) {
             res.status(400).json({ error: 'content is required in body' });
             return;
         }
+        if (ifMatch !== undefined && typeof ifMatch !== 'string') {
+            res.status(400).json({ error: 'ifMatch, if provided, must be a string' });
+            return;
+        }
         const user = await requireUser(req, res);
         if (!user)
             return;
+        // A precondition ANSWERS A QUESTION ABOUT CONTENT, so it is gated on
+        // READING, not writing. Write authorisation happens at `acquireLock`
+        // inside `withLock` below, which is after the compare: without this gate
+        // the 409-versus-403 difference is a content-equality oracle on a file the
+        // caller may not read, and the confirming case is a write. Same gate and
+        // same 403 as `GET /file`; a caller who may write but not read can still
+        // save, just not ask questions about what is there.
+        if (ifMatch !== undefined && !(await requireReadPermission(req, res, id, filePath)))
+            return;
         try {
             // Refuse a hand-edit that would leave roles.yaml unparseable BEFORE any
             // byte hits disk — a broken roles.yaml is an app-wide admin lockout
-            // (loadModel hard-throws). The dedicated Roles & Members surface has its
+            // (loadModel hard-throws). The dedicated App roles surface has its
             // own validate gate; this covers the raw-text editor path.
             if (isRolesYamlPath(filePath, kbDirName))
                 assertRolesYamlParsable(content);
-            // Creator read grant: a brand-new file at a spot whose access chain
-            // doesn't grant the creator `read` would vanish from their own explorer
-            // (read is default-deny). Plan BEFORE the write: a new subtree gets its
-            // access.md seeded first; a loose .md carries the grant in its own
-            // frontmatter as part of this same single write.
-            const plan = await creatorAccess.planForCreate(id, user, filePath, 'file');
-            if (plan?.kind === 'seed-access-md')
-                await seedCreatorAccessMd(id, user, plan);
-            const toWrite = plan?.kind === 'frontmatter' ? plan.apply(content) : content;
-            // `ifAbsent` = exclusive create: the service's `wx` write turns a
-            // concurrent or stale create against an existing file into a 409
-            // instead of a silent replace. `withLock`'s failure arm releases
-            // without committing, so the refusal leaves no trace.
-            await withLock(id, user, filePath, () => workspaceService.writeFile(id, filePath, toWrite, { failIfExists: ifAbsent === true }));
-            res.json({ status: 'written' });
+            // One turn for the whole sequence, because the DECISION spans three
+            // steps that must agree about the same file: check the precondition,
+            // plan a creator-access grant that COMMITS, then write. A save landing
+            // in between would leave that grant behind for a write about to be
+            // refused, so the check is made here, before the plan, and nothing else
+            // in this process may touch the path until the write is done. The write
+            // inside takes the same turn re-entrantly.
+            //
+            // Across instances the workflow lock below is still the coordinator;
+            // this only orders what this server is doing.
+            await workspaceService.withPathTurn(id, filePath, async () => {
+                // A stale `ifMatch` is refused before anything commits.
+                if (ifMatch !== undefined)
+                    await workspaceService.assertContentMatches(id, filePath, ifMatch);
+                // Creator read grant: a file that starts a new folder at a root the
+                // creator cannot read would vanish from their own explorer (read is
+                // default-deny). Plan BEFORE the write: the new folder gets its
+                // access.md seeded first. Anywhere else the lock's read gate has
+                // already decided — a creation the creator could not see is refused,
+                // and one they can see needs no grant.
+                const plan = await creatorAccess.planForCreate(id, user, filePath, 'file');
+                if (plan?.kind === 'seed-access-md')
+                    await seedCreatorAccessMd(id, user, plan);
+                const toWrite = content;
+                // `ifAbsent` = exclusive create: the service's `wx` write turns a
+                // concurrent or stale create against an existing file into a 409
+                // instead of a silent replace. `withLock`'s failure arm releases
+                // without committing, so the refusal leaves no trace.
+                //
+                // `ifMatch` = conditional write, the same 409 for a stale UPDATE: the
+                // file must still hold the text the caller last read, re-checked at
+                // the write itself as the decision that counts.
+                await withLock(id, user, filePath, () => workspaceService.writeFile(id, filePath, toWrite, {
+                    failIfExists: ifAbsent === true,
+                    expectedContent: ifMatch,
+                }));
+            });
+            // After the write, and only ever advisory: the check reports what the
+            // saved skill names, it has no say in whether it saved.
+            const warnings = skillSaveCheck ? await skillSaveCheck.checkSave(user.email, filePath, content) : [];
+            res.json({ status: 'written', ...(warnings.length > 0 ? { warnings } : {}) });
         }
         catch (err) {
             sendError(res, err);
@@ -836,11 +1218,18 @@ export function createWorkspaceRoutes(workspaceService, authService, workflowSer
         const id = authenticated(req, res);
         if (id === null)
             return;
-        const { path: dirPath, defer } = req.body;
-        if (!dirPath) {
+        const { path: requested, defer } = req.body;
+        const canonical = requestPath(requested);
+        if (canonical === null) {
             res.status(400).json({ error: 'path is required in body' });
             return;
         }
+        // The folder this call creates, as a repository path. `KnowledgeBase/Reports`
+        // is `<kbDirName>/KnowledgeBase/Reports` — the access plan below, the
+        // `.gitkeep` lock and the mkdir all use this one spelling.
+        const dirPath = inRepo(res, canonical);
+        if (dirPath === null)
+            return;
         const user = await requireUser(req, res);
         if (!user)
             return;
@@ -880,20 +1269,49 @@ export function createWorkspaceRoutes(workspaceService, authService, workflowSer
         if (id === null)
             return;
         const body = (req.body ?? {});
-        const zipPath = body.path;
-        const destination = body.destination;
-        if (typeof zipPath !== 'string' || zipPath.length === 0) {
+        const requestedZip = body.path;
+        const requestedDest = body.destination;
+        if (typeof requestedZip !== 'string' || requestedZip.length === 0) {
             res.status(400).json({ error: 'path is required in body and must be a string' });
             return;
         }
-        if (destination !== undefined && (typeof destination !== 'string' || destination.length === 0)) {
+        if (requestedDest !== undefined && (typeof requestedDest !== 'string' || requestedDest.length === 0)) {
             res.status(400).json({ error: 'destination, if provided, must be a non-empty string' });
             return;
         }
+        const zipPath = inRepo(res, requestedZip);
+        if (zipPath === null)
+            return;
+        let destination;
+        if (requestedDest !== undefined) {
+            const normalizedDest = inRepo(res, requestedDest);
+            if (normalizedDest === null)
+                return;
+            destination = normalizedDest;
+        }
         const user = await requireUser(req, res);
         if (!user)
             return;
         try {
+            // The destination is asked about BEFORE anything is extracted: this is
+            // the one route whose bytes land on disk ahead of the lock, so the
+            // lock's read gate would find them already there. Same verdict, same
+            // refusal, one step earlier. A destination inside a folder the caller
+            // cannot read is refused whole; a folder they can read — or a new
+            // folder directly under a root — extracts, and each file then meets
+            // the lock as any other write does.
+            //
+            // A new root folder gets its creator's access.md seeded first, as
+            // every other creation route does: extraction would otherwise bring
+            // the folder into existence itself, and the first file's lock would
+            // then find an existing folder the caller cannot read.
+            // Both spellings are already repository paths, so the inferred parent is
+            // one too — the same destination the service resolves.
+            const destDir = destination ?? path.posix.dirname(zipPath);
+            const plan = await creatorAccess.planForCreate(id, user, destDir, 'dir');
+            if (plan?.kind === 'seed-access-md')
+                await seedCreatorAccessMd(id, user, plan);
+            await changeGate?.assertMayChange(id, user.email, destDir, 'dir');
             // Extract first (all files land on disk), then sweep each extracted
             // file through a lock+release so it commits + pushes as its own
             // one-file change. Per-file commits mean the validator runs N times
@@ -901,26 +1319,18 @@ export function createWorkspaceRoutes(workspaceService, authService, workflowSer
             // but correct for a 100-file zip. If a single file's release fails
             // (e.g. validator 422), the loop stops there so the user sees the
             // first concrete problem rather than a list of N similar failures.
-            const result = await workspaceService.unzipFile(id, zipPath, destination);
+            //
+            // Each entry is asked about before it is written, through the same
+            // gate: an archive can carry a path into a nested folder the caller
+            // cannot read, which the destination check above cannot see. Such an
+            // entry is skipped and reported, never written and then refused.
+            const result = await workspaceService.unzipFile(id, zipPath, destination, async (entryPath) => {
+                await changeGate?.assertMayChange(id, user.email, entryPath, 'file');
+            });
             for (const relFile of result.extracted) {
-                await withLock(id, user, relFile, async () => {
-                    // The file is already on disk from the unzip; the release commits +
-                    // pushes it. If the extraction landed a markdown node the creator
-                    // can't read (default-deny chains), splice their read grant into
-                    // its frontmatter first so the committed change already carries it.
-                    // Best-effort: a failed grant write must not throw — withLock's
-                    // failure path releases WITHOUT committing and would discard the
-                    // extracted file from disk, turning a cosmetic grant failure into
-                    // data loss.
-                    try {
-                        const granted = await creatorAccess.grantInExtractedFile(id, user, relFile);
-                        if (granted !== null)
-                            await workspaceService.writeFile(id, relFile, granted);
-                    }
-                    catch (err) {
-                        console.warn(`[workspace.routes] creator grant on extracted "${relFile}" failed:`, err instanceof Error ? err.message : err);
-                    }
-                });
+                // The file is already on disk from the unzip; the release commits +
+                // pushes it.
+                await withLock(id, user, relFile, async () => undefined);
             }
             res.json(result);
         }
@@ -932,11 +1342,17 @@ export function createWorkspaceRoutes(workspaceService, authService, workflowSer
         const id = authenticated(req, res);
         if (id === null)
             return;
-        const filePath = req.query.path;
-        if (!filePath) {
+        const requested = requestPath(req.query.path);
+        if (requested === null) {
             res.status(400).json({ error: 'path query parameter is required' });
             return;
         }
+        // An upload with no folder lands at the repository ROOT inside the
+        // checkout, not beside it — eight staging test documents sat beside it
+        // because this route took the path as written.
+        const filePath = inRepo(res, requested);
+        if (filePath === null)
+            return;
         // `?defer=true` is the bulk-upload caller's signal to suppress the
         // per-file `fs-tree-changed` SSE — the caller emits one combined
         // refresh at end-of-burst via `POST /flush`. Pushing isn't deferred
@@ -964,17 +1380,14 @@ export function createWorkspaceRoutes(workspaceService, authService, workflowSer
                 chunks.push(buf);
             }
             const data = Buffer.concat(chunks);
-            // Creator read grant, mirroring PUT /file: seed a new subtree's
-            // access.md first, or fold the grant into an uploaded markdown file's
-            // frontmatter. Binary uploads into a pre-existing unreadable folder
-            // can't carry a per-file grant (no frontmatter) and proceed ungranted.
+            // Creator read grant, mirroring PUT /file: an upload that starts a new
+            // folder at a root seeds that folder's access.md first. An upload into
+            // a folder the caller cannot read never gets this far — the lock's read
+            // gate refuses it.
             const plan = await creatorAccess.planForCreate(id, user, filePath, 'file');
             if (plan?.kind === 'seed-access-md')
                 await seedCreatorAccessMd(id, user, plan);
-            const toWrite = plan?.kind === 'frontmatter'
-                ? Buffer.from(plan.apply(data.toString('utf8')), 'utf8')
-                : data;
-            await withLock(id, user, filePath, () => workspaceService.writeFileBinary(id, filePath, toWrite), defer ? { skipFsTreeEvent: true } : undefined);
+            await withLock(id, user, filePath, () => workspaceService.writeFileBinary(id, filePath, data), defer ? { skipFsTreeEvent: true } : undefined);
             res.json({ status: 'uploaded' });
         }
         catch (err) {
@@ -987,6 +1400,8 @@ export function createWorkspaceRoutes(workspaceService, authService, workflowSer
     // happens out of band in the worker, so this route's only remaining
     // responsibility is to emit the single combined `fs-tree-changed`
     // event the bulk caller suppressed per file.
+    // It takes NO path: there is nothing for the normaliser to place, which is
+    // why this route is the one on the surface that does not call it.
     router.post('/workspace/:id/flush', async (req, res) => {
         const id = authenticated(req, res);
         if (id === null)
@@ -1011,67 +1426,63 @@ export function createWorkspaceRoutes(workspaceService, authService, workflowSer
  * a recursive directory delete into per-file lock+release cycles so each
  * deletion lands as its own one-file change.
  *
- * Skips `.git` to avoid trying to commit the internal git index when a
- * caller targets it accidentally. Returns paths in stable lexical order
- * for predictable commit sequencing.
+ * Skips the git folder, in any spelling (`hasGitInternalsSegment`), so a
+ * folder delete never enumerates — or deletes — the repository's git data. Returns paths in the walk's order — stable
+ * and lexical — for predictable commit sequencing. A link counts as a file:
+ * it is deleted as one, never followed. A folder that cannot be listed is
+ * the delete's error: an enumeration with a hole in it would delete what it
+ * saw and report success over what it did not.
  */
-async function enumerateFilesUnder(absoluteDir, workspaceDir) {
+async function enumerateFilesUnder(disk, absoluteDir, workspaceDir) {
     const out = [];
-    async function walk(dir) {
-        let entries;
-        try {
-            entries = await fs.readdir(dir, { withFileTypes: true });
-        }
-        catch {
-            return;
-        }
-        entries.sort((a, b) => a.name.localeCompare(b.name));
-        for (const entry of entries) {
-            if (entry.name === '.git' && entry.isDirectory())
-                continue;
-            const child = path.join(dir, entry.name);
-            if (entry.isDirectory()) {
-                await walk(child);
-            }
-            else {
-                out.push(path.relative(workspaceDir, child).replace(/\\/g, '/'));
-            }
-        }
+    const relOf = (dir, name) => path.relative(workspaceDir, path.join(absoluteDir, dir, name)).replace(/\\/g, '/');
+    try {
+        await disk.walk(absoluteDir, { skip: (e) => hasGitInternalsSegment(e.name), unreadable: 'throw' }, [
+            {
+                onFile: (dir, name) => void out.push(relOf(dir, name)),
+                onOther: (dir, e) => void out.push(relOf(dir, e.name)),
+            },
+        ]);
+    }
+    catch (err) {
+        // The operator's line carries the errno and the path; the caller's answer
+        // names only the folder they asked about — an OS message would leak the
+        // server's spelling of the workspace, and would not help them anyway.
+        // Both halves of the log line are user- or disk-controlled text, so both
+        // go through `printable`: a folder name or an OS message carrying a
+        // control character must not steer the terminal or forge a log line.
+        const folder = path.relative(workspaceDir, absoluteDir).replace(/\\/g, '/');
+        const reason = err instanceof Error ? err.message : String(err);
+        logger('workspace').error(`could not list every file under ${printable(folder)} for a delete: ${printable(reason)}`);
+        throw Object.assign(new Error(`Could not list every file under "${folder}" — nothing was deleted. Try again, or ask an admin.`), {
+            status: 500,
+        });
     }
-    await walk(absoluteDir);
     return out;
 }
 /**
- * Recursively remove empty directories under `absoluteDir`, bottom-up, then
- * remove `absoluteDir` itself if it ends up empty. A directory is removed only
- * if it contains nothing at the moment it's visited, so any file a concurrent
- * writer dropped in mid-delete — and every parent directory on its path —
- * survives. `.git` is left alone. Used after a recursive folder delete to
- * sweep the leftover empty-folder shells off disk so the file tree (which
- * lists on-disk directories, not just tracked files) stops showing the
- * deleted container.
+ * The error a failed folder keep answers: the original one — its type,
+ * status and payload decide the response — with `message` saying what
+ * landed and what did not. Anything that is not an Error becomes one.
+ */
+function withKeptFolderContext(err, message) {
+    if (!(err instanceof Error))
+        return new Error(message);
+    err.message = message;
+    return err;
+}
+/**
+ * Whether a folder exists and holds nothing. A folder that is gone answers
+ * false: it was deleted explicitly, and keeping it would bring it back.
  */
-async function removeEmptyDirs(absoluteDir) {
-    let entries;
+async function isEmptyFolder(absoluteDir) {
     try {
-        entries = await fs.readdir(absoluteDir, { withFileTypes: true });
+        return (await fs.readdir(absoluteDir)).length === 0;
     }
-    catch {
-        // Already gone (raced delete) — nothing to do.
-        return;
-    }
-    for (const entry of entries) {
-        if (entry.name === '.git' && entry.isDirectory())
-            continue;
-        if (entry.isDirectory()) {
-            await removeEmptyDirs(path.join(absoluteDir, entry.name));
-        }
-    }
-    // Re-read after pruning children: a subdir we just emptied now lets this
-    // dir become removable too. Any surviving file (or `.git`) keeps it.
-    const remaining = await fs.readdir(absoluteDir);
-    if (remaining.length === 0) {
-        await fs.rmdir(absoluteDir);
+    catch (err) {
+        if (isAbsence(err))
+            return false;
+        throw err;
     }
 }
 //# sourceMappingURL=workspace.routes.js.map