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

package/src/modules/workflow/workflow.service.ts

@@ -43,6 +43,7 @@ import type {
   ChangeRequestApplyFailureKind,
   ChangeRequestComment,
   ChangeRequestDetail,
+  ChangeRequestUpdateResult,
   ChangeRequestState,
   ChangedFile,
   FileApproval,
@@ -57,16 +58,16 @@ import type {
   RemoteSyncPullResult,
 } from '@bevel-software/platform-shared';
 import {
-  isProtectedBranch,
-  DEFAULT_BRANCH,
   isFolderPlaceholder,
   folderPlaceholderPath,
   isPlatformRestoreShape,
 } from '@bevel-software/platform-shared';
-import { and, eq, inArray, isNotNull, isNull, lt, or } from 'drizzle-orm';
+import type { KbContext } from '../../shared/kb-context.js';
+import { and, desc, eq, inArray, isNotNull, isNull, lt, ne, or } from 'drizzle-orm';
 import type { Database } from '../database/connection.js';
 import { changeRequests } from '../database/schema.js';
 import type { GitService } from './git/git.service.js';
+import { redactSecret } from '../../shared/redact-secret.js';
 import type { PullRequestService } from './git/pull-request.service.js';
 import type { IReviewWorkflowService } from './review-workflow/review-workflow.interface.js';
 import type { WorkspaceService } from '../workspace/workspace.service.js';
@@ -156,12 +157,13 @@ export function syncConflictMessage(branch: string, conflictedPaths: string[]):
 /** How many conflicted files the sync-conflict sentence names before "and N more". */
 const SYNC_CONFLICT_FILES_NAMED = 3;
 
-/** Redact the shared GitHub token from any error string before surfacing it. */
-function redactTokens(msg: string): string {
-  const tokens = [process.env.GITHUB_TOKEN, process.env.GH_TOKEN].filter(
-    (t): t is string => !!t && t.length > 0,
-  );
-  return tokens.reduce((m, t) => m.replaceAll(t, '***'), msg);
+/**
+ * Redact a git token from an error string before surfacing it: the one the
+ * knowledge base's runner authenticates with, plus whatever the environment
+ * holds (`redactSecret` names those itself).
+ */
+function redactTokens(msg: string, token: string | null | undefined): string {
+  return redactSecret(msg, [token]);
 }
 
 /**
@@ -275,6 +277,10 @@ export class WorkflowService implements IWorkflowService {
    * implementation detail of the workflow auto-merge story; nothing outside
    * the facade should call it directly.
    */
+  private get kbDirName(): string {
+    return this.kb.kbDirName;
+  }
+
   constructor(
     private readonly db: Database,
     private readonly git: GitService,
@@ -291,7 +297,7 @@ export class WorkflowService implements IWorkflowService {
      * See `lock-decoupling-plan.md` for the full design.
      */
     private readonly pendingCommits: PendingCommitsService,
-    private readonly kbDirName: string,
+    private readonly kb: KbContext,
     /**
      * The read-before-write gate `acquireLock` asks on every branch (see
      * `access-model/change-gate.ts`). Required, and checked at construction:
@@ -419,7 +425,7 @@ export class WorkflowService implements IWorkflowService {
     fn: () => Promise<T>,
   ): Promise<T> {
     const keys = [`branch:${source}`];
-    if (!isProtectedBranch(target)) keys.push(`branch:${target}`);
+    if (!this.kb.isProtectedBranch(target)) keys.push(`branch:${target}`);
     return this.branchLifecycle.runAll(keys, fn);
   }
 
@@ -571,10 +577,14 @@ export class WorkflowService implements IWorkflowService {
    * and nothing else. The pull itself reports the change, since it is the
    * only code that can observe it under the workspace mutex.
    */
-  private async pullWorkspace(workspaceId: string): Promise<boolean> {
-    const { treeChanged } = await this.git.pull(workspaceId);
-    if (treeChanged && branchForWorkspaceId(workspaceId) === DEFAULT_BRANCH) {
-      this.events?.emit({ kind: 'fs-tree-changed', workspaceId, branch: DEFAULT_BRANCH });
+  private async pullWorkspace(
+    workspaceId: string,
+    opts: { preserveMerges?: boolean } = {},
+  ): Promise<boolean> {
+    const { treeChanged } = await this.git.pull(workspaceId, opts);
+    const defaultBranch = this.kb.defaultBranch;
+    if (treeChanged && branchForWorkspaceId(workspaceId) === defaultBranch) {
+      this.events?.emit({ kind: 'fs-tree-changed', workspaceId, branch: defaultBranch });
       return true;
     }
     return false;
@@ -961,7 +971,7 @@ export class WorkflowService implements IWorkflowService {
     // future caller can make that claim by passing a flag.
     if (
       typeof platformRestore?.source === 'string' &&
-      isPlatformRestoreShape(toRepoRelative(platformRestore.source), repoRelative) &&
+      isPlatformRestoreShape(toRepoRelative(platformRestore.source), repoRelative, this.kb.layout) &&
       (await this.accessControl.canRestorePlatformFile(workspaceId, userEmail, repoRelative))
     ) {
       return 'restore';
@@ -1037,7 +1047,7 @@ export class WorkflowService implements IWorkflowService {
     // coordination hold as write possession (see those methods).
     if (!opts?.coordination) {
       let via: 'granted' | 'restore' = 'granted';
-      if (isProtectedBranch(branch)) {
+      if (this.kb.isProtectedBranch(branch)) {
         // `assertCanWriteAtPath` throws AccessDeniedError on denial, with the
         // eligible-writers payload so the frontend can render a useful refusal.
         via = await this.assertCanWriteAtPath(
@@ -1321,7 +1331,8 @@ export class WorkflowService implements IWorkflowService {
     branch: string,
     targetPath: string,
     user: AuthUser,
-    opts?: { systemAuthorized?: boolean; skipValidation?: boolean },
+    /** `summary` overrides the path-derived commit subject; see `commitFile`. */
+    opts?: { systemAuthorized?: boolean; skipValidation?: boolean; summary?: string },
   ): Promise<void> {
     // `skipValidation` is the worker telling us this commit is not the last of
     // a burst. The validator is advisory — it parses the whole KB to produce a
@@ -1332,7 +1343,7 @@ export class WorkflowService implements IWorkflowService {
       workspaceId,
       user,
       targetPath,
-      undefined,
+      opts?.summary,
       opts?.skipValidation,
     );
     if (!change) {
@@ -1722,6 +1733,38 @@ export class WorkflowService implements IWorkflowService {
     return this.prs.getPr(number);
   }
 
+  /**
+   * The newest non-open change request from `sourceBranch` by `authorEmail`.
+   *
+   * Read straight off `change_requests` rather than through the PR listing,
+   * which serves OPEN requests only: the whole point here is the closed ones.
+   * `author_email` is stored lowercased at insert, so the needle is too.
+   * Ordered by `closed_at` with `created_at` as the tiebreak, because a row
+   * closed before the column existed (or by a path that forgot to stamp it)
+   * still has a creation time and must not sort as the oldest.
+   */
+  async latestClosedChangeRequest(
+    authorEmail: string,
+    sourceBranch: string,
+  ): Promise<{ number: number; state: ChangeRequestState } | null> {
+    const email = authorEmail.trim().toLowerCase();
+    if (!email || !sourceBranch) return null;
+    const [row] = await this.db
+      .select({ number: changeRequests.number, state: changeRequests.state })
+      .from(changeRequests)
+      .where(
+        and(
+          eq(changeRequests.authorEmail, email),
+          eq(changeRequests.sourceBranch, sourceBranch),
+          ne(changeRequests.state, 'open'),
+        ),
+      )
+      .orderBy(desc(changeRequests.closedAt), desc(changeRequests.createdAt))
+      .limit(1);
+    if (!row) return null;
+    return { number: row.number, state: row.state as ChangeRequestState };
+  }
+
   getChangeRequestDetail(
     number: number,
     opts?: { fresh?: boolean; workspaceId?: string; viewerEmail?: string; patches?: boolean },
@@ -1759,7 +1802,7 @@ export class WorkflowService implements IWorkflowService {
       throw new WorkflowValidationError('source and target branches must differ');
     }
     if (!input.title?.trim()) throw new WorkflowValidationError('title is required');
-    if (isProtectedBranch(input.sourceBranch)) {
+    if (this.kb.isProtectedBranch(input.sourceBranch)) {
       throw new WorkflowValidationError(
         `Cannot open a change request *from* a protected branch ("${input.sourceBranch}").`,
         { kind: 'source-is-protected', sourceBranch: input.sourceBranch },
@@ -1897,7 +1940,7 @@ export class WorkflowService implements IWorkflowService {
       // up-to-date) auto-merge, and inserts the row.
       const rawMsg = err instanceof Error ? err.message : String(err);
       throw new WorkflowValidationError(
-        `Failed to open change request: ${redactTokens(rawMsg)}`,
+        `Failed to open change request: ${redactTokens(rawMsg, this.git.credentials?.token())}`,
         { kind: 'open-change-request-failed' },
       );
     }
@@ -1946,13 +1989,29 @@ export class WorkflowService implements IWorkflowService {
    * the enforcement read one predicate. A conflicting merge is aborted
    * inside `mergeFromOrigin`: nothing is committed or pushed, and the branch
    * is exactly what it was.
+   *
+   * ONE detail read after the merge. The read before it exists only to
+   * decide authority and to name the two branches, so it asks for no patches
+   * — that is one git subprocess per changed file it does not spend. The
+   * approvals carry-forward runs BEFORE the final read rather than after it,
+   * against a head resolved with `resolvePrShas` (two rev-parses) instead of
+   * a whole second detail, so the detail that goes back already describes the
+   * approvals it carried. What used to be three detail reads is now one.
    */
   async updateFromTarget(
     workspaceId: string,
     user: AuthUser,
     number: number,
-  ): Promise<ChangeRequestDetail> {
-    const detail = await this.prs.getPrDetail(number, { fresh: true, workspaceId, viewerEmail: user.email });
+  ): Promise<ChangeRequestUpdateResult> {
+    // No patches: all this read decides is authority, state and the two
+    // branch names. Asking for patch text here would diff every changed file
+    // in a request that is about to be merged and read in full anyway.
+    const detail = await this.prs.getPrDetail(number, {
+      fresh: true,
+      workspaceId,
+      viewerEmail: user.email,
+      patches: false,
+    });
     if (!detail) {
       throw new WorkflowValidationError(
         `Change request #${number} not found.`,
@@ -1980,8 +2039,15 @@ export class WorkflowService implements IWorkflowService {
     // merge commit that then cannot push, stranding it in the workspace. A
     // rebase conflict hands the stranded saves to recovery, as every other
     // pull does, before the refusal reaches the caller.
+    //
+    // `preserveMerges`: this is the one pull whose unpushed commit may be a
+    // MERGE — the update that ran before this one and could not push. A plain
+    // rebase replays it as cherry-picks of the target's commits, which drops
+    // the target as a parent, so the branch never contains the target's head
+    // however many times the update runs. Replayed with `--rebase-merges` it
+    // stays a merge and the next push ends the loop.
     try {
-      await this.pullWorkspace(workspaceId);
+      await this.pullWorkspace(workspaceId, { preserveMerges: true });
     } catch (err) {
       if (err instanceof PullRebaseConflictError) {
         await this.queuePullConflictRecovery(workspaceId, err, user);
@@ -2019,24 +2085,53 @@ export class WorkflowService implements IWorkflowService {
     if (outcome.kind === 'conflicts') {
       throw new ChangeRequestConflictsError(detail.branch, detail.base, outcome.paths);
     }
-    // If a new merge commit landed, push so the CR picks it up. When
-    // already up to date there's nothing to share — short-circuit the push.
-    if (!outcome.alreadyUpToDate) {
+    // Push whenever the CLONE holds a commit origin has not seen — not when
+    // THIS merge authored one. The two differ in exactly the case that keeps
+    // a request behind for good: an earlier update merged, its push failed,
+    // and the merge is sitting in the workspace. That merge already contains
+    // the target, so this call's `mergeFromOrigin` reports
+    // `alreadyUpToDate` and the old gate skipped the push — leaving the
+    // request behind on the remote, and the next open with the same work to
+    // do. Asking git what is unpushed retries it instead.
+    //
+    // A failed probe falls back to the old gate rather than to "push
+    // anyway": `trackedPush` on a clone with nothing to push is a wasted
+    // round trip on every single update.
+    const hasUnpushed = await this.git
+      .hasUnpushedCommits(workspaceId)
+      .catch((err: unknown) => {
+        log.warn(
+          `could not tell whether change request #${number} has unpushed commits; falling back to whether this merge authored one`,
+          { err },
+        );
+        return !outcome.alreadyUpToDate;
+      });
+    if (hasUnpushed) {
       await this.trackedPush(workspaceId, user);
-      // The source head moved: the refusal described a revision that is gone.
-      await this.clearApplyFailure(number, { recordedBefore: headMovedAfter });
     }
-    this.prs.invalidateDetailCache(number);
-    const refreshed = await this.prs.getPrDetail(number, {
-      fresh: true,
-      workspaceId,
-      viewerEmail: user.email,
-    });
-    if (!refreshed) {
-      throw new WorkflowValidationError(
-        `Refreshed change request #${number} but could not re-fetch its detail.`,
+    // Where the branch ended up, as PUBLISHED — two rev-parses, not a second
+    // detail read. Everything below needs only the sha, and the detail that
+    // goes back to the caller is read once, at the end, after the approvals
+    // it should describe have been carried.
+    let headAfterMerge = headBeforeMerge;
+    try {
+      const at = await this.git.resolvePrShas(workspaceId, detail.base, detail.branch);
+      headAfterMerge = at.headSha;
+    } catch (err) {
+      log.warn(
+        `could not resolve the published head of change request #${number} after updating it from target`,
+        { err },
       );
     }
+    const headMoved = Boolean(headBeforeMerge) && headAfterMerge !== headBeforeMerge;
+    // The source head moved: the refusal described a revision that is gone.
+    // `hasUnpushed` counts as well as the sha comparison, and deliberately —
+    // a push that just landed moved the published head by definition, and
+    // reading the sha to confirm it is a call that can fail. A refusal left
+    // standing over a revision nobody can apply any more is the worse error.
+    if (headMoved || hasUnpushed) {
+      await this.clearApplyFailure(number, { recordedBefore: headMovedAfter });
+    }
     // The merge is a commit the APPROVERS did not make. Re-pin their
     // approvals onto the new head for every file whose bytes it left alone —
     // git's own two-dot diff between the two heads is the verdict on which
@@ -2044,45 +2139,61 @@ export class WorkflowService implements IWorkflowService {
     // than the bookkeeping, so a failure here is logged and the fresh detail
     // still goes back.
     //
-    // `alreadyUpToDate` is the real gate: no merge commit, no head to compare,
-    // nothing moved under anyone. The other two conditions are belt-and-braces
-    // over a sha that is not a sha — a resolve that failed onto a detail with
-    // no head, or two heads that somehow read equal — both of which
-    // `pathsChangedBetween` and `carryApprovalsForward` would refuse anyway.
-    // A merge that authored a commit cannot leave the head where it was.
-    if (!outcome.alreadyUpToDate && headBeforeMerge && refreshed.headSha !== headBeforeMerge) {
+    // The head moving is the real gate: nothing moved, nothing moved under
+    // anyone. It also covers the sha that is not a sha — a resolve that
+    // failed onto a detail with no head — which `pathsChangedBetween` and
+    // `carryApprovalsForward` would refuse anyway.
+    //
+    // This runs BEFORE the detail read, not after it. The rows it writes are
+    // what the caller's `approvals` must describe, so doing it first means
+    // the one read at the end is already correct — where carrying afterwards
+    // needed a THIRD read to correct a detail assembled before the rows
+    // existed.
+    //
+    // The same list answers the caller's `updatedPaths`: "which files did
+    // this merge change" is one question, and the two answers must not be
+    // allowed to differ — a file whose approval was carried (so: untouched)
+    // that the dialog then re-read would be the dialog discarding content the
+    // server just called unchanged.
+    let updatedPaths: string[] = [];
+    if (headMoved) {
       try {
-        const changedPaths = await this.git.pathsChangedBetween(
+        updatedPaths = await this.git.pathsChangedBetween(
           workspaceId,
           headBeforeMerge,
-          refreshed.headSha,
+          headAfterMerge,
         );
-        const carried = await this.reviewWorkflow.carryApprovalsForward(
+        await this.reviewWorkflow.carryApprovalsForward(
           number,
           headBeforeMerge,
-          refreshed.headSha,
-          changedPaths,
+          headAfterMerge,
+          updatedPaths,
         );
-        // The detail above was assembled before those rows existed, so its
-        // `approvals` (and the merge gate derived from them) still describe
-        // the pre-merge head. Only re-read when something actually carried.
-        if (carried > 0) {
-          this.prs.invalidateDetailCache(number);
-          const withApprovals = await this.prs.getPrDetail(number, {
-            fresh: true,
-            workspaceId,
-            viewerEmail: user.email,
-          });
-          if (withApprovals) return withApprovals;
-        }
       } catch (err) {
         log.warn(
           `could not carry approvals forward on change request #${number} after updating from target`,
           { err },
         );
+        // The diff is what failed, so which files moved is unknown. Say so as
+        // "every file this request had", which is every file a caller can
+        // already be showing: slow beats a dialog that goes on presenting
+        // pre-merge text as current. Anything the merge ADDED is not on the
+        // list and does not need to be — no caller has read it yet.
+        updatedPaths = (detail.files ?? []).map((f) => f.path);
       }
     }
-    return refreshed;
+    this.prs.invalidateDetailCache(number);
+    const refreshed = await this.prs.getPrDetail(number, {
+      fresh: true,
+      workspaceId,
+      viewerEmail: user.email,
+    });
+    if (!refreshed) {
+      throw new WorkflowValidationError(
+        `Refreshed change request #${number} but could not re-fetch its detail.`,
+      );
+    }
+    return { ...refreshed, updatedPaths };
   }
 
   listComments(number: number): Promise<ChangeRequestComment[]> {
@@ -2644,11 +2755,16 @@ export class WorkflowService implements IWorkflowService {
   /**
    * DELETE a change request outright: close it (whatever its diff says) and
    * retire its source branch — the request, its proposal, and the branch that
-   * carried it are gone in one verb. Admin-only, resolved the same way every
-   * other admin check here is (write on `roles.yaml` at `origin/<base>`,
-   * never a local ref): this is the moderation verb for a shared deployment,
-   * stronger than reject (which the author or the files' owners can do, and
-   * which leaves the branch for a second round).
+   * carried it are gone in one verb. The request's AUTHOR or an admin, and
+   * nobody else: it is the author's own proposal and their own branch to throw
+   * away, and it is the moderation verb for a shared deployment. Admin rights
+   * resolve the same way every other admin check here does (write on
+   * `roles.yaml` at `origin/<base>`, never a local ref); authorship is the
+   * STORED `authorId` hash, never anything the caller sends.
+   *
+   * Stronger than reject, which the changed files' owners may also do and which
+   * leaves the branch for a second round. They keep reject and do not get this:
+   * an owner must not be able to destroy someone else's text and branch.
    */
   async deleteChangeRequest(number: number, user: AuthUser): Promise<void> {
     const summary = await this.prs.getPr(number);
@@ -2707,8 +2823,17 @@ export class WorkflowService implements IWorkflowService {
         409,
       );
     }
-    if (isAdmin !== true) {
-      throw new WorkflowDomainError('Only an admin can delete a change request.', 403);
+    // Authorship is decided from the STORED author hash, never from anything
+    // the caller sends. Note what is deliberately NOT short-circuited for an
+    // author: the strict fetch and the `null` check above still run. An
+    // author's grant needs no `roles.yaml` read, so skipping them would look
+    // free — but it would let a delete close the request while the branch
+    // removal silently failed against an unreachable origin, and "the shared
+    // repository was down, so nothing changed" is the one refusal that has to
+    // stay honest.
+    const callerIsAuthor = !!(summary.authorId && summary.authorId === hashEmail(user.email));
+    if (!callerIsAuthor && isAdmin !== true) {
+      throw new WorkflowDomainError("Only the request's author or an admin can delete it.", 403);
     }
 
     // Close first (idempotent: an already-closed request just skips to the
@@ -2851,7 +2976,7 @@ export class WorkflowService implements IWorkflowService {
 
     let live: Set<string>;
     try {
-      const branches = await this.git.listBranches(workspaceIdForBranch(DEFAULT_BRANCH), {
+      const branches = await this.git.listBranches(this.kb.defaultWorkspaceId(), {
         freshFetch: true,
         // The list is used to PROVE absence, and the listing's normal
         // degrade-to-stale behaviour would report every branch created since
@@ -3166,8 +3291,8 @@ export class WorkflowService implements IWorkflowService {
     // outright if it disagrees with the request's own base.) The failure the
     // pull reports is about OTHER people's commits not arriving, which leaves
     // the catalogs no staler than they were.
-    if (!announced && targetWorkspaceId && targetBranch === DEFAULT_BRANCH) {
-      this.events?.emit({ kind: 'fs-tree-changed', workspaceId: targetWorkspaceId, branch: DEFAULT_BRANCH });
+    if (!announced && targetWorkspaceId && targetBranch === this.kb.defaultBranch) {
+      this.events?.emit({ kind: 'fs-tree-changed', workspaceId: targetWorkspaceId, branch: targetBranch });
     }
   }
 
@@ -3234,7 +3359,7 @@ export class WorkflowService implements IWorkflowService {
           // change request's merge, nothing strips it here — so its presence
           // is what the hook refuses on) and both sides of a rename, since the
           // old name is a file this merge deletes.
-          authorize: isProtectedBranch(targetBranch)
+          authorize: this.kb.isProtectedBranch(targetBranch)
             ? async ({ sha, changedPaths }) => {
                 if (changedPaths.length === 0) return;
                 // roles.yaml never changes through a merge. A change request's
@@ -3445,7 +3570,7 @@ export class WorkflowService implements IWorkflowService {
         .where(eq(changeRequests.number, number))
         .limit(1);
       const sourceBranch = rows[0]?.sourceBranch;
-      if (!sourceBranch || isProtectedBranch(sourceBranch)) return;
+      if (!sourceBranch || this.kb.isProtectedBranch(sourceBranch)) return;
       // The open-check and the deletion hold the branch's lifecycle lock
       // TOGETHER — `openChangeRequest` holds the same lock across its own
       // check-then-insert, so a request being opened from this branch either
@@ -3620,7 +3745,7 @@ export class WorkflowService implements IWorkflowService {
       return stdout.split('\n').map((s) => s.trim()).filter(Boolean);
     } catch (err) {
       log.warn('listChangedPathsBetweenBranches failed:', {
-        detail: redactTokens(err instanceof Error ? err.message : String(err)),
+        detail: redactTokens(err instanceof Error ? err.message : String(err), this.git.credentials?.token()),
       });
       return [];
     }

package/src/modules/workspace/__tests__/file-stat-access.test.ts

@@ -4,6 +4,7 @@ import { tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
 import express from 'express';
 import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 import { LocalFilesystem } from '@mastra/core/workspace';
 import { ToolRegistry } from '../../tool-registry/tool-registry.js';
 import { createToolHandlerFactory } from '../../tool-helpers/tool-handler.js';
@@ -86,8 +87,8 @@ beforeAll(async () => {
     new SpillStore(join(tmpdir(), 'bevel-test-spills')),
     new DocExtractService(docCache),
     service,
-    KB,
-    { service: {} as never, enabled: false, kbDirName: KB, recoveryBotEmail: 'recovery-bot@bevel.local', hooks: new WorkflowHooks() },
+    testKbContext({ kbDirName: KB }),
+    { service: {} as never, enabled: false, kb: testKbContext({ kbDirName: KB }), recoveryBotEmail: 'recovery-bot@bevel.local', hooks: new WorkflowHooks() },
     new RoutineWritePolicyService(),
     {} as never,
   );

package/src/modules/workspace/__tests__/git-internals.security.test.ts

@@ -6,6 +6,7 @@ import { join } from 'node:path';
 import AdmZip from 'adm-zip';
 import express from 'express';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 import type { IWorkflowService } from '@bevel-software/platform-shared';
 import { GIT_INTERNALS_MESSAGE, GitInternalsError } from '../../../shared/domain-errors.js';
 import { workspaceIdForBranch } from '../../../shared/workspace-id.js';
@@ -241,7 +242,7 @@ describe('workspace tools refuse the git folder', () => {
 
   beforeEach(async () => {
     workflow = makeWorkflow();
-    const service = new WorkspaceService(root, 'https://example.invalid/kb.git', KB, new NodeFs());
+    const service = new WorkspaceService(root, 'https://example.invalid/kb.git', testKbContext({ kbDirName: KB }), new NodeFs());
     unzipSpy = vi.spyOn(service, 'unzipFile');
     bootstrappedSpy = vi.spyOn(service, 'hasBootstrappedWorkspace');
     const lockingFs = new LockingFilesystem(
@@ -275,8 +276,8 @@ describe('workspace tools refuse the git folder', () => {
       new SpillStore(join(root, 'spills')),
       new DocExtractService(join(root, 'doc-cache')),
       allowAll,
-      KB,
-      { service: {} as never, enabled: false, kbDirName: KB, recoveryBotEmail: 'recovery-bot@bevel.local', hooks: new WorkflowHooks() },
+      testKbContext({ kbDirName: KB }),
+      { service: {} as never, enabled: false, kb: testKbContext({ kbDirName: KB }), recoveryBotEmail: 'recovery-bot@bevel.local', hooks: new WorkflowHooks() },
       new RoutineWritePolicyService(),
       {} as never,
     );
@@ -416,7 +417,7 @@ describe('workspace routes refuse the git folder', () => {
 
   beforeEach(async () => {
     workflow = makeWorkflow();
-    service = new WorkspaceService(root, 'https://example.invalid/kb.git', KB, new NodeFs());
+    service = new WorkspaceService(root, 'https://example.invalid/kb.git', testKbContext({ kbDirName: KB }), new NodeFs());
     const app = express();
     app.use(express.json());
     app.use('/api', (req, _res, next) => {
@@ -436,7 +437,7 @@ describe('workspace routes refuse the git folder', () => {
         workflow as unknown as IWorkflowService,
         { emit: vi.fn() } as unknown as WorkflowEventBus,
         allowAll,
-        KB,
+        testKbContext({ kbDirName: KB }),
         stubCreatorAccess,
         { isAdmin: async () => true } as unknown as IAdminAccessService,
         new NodeFs(),
@@ -563,7 +564,7 @@ describe('WorkspaceService refuses the git folder on its own', () => {
   let service: WorkspaceService;
 
   beforeEach(() => {
-    service = new WorkspaceService(root, 'https://example.invalid/kb.git', KB, new NodeFs());
+    service = new WorkspaceService(root, 'https://example.invalid/kb.git', testKbContext({ kbDirName: KB }), new NodeFs());
   });
 
   afterEach(async () => {
@@ -620,7 +621,7 @@ describe('WorkspaceService refuses the git folder on its own', () => {
         return { stdout: '.git\n', stderr: '', code: 0 };
       }),
     };
-    const refService = new WorkspaceService(root, 'https://example.invalid/kb.git', KB, new NodeFs(), 'x-access-token', gitRunner as never);
+    const refService = new WorkspaceService(root, 'https://example.invalid/kb.git', testKbContext({ kbDirName: KB }), new NodeFs(), gitRunner as never);
 
     for (const [form, raw] of Object.entries(fileForms('config'))) {
       if (!form.startsWith('symlinked')) continue;
@@ -674,7 +675,7 @@ describe('the route guard on its own', () => {
   beforeEach(async () => {
     reached = 0;
     userId = USER.id;
-    const service = new WorkspaceService(root, 'https://example.invalid/kb.git', KB, new NodeFs());
+    const service = new WorkspaceService(root, 'https://example.invalid/kb.git', testKbContext({ kbDirName: KB }), new NodeFs());
     const app = express();
     // The server's own order: the guard ahead of the body parser, then again
     // on the parsed body, then again once the caller is known.
@@ -774,7 +775,7 @@ describe('DiffService refuses the git folder on its own', () => {
   let diffService: DiffService;
 
   beforeEach(() => {
-    const service = new WorkspaceService(root, 'https://example.invalid/kb.git', KB, new NodeFs());
+    const service = new WorkspaceService(root, 'https://example.invalid/kb.git', testKbContext({ kbDirName: KB }), new NodeFs());
     diffService = new DiffService(service, new WorkspaceMutex(), root, join(root, 'backups'), KB, new NodeFs());
   });
 

package/src/modules/workspace/__tests__/session-ontology.gate.test.ts

@@ -11,8 +11,10 @@ import type { ToolContext } from '../../tool-helpers/tool.contract.js';
 import type { ISessionOntologyService, OperationDecision } from '../../workflow/session-ontology.service.js';
 import { WorkflowHooks } from '../../workflow/workflow-hooks.js';
 import { ontologyOf } from '../../../shared/kb-layout.js';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 
 const KB = 'knowledge-base';
+const kbContext = testKbContext({ kbDirName: KB });
 const P_FILE = 'KnowledgeBase/Product/Knowledge/Foo.md';
 const PL_FILE = 'KnowledgeBase/Platform/Knowledge/Bar.md';
 const NEUTRAL = 'access.md';
@@ -28,7 +30,7 @@ function makeFakeService(): ISessionOntologyService {
   const setFor = (s: string) => touched.get(s) ?? new Set<string>();
   return {
     async checkOperation(sessionId, wsPath, isWrite): Promise<OperationDecision> {
-      const ont = ontologyOf(wsPath, KB);
+      const ont = ontologyOf(wsPath, kbContext.layout, KB);
       const set = setFor(sessionId);
       if (ont === null) return { allow: true, touched: [...set].sort() };
       if (isWrite) {
@@ -63,7 +65,7 @@ function makeFakeService(): ISessionOntologyService {
 function makeGate(): SessionOntologyGate {
   const service = makeFakeService();
   const hooks = new WorkflowHooks();
-  return { service, enabled: true, kbDirName: KB, recoveryBotEmail: RECOVERY_EMAIL, hooks };
+  return { service, enabled: true, kb: kbContext, recoveryBotEmail: RECOVERY_EMAIL, hooks };
 }
 
 function ctx(overrides: Partial<ToolContext> = {}): ToolContext {

package/src/modules/workspace/__tests__/workspace-paths-inside-the-repo.test.ts

@@ -7,6 +7,7 @@ import { fileURLToPath } from 'node:url';
 import AdmZip from 'adm-zip';
 import express from 'express';
 import { describe, it, expect, afterEach, vi } from 'vitest';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 import type { IWorkflowService } from '@bevel-software/platform-shared';
 import { NodeFs } from '../../kb-fs/node-fs.js';
 import type { IAccessControl } from '../../access/access-control.interface.js';
@@ -55,7 +56,7 @@ async function makeHarness(): Promise<Harness> {
   const workspaceDir = path.join(root, workspaceId);
   // The inner `.git` lets the service accept the workspace without cloning.
   await fs.mkdir(path.join(workspaceDir, KB, '.git'), { recursive: true });
-  const workspaceService = new WorkspaceService(root, 'https://example.invalid/kb.git', KB, new NodeFs());
+  const workspaceService = new WorkspaceService(root, 'https://example.invalid/kb.git', testKbContext({ kbDirName: KB }), new NodeFs());
   await workspaceService.getWorkspacePath(workspaceId);
 
   const asked: string[] = [];
@@ -102,7 +103,7 @@ async function makeHarness(): Promise<Harness> {
       workflowService,
       { emit: vi.fn() } as unknown as WorkflowEventBus,
       accessControl,
-      KB,
+      testKbContext({ kbDirName: KB }),
       stubCreatorAccess,
       { isAdmin: async () => false } as unknown as IAdminAccessService,
       new NodeFs(),

package/src/modules/workspace/__tests__/workspace.routes.branch-errors.test.ts

@@ -2,6 +2,7 @@ import type { Server } from 'node:http';
 import type { AddressInfo } from 'node:net';
 import express from 'express';
 import { describe, it, expect, afterEach, vi } from 'vitest';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 import { NodeFs } from '../../kb-fs/node-fs.js';
 import type { FileTreeEntry, IWorkflowService } from '@bevel-software/platform-shared';
 import type { IAccessControl } from '../../access/access-control.interface.js';
@@ -55,7 +56,7 @@ async function makeHarness(
     {} as unknown as IWorkflowService,
     { emit: vi.fn() } as unknown as WorkflowEventBus,
     accessControl,
-    'knowledge-base',
+    testKbContext(),
     stubCreatorAccess,
     { isAdmin: async () => false } as unknown as IAdminAccessService,
     new NodeFs(),