@bevel-software/platform-core-backend 0.20.0 → 0.22.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(() => {});
@@ -647,15 +649,31 @@ export class WorkspaceService implements IWorkspaceService {
     }
     this.inFlightBootstraps.set(branch, bootstrap);
 
+    // `mkdir --recursive` answers with the first path it CREATED, or undefined
+    // when the directory was already there. That is the only honest signal for
+    // what the rollback below may remove: a directory this attempt made is ours
+    // to take back, one that predates us belongs to whatever put it there.
+    let createdWorkspaceDir: string | undefined;
     try {
       // A clone with `-b <branch>` against a never-seeded remote fails
       // naturally; seeding the remote is the KB startup phase's job, at boot.
-      await fs.mkdir(workspaceDir, { recursive: true });
+      createdWorkspaceDir = await fs.mkdir(workspaceDir, { recursive: true });
       await this.cloneProcessMapForBranch(workspaceDir, branch);
       this.registerBranchDir(branch, workspaceDir);
       resolveBootstrap();
     } catch (err) {
       this.branchDirs.delete(branch);
+      // A bootstrap that failed leaves NOTHING behind. The clone rolls its own
+      // target back, but the workspace directory around it would survive as an
+      // empty shell named after the branch — and a directory named after a
+      // branch is read as the platform having known that branch: by
+      // `hasHeardOfBranch`, which would turn the next attempt's honest 404 into
+      // "no longer exists on the remote" (410), and by anyone reading the
+      // workspaces root. Best-effort: a rollback that cannot delete must not
+      // replace the real failure (the clone's) with its own.
+      if (createdWorkspaceDir !== undefined) {
+        await fs.rm(workspaceDir, { recursive: true, force: true }).catch(() => {});
+      }
       rejectBootstrap(err);
       throw err;
     } finally {
@@ -675,7 +693,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 +759,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 +768,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 +791,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 +801,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 +817,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 +933,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 +955,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}`);
         }
@@ -1255,7 +1274,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

@@ -18,6 +18,7 @@ import type { IRoutineWritePolicy } from './routine-write-policy.js';
 import type { ToolHandlerFactory } from '../tool-helpers/tool-handler.js';
 import { requireInternalSource, requireExternalSource } from '../tool-auth/tool-auth.middleware.js';
 import { workspaceIdForBranch } from '../../shared/workspace-id.js';
+import { assertBranchProvided } from '../../shared/domain-errors.js';
 // Leaf-level shared primitive (same exception `workspace.service.ts` already
 // relies on) — not a workflow service, so this stays inside the module boundary.
 import { assertValidBranchName } from '../kb-fs/branch-name.js';
@@ -39,21 +40,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 +216,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 +680,7 @@ export function registerWorkspaceTools(
   spillStore: SpillStore,
   docExtract: DocExtractService,
   accessControl: IAccessControl,
-  kbDirName: string,
+  kb: KbContext,
   sessionOntologyGate: SessionOntologyGate,
   writePolicy: IRoutineWritePolicy,
   sessionSink: ISessionSink,
@@ -697,6 +698,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,
@@ -871,7 +873,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);
@@ -934,11 +936,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`. */
@@ -1170,6 +1172,15 @@ export function registerWorkspaceTools(
     proposable?: boolean;
     /** False for a tool that is not a file tool (the shell), which the content rule does not describe. */
     fileTool?: boolean;
+    /**
+     * This tool resolves `branch` ITSELF and must not be pre-checked here.
+     * Only `execute_command` sets it: for an internal session that leaves the
+     * argument off, it falls back to the caller's own focused branch (from its
+     * signed token) rather than refusing. It still answers the same
+     * `branch-required` kind when there is nothing to fall back on — see its
+     * handler. Every other tool takes the check below.
+     */
+    resolvesBranchItself?: boolean;
     handler: ToolHandler;
   }): void => {
     const path = `/api/agent/tools/${spec.name}`;
@@ -1177,11 +1188,17 @@ export function registerWorkspaceTools(
     // tool the one content rule, and every tool a permission can refuse the
     // proposal route — appended once here so no tool (especially the
     // read-only ones a session hits first) can miss them.
+    // Whether a call to this tool MUST name a branch, read off the tool's own
+    // declaration rather than assumed of the family. Every tool mounted here
+    // requires `branch` today; keying on the schema means a tool that declares
+    // it optional (and resolves absence itself, as `list_tool_setup` does on its
+    // own route) is not handed a refusal it never asked for.
+    const requiresBranch = ((spec.inputs as { required?: string[] }).required ?? []).includes('branch');
     const describe = (): string =>
       (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(),
@@ -1199,7 +1216,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 —
@@ -1222,6 +1239,16 @@ export function registerWorkspaceTools(
       // never reached the repository — the whole bug, spelled with a prefix.
       toolHandler(
         async (args, ctx) => {
+          // FIRST, before the path work and before any handler: every tool
+          // mounted here declares `branch` as a required, non-empty string, and
+          // nothing enforced that, so a call that named none was carried down
+          // until `workspaceIdForBranch` made a workspace directory out of the
+          // missing value. Most of these tools would meet the same refusal one
+          // layer down at `getFilesystem`, but not all of them do — `unzip`
+          // hands `branch` straight to the workspace service by id — so the
+          // check belongs on the mount every one of them shares rather than on
+          // the resolver only some of them reach.
+          if (requiresBranch && !spec.resolvesBranchItself) assertBranchProvided(args.branch);
           // BEFORE the normaliser: see `assertToolPathsNotGitInternals`.
           if (spec.fileTool !== false) await assertToolPathsNotGitInternals(args, ctx);
           const normalized = normalizePathArgs(
@@ -1250,7 +1277,7 @@ export function registerWorkspaceTools(
               err,
               { tool: spec.name, branch: args.branch, userEmail: ctx.user.email, userId: ctx.user.id },
               accessControl,
-              kbDirName,
+              kb,
               changeGate,
             );
           }
@@ -1432,7 +1459,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.' +
@@ -2042,7 +2069,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',
@@ -2262,7 +2289,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,
@@ -2593,6 +2620,9 @@ export function registerWorkspaceTools(
       ONTOLOGY_BOUNDARY_NOTE,
     internalOnly: true,
     fileTool: false,
+    // The one tool the mount's branch check skips: the handler below resolves an
+    // omitted `branch` to the internal caller's focused branch before refusing.
+    resolvesBranchItself: true,
     inputs: {
       type: 'object',
       properties: {
@@ -2649,6 +2679,11 @@ export function registerWorkspaceTools(
         throw new ToolError(
           'execute_command requires a `branch`: pass the branch (draft) whose workspace to run the command in — the one you are currently working on.',
           400,
+          // The same discriminator every other KB tool answers a branch-less
+          // call with, so a client switches on one kind across the surface.
+          // The MESSAGE stays this tool's own: it can name the focused-branch
+          // fallback that only applies here.
+          { kind: 'branch-required' },
         );
       }
       // A stringified absent value. Both are syntactically valid git branch names,
@@ -2661,6 +2696,7 @@ export function registerWorkspaceTools(
           `execute_command got the literal string "${branch}" as \`branch\` — that is a stringified absent value, not a branch. ` +
             'Pass the real branch (draft) whose workspace to run the command in.',
           400,
+          { kind: 'branch-required' },
         );
       }
       // Then the SHAPE, via the one canonical validator every other branch path

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__/kb-layout.plugin.test.ts

@@ -1,5 +1,8 @@
 import { describe, it, expect } from 'vitest';
-import { pluginOfPath, PLUGINS_DIR } from '@bevel-software/platform-shared';
+import { DEFAULT_KB_LAYOUT, pluginOfPath, PLUGINS_DIR } from '@bevel-software/platform-shared';
+
+/** `pluginOfPath` under the default layout, which these cases are written against. */
+const plugin = (path: string) => pluginOfPath(path, DEFAULT_KB_LAYOUT);
 
 /**
  * `pluginOfPath` is the whole of the grouping contract — the sidebar, the
@@ -9,9 +12,9 @@ import { pluginOfPath, PLUGINS_DIR } from '@bevel-software/platform-shared';
  */
 describe('pluginOfPath', () => {
   it('reads the plugin from the Plugins root', () => {
-    expect(pluginOfPath(`${PLUGINS_DIR}/GTM/heyreach-campaign/SKILL.md`)).toBe('GTM');
-    expect(pluginOfPath(`${PLUGINS_DIR}/GTM/heyreach.tool`)).toBe('GTM');
-    expect(pluginOfPath(`${PLUGINS_DIR}/Engineering/review/architecture-review`)).toBe(
+    expect(plugin(`${PLUGINS_DIR}/GTM/heyreach-campaign/SKILL.md`)).toBe('GTM');
+    expect(plugin(`${PLUGINS_DIR}/GTM/heyreach.tool`)).toBe('GTM');
+    expect(plugin(`${PLUGINS_DIR}/Engineering/review/architecture-review`)).toBe(
       'Engineering',
     );
   });
@@ -19,27 +22,27 @@ describe('pluginOfPath', () => {
   it('returns null for content directly under the root — it has no plugin folder', () => {
     // The regression this guards: `Plugins/slack.tool` must NOT report a plugin
     // called "slack.tool", and `Plugins/GTM` must not report itself.
-    expect(pluginOfPath(`${PLUGINS_DIR}/slack.tool`)).toBeNull();
-    expect(pluginOfPath(`${PLUGINS_DIR}/GTM`)).toBeNull();
-    expect(pluginOfPath(PLUGINS_DIR)).toBeNull();
+    expect(plugin(`${PLUGINS_DIR}/slack.tool`)).toBeNull();
+    expect(plugin(`${PLUGINS_DIR}/GTM`)).toBeNull();
+    expect(plugin(PLUGINS_DIR)).toBeNull();
   });
 
   it('returns null outside the plugin root', () => {
-    expect(pluginOfPath('KnowledgeBase/Product/Knowledge/Foo.md')).toBeNull();
-    expect(pluginOfPath('Data/Engineering/Knowledge/Bar.md')).toBeNull();
+    expect(plugin('KnowledgeBase/Product/Knowledge/Foo.md')).toBeNull();
+    expect(plugin('Data/Engineering/Knowledge/Bar.md')).toBeNull();
     // The retired pre-merge roots are ordinary non-plugin folders now.
-    expect(pluginOfPath('Skills/GTM/heyreach-campaign')).toBeNull();
-    expect(pluginOfPath('Tools/NewsAgent/serper.tool')).toBeNull();
-    expect(pluginOfPath('access.md')).toBeNull();
-    expect(pluginOfPath('')).toBeNull();
+    expect(plugin('Skills/GTM/heyreach-campaign')).toBeNull();
+    expect(plugin('Tools/NewsAgent/serper.tool')).toBeNull();
+    expect(plugin('access.md')).toBeNull();
+    expect(plugin('')).toBeNull();
   });
 
   it('is not fooled by a prefix match on the root name', () => {
-    expect(pluginOfPath('PluginsOld/GTM/x')).toBeNull();
+    expect(plugin('PluginsOld/GTM/x')).toBeNull();
   });
 
   it('tolerates leading and doubled separators', () => {
-    expect(pluginOfPath(`/${PLUGINS_DIR}/GTM/x`)).toBe('GTM');
-    expect(pluginOfPath(`${PLUGINS_DIR}//GTM//x`)).toBe('GTM');
+    expect(plugin(`/${PLUGINS_DIR}/GTM/x`)).toBe('GTM');
+    expect(plugin(`${PLUGINS_DIR}//GTM//x`)).toBe('GTM');
   });
 });