@bevel-software/platform-core-backend 0.20.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}`);
         }
@@ -1255,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

@@ -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,
@@ -871,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);
@@ -934,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`. */
@@ -1181,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(),
@@ -1199,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 —
@@ -1250,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,
             );
           }
@@ -1432,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.' +
@@ -2042,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',
@@ -2262,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__/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');
   });
 });

package/src/shared/git.contract.ts

@@ -39,21 +39,76 @@
  */
 
 /**
- * Strip the configured git token out of text on its way into an error, a log
- * line or a response.
+ * The credential git authenticates a knowledge base's remote with: the
+ * Basic-auth username the host expects and the token that is its password.
+ *
+ * A PROVIDER, read at every call, not a value captured at boot: the setup
+ * screen can supply a token after the graph is built, and a token rotated in
+ * the settings has to be the one the next push carries. The runner puts the
+ * token into the child's environment under {@link GIT_TOKEN_ENV}, which is
+ * the only place git reads it from (the inline credential helper spells
+ * `password=$GITHUB_TOKEN`), so the value never enters argv, a clone's
+ * config, or a message that quotes either. Nothing writes it into THIS
+ * process's environment: a server hosting several knowledge bases has one
+ * environment and several tokens.
+ */
+export interface GitCredentials {
+  /**
+   * The username sent in the Basic credential: GitHub `x-access-token`,
+   * GitLab `oauth2`, Bitbucket `x-token-auth`. Interpolated into the helper
+   * snippet, so callers validate it against `[A-Za-z0-9._-]+` before it
+   * gets here.
+   */
+  username(): string;
+  /** The token in effect, or null when the deployment has none configured. */
+  token(): string | null;
+}
+
+/** The username git is given when a deployment names none. */
+export const DEFAULT_GIT_USERNAME = 'x-access-token';
+
+/**
+ * The environment variable the child git process reads the token from. The
+ * name is historical (the first supported host), and it is the literal every
+ * app-stamped credential helper carries, which is what lets a re-stamp find
+ * its own helpers in a clone's config and leave an operator's alone.
+ */
+export const GIT_TOKEN_ENV = 'GITHUB_TOKEN';
+
+/** No token, the default username: an unauthenticated runner. */
+export const NO_GIT_CREDENTIALS: GitCredentials = Object.freeze({
+  username: () => DEFAULT_GIT_USERNAME,
+  token: () => null,
+});
+
+/** A provider from values or thunks, for a composition root or a test. */
+export function gitCredentials(
+  username: string | (() => string) = DEFAULT_GIT_USERNAME,
+  token: string | null | (() => string | null) = null,
+): GitCredentials {
+  const user = typeof username === 'function' ? username : () => username;
+  const secret = typeof token === 'function' ? token : () => token;
+  return {
+    username: () => user() || DEFAULT_GIT_USERNAME,
+    token: () => secret() || null,
+  };
+}
+
+/**
+ * Strip a git token out of text on its way into an error, a log line or a
+ * response.
  *
  * git puts the remote URL into a great many of its messages, and on a
  * token-authenticated remote that URL carries the credential. Without this, a
  * push failure writes the deployment's token into the container log, the API
  * response, and any change request the recovery agent opens about it.
  *
- * Read from the environment at call time rather than captured: the setup screen
- * can supply a token after boot, and `DeploymentSettingsService.syncGitTokenEnv`
- * puts it here — a value captured at module load would be the empty string for
- * exactly the deployments that configure their token that way.
+ * The token is the caller's to name (the runner names its own), never read
+ * from this process's environment: the environment holds no per-knowledge-
+ * base token any more, and a scrub that silently found none there would look
+ * like one that worked.
  */
-export function redactGitToken(text: string): string {
-  const token = process.env.GITHUB_TOKEN;
+export function redactGitToken(text: string, token: string | null | undefined): string {
   const scrubbed = token ? text.replaceAll(token, '***') : text;
   // URL userinfo as well: a remote spelled `https://user:pass@host` would
   // otherwise leak `pass` verbatim through every git failure that quotes the
@@ -165,6 +220,13 @@ export interface IGitRunner {
    * constant.
    */
   readonly defaultTimeoutMs: number;
+  /**
+   * The credential every call through this runner authenticates with — see
+   * {@link GitCredentials}. Exposed so the code that stamps a clone's helper
+   * or scrubs a message can ask the same runner it runs git through whether
+   * a token is in effect, rather than a second source that could disagree.
+   */
+  readonly credentials: GitCredentials;
   run(cwd: string, args: string[], opts: GitRunOptions & { encoding: 'buffer' }): Promise<GitRunResult<Buffer>>;
   run(cwd: string, args: string[], opts?: GitRunOptions & { encoding?: 'utf8' }): Promise<GitRunResult>;
 }