@bevel-software/platform-core-backend 0.34.0 → 0.36.1

package/src/modules/kb-fs/__tests__/move-with-edits.test.ts

@@ -4,10 +4,10 @@ import { promisify } from 'node:util';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import os from 'node:os';
-import type { AuthUser, IWorkflowService } from '@bevel-software/platform-shared';
+import type { AuthUser, IVersionControlService } from '@bevel-software/platform-shared';
 import { testKbContext } from '../../../__tests__/kb-context.js';
-import { GitService } from '../../workflow/git/git.service.js';
-import { WorkflowHooks } from '../../workflow/workflow-hooks.js';
+import { GitService } from '../../version-control/git/git.service.js';
+import { VersionControlHooks } from '../../version-control/version-control-hooks.js';
 import type { WorkspaceService } from '../../workspace/workspace.service.js';
 import { LockingFilesystem, MoveLockedError, MoveRacedError, MoveUndoError } from '../locking-filesystem.js';
 import { PushNeedsAgentResolutionError } from '../../../shared/domain-errors.js';
@@ -34,7 +34,7 @@ async function git(cwd: string, args: string[]): Promise<string> {
 
 let root: string;
 let repo: string;
-let workflow: IWorkflowService;
+let versionControl: IVersionControlService;
 let lockedPaths: Set<string>;
 
 async function put(rel: string, content: string | Buffer): Promise<void> {
@@ -62,14 +62,14 @@ beforeEach(async () => {
   const svc = new GitService(
     { getWorkspacePath: async () => root } as unknown as WorkspaceService,
     (() => {
-      const hooks = new WorkflowHooks();
+      const hooks = new VersionControlHooks();
       hooks.onCommitValidation(vi.fn(async () => ({ ok: true, mustFix: [], warnings: [], rawOutput: '' })));
       return hooks;
     })(),
     testKbContext({ kbDirName: KB }),
   );
   lockedPaths = new Set();
-  workflow = {
+  versionControl = {
     acquireLock: vi.fn(async (_w: string, _b: string, p: string) =>
       lockedPaths.has(p)
         ? { acquired: false, lock: { holderName: 'Bob' } }
@@ -78,7 +78,7 @@ beforeEach(async () => {
     releaseLockNoCommit: vi.fn(async () => undefined),
     releaseLockUntouched: vi.fn(async () => undefined),
     commitChanges: vi.fn((w: string, u: AuthUser, s: string, paths?: string[]) => svc.commitChanges(w, u, s, paths)),
-  } as unknown as IWorkflowService;
+  } as unknown as IVersionControlService;
 });
 
 afterEach(async () => {
@@ -88,7 +88,7 @@ afterEach(async () => {
 const fsLayer = (validateWrite?: (p: string, content: unknown) => Promise<void>) =>
   new LockingFilesystem(
     { basePath: root, contained: true },
-    { workflow, workspaceId: WS, branch: 'feature-test', user: USER, kbDirName: KB, ...(validateWrite ? { validateWrite } : {}) },
+    { versionControl, workspaceId: WS, branch: 'feature-test', user: USER, kbDirName: KB, ...(validateWrite ? { validateWrite } : {}) },
   );
 
 /** The paths each release kind was called with. */
@@ -147,16 +147,16 @@ describe('LockingFilesystem.moveWithEdits', () => {
     expect((err as Error).message).toContain(`"${KB}/Projects/A/Two.md" is being edited by Bob`);
     expect(await git(repo, ['rev-parse', 'HEAD'])).toBe(head);
     expect((await git(repo, ['status', '--porcelain'])).trim()).toBe('');
-    expect(workflow.commitChanges).not.toHaveBeenCalled();
+    expect(versionControl.commitChanges).not.toHaveBeenCalled();
     // Every lock taken was given back untouched.
-    expect(released(workflow.releaseLockUntouched)).toEqual([`${KB}/Index.md`, `${KB}/Projects/A`, `${KB}/Projects/A/One.md`]);
-    expect(workflow.releaseLockNoCommit).not.toHaveBeenCalled();
-    expect(workflow.releaseLock).not.toHaveBeenCalled();
+    expect(released(versionControl.releaseLockUntouched)).toEqual([`${KB}/Index.md`, `${KB}/Projects/A`, `${KB}/Projects/A/One.md`]);
+    expect(versionControl.releaseLockNoCommit).not.toHaveBeenCalled();
+    expect(versionControl.releaseLock).not.toHaveBeenCalled();
     expect(await read('Index.md')).toBe('[one](Projects/A/One.md)\n');
   }, 20_000);
 
   it('a file saved into the folder while the locks were being taken refuses the move, nothing moved', async () => {
-    const acquire = workflow.acquireLock as ReturnType<typeof vi.fn>;
+    const acquire = versionControl.acquireLock as ReturnType<typeof vi.fn>;
     let arrived = false;
     acquire.mockImplementation(async () => {
       // The first lock is the moment somebody else's save lands in the folder.
@@ -171,15 +171,15 @@ describe('LockingFilesystem.moveWithEdits', () => {
     expect(err).toBeInstanceOf(MoveRacedError);
     expect((err as Error).message).toContain(`"${KB}/Projects/A/Late.md" was added`);
     expect(await git(repo, ['rev-parse', 'HEAD'])).toBe(head);
-    expect(workflow.commitChanges).not.toHaveBeenCalled();
+    expect(versionControl.commitChanges).not.toHaveBeenCalled();
     expect(await read('Projects/A/Late.md')).toBe('late\n');
     expect(await read('Index.md')).toBe('[one](Projects/A/One.md)\n');
-    expect(workflow.releaseLockNoCommit).not.toHaveBeenCalled();
-    expect(released(workflow.releaseLockUntouched).length).toBeGreaterThan(0);
+    expect(versionControl.releaseLockNoCommit).not.toHaveBeenCalled();
+    expect(released(versionControl.releaseLockUntouched).length).toBeGreaterThan(0);
   });
 
   it('a move that fails and cannot be undone releases every lock with the discard, and says both', async () => {
-    (workflow.commitChanges as ReturnType<typeof vi.fn>).mockImplementation(async () => {
+    (versionControl.commitChanges as ReturnType<typeof vi.fn>).mockImplementation(async () => {
       // Something takes the old place while the move is in flight, so the
       // undo's rename finds its destination occupied.
       await put('Projects/A/Taken.md', 'x\n');
@@ -190,8 +190,8 @@ describe('LockingFilesystem.moveWithEdits', () => {
     expect((err as Error).message).toContain('commit exploded');
     expect((err as Error).message).toContain('could not be undone');
     // Nothing is handed back as untouched: every path goes with the discard.
-    expect(workflow.releaseLockUntouched).not.toHaveBeenCalled();
-    const discarded = released(workflow.releaseLockNoCommit);
+    expect(versionControl.releaseLockUntouched).not.toHaveBeenCalled();
+    const discarded = released(versionControl.releaseLockNoCommit);
     expect(discarded).toContain(`${KB}/Projects/A`);
     expect(discarded).toContain(`${KB}/Topics/Deep/A/One.md`);
     expect(discarded).toContain(`${KB}/Index.md`);
@@ -199,8 +199,8 @@ describe('LockingFilesystem.moveWithEdits', () => {
 
   it('a commit that landed but could not be pushed enqueues the committed paths only; the folder locks go back untouched', async () => {
     // The real commit lands; only its push is refused.
-    const commit = (workflow.commitChanges as ReturnType<typeof vi.fn>).getMockImplementation()!;
-    (workflow.commitChanges as ReturnType<typeof vi.fn>).mockImplementation(async (...args: unknown[]) => {
+    const commit = (versionControl.commitChanges as ReturnType<typeof vi.fn>).getMockImplementation()!;
+    (versionControl.commitChanges as ReturnType<typeof vi.fn>).mockImplementation(async (...args: unknown[]) => {
       await commit(...args);
       throw new PushNeedsAgentResolutionError('feature-test', `${KB}/Index.md`, 'refused', '(not attempted)', 'refused');
     });
@@ -213,8 +213,8 @@ describe('LockingFilesystem.moveWithEdits', () => {
     expect(Number(await git(repo, ['rev-list', '--count', 'HEAD']))).toBe(Number(commitsBefore) + 1);
     expect((await git(repo, ['status', '--porcelain'])).trim()).toBe('');
     expect(await read('Topics/Deep/A/One.md')).toContain('../../../NodeTypes/Task.md');
-    const enqueued = released(workflow.releaseLock);
-    const untouched = released(workflow.releaseLockUntouched);
+    const enqueued = released(versionControl.releaseLock);
+    const untouched = released(versionControl.releaseLockUntouched);
     // Every file the commit named is enqueued…
     for (const p of [`${KB}/Index.md`, `${KB}/Projects/A/One.md`, `${KB}/Topics/Deep/A/One.md`, `${KB}/Topics/Deep/A/pic.png`]) {
       expect(enqueued).toContain(p);
@@ -227,7 +227,7 @@ describe('LockingFilesystem.moveWithEdits', () => {
 
   it('locks every file of a moved folder at its old and its new path', async () => {
     await fsLayer().moveWithEdits(`${KB}/Projects/A`, `${KB}/Topics/Deep/A`, edits(), 'Move A');
-    const locked = (workflow.acquireLock as ReturnType<typeof vi.fn>).mock.calls.map((c) => c[2] as string);
+    const locked = (versionControl.acquireLock as ReturnType<typeof vi.fn>).mock.calls.map((c) => c[2] as string);
     for (const name of ['One.md', 'Two.md', 'pic.png']) {
       expect(locked).toContain(`${KB}/Projects/A/${name}`);
       expect(locked).toContain(`${KB}/Topics/Deep/A/${name}`);
@@ -236,19 +236,19 @@ describe('LockingFilesystem.moveWithEdits', () => {
   });
 
   it('a lock store that throws gives back the locks already held, and changes nothing', async () => {
-    (workflow.acquireLock as ReturnType<typeof vi.fn>).mockImplementation(async (_w: string, _b: string, p: string) => {
+    (versionControl.acquireLock as ReturnType<typeof vi.fn>).mockImplementation(async (_w: string, _b: string, p: string) => {
       if (p === `${KB}/Projects/A/One.md`) throw new Error('lock store down');
       return { acquired: true, lock: { holderName: 'Alice' } };
     });
     await expect(
       fsLayer().moveWithEdits(`${KB}/Projects/A`, `${KB}/Topics/Deep/A`, edits(), 'Move A'),
     ).rejects.toThrow('lock store down');
-    expect(released(workflow.releaseLockUntouched)).toEqual([`${KB}/Index.md`, `${KB}/Projects/A`]);
+    expect(released(versionControl.releaseLockUntouched)).toEqual([`${KB}/Index.md`, `${KB}/Projects/A`]);
     expect((await git(repo, ['status', '--porcelain'])).trim()).toBe('');
   });
 
   it('every edit is judged again once the locks are held, and a refusal there changes nothing', async () => {
-    const acquire = workflow.acquireLock as ReturnType<typeof vi.fn>;
+    const acquire = versionControl.acquireLock as ReturnType<typeof vi.fn>;
     // A validator whose verdict depends on the state under the locks.
     const validateWrite = vi.fn(async (p: string) => {
       if (acquire.mock.calls.length > 0 && p.endsWith('Index.md')) throw new Error('refused under lock');
@@ -260,12 +260,12 @@ describe('LockingFilesystem.moveWithEdits', () => {
     expect(validateWrite.mock.calls.filter((c) => c[0] === `${KB}/Index.md`)).toHaveLength(2);
     expect(await git(repo, ['rev-parse', 'HEAD'])).toBe(head);
     expect((await git(repo, ['status', '--porcelain'])).trim()).toBe('');
-    expect(workflow.releaseLockNoCommit).not.toHaveBeenCalled();
-    expect(released(workflow.releaseLockUntouched)).toContain(`${KB}/Index.md`);
+    expect(versionControl.releaseLockNoCommit).not.toHaveBeenCalled();
+    expect(released(versionControl.releaseLockUntouched)).toContain(`${KB}/Index.md`);
   });
 
   it('an edit whose bytes cannot be put back is released with the discard, not untouched', async () => {
-    (workflow.commitChanges as ReturnType<typeof vi.fn>).mockImplementationOnce(async () => {
+    (versionControl.commitChanges as ReturnType<typeof vi.fn>).mockImplementationOnce(async () => {
       // The restore of Index.md will fail: a folder now sits at its path.
       await fs.rm(path.join(repo, 'Index.md'));
       await fs.mkdir(path.join(repo, 'Index.md'));
@@ -274,11 +274,11 @@ describe('LockingFilesystem.moveWithEdits', () => {
     await expect(
       fsLayer().moveWithEdits(`${KB}/Projects/A`, `${KB}/Topics/Deep/A`, edits(), 'Move A'),
     ).rejects.toThrow('commit exploded');
-    expect(released(workflow.releaseLockNoCommit)).toEqual([`${KB}/Index.md`]);
-    expect(released(workflow.releaseLockUntouched)).not.toContain(`${KB}/Index.md`);
+    expect(released(versionControl.releaseLockNoCommit)).toEqual([`${KB}/Index.md`]);
+    expect(released(versionControl.releaseLockUntouched)).not.toContain(`${KB}/Index.md`);
     // The moved file's edit was put back, and its lock released untouched.
     expect(await read('Projects/A/One.md')).toContain('../../NodeTypes/Task.md');
-    expect(released(workflow.releaseLockUntouched)).toContain(`${KB}/Projects/A/One.md`);
+    expect(released(versionControl.releaseLockUntouched)).toContain(`${KB}/Projects/A/One.md`);
   });
 
   it('a check refusal under the locks changes nothing', async () => {
@@ -293,7 +293,7 @@ describe('LockingFilesystem.moveWithEdits', () => {
   });
 
   it('a failing commit puts every byte back and undoes the move', async () => {
-    (workflow.commitChanges as ReturnType<typeof vi.fn>).mockRejectedValueOnce(new Error('commit exploded'));
+    (versionControl.commitChanges as ReturnType<typeof vi.fn>).mockRejectedValueOnce(new Error('commit exploded'));
     await expect(
       fsLayer().moveWithEdits(`${KB}/Projects/A`, `${KB}/Topics/Deep/A`, edits(), 'Move A'),
     ).rejects.toThrow('commit exploded');

package/src/modules/kb-fs/__tests__/repo-path.test.ts

@@ -9,7 +9,7 @@ import {
   normalizePathArgs,
   normalizeWorkspacePath,
 } from '../repo-path.js';
-import { WorkflowValidationError } from '../../../shared/domain-errors.js';
+import { VersionControlValidationError } from '../../../shared/domain-errors.js';
 
 const KB = 'knowledge-base';
 
@@ -80,8 +80,8 @@ describe('assertInsideRepo', () => {
     } catch (e) {
       err = e;
     }
-    expect(err).toBeInstanceOf(WorkflowValidationError);
-    const e = err as WorkflowValidationError;
+    expect(err).toBeInstanceOf(VersionControlValidationError);
+    const e = err as VersionControlValidationError;
     expect(e.status).toBe(400);
     // The offending path, the rule, and the exact path to use instead: an
     // agent reading this error can retry without guessing.
@@ -144,8 +144,8 @@ describe('a line break in a path — one name to the gates, two object names to
     } catch (e) {
       err = e;
     }
-    expect(err).toBeInstanceOf(WorkflowValidationError);
-    const e = err as WorkflowValidationError;
+    expect(err).toBeInstanceOf(VersionControlValidationError);
+    const e = err as VersionControlValidationError;
     expect(e.status).toBe(400);
     expect(e.message).toMatch(/control character/);
     // Never "use this instead": there is no corrected spelling of a name with
@@ -173,7 +173,7 @@ describe('a line break in a path — one name to the gates, two object names to
   it('refuses every control character, not only the line breaks', () => {
     for (const ch of ['\u0000', '\u0001', '\t', '\n', '\u000B', '\r', '\u001F', '\u007F']) {
       expect(() => normalizeWorkspacePath(`knowledge-base/Docs/a${ch}b.md`, KB), ch).toThrow(
-        WorkflowValidationError,
+        VersionControlValidationError,
       );
     }
   });
@@ -189,8 +189,8 @@ describe('a line break in a path — one name to the gates, two object names to
     } catch (e) {
       err = e;
     }
-    expect(err).toBeInstanceOf(WorkflowValidationError);
-    const e = err as WorkflowValidationError;
+    expect(err).toBeInstanceOf(VersionControlValidationError);
+    const e = err as VersionControlValidationError;
     // Named as the CONFIGURATION error it is: an operator told their own path
     // was invalid would have nothing to fix.
     expect(e.message).toMatch(/checkout folder name/);

package/src/modules/kb-fs/branch-name.ts

@@ -1,4 +1,4 @@
-import { BranchNameError, WorkflowValidationError } from '../../shared/domain-errors.js';
+import { BranchNameError, VersionControlValidationError } from '../../shared/domain-errors.js';
 
 // The protected-branch list is the knowledge base's (`KbContext.protectedBranches`):
 // services ask the context they were built with, so the backend guard and the
@@ -47,8 +47,8 @@ export function assertValidBranchName(name: string): void {
  * path we pass to `git` as a pathspec. Must stay within the repo; forward slashes only.
  */
 export function assertValidRelativePath(relativePath: string): void {
-  if (!relativePath) throw new WorkflowValidationError('path is required');
-  if (relativePath.length > 1024) throw new WorkflowValidationError('path too long');
+  if (!relativePath) throw new VersionControlValidationError('path is required');
+  if (relativePath.length > 1024) throw new VersionControlValidationError('path too long');
   // NUL, every other C0 control and DEL. A NUL is named on its own because it
   // terminates a C string and git's `-z` output; the rest are refused with it
   // because a LINE BREAK in a path is a separator in git's line-oriented stdin
@@ -59,22 +59,22 @@ export function assertValidRelativePath(relativePath: string): void {
   // check every path handed to git as a pathspec passes through.
   // eslint-disable-next-line no-control-regex
   if (/[\x00-\x1F\x7F]/.test(relativePath)) {
-    throw new WorkflowValidationError(
+    throw new VersionControlValidationError(
       relativePath.includes('\0') ? 'path contains NUL' : 'path contains a control character',
     );
   }
   if (relativePath.includes('\\')) {
-    throw new WorkflowValidationError('path must use forward slashes only');
+    throw new VersionControlValidationError('path must use forward slashes only');
   }
   if (relativePath.startsWith('/') || /^[A-Za-z]:/.test(relativePath)) {
-    throw new WorkflowValidationError('path must be relative');
+    throw new VersionControlValidationError('path must be relative');
   }
   const parts = relativePath.split('/');
   if (parts.some((p) => p === '..' || p === '.')) {
-    throw new WorkflowValidationError('path must not contain "." or ".."');
+    throw new VersionControlValidationError('path must not contain "." or ".."');
   }
   if (relativePath.startsWith('-')) {
-    throw new WorkflowValidationError('path must not start with "-"');
+    throw new VersionControlValidationError('path must not start with "-"');
   }
   // Pathspec glob characters (`*`, `?`, `[`, `]`, `!`) and pathspec magic (`:(…)`)
   // would otherwise be interpreted by `git add -- <path>` / `git log -- <path>`

package/src/modules/kb-fs/file-change-notifier.ts

@@ -1,7 +1,7 @@
 /**
  * One in-process notification fired AFTER a set of file changes is committed +
  * pushed (post-lock-release), so backend services can react to KB writes without
- * the per-file TTL wait. Distinct from the SSE `WorkflowEventBus`, which fans
+ * the per-file TTL wait. Distinct from the SSE `VersionControlEventBus`, which fans
  * scoped events to browser sessions; this is an unscoped, server-side domain hook.
  *
  * BATCHED by design: a single-file save emits `paths: [p]`, a batch write
@@ -10,7 +10,7 @@
  * id-repair rebuilds the id index) handle a whole batch off one rebuild instead
  * of N back-to-back ones.
  *
- * Emitted from the two post-commit chokepoints (`WorkflowService.runPendingCommit`
+ * Emitted from the two post-commit chokepoints (`VersionControlService.runPendingCommit`
  * for single-file writes, `LockingFilesystem.writeFiles` for batches).
  *
  * Every listener is invoked inside try/catch — a throwing subscriber must never

package/src/modules/kb-fs/locking-filesystem.ts

@@ -1,12 +1,12 @@
 /**
- * A `LocalFilesystem` that wraps every mutating operation in a workflow
+ * A `LocalFilesystem` that wraps every mutating operation in a version-control
  * lock acquire → super-call → release-with-auto-commit-and-push cycle.
  * This is the agent's file edit surface — Mastra hands the agent the
  * workspace's filesystem tools (write_file / edit_file / etc.), and those
  * call directly into this class, so the agent's edits go through the same
  * lock + commit + push pipeline as the human editor's saves.
  *
- * Per the workflow spec (PLAN.md §2):
+ * Per the version-control spec (PLAN.md §2):
  *   - Each tool call is one acquire/release cycle. The agent never holds a
  *     lock while it's "thinking" between tool calls — a fast human editor
  *     can always grab a file the agent isn't actively writing.
@@ -14,11 +14,11 @@
  *     2-second intervals (~6s ceiling) then surface a structured error
  *     so the agent can skip the file and continue with the rest of its
  *     turn rather than aborting the whole call.
- *   - Lock-release inside `WorkflowService.releaseLock` is the thing that
+ *   - Lock-release inside `VersionControlService.releaseLock` is the thing that
  *     actually commits + pushes the file — see that method for the
  *     `commitFile → release → push` sequence. We don't repeat the commit
  *     step here; releasing IS committing.
- *   - `rmdir` is refused. The workflow invariant is "each change touches
+ *   - `rmdir` is refused. The version-control invariant is "each change touches
  *     exactly one file" and a recursive directory delete violates that.
  *     The agent must delete entries individually via `deleteFile`.
  *   - `mkdir` followed by a `.gitkeep` write is the canonical way to land
@@ -47,7 +47,7 @@ import {
   type RemoveOptions,
   type WriteOptions,
 } from '@mastra/core/workspace';
-import type { AuthUser, Change, IWorkflowService } from '@bevel-software/platform-shared';
+import type { AuthUser, Change, IVersionControlService } from '@bevel-software/platform-shared';
 import { PushNeedsAgentResolutionError } from '../../shared/domain-errors.js';
 import type { FileChangeNotifier } from './file-change-notifier.js';
 import { isAbsence } from '../../shared/fs.contract.js';
@@ -134,13 +134,13 @@ export type WriteValidator = ((path: string, content: FileContent) => void | Pro
 };
 
 /**
- * Dependencies the wrapper needs to talk to the workflow lock service.
+ * Dependencies the wrapper needs to talk to the version-control lock service.
  * Captured at construction time so every per-method call resolves to the
  * same `(workspace, branch, user)` triple — the agent can't accidentally
  * target a different workspace through this filesystem.
  */
 export interface LockingFilesystemContext {
-  workflow: IWorkflowService;
+  versionControl: IVersionControlService;
   workspaceId: string;
   branch: string;
   user: AuthUser;
@@ -475,7 +475,7 @@ export class LockingFilesystem extends GitGuardedFilesystem {
     summary: string,
     check?: () => Promise<void>,
   ): Promise<Change | null> {
-    const { workflow, workspaceId, branch, user } = this.lockContext;
+    const { versionControl, workspaceId, branch, user } = this.lockContext;
     await this.assertNotGitInternals(src);
     await this.assertNotGitInternals(dest);
     this.assertInsideRepo(dest);
@@ -512,10 +512,10 @@ export class LockingFilesystem extends GitGuardedFilesystem {
     const release = async (mode: 'untouched' | 'enqueue'): Promise<void> => {
       for (const p of acquired) {
         try {
-          if (mode === 'enqueue' && scope.includes(p)) await workflow.releaseLock(workspaceId, branch, p, user);
-          else if (mode === 'enqueue') await workflow.releaseLockUntouched(workspaceId, branch, p, user);
-          else if (dirtyLeft.has(p)) await workflow.releaseLockNoCommit(workspaceId, branch, p, user);
-          else await workflow.releaseLockUntouched(workspaceId, branch, p, user);
+          if (mode === 'enqueue' && scope.includes(p)) await versionControl.releaseLock(workspaceId, branch, p, user);
+          else if (mode === 'enqueue') await versionControl.releaseLockUntouched(workspaceId, branch, p, user);
+          else if (dirtyLeft.has(p)) await versionControl.releaseLockNoCommit(workspaceId, branch, p, user);
+          else await versionControl.releaseLockUntouched(workspaceId, branch, p, user);
         } catch (releaseErr) {
           log.warn(`lock release failed for "${p}" during moveWithEdits:`, { err: releaseErr });
         }
@@ -526,7 +526,7 @@ export class LockingFilesystem extends GitGuardedFilesystem {
       let ok = false;
       try {
         for (let attempt = 0; attempt < ACQUIRE_RETRY_ATTEMPTS; attempt++) {
-          const result = await workflow.acquireLock(workspaceId, branch, p, user);
+          const result = await versionControl.acquireLock(workspaceId, branch, p, user);
           if (result.acquired) {
             ok = true;
             break;
@@ -599,7 +599,7 @@ export class LockingFilesystem extends GitGuardedFilesystem {
           ...edits.map((e) => e.path),
         ]),
       ].sort();
-      const change = await workflow.commitChanges(workspaceId, user, summary, scope);
+      const change = await versionControl.commitChanges(workspaceId, user, summary, scope);
       await release('untouched');
       if (change) this.lockContext.fileChanges?.emit({ workspaceId, branch, paths: scope, byUser: user });
       return change;
@@ -681,7 +681,7 @@ export class LockingFilesystem extends GitGuardedFilesystem {
    * `writeFile` takes one lock cycle per file and lets the deferred queue commit
    * it, this wraps the WHOLE batch in one cycle: acquire every path's lock up
    * front, write every file to disk, then commit the whole set synchronously as
-   * one change via the workflow service's `commitChanges` (one `git add` + one
+   * one change via the version-control service's `commitChanges` (one `git add` + one
    * `git commit`, then push), and release WITHOUT a per-file commit. Fail-closed:
    * if any lock can't be acquired, or a write/commit throws, nothing is committed
    * (the failure-path `releaseLockNoCommit` discards the uncommitted bytes).
@@ -713,7 +713,7 @@ export class LockingFilesystem extends GitGuardedFilesystem {
       writes: readonly { path: string; content: FileContent }[],
     ) => Promise<{ path: string; content: FileContent }[]>,
   ): Promise<Change | null> {
-    const { workflow, workspaceId, branch, user } = this.lockContext;
+    const { versionControl, workspaceId, branch, user } = this.lockContext;
     // Fail the whole batch before any plan, validator or lock: one stray path
     // must not let its siblings land while it silently misses git.
     for (const w of writes) await this.assertNotGitInternals(w.path);
@@ -760,7 +760,7 @@ export class LockingFilesystem extends GitGuardedFilesystem {
     // with the discard so the corrupt bytes can't outlive the batch.
     const failedSeedDiscards = new Set<string>();
     // Release every acquired lock, each with the semantics its outcome
-    // earned. Three shapes (mirroring the three WorkflowService releases):
+    // earned. Three shapes (mirroring the three VersionControlService releases):
     //
     //   'discard'   → releaseLockNoCommit: resets the path's working tree to
     //     HEAD. Only for bytes this batch itself owns — its committed paths
@@ -783,11 +783,11 @@ export class LockingFilesystem extends GitGuardedFilesystem {
         try {
           const mode = modeOf(p);
           if (mode === 'discard') {
-            await workflow.releaseLockNoCommit(workspaceId, branch, p, user);
+            await versionControl.releaseLockNoCommit(workspaceId, branch, p, user);
           } else if (mode === 'enqueue') {
-            await workflow.releaseLock(workspaceId, branch, p, user);
+            await versionControl.releaseLock(workspaceId, branch, p, user);
           } else {
-            await workflow.releaseLockUntouched(workspaceId, branch, p, user);
+            await versionControl.releaseLockUntouched(workspaceId, branch, p, user);
           }
         } catch (releaseErr) {
           log.warn(`lock release failed for "${p}" during writeFiles:`, { err: releaseErr });
@@ -800,7 +800,7 @@ export class LockingFilesystem extends GitGuardedFilesystem {
       let holderName: string | null = null;
       let ok = false;
       for (let attempt = 0; attempt < ACQUIRE_RETRY_ATTEMPTS; attempt++) {
-        const result = await workflow.acquireLock(workspaceId, branch, p, user);
+        const result = await versionControl.acquireLock(workspaceId, branch, p, user);
         if (result.acquired) {
           ok = true;
           break;
@@ -864,7 +864,7 @@ export class LockingFilesystem extends GitGuardedFilesystem {
     // without it would leave that folder invisible to them.
     for (const p of [...seeds.keys()].sort()) {
       if (paths.includes(p)) continue; // already locked as a caller path
-      const result = await workflow.acquireLock(workspaceId, branch, p, user);
+      const result = await versionControl.acquireLock(workspaceId, branch, p, user);
       if (result.acquired) {
         acquired.push(p);
       } else {
@@ -967,7 +967,7 @@ export class LockingFilesystem extends GitGuardedFilesystem {
       // seeds): on the shared per-branch workspace another save's bytes may be
       // dirty with their commit still queued, and an unscoped commit would
       // sweep them in under this batch's author/summary.
-      change = await workflow.commitChanges(workspaceId, user, summary, touched);
+      change = await versionControl.commitChanges(workspaceId, user, summary, touched);
       if (seeds.size > 0) this.lockContext.creatorAccess?.noteAccessFileWritten(workspaceId);
     } catch (err) {
       if (err instanceof PushNeedsAgentResolutionError) {
@@ -1052,7 +1052,7 @@ export class LockingFilesystem extends GitGuardedFilesystem {
     const plan = await this.planCreate(inputPath, 'dir');
     // mkdir itself is not a lockable op (it touches no file content), so we
     // do the bare super-call without acquiring. The lock + commit happens on
-    // the `.gitkeep` write below — that's the file the workflow change
+    // the `.gitkeep` write below — that's the file the version-control change
     // attaches to. If the dir already has content (rare; e.g. recursive
     // create where a sibling already exists), we skip the .gitkeep — empty-
     // folder placeholders are only useful for actually-empty folders.
@@ -1180,7 +1180,7 @@ export class LockingFilesystem extends GitGuardedFilesystem {
 
   /**
    * Acquire the lock, run `op`, release. The release does the commit +
-   * push via `WorkflowService.releaseLock`. On contention we retry a few
+   * push via `VersionControlService.releaseLock`. On contention we retry a few
    * times before surfacing a structured failure — long enough to ride
    * out a human typing a quick edit, short enough that the agent doesn't
    * stall a whole turn waiting for someone to step away from a file.
@@ -1214,12 +1214,12 @@ export class LockingFilesystem extends GitGuardedFilesystem {
     op: () => Promise<T>,
     check?: () => Promise<void>,
   ): Promise<T> {
-    const { workflow, workspaceId, branch, user } = this.lockContext;
+    const { versionControl, workspaceId, branch, user } = this.lockContext;
 
     let lastHolderName: string | null = null;
     let acquired = false;
     for (let attempt = 0; attempt < ACQUIRE_RETRY_ATTEMPTS; attempt++) {
-      const result = await workflow.acquireLock(workspaceId, branch, inputPath, user);
+      const result = await versionControl.acquireLock(workspaceId, branch, inputPath, user);
       if (result.acquired) {
         acquired = true;
         break;
@@ -1263,9 +1263,9 @@ export class LockingFilesystem extends GitGuardedFilesystem {
       // caller actually cares about.
       try {
         if (err instanceof CheckRefusal || err instanceof DestinationTakenError) {
-          await workflow.releaseLockUntouched(workspaceId, branch, inputPath, user);
+          await versionControl.releaseLockUntouched(workspaceId, branch, inputPath, user);
         } else {
-          await workflow.releaseLockNoCommit(workspaceId, branch, inputPath, user);
+          await versionControl.releaseLockNoCommit(workspaceId, branch, inputPath, user);
         }
       } catch (releaseErr) {
         log.warn(`lock release failed for "${inputPath}" after op error:`, { err: releaseErr });
@@ -1278,7 +1278,7 @@ export class LockingFilesystem extends GitGuardedFilesystem {
     // actual `commitFile + push` out of band. The agent's tool call
     // returns once disk + lock + enqueue are done — the commit lands
     // moments later (typically <1s) without blocking the agent's turn.
-    await workflow.releaseLock(workspaceId, branch, inputPath, user);
+    await versionControl.releaseLock(workspaceId, branch, inputPath, user);
     return result;
   }
 }

package/src/modules/kb-fs/repo-path.ts

@@ -1,5 +1,5 @@
 import path from 'node:path';
-import { WorkflowValidationError } from '../../shared/domain-errors.js';
+import { VersionControlValidationError } from '../../shared/domain-errors.js';
 import { sanitizedPath } from '../../shared/printable.js';
 import { assertTmpRefsTaken, isTmpRef } from './tmp-ref.js';
 
@@ -112,7 +112,7 @@ export function assertInsideRepo(wsPath: string, kbDirName: string): void {
     // forge a second line of the answer, in the message and in the `path` a
     // JSON consumer reads.
     const shown = sanitizedPath(wsPath);
-    throw new WorkflowValidationError(
+    throw new VersionControlValidationError(
       `"${shown}" contains a control character: a line break, a NUL or another invisible byte is not part of any ` +
         'file name, and git reads a line break in a path as the end of one object name and the start of another. ' +
         'Remove it and send the name as it is written.',
@@ -127,7 +127,7 @@ export function assertInsideRepo(wsPath: string, kbDirName: string): void {
     .replace(/^(\.\.(\/|$))+/, '')
     .replace(/^\.$/, '');
   const corrected = isInsideRepo(normalized, kbDirName) ? normalized : `${kbDirName}/${normalized}`;
-  throw new WorkflowValidationError(
+  throw new VersionControlValidationError(
     `"${wsPath}" is outside the knowledge base repository: paths are workspace-relative, must start with "${kbDirName}/" and may not contain "." or ".." segments or backslashes. ` +
       `Use "${corrected}" instead. A file written without that prefix lands beside the repository, where it is never committed or pushed.`,
     { kind: 'path-outside-repo', path: wsPath, kbDirName, corrected },
@@ -183,7 +183,7 @@ export function normalizeWorkspacePath(wsPath: string, kbDirName: string): strin
   // `core-config` and the `kbDirName` setting validator both refuse this at
   // the point it is SET, so reaching here means the two drifted.
   if (CONTROL_CHARACTERS.test(kbDirName)) {
-    throw new WorkflowValidationError(
+    throw new VersionControlValidationError(
       `the configured checkout folder name (kbDirName / KB_DIR_NAME) contains a control character: "${sanitizedPath(kbDirName)}". ` +
         'Every workspace path is prefixed with it, so no path can be resolved until the setting is corrected.',
       { kind: 'kb-dir-name-control-character', kbDirName: sanitizedPath(kbDirName) },
@@ -237,7 +237,7 @@ export function assertRepoRootNameFree(wsPath: string, kbDirName: string): void
   const segments = String(wsPath).replace(/\/+$/, '').split('/');
   const reserved = kbDirName.toLowerCase();
   if (segments[0] !== kbDirName || segments[1]?.toLowerCase() !== reserved) return;
-  throw new WorkflowValidationError(
+  throw new VersionControlValidationError(
     `"${segments[1]}" is reserved: it is the checkout folder's name. A folder of that name at the repository root ` +
       `could never be reached — every workspace path starting with "${kbDirName}/" names the checkout itself — so it cannot be created, moved to or renamed to.` +
       // Said only when the caller spelled it differently, so the ordinary

package/src/modules/kb-fs/tmp-ref.ts

@@ -1,4 +1,4 @@
-import { WorkflowValidationError } from '../../shared/domain-errors.js';
+import { VersionControlValidationError } from '../../shared/domain-errors.js';
 import { sanitizedPath } from '../../shared/printable.js';
 
 /**
@@ -33,9 +33,9 @@ export function isTmpRef(value: unknown): boolean {
  * copying it into the repository. A 400 with a `kind` to branch on, before
  * any gate, lock or write.
  */
-export function tmpRefReadOnlyRefusal(ref: string, tool: string): WorkflowValidationError {
+export function tmpRefReadOnlyRefusal(ref: string, tool: string): VersionControlValidationError {
   const shown = sanitizedPath(ref);
-  return new WorkflowValidationError(
+  return new VersionControlValidationError(
     `"${shown}" is a tmp ref, and ${tool} does not take one there: the workspace's tmp folder is read-only through ` +
       'the ref. read_file, file_stat and grep read the one file it names; to keep the file, copy_file it to a ' +
       'repository path (the ref as `src`, the repository path as `dest`).',