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

package/src/modules/workspace/workspace.routes.ts

@@ -9,7 +9,6 @@ import type { IAdminAccessService } from '../admin/admin.interface.js';
 import express from 'express';
 import type { AuthUser, IWorkflowService } from '@bevel-software/platform-shared';
 import {
-  DEFAULT_BRANCH,
   KNOWLEDGE_DIR,
   canonicalRelativePath,
   folderPlaceholderPath,
@@ -21,6 +20,7 @@ import {
 } from '@bevel-software/platform-shared';
 import { FolderTooLargeError, type ReadTreeFilter } from './workspace.service.js';
 import { branchForWorkspaceId } from '../../shared/workspace-id.js';
+import type { KbContext } from '../../shared/kb-context.js';
 import { EntryExistsError, type WorkspaceService } from './workspace.service.js';
 import type { AuthService } from '../auth/auth.service.js';
 import type { IAccessControl } from '../access/access-control.interface.js';
@@ -82,7 +82,7 @@ export function createWorkspaceRoutes(
   workflowService: IWorkflowService,
   eventBus: WorkflowEventBus,
   accessControl: IAccessControl,
-  kbDirName: string,
+  kb: KbContext,
   creatorAccess: ICreatorAccess,
   adminAccess: IAdminAccessService,
   disk: ITreeWalker,
@@ -97,6 +97,7 @@ export function createWorkspaceRoutes(
   changeGate?: IChangeReadGate,
 ): express.Router {
   const router = express.Router();
+  const { kbDirName } = kb;
   const gitInternalsRouteGuard = createGitInternalsRouteGuard(workspaceService);
 
   // The git folder is refused ahead of every route here by
@@ -463,7 +464,7 @@ export function createWorkspaceRoutes(
       }
       const branch = typeof req.query.branch === 'string' && req.query.branch.length > 0
         ? req.query.branch
-        : DEFAULT_BRANCH;
+        : kb.defaultBranch;
       const workspace = await workspaceService.getOrCreateForBranch(branch);
       // Bootstrap must use the same read-filtered tree as GET /workspace/:id/files.
       // Otherwise the first sidebar render can expose restricted nodes until the
@@ -663,7 +664,7 @@ export function createWorkspaceRoutes(
       // same treatment so legacy clones don't collapse. Only the folders
       // themselves are forced visible — their contents stay gated by the
       // verdict above.
-      const structuralRoots = new Set([...reservedRootDirNames(), KNOWLEDGE_DIR]);
+      const structuralRoots = new Set([...reservedRootDirNames(kb.layout), KNOWLEDGE_DIR]);
       for (const wp of wsRelPaths) {
         const rel = toKbRelative(wp, kbDirName);
         if (rel !== null && structuralRoots.has(rel)) verdict.set(wp, true);
@@ -1128,11 +1129,11 @@ export function createWorkspaceRoutes(
       const oldRel = toKbRelative(oldPath, kbDirName);
       const newRel = toKbRelative(newPath, kbDirName);
       let platformRestore = false;
-      if (oldRel !== null && newRel !== null && isPlatformRestoreShape(oldRel, newRel)) {
+      if (oldRel !== null && newRel !== null && isPlatformRestoreShape(oldRel, newRel, kb.layout)) {
         platformRestore = await accessControl.canRestorePlatformFile(id, user.email, newRel);
       }
       // A platform file stays where the platform reads it …
-      if (oldRel !== null && isPlatformFile(oldRel) && !platformRestore) {
+      if (oldRel !== null && isPlatformFile(oldRel, kb.layout) && !platformRestore) {
         res.status(409).json({ error: platformFileRefusal(oldRel) });
         return;
       }
@@ -1145,7 +1146,7 @@ export function createWorkspaceRoutes(
       // 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) {
+      if (newRel !== null && isPlatformFile(newRel, kb.layout) && !platformRestore) {
         res.status(409).json({ error: platformFileCreationRefusal(newRel) });
         return;
       }

package/src/modules/workspace/workspace.service.ts

@@ -9,7 +9,6 @@ import { AsyncLocalStorage } from 'node:async_hooks';
 import {
   validateRelativePath,
   validateFilename,
-  DEFAULT_BRANCH,
   FOLDER_PLACEHOLDER,
   isFolderPlaceholder,
   entryExistsMessage,
@@ -22,6 +21,7 @@ import {
   renameNoReplace,
 } from '../../shared/rename-no-replace.js';
 import type { IGitRunner } from '../../shared/git.contract.js';
+import type { KbContext } from '../../shared/kb-context.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';
@@ -149,9 +149,8 @@ const CLONE_TIMEOUT_MS = 600_000;
 const BOT_NAME = 'Bevel Workflow';
 const BOT_EMAIL = 'bevel-workflow@bevel.software';
 
-/** Redact any token that might leak into an error message. */
-function redactError(err: unknown): string {
-  const token = process.env.GITHUB_TOKEN;
+/** Redact the token the runner authenticates with from an error message. */
+function redactError(err: unknown, token: string | null): string {
   const msg = err instanceof Error ? err.message : String(err);
   return token ? msg.replaceAll(token, '***') : msg;
 }
@@ -297,23 +296,26 @@ export class WorkspaceService implements IWorkspaceService {
      * buy an inconsistency rather than a feature.
      */
     kbRepoUrl: string | (() => string),
-    private readonly kbDirName: string,
+    /** The checkout folder's name, and which branch a caller lands on when naming none. */
+    private readonly kb: Pick<KbContext, 'kbDirName' | 'defaultBranch'>,
     private readonly disk: ITreeWalker,
-    gitUsername: string | (() => string) = '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.
+     * passes the one runner carrying the deployment's deadline and the
+     * credentials every clone authenticates with; the default is the same
+     * runner on its default deadline and no token, for a directly
+     * constructed service.
      */
     private readonly gitRunner: IGitRunner = new NodeGitRunner(),
   ) {
     this.kbRepoUrl = typeof kbRepoUrl === 'function' ? kbRepoUrl : () => kbRepoUrl;
-    this.gitUsername = typeof gitUsername === 'function' ? gitUsername : () => gitUsername;
+  }
+
+  private get kbDirName(): string {
+    return this.kb.kbDirName;
   }
 
   private readonly kbRepoUrl: () => string;
-  private readonly gitUsername: () => string;
 
   setDiffService(diffService: IDiffService): void {
     this.diffService = diffService;
@@ -417,7 +419,7 @@ export class WorkspaceService implements IWorkspaceService {
     // Persisted into the new repo's config (`clone --config`), not just applied
     // to this invocation — every later push from this clone depends on finding
     // the helper there. See `cloneCredentialArgs`.
-    args.push(...cloneCredentialArgs(this.gitUsername()));
+    args.push(...cloneCredentialArgs(this.gitRunner.credentials));
     args.push(this.kbRepoUrl(), targetDir);
     return args;
   }
@@ -531,7 +533,7 @@ export class WorkspaceService implements IWorkspaceService {
         cloned.push({
           id: entry.name,
           branch,
-          unreadable: `Could not read this branch's clone: ${redactError(err)}`,
+          unreadable: `Could not read this branch's clone: ${redactError(err, this.gitRunner.credentials.token())}`,
         });
         continue;
       }
@@ -566,7 +568,7 @@ export class WorkspaceService implements IWorkspaceService {
         return;
       } catch (err) {
         log.warn(`referenced clone for "${branch}" failed, retrying without reference:`, {
-          detail: redactError(err),
+          detail: redactError(err, this.gitRunner.credentials.token()),
         });
         // Clear any partial output so the retry clones into a clean dir.
         await fs.rm(targetDir, { recursive: true, force: true }).catch(() => {});
@@ -675,7 +677,7 @@ export class WorkspaceService implements IWorkspaceService {
    * `branch` is passed.
    */
   async getOrCreateForUser(_user: AuthUser, branch?: string): Promise<WorkspaceInfo> {
-    return this.getOrCreateForBranch(branch ?? DEFAULT_BRANCH);
+    return this.getOrCreateForBranch(branch ?? this.kb.defaultBranch);
   }
 
   private buildWorkspaceInfo(branch: string, workspaceDir: string): WorkspaceInfo {
@@ -741,7 +743,7 @@ export class WorkspaceService implements IWorkspaceService {
     } 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.
-      log.warn(`could not normalize the config of the "${branch}" clone:`, { detail: redactError(err) });
+      log.warn(`could not normalize the config of the "${branch}" clone:`, { detail: redactError(err, this.gitRunner.credentials.token()) });
     }
     await this.stampCredentialHelper(repoDir, branch);
   }
@@ -750,12 +752,13 @@ export class WorkspaceService implements IWorkspaceService {
    * Fingerprint of the credential state a clone's helper is derived from: the
    * username (baked into the helper literal) and whether a token exists at all
    * (the helper is present-or-absent on that). The token VALUE is deliberately
-   * excluded — the helper reads `$GITHUB_TOKEN` at call time, so rotating the
-   * token needs no re-stamp; only a username change or a token appearing /
-   * disappearing does.
+   * excluded — the helper reads `$GITHUB_TOKEN` from the environment the
+   * runner hands each git call, so rotating the token needs no re-stamp; only
+   * a username change or a token appearing / disappearing does.
    */
   private credentialFingerprint(): string {
-    return `${this.gitUsername()}::${process.env.GITHUB_TOKEN ? '1' : '0'}`;
+    const { credentials } = this.gitRunner;
+    return `${credentials.username()}::${credentials.token() ? '1' : '0'}`;
   }
 
   /** Last credential fingerprint stamped into each branch's clone, this process. */
@@ -772,7 +775,7 @@ export class WorkspaceService implements IWorkspaceService {
   private async stampCredentialHelper(repoDir: string, branch: string): Promise<void> {
     let argLists: string[][];
     try {
-      argLists = cloneCredentialConfigArgs(this.gitUsername());
+      argLists = cloneCredentialConfigArgs(this.gitRunner.credentials);
     } catch (err) {
       // `credentialHelperValue` fails closed on a username outside its safe
       // charset. Normally unreachable (CoreConfig and the settings service
@@ -782,7 +785,7 @@ export class WorkspaceService implements IWorkspaceService {
       // 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.
-      log.warn(`refusing to stamp the credential helper of the "${branch}" clone:`, { detail: redactError(err) });
+      log.warn(`refusing to stamp the credential helper of the "${branch}" clone:`, { detail: redactError(err, this.gitRunner.credentials.token()) });
       this.stampedCredentialFingerprint.delete(branch);
       return;
     }
@@ -798,7 +801,7 @@ export class WorkspaceService implements IWorkspaceService {
         if (!(args.includes('--unset-all') && code === 5)) {
           stamped = false;
           log.warn(`could not stamp the credential helper of the "${branch}" clone:`, {
-            detail: redactError(err),
+            detail: redactError(err, this.gitRunner.credentials.token()),
           });
         }
       }
@@ -914,11 +917,11 @@ export class WorkspaceService implements IWorkspaceService {
         this.onWorkspaceCloned?.(workspaceIdForBranch(branch));
       } catch (listenerErr) {
         log.error(`onWorkspaceCloned listener failed for branch "${branch}":`, {
-          detail: redactError(listenerErr),
+          detail: redactError(listenerErr, this.gitRunner.credentials.token()),
         });
       }
     } catch (err) {
-      const redacted = redactError(err);
+      const redacted = redactError(err, this.gitRunner.credentials.token());
       // 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
@@ -936,7 +939,7 @@ export class WorkspaceService implements IWorkspaceService {
           // 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),
+            detail: redactError(probeErr, this.gitRunner.credentials.token()),
           });
           throw new Error(`Failed to clone process map: ${redacted}`);
         }
@@ -995,6 +998,14 @@ export class WorkspaceService implements IWorkspaceService {
    * 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.
    *
+   * The git rule reads the caller's RAW spelling before either step — the
+   * whole rule, links resolved, not just the spelling. Those two refuse
+   * `.`/`..`, backslashes and absolute paths with a message that quotes the
+   * path back and names a corrected one, and a git path spelled any of those
+   * ways was answered by THAT rather than by the one sanitized refusal
+   * (measured in production), as was a LINK into the folder spelled the same
+   * ways. Which rule speaks is not the caller's to choose.
+   *
    * 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
@@ -1006,6 +1017,7 @@ export class WorkspaceService implements IWorkspaceService {
     wsPath: string,
   ): Promise<{ workspaceDir: string; relativePath: string; absolutePath: string }> {
     const workspaceDir = await this.resolveWorkspaceDir(workspaceId);
+    await assertNotGitInternals(workspaceDir, wsPath); // The RAW spelling, first — see above.
     const relativePath = normalizeWorkspacePath(wsPath, this.kbDirName);
     const absolutePath = path.resolve(workspaceDir, relativePath);
     assertWithinDirectory(absolutePath, this.repoRoot(workspaceDir));
@@ -1246,7 +1258,7 @@ export class WorkspaceService implements IWorkspaceService {
       })
       .catch((err) => {
         this.lastFetchOk.set(repoDir, false);
-        log.warn('git fetch origin failed:', { detail: redactError(err) });
+        log.warn('git fetch origin failed:', { detail: redactError(err, this.gitRunner.credentials.token()) });
       })
       .finally(() => {
         if (this.inFlightFetches.get(repoDir) === promise) {

package/src/modules/workspace/workspace.tools.ts

@@ -23,7 +23,7 @@ import { workspaceIdForBranch } from '../../shared/workspace-id.js';
 import { assertValidBranchName } from '../kb-fs/branch-name.js';
 import { assertInsideRepo, assertRepoRootNameFreeArgs, normalizePathArgs } from '../kb-fs/repo-path.js';
 import { GitGuardedFilesystem } from '../kb-fs/git-guarded-filesystem.js';
-import { assertNoGitInternalsSegment, hasGitInternalsSegment } from '../../shared/git-internals.js';
+import { assertNoGitInternalsSegment, assertNotGitInternals, hasGitInternalsSegment } from '../../shared/git-internals.js';
 import { isRolesYamlPath } from '../access-model/roles-yaml-guard.js';
 import type { ISessionSink } from './session-sink.js';
 import { isAbsence } from '../../shared/fs.contract.js';
@@ -39,21 +39,20 @@ import { createFileReaderRegistry } from './file-readers/file-reader.registry.js
 import { DocumentReader } from './file-readers/document-reader.js';
 import { mcpImageResult } from '@bevel-software/platform-mcp-core';
 import {
-  AGENTS_FILE,
   LEGACY_AGENTS_FILE,
   folderPlaceholderPath,
   isFolderPlaceholder,
   isPlatformFile,
   isPlatformFolder,
-  isProtectedBranch,
-  onKbLayoutApplied,
   platformFileCreationRefusal,
   platformFileNames,
   platformFileRefusal,
   platformFolderRefusal,
   entryExistsMessage,
   type ExistingEntryKind,
+  type KbLayout,
 } from '@bevel-software/platform-shared';
+import type { KbContext } from '../../shared/kb-context.js';
 import { AccessDeniedError } from '../access-model/access-errors.js';
 import { removeEmptyDirs } from './empty-dirs.js';
 import { PROPOSAL_ROUTE_NOTE, rethrowAsWriteDenial } from './write-denial.js';
@@ -216,22 +215,23 @@ async function keepFolderOf(
  * working in their knowledge base. Under the default name the wording collapses
  * to the one file it has always named.
  *
- * A FUNCTION, called at mount time: the name is a deployment setting applied at
- * boot, and a module-scope string would snapshot the default.
+ * A FUNCTION of the layout, called when a description is built: the name is a
+ * deployment setting, and a module-scope string would snapshot the default.
  */
-function kbConventionsNote(): string {
-  if (AGENTS_FILE === LEGACY_AGENTS_FILE) {
+function kbConventionsNote(layout: KbLayout): string {
+  const agentsFile = layout.agentsFile ?? LEGACY_AGENTS_FILE;
+  if (agentsFile === LEGACY_AGENTS_FILE) {
     return ' Before your first read or change in a workspace, read `AGENTS.md` at the KB root — or `CLAUDE.md` on a knowledge base seeded before it was renamed — if either exists: it holds the author\'s conventions for this knowledge base, and you should follow them.';
   }
   return (
-    ` Before your first read or change in a workspace, read \`${AGENTS_FILE}\` at the KB root, then ` +
+    ` Before your first read or change in a workspace, read \`${agentsFile}\` at the KB root, then ` +
     '`AGENTS.md` if it also exists (the organisation\'s own conventions) — or `CLAUDE.md` on a knowledge base seeded before it was renamed: together they hold the conventions for this knowledge base, and you should follow them.'
   );
 }
 
 /** The platform files as a tool description lists them — the guide under its own name. */
-function platformFileList(): string {
-  return platformFileNames()
+function platformFileList(layout: KbLayout): string {
+  return platformFileNames(layout)
     .map((name) => `\`${name}\``)
     .join(', ');
 }
@@ -679,7 +679,7 @@ export function registerWorkspaceTools(
   spillStore: SpillStore,
   docExtract: DocExtractService,
   accessControl: IAccessControl,
-  kbDirName: string,
+  kb: KbContext,
   sessionOntologyGate: SessionOntologyGate,
   writePolicy: IRoutineWritePolicy,
   sessionSink: ISessionSink,
@@ -697,6 +697,7 @@ export function registerWorkspaceTools(
    */
   changeGate?: IChangeReadGate,
 ): void {
+  const { kbDirName } = kb;
   /**
    * The one extension→reader registry every read-shaped decision routes
    * through: read_file dispatches on it, grep asks it for searchable text,
@@ -782,7 +783,7 @@ export function registerWorkspaceTools(
    * not cloned yet (or that does not resolve) is left to the handler; the
    * filesystem refuses again underneath regardless.
    */
-  const assertToolPathsNotGitInternals = async (args: Record<string, unknown>, ctx: ToolContext): Promise<void> => {
+  const toolPathArgs = (args: Record<string, unknown>): string[] => {
     const paths: string[] = [];
     for (const key of ['path', 'src', 'dest', 'destination'] as const) {
       if (typeof args[key] === 'string') paths.push(args[key]);
@@ -793,18 +794,52 @@ export function registerWorkspaceTools(
         if (typeof fp === 'string') paths.push(fp);
       }
     }
-    for (const p of paths) assertNoGitInternalsSegment(p);
-    const onDisk = paths.filter((p) => !spillStore.isSpillRef(p));
-    if (onDisk.length === 0 || typeof args.branch !== 'string' || args.branch === '') return;
-    let fs: LocalFilesystem;
+    return paths;
+  };
+
+  /**
+   * The branch's workspace root, to judge a spelling against what is on disk
+   * — or null when there is nothing to judge it against yet. Only a branch
+   * ALREADY cloned is used: bootstrapping one here would clone before the
+   * handler's access and ontology gates have had their say.
+   */
+  const gitCheckRootFor = async (args: Record<string, unknown>, ctx: ToolContext): Promise<string | null> => {
+    if (typeof args.branch !== 'string' || args.branch === '') return null;
     try {
-      if (!(await ctx.workspaceService.hasBootstrappedWorkspace(workspaceIdForBranch(args.branch)))) return;
-      fs = await ctx.getFilesystem(args.branch);
+      if (!(await ctx.workspaceService.hasBootstrappedWorkspace(workspaceIdForBranch(args.branch)))) return null;
+      const fs = await ctx.getFilesystem(args.branch);
+      return fs instanceof GitGuardedFilesystem ? fs.basePath : null;
     } catch {
-      return;
+      return null;
     }
-    if (!(fs instanceof GitGuardedFilesystem)) return;
-    for (const p of onDisk) await fs.assertNotGitInternals(p);
+  };
+
+  /**
+   * The WHOLE rule — the spelling and where it lands, links resolved — over
+   * the caller's own arguments, before any gate, lock or read.
+   *
+   * Run before `normalizePathArgs`, which refuses a `..` segment, a `.`
+   * segment, a backslash and an absolute path as PATHS: a 400 that quotes the
+   * spelling back and names a corrected one. That answer used to arrive first
+   * for five families of spelling, so `knowledge-base/Notes/../.git/config`
+   * was told which path it meant instead of being refused. Running only the
+   * LEXICAL half here fixed those and left the same hole one step along: a
+   * link into the folder (`Notes/../gitlink/config`) has no `.git` to read in
+   * its spelling, so it took the path rule's answer too. Both halves therefore
+   * read the caller's spelling before anything may rewrite or refuse it.
+   *
+   * Nothing under the folder was reachable through any of it — the filesystem
+   * refuses again underneath — but which rule answers is not the caller's to
+   * choose by how they spell the path.
+   */
+  const assertToolPathsNotGitInternals = async (args: Record<string, unknown>, ctx: ToolContext): Promise<void> => {
+    const paths = toolPathArgs(args);
+    for (const p of paths) assertNoGitInternalsSegment(p);
+    const onDisk = paths.filter((p) => !spillStore.isSpillRef(p));
+    if (onDisk.length === 0) return;
+    const root = await gitCheckRootFor(args, ctx);
+    if (root === null) return;
+    for (const p of onDisk) await assertNotGitInternals(root, p);
   };
 
   // ── preflight for moves and deletes ─────────────────────────────────────
@@ -837,7 +872,7 @@ export function registerWorkspaceTools(
    * branch only through a change request.
    */
   const writeBlocked = async (branch: string, ctx: ToolContext, paths: string[]): Promise<string[]> => {
-    if (!isProtectedBranch(branch)) return [];
+    if (!kb.isProtectedBranch(branch)) return [];
     const byRel = new Map<string, string>();
     for (const p of paths) {
       const rel = toKbRelative(p, kbDirName);
@@ -900,11 +935,11 @@ export function registerWorkspaceTools(
     if (isGitMetadata(norm)) return `"${norm}" is git metadata and cannot be moved or deleted.`;
     if (kind === 'file') {
       const rel = toKbRelative(norm, kbDirName);
-      return rel !== null && isPlatformFile(rel) ? platformFileRefusal(rel) : undefined;
+      return rel !== null && isPlatformFile(rel, kb.layout) ? platformFileRefusal(rel) : undefined;
     }
     if (norm === '' || norm === kbDirName) return platformFolderRefusal('');
     const rel = toKbRelative(norm, kbDirName);
-    return rel !== null && isPlatformFolder(rel) ? platformFolderRefusal(rel) : undefined;
+    return rel !== null && isPlatformFolder(rel, kb.layout) ? platformFolderRefusal(rel) : undefined;
   };
 
   /** The workspace root on disk for `branch`. */
@@ -1147,7 +1182,7 @@ export function registerWorkspaceTools(
       (typeof spec.description === 'function' ? spec.description() : spec.description) +
       (spec.proposable ? PROPOSAL_ROUTE_NOTE : '') +
       (spec.fileTool === false ? '' : CONTENT_RULE) +
-      kbConventionsNote();
+      kbConventionsNote(kb.layout);
     const def = toolDef({
       name: spec.name,
       description: describe(),
@@ -1165,7 +1200,7 @@ export function registerWorkspaceTools(
     // move the text with them. Rewritten in place: the registry holds this
     // object, both surfaces hold the same one, and re-registering would be a
     // duplicate name.
-    onKbLayoutApplied(() => {
+    kb.onLayoutApplied(() => {
       def.description = describe();
     });
     // Internal-only tools (e.g. `execute_command`) keep their route mounted —
@@ -1188,6 +1223,8 @@ export function registerWorkspaceTools(
       // never reached the repository — the whole bug, spelled with a prefix.
       toolHandler(
         async (args, ctx) => {
+          // BEFORE the normaliser: see `assertToolPathsNotGitInternals`.
+          if (spec.fileTool !== false) await assertToolPathsNotGitInternals(args, ctx);
           const normalized = normalizePathArgs(
             args,
             kbDirName,
@@ -1214,7 +1251,7 @@ export function registerWorkspaceTools(
               err,
               { tool: spec.name, branch: args.branch, userEmail: ctx.user.email, userId: ctx.user.id },
               accessControl,
-              kbDirName,
+              kb,
               changeGate,
             );
           }
@@ -1396,7 +1433,7 @@ export function registerWorkspaceTools(
     description: () =>
       'Get a file/directory\'s metadata (name, type, size, …) without returning content. A file also reports `contentMode`: `text` (read, write and edit it as text), `document` (read returns an extraction; replace it by upload) or `binary` (bytes: copy, move, delete, or replace by upload), plus `kind` (`text` | `document` | `image` | `binary`), `mime`, `mimeSource` and `textEditable` — decided by the same file readers read_file, grep and the write tools use, so an extensionless text file is `text/plain`.' +
       ' Every entry also reports what you may DO with it. ' +
-      `\`managed\` is true for a platform item — a platform file (${platformFileList()}) or a platform folder (the repository root or a reserved root folder such as \`KnowledgeBase/\`); managed items are never movable or deletable through these tools. ` +
+      `\`managed\` is true for a platform item — a platform file (${platformFileList(kb.layout)}) or a platform folder (the repository root or a reserved root folder such as \`KnowledgeBase/\`); managed items are never movable or deletable through these tools. ` +
       '`access: { read, write, download, owner }` is your own verdict under the access rules; pass `explainAccess: true` to learn why, and who else holds each verb. `movable` and `deletable` say whether `move_file` / `delete_file` / `delete_folder` would be allowed for you, judged like their dry runs: not managed, no symbolic link, and on a protected branch you hold write on the item AND on every file under a folder (on a draft branch writes are not gated). `movable` judges the source side only; the destination is judged by a `move_file` dry run. ' +
       'For a folder, `descendants` is the number of files under it at any depth; counting stops at 10000 and `descendantsTruncated` says so, and past that point `movable` and `deletable` are false because a folder that large was not judged in full — run the `move_file` or `delete_folder` dry run for the real verdict. ' +
       'Call this before a move or delete to see what it would touch.' +
@@ -2006,7 +2043,7 @@ export function registerWorkspaceTools(
     name: 'delete_file',
     description: () =>
       'Delete ONE workspace file (a symbolic link is refused: links are never followed or removed). Committed + pushed as you. Its folder stays, even when this was its last file. Files only: a folder is refused with a pointer to `delete_folder`. ' +
-      `A platform file (\`access.md\` or \`.bevelignore\` in any folder, \`roles.yaml\` or \`${AGENTS_FILE}\` at the repository root) and git metadata are refused.` +
+      `A platform file (\`access.md\` or \`.bevelignore\` in any folder, \`roles.yaml\` or \`${kb.layout.agentsFile}\` at the repository root) and git metadata are refused.` +
       ONTOLOGY_BOUNDARY_NOTE,
     inputs: {
       type: 'object',
@@ -2226,7 +2263,7 @@ export function registerWorkspaceTools(
     name: 'move_file',
     description: () =>
       'Move or rename a workspace FILE or FOLDER; a folder moves recursively, with everything under it. `dest` is the full new path, not the folder to move into. Lands as a delete + create, committed + pushed as you. ' +
-      `Rules: the destination must not exist — a move never overwrites a file or merges into a folder; a platform file (\`access.md\` or \`.bevelignore\` in any folder, \`roles.yaml\` or \`${AGENTS_FILE}\` at the repository root) is refused with "<name> is a platform file and stays in its folder." — a folder that moves takes its own platform files along, still in their folder; a platform folder (the repository root or a reserved root folder such as \`KnowledgeBase/\`) and git metadata are refused; a move cannot create a platform file or folder at \`dest\` either (renaming a note to \`access.md\` is refused); a path through a symbolic link is refused, since links are never followed; on a protected branch you must be able to write both ends — for a folder, every file under it at its old and its new path. ` +
+      `Rules: the destination must not exist — a move never overwrites a file or merges into a folder; a platform file (\`access.md\` or \`.bevelignore\` in any folder, \`roles.yaml\` or \`${kb.layout.agentsFile}\` at the repository root) is refused with "<name> is a platform file and stays in its folder." — a folder that moves takes its own platform files along, still in their folder; a platform folder (the repository root or a reserved root folder such as \`KnowledgeBase/\`) and git metadata are refused; a move cannot create a platform file or folder at \`dest\` either (renaming a note to \`access.md\` is refused); a path through a symbolic link is refused, since links are never followed; on a protected branch you must be able to write both ends — for a folder, every file under it at its old and its new path. ` +
       'Access follows the destination folder. Preflight first: `dryRun: true` changes nothing and answers `{ src, dest, kind, descendants, access: { before, after }, accessChanges, allowed, reason? }` — `access` is your own `{ read, write, download, owner }` at the source and at the destination. ' +
       'A move whose `accessChanges` is true runs only with `confirm: true`; without it the call moves nothing and returns the same impact with `confirmationRequired: true`. Do NOT set `confirm: true` on your first call — dry-run, check the impact, then confirm.' +
       ONTOLOGY_BOUNDARY_NOTE,

package/src/modules/workspace/write-denial.ts

@@ -1,4 +1,5 @@
-import { branchAuthorLocalpart, isProtectedBranch, suggestionsBranchPrefixFor } from '@bevel-software/platform-shared';
+import { branchAuthorLocalpart, suggestionsBranchPrefixFor } from '@bevel-software/platform-shared';
+import type { KbContext } from '../../shared/kb-context.js';
 import { ToolError } from '../tool-helpers/tool.contract.js';
 import { AccessDeniedError } from '../access-model/access-errors.js';
 import type { IChangeReadGate } from '../access-model/change-gate.js';
@@ -111,9 +112,10 @@ export async function writeDenial(
   err: AccessDeniedError,
   input: { tool: string; branch: string; userEmail: string; userId: string },
   accessControl: IAccessControl,
-  kbDirName: string,
+  kb: Pick<KbContext, 'kbDirName' | 'isProtectedBranch'>,
   changeGate?: IChangeReadGate,
 ): Promise<ToolError> {
+  const { kbDirName } = kb;
   const path = err.access.path;
   const base = { kind: 'write-denied' as const, path, reason: reasonOf(err) };
   const refuse = (cannotProposeReason: string): ToolError => {
@@ -121,7 +123,7 @@ export async function writeDenial(
     return new ToolError(`${err.message} ${cannotProposeReason}`, 403, { ...details });
   };
 
-  if (!isProtectedBranch(input.branch)) {
+  if (!kb.isProtectedBranch(input.branch)) {
     return refuse(`Proposing is not available: "${input.branch}" is not a branch that accepts change requests.`);
   }
   // The lock gate reports workspace paths, the git gates repo-relative ones.
@@ -179,11 +181,11 @@ export async function rethrowAsWriteDenial(
   err: unknown,
   input: { tool: string; branch: unknown; userEmail: string; userId: string },
   accessControl: IAccessControl,
-  kbDirName: string,
+  kb: Pick<KbContext, 'kbDirName' | 'isProtectedBranch'>,
   changeGate?: IChangeReadGate,
 ): Promise<never> {
   if (err instanceof AccessDeniedError && typeof input.branch === 'string') {
-    throw await writeDenial(err, { ...input, branch: input.branch }, accessControl, kbDirName, changeGate);
+    throw await writeDenial(err, { ...input, branch: input.branch }, accessControl, kb, changeGate);
   }
   throw err;
 }

package/src/shared/__tests__/git-internals.test.ts

@@ -98,6 +98,47 @@ describe('assertNotGitInternals — the resolved form', () => {
     await expect(assertNotGitInternals(root, 'knowledge-base/dangling')).rejects.toMatchObject({ code: 'EACCES' });
   });
 
+  it.each(['/etc/shadow', '../../../../etc/shadow', '/proc/1/root/secret'])(
+    'never probes a spelling that lands outside the workspace on disk: %s',
+    async (outside) => {
+      // A raw spelling fans out into candidates, and one can name somewhere
+      // the server may not read. Probing it would answer with that place's own
+      // EACCES instead of the path rule's typed refusal for a spelling that
+      // was never a workspace path — so the disk is only asked about
+      // candidates that land under the root. The lexical reading still judges
+      // the rest, which is what catches a climb into another checkout's .git.
+      const realpath = fs.realpath.bind(fs);
+      const asked: string[] = [];
+      vi.spyOn(fs, 'realpath').mockImplementation((async (p: string) => {
+        asked.push(p);
+        if (!p.startsWith(root)) throw Object.assign(new Error('EACCES: permission denied'), { code: 'EACCES' });
+        return realpath(p);
+      }) as typeof fs.realpath);
+
+      await expect(assertNotGitInternals(root, outside)).resolves.toBeUndefined();
+      expect(asked.filter((p) => !p.startsWith(root))).toEqual([]);
+    },
+  );
+
+  it.each(['..link', '..link/config', './..link/config', '..dir/deeper'])(
+    'probes a name that merely BEGINS with dots, and refuses it when it lands in the folder: %s',
+    async (p) => {
+      // Judged from the folder these sit DIRECTLY in, which is where the
+      // outside-the-root test can mistake them: relative to that root, the
+      // whole path is `..link/…`. `..link` is not a climb — it is a file name
+      // — so it is probed like any other entry, or a link by that name reaches
+      // the folder unchecked.
+      const kb = path.join(root, 'knowledge-base');
+      await fs.symlink('.git', path.join(kb, '..link'));
+      await fs.symlink('.git', path.join(kb, '..dir'));
+      await expect(assertNotGitInternals(kb, p)).rejects.toBeInstanceOf(GitInternalsError);
+    },
+  );
+
+  it('still refuses a climb into another checkout’s git folder, which is judged without the disk', async () => {
+    await expect(assertNotGitInternals(root, '../other-checkout/.git/config')).rejects.toBeInstanceOf(GitInternalsError);
+  });
+
   it('a link loop is no refusal of its own, and does not hang', async () => {
     await expect(assertNotGitInternals(root, 'knowledge-base/loop-a')).resolves.toBeUndefined();
   });