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

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

@@ -10,40 +10,38 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { testKbContext } from '../../../__tests__/kb-context.js';
 import { slowRipgrep } from '../../../__tests__/slow-ripgrep.js';
 import { LocalFilesystem } from '@mastra/core/workspace';
-import { ToolRegistry } from '../../tool-registry/tool-registry.js';
-import { createToolHandlerFactory } from '../../tool-helpers/tool-handler.js';
-import { ToolError, type ToolContext } from '../../tool-helpers/tool.contract.js';
-import type { ToolAuth } from '../../tool-auth/tool-auth.middleware.js';
+import { GUIDE_FIRST_SENTENCE, ToolRegistry } from '../../tool-registry/index.js';
+import { AccessControlService, VersionControlHooks, createToolHandlerFactory, type AgentOperationContext } from '../../../__tests__/tool-wiring.js';
+import { ToolError, type ToolContext } from '../../tool-helpers/index.js';
+import type { ToolAuth } from '../../tool-auth/index.js';
 import { registerWorkspaceTools } from '../workspace.tools.js';
 import { RipgrepPatternMatcher, type RipgrepPatternMatcherOptions } from '../index.js';
-import { sharedFileRules, sharedFileRulesSection } from '../../agent-instructions/shared-file-rules.js';
-import { composeAgentGuide } from '../../agent-guide/agent-guide.js';
-import { GUIDE_FIRST_SENTENCE } from '../../tool-registry/guide-first.js';
+import { sharedFileRules, sharedFileRulesSection } from '../../agent-instructions/index.js';
+import { composeAgentGuide } from '../../agent-guide/index.js';
 import { RoutineWritePolicyService } from '../routine-write-policy.js';
 import { UuidSessionSink, type ISessionSink } from '../session-sink.js';
 import { FIRST_RUN_SECTION_ID, STARTER_GUIDE_FILE, firstRunNote, type FirstRunStarterSource } from '../first-run.js';
-import { WorkflowHooks, type AgentOperationContext } from '../../workflow/workflow-hooks.js';
 import { SESSION_ID_DESCRIPTION, ToolDescriptionNotes } from '../agent-access.gate.js';
 import { SpillStore } from '../spill-store.js';
 import { DocExtractService } from '../file-readers/doc-extract.service.js';
 import { WorkerDocumentExtractor } from '../file-readers/extract-in-worker.js';
 import { OCTET_STREAM_FALLBACK_NOTE } from '../file-readers/content-mode.js';
-import type { IAccessControl } from '../../access/access-control.interface.js';
-import { AccessControlService } from '../../access/access-control.service.js';
-import { NodeFs } from '../../kb-fs/node-fs.js';
+import type { IAccessControl } from '../../access/index.js';
+import { realDisk } from '../../../__tests__/real-disk.js';
 import type { WorkspaceService } from '../workspace.service.js';
 import { DEFAULT_KB_LAYOUT, isBranchAuthoredBy, isOwnSuggestionsBranch } from '@bevel-software/platform-shared';
-import { normalizeWorkspacePath } from '../../kb-fs/repo-path.js';
+import { normalizeWorkspacePath } from '../../kb-fs/index.js';
 import { GIT_INTERNALS_MESSAGE, PathNotFoundError } from '../../../shared/domain-errors.js';
-import { AccessDeniedError } from '../../access-model/access-errors.js';
+import { AccessDeniedError } from '../../access-model/index.js';
 import { proposalTitleFor } from '../write-denial.js';
 import { NOT_FOUND_NEXT_STEP } from '../not-found.js';
 import { compileCheck, exampleArguments } from '@bevel-software/platform-mcp-core';
-import { routeToolSchemas } from '../../tool-helpers/route-tool-schemas.js';
-import { TOOL_DESCRIPTION_CAP, clientVisibleLength } from '../../tool-registry/description-length.js';
 
 const KB_DIR = 'knowledge-base';
 
+/** A move that changes nobody's access: what a stand-in without rules answers. */
+const NO_CHANGES = { lose: [], gain: [] };
+
 /** Allow-all access control — the default for tests not exercising read gating. */
 const allowAll = {
   canRead: async () => true,
@@ -67,6 +65,8 @@ const allowAll = {
   // a folder's `access.md` files actually does to it is exercised against
   // REAL rules in "a move preview judges the destination as it will be".
   previewAccessAfterRelocation: async () => ({ read: true, write: true, download: true, owner: true }),
+  // Who else loses or gains access in a move: nobody, here.
+  prospectiveHolderChanges: async () => NO_CHANGES,
 } as unknown as IAccessControl;
 
 /** Access control that denies `canRead` for an explicit set of repo-relative paths. */
@@ -120,7 +120,7 @@ let focusedBranch: string | undefined;
 /** The registry the tools were mounted into, so a test can inspect their defs. */
 let toolRegistry: ToolRegistry;
 /** The hook registry the tools were mounted against, so a test can register one. */
-let hooks: WorkflowHooks;
+let hooks: VersionControlHooks;
 /** The note registry the tools were mounted against, so a test can register a note. */
 let notes: ToolDescriptionNotes;
 /**
@@ -165,7 +165,7 @@ async function start(
   await docExtractor?.close();
   const extractor = new WorkerDocumentExtractor();
   docExtractor = extractor;
-  hooks = new WorkflowHooks();
+  hooks = new VersionControlHooks();
   notes = new ToolDescriptionNotes();
   callerSource = 'internal';
   tempDir = await mkdtemp(join(tmpdir(), 'ws-tools-'));
@@ -307,7 +307,7 @@ async function start(
         return { destination: '', extracted, skipped };
       },
     } as never,
-    workflowService: {} as never,
+    versionControlService: {} as never,
     events: {} as never,
     getFilesystem: async () => fs,
   });
@@ -825,10 +825,10 @@ describe('write modes and per-path outcomes', () => {
     // The paragraph that said this in BOTH descriptions is one shared rule now.
     // What stays on the tool is the input the agent fills, which is where the
     // decision is actually taken.
-    const rule = sharedFileRules(testKbContext().layout).find((r) => r.id === 'write-mode')!;
+    const rule = sharedFileRules(testKbContext().layout, testKbContext().defaultBranch).find((r) => r.id === 'write-mode')!;
     expect(rule.body).toContain('DEFAULTS TO `create`');
     expect(rule.body).toContain('On write_file and write_files');
-    expect(sharedFileRulesSection(testKbContext().layout).split(rule.body)).toHaveLength(2);
+    expect(sharedFileRulesSection(testKbContext().layout, testKbContext().defaultBranch).split(rule.body)).toHaveLength(2);
     for (const name of ['write_file', 'write_files']) {
       const def = tools.find((t) => t.name === name)!;
       expect(def.description, name).not.toContain('DEFAULTS TO `create`');
@@ -2089,7 +2089,7 @@ describe('office documents and PDFs', () => {
       // description. Checked on the whole body rather than on a phrase: the
       // drift this PR exists to prevent is a paragraph pasted back onto a
       // tool, and naming only two marker phrases would catch two of eight.
-      for (const rule of sharedFileRules(testKbContext().layout)) {
+      for (const rule of sharedFileRules(testKbContext().layout, testKbContext().defaultBranch)) {
         expect(def!.description, `${name} / ${rule.id}`).not.toContain(rule.body);
       }
       // The two lead-in labels the paragraphs used to arrive under are gone
@@ -2124,30 +2124,12 @@ describe('office documents and PDFs', () => {
       // Narrowed by hand: the assertion above already failed the test if not.
       if (!compiled.checkable) throw new Error(compiled.reason);
       expect(compiled.check(exampleArguments(def.inputs)), def.name).toEqual([]);
-      // And the FLAT schema, which is what the tool's own route checks the
-      // call against: the two must agree, or a call the example produced would
-      // be refused one layer in.
-      const flat = routeToolSchemas(def.name)?.flat;
-      expect(flat, def.name).toBeDefined();
-      const flatCheck = compileCheck(flat);
-      expect(flatCheck.checkable, `${def.name} (flat): ${flatCheck.checkable ? '' : flatCheck.reason}`).toBe(true);
-      if (!flatCheck.checkable) throw new Error(flatCheck.reason);
-      expect(flatCheck.check(exampleArguments(flat)), `${def.name} (flat)`).toEqual([]);
-    }
-  });
-
-  it('every description, call example and purpose prefix included, stays inside the cap a client shows', async () => {
-    await start();
-    const tools = await toolRegistry.listInternal();
-    for (const def of tools) {
-      // Measured as a CLIENT receives it: the call line, the purpose prefix at
-      // its own cap (the four knowledge-base tools carry one), and the
-      // description — the three things that ride one tool's entry.
-      const received = clientVisibleLength(def);
-      expect(received, `${def.name} is ${received} characters (cap ${TOOL_DESCRIPTION_CAP})`).toBeLessThanOrEqual(
-        TOOL_DESCRIPTION_CAP,
-      );
     }
+    // That the FLAT schema each route checks a call against agrees with the
+    // example is the route layer's own property: tool-helpers'
+    // `route-tool-schemas.catalog.test.ts` holds it over the whole catalog.
+    // And that every description stays inside the cap a client shows is the
+    // registry's: `tool-description-length.test.ts`, over the same catalog.
   });
 
   describe('binary capability contract: a text file, a document, an image and a zip', () => {
@@ -2296,10 +2278,10 @@ describe('office documents and PDFs', () => {
   it('says where the images a page uses go — once, in the shared rules', async () => {
     await start();
     const tools = await toolRegistry.listInternal();
-    const rule = sharedFileRules(testKbContext().layout).find((r) => r.id === 'images-in-pages')!;
+    const rule = sharedFileRules(testKbContext().layout, testKbContext().defaultBranch).find((r) => r.id === 'images-in-pages')!;
     expect(rule.body).toContain('`assets/` folder next to the page');
     expect(rule.body).toContain('![Approval screen](./assets/approval-screen.png)');
-    expect(sharedFileRulesSection(testKbContext().layout)).toContain(rule.body);
+    expect(sharedFileRulesSection(testKbContext().layout, testKbContext().defaultBranch)).toContain(rule.body);
     for (const name of ['write_file', 'write_files']) {
       expect(tools.find((t) => t.name === name)!.description, name).not.toContain('`assets/` folder next to the page');
     }
@@ -2420,7 +2402,7 @@ describe('start_session', () => {
     // The default branch's workspace directory, for the tests about the
     // `firstRun` note. Without one the workspace service is a bare stand-in
     // the note's check cannot use, which is what every other test here wants:
-    // the call answers with the id alone.
+    // the call answers with the id and the default branch, never `firstRun`.
     defaultWorkspaceDir?: string,
     // The starter pack the knowledge base was filled from, for the note.
     starterPacks?: FirstRunStarterSource,
@@ -2440,7 +2422,7 @@ describe('start_session', () => {
             getWorkspacePath: async () => defaultWorkspaceDir,
           }
         : {}) as never,
-      workflowService: {} as never,
+      versionControlService: {} as never,
       events: {} as never,
       getFilesystem: async () => ({}) as never,
     });
@@ -2466,7 +2448,7 @@ describe('start_session', () => {
     registerWorkspaceTools(
       registry, router, auth, toolHandler,
       new SpillStore(join(tmpdir(), 'bevel-test-spills')), new DocExtractService(join(tmpdir(), 'bevel-test-doc-extract'), extractor), access, testKbContext({ kbDirName: KB_DIR }),
-      { recoveryBotEmail: RECOVERY_BOT, hooks: new WorkflowHooks(), notes: new ToolDescriptionNotes() },
+      { recoveryBotEmail: RECOVERY_BOT, hooks: new VersionControlHooks(), notes: new ToolDescriptionNotes() },
       new RoutineWritePolicyService(),
       sink ?? fakeSessionSink,
       undefined,
@@ -2475,7 +2457,7 @@ describe('start_session', () => {
       undefined,
       undefined /* downloads */,
       starterPacks,
-      new NodeFs(),
+      realDisk(),
     );
     app.use('/api', router);
     server = await new Promise<HttpServer>((r) => {
@@ -2601,7 +2583,7 @@ describe('start_session', () => {
     registerWorkspaceTools(
       registry, router, noopAuth, (() => () => {}) as never,
       new SpillStore(join(tmpdir(), 'bevel-test-spills')), new DocExtractService(join(tmpdir(), 'bevel-test-doc-extract'), extractor), allowAll, testKbContext({ kbDirName: KB_DIR }),
-      { recoveryBotEmail: RECOVERY_BOT, hooks: new WorkflowHooks(), notes: new ToolDescriptionNotes() },
+      { recoveryBotEmail: RECOVERY_BOT, hooks: new VersionControlHooks(), notes: new ToolDescriptionNotes() },
       new RoutineWritePolicyService(),
       {} as never,
     );
@@ -2700,7 +2682,7 @@ describe('start_session', () => {
 
     /**
      * The note is a read: it says what the knowledge folder holds. A caller
-     * who may not read the folder gets the id alone, and a pack page the
+     * who may not read the folder gets the id and the default branch alone, and a pack page the
      * caller may not read is judged as anybody's page, so the note never
      * tells them it is still a placeholder.
      */
@@ -2708,7 +2690,7 @@ describe('start_session', () => {
       const closed = { ...allowAll, canRead: async () => false } as unknown as IAccessControl;
       const base = await startSessionApp('external', undefined, wsDir, undefined, closed);
       const res = (await (await postRaw(`${base}/api/agent/tools/start_session`)).json()) as { firstRun?: string };
-      expect(res).toEqual({ sessionId: 'thread-xyz' });
+      expect(res).toEqual({ sessionId: 'thread-xyz', defaultBranch: 'target-company-state' });
     });
 
     it('judges the folder as the caller may see it: a page they may not read leaves the note standing', async () => {
@@ -2741,15 +2723,15 @@ describe('start_session', () => {
       } as unknown as IAccessControl;
       const base = await startSessionApp('external', undefined, wsDir, starter, pageClosed);
       const res = (await (await postRaw(`${base}/api/agent/tools/start_session`)).json()) as { firstRun?: string };
-      expect(res).toEqual({ sessionId: 'thread-xyz' });
+      expect(res).toEqual({ sessionId: 'thread-xyz', defaultBranch: 'target-company-state' });
     });
 
-    it('never costs the session id: a workspace it cannot read answers with the id alone', async () => {
+    it('never costs the session id: a workspace it cannot read answers with the id and the default branch', async () => {
       await rm(wsDir, { recursive: true, force: true });
 
       const res = await startSession();
 
-      expect(res).toEqual({ sessionId: 'thread-xyz' });
+      expect(res).toEqual({ sessionId: 'thread-xyz', defaultBranch: 'target-company-state' });
     });
   });
 });
@@ -2786,7 +2768,7 @@ describe('branch is a required parameter in the tool contract', () => {
       new DocExtractService(join(tmpdir(), 'bevel-test-doc-extract'), extractor),
       allowAll,
       testKbContext({ kbDirName: KB_DIR }),
-      { recoveryBotEmail: RECOVERY_BOT, hooks: new WorkflowHooks(), notes: new ToolDescriptionNotes() },
+      { recoveryBotEmail: RECOVERY_BOT, hooks: new VersionControlHooks(), notes: new ToolDescriptionNotes() },
       new RoutineWritePolicyService(),
       {} as never,
       // Skill check, change gate, uploads, guide, downloads, starter packs, disk: not this harness's business.
@@ -3256,7 +3238,8 @@ describe('preflight for moves and deletes', () => {
     if (rel === 'sealed.md' || rel.endsWith('/sealed.md')) return { read: true, write: false, download: false, owner: false };
     if (rel.startsWith('HR/')) return { read: true, write: true, download: false, owner: false };
     if (rel.startsWith('Locked/')) return { read: true, write: false, download: false, owner: false };
-    if (rel.startsWith('Secret/')) return { read: false, write: false, download: false, owner: false };
+    // The folder itself answers as its contents do, as the resolver's scopes do.
+    if (rel === 'Secret' || rel.startsWith('Secret/')) return { read: false, write: false, download: false, owner: false };
     return { read: true, write: true, download: true, owner: true };
   };
   const rules = {
@@ -3273,6 +3256,7 @@ describe('preflight for moves and deletes', () => {
     // preview learned to relocate them, which keeps every ordering and
     // oracle test below about what it is about.
     previewAccessAfterRelocation: async (_w: string, _u: string, _from: string, to: string) => verbsFor(to),
+    prospectiveHolderChanges: async () => NO_CHANGES,
   } as unknown as IAccessControl;
 
   const call = async (base: string, tool: string, body: Record<string, unknown>) => {
@@ -3401,10 +3385,12 @@ describe('preflight for moves and deletes', () => {
           writes.push(op.wsPath ?? '');
         });
         expect((await call(base, 'move_file', args)).body).toMatchObject({ moved: true });
-        // `Locked/refs.md` is named (left for want of write access, its links
-        // listed), so the read hook hears of it; the unreadable page and the
-        // transcript are never named, so it never hears of them.
-        expect(reads.sort()).toEqual([KB('Locked/refs.md'), KB('Sales/deal.md'), KB('Sales/index.md')]);
+        // The move's two ends first, as read_file tells it (what moves, and
+        // the folder it lands in); then `Locked/refs.md` is named (left for
+        // want of write access, its links listed), so the read hook hears of
+        // it; the unreadable page and the transcript are never named, so it
+        // never hears of them.
+        expect(reads.sort()).toEqual([KB('Locked/refs.md'), KB('Sales/2026'), KB('Sales/deal.md'), KB('Sales/deal.md'), KB('Sales/index.md')]);
         expect([...new Set(writes)].sort()).toEqual([KB('Sales/2026/deal.md'), KB('Sales/deal.md'), KB('Sales/index.md')]);
       });
 
@@ -3450,6 +3436,32 @@ describe('preflight for moves and deletes', () => {
       expect(await exists(args.src)).toBe(false);
     });
 
+    it('a caller who cannot read what moves is refused as read_file refuses them, on a draft too, and nothing is looked at', async () => {
+      const resolved: string[] = [];
+      const base = await start('write', {
+        ...rules,
+        prospectiveHolderChanges: async (_w: string, from: string) => {
+          resolved.push(from);
+          return { lose: [{ kind: 'group', name: 'Board', verb: 'read' }], gain: [] };
+        },
+      } as unknown as IAccessControl);
+      await fs.writeFile(KB('Secret/plan.md'), 'plan');
+      // A draft is not write-gated, so only the read gate stands between a
+      // caller and a move of a file they may not open — and it does: the dry
+      // run, the unconfirmed move and the confirmed one are all read_file's
+      // own refusal, with nobody resolved and nothing moved.
+      const args = { branch: 'someone/draft', src: KB('Secret/plan.md'), dest: KB('Secret/old/plan.md') };
+      const read = await call(base, 'read_file', { branch: args.branch, path: args.src });
+      expect(read.status).toBe(403);
+      for (const body of [{ ...args, dryRun: true }, args, { ...args, confirm: true }]) {
+        const res = await call(base, 'move_file', body);
+        expect(res.status).toBe(403);
+        expect(res.body).toEqual(read.body);
+      }
+      expect(resolved).toEqual([]);
+      expect(await exists(args.src)).toBe(true);
+    });
+
     it('an access-changing move shows before/after and runs only with confirm: true', async () => {
       const base = await seeded();
       const args = { src: KB('Sales/deal.md'), dest: KB('HR/deal.md') };
@@ -3648,13 +3660,18 @@ describe('preflight for moves and deletes', () => {
       expect(await exists(KB('Sales/moved'))).toBe(false);
     });
 
-    it('a denied move into a path the caller cannot read cannot be proposed, and says why', async () => {
+    it('a move into a folder the caller cannot read is refused as read_file refuses the folder, before the write verdict', async () => {
       const base = await seeded();
+      // The folder's rules are what a move preview would read back (the
+      // caller's verdicts there, who else is affected), so the read refusal
+      // comes first — not the write denial, which would say whether the path
+      // can be proposed and name the folder's contents on a collision.
       const run = await call(base, 'move_file', { src: KB('Sales/deal.md'), dest: KB('Secret/deal.md'), confirm: true });
       expect(run.status).toBe(403);
-      expect(run.body).toMatchObject({ kind: 'write-denied', canPropose: false });
+      expect(run.body.error).toContain(`permission to read "${KB('Secret')}"`);
+      expect(run.body.kind).toBeUndefined();
       expect(run.body.proposal).toBeUndefined();
-      expect(run.body.cannotProposeReason).toContain('you cannot read this path');
+      expect(await exists(KB('Sales/deal.md'))).toBe(true);
     });
 
     it('a draft branch is not write-gated, so the same move is allowed there', async () => {
@@ -4195,7 +4212,7 @@ describe('preflight for moves and deletes', () => {
       expect(d.description).toMatch(/destination must not exist/);
       // What refuses a move, and the dry-run/confirm protocol it shares with the
       // deletes, are shared rules — stated once, in the two shared places.
-      const rules = sharedFileRulesSection(testKbContext().layout);
+      const rules = sharedFileRulesSection(testKbContext().layout, testKbContext().defaultBranch);
       expect(rules).toContain('is a platform file and stays in its folder.');
       expect(rules).toContain('`dryRun: true`');
       expect(rules).toContain('`confirm: true`');
@@ -4223,9 +4240,10 @@ describe('preflight for moves and deletes', () => {
       const d = await def('delete_folder');
       expect(d.description).toContain('a non-empty folder wants `confirm: true`');
       // The protocol itself, and what a platform folder does to it, are shared.
-      const rules = sharedFileRulesSection(testKbContext().layout);
+      const rules = sharedFileRulesSection(testKbContext().layout, testKbContext().defaultBranch);
       expect(rules).toContain('`dryRun: true`');
-      expect(rules).toContain('A non-empty folder is deleted, and a move that changes your access runs, only with `confirm: true`');
+      // Anyone's: a move asks when it changes who else may open or edit the file too (`holderChanges`).
+      expect(rules).toContain("A non-empty folder is deleted, and a move that changes anyone's access runs, only with `confirm: true`");
       expect(rules).toContain('platform folder');
       const dry = await call(base, 'delete_folder', { path: KB('Sales/archive'), dryRun: true });
       const unconfirmed = await call(base, 'delete_folder', { path: KB('Sales/archive') });
@@ -4247,7 +4265,7 @@ describe('preflight for moves and deletes', () => {
       expect(stat.description).toContain('shared rules on what these tools never move or delete');
       // The proposal route applies to every tool a permission can refuse, so it
       // is stated once in the shared rules rather than on each of them.
-      expect(sharedFileRulesSection(testKbContext().layout)).toContain('`write-denied`');
+      expect(sharedFileRulesSection(testKbContext().layout, testKbContext().defaultBranch)).toContain('`write-denied`');
       for (const name of ['move_file', 'delete_file', 'delete_folder']) {
         expect((await def(name)).description.startsWith(GUIDE_FIRST_SENTENCE), name).toBe(true);
       }
@@ -4291,6 +4309,7 @@ describe('a write refused for permissions says whether and how to propose it', (
       canOwner: async () => true,
       canWriteBatchAtRef: async () => null,
       previewAccessAfterRelocation: async () => ({ read: true, write: true, download: true, owner: true }),
+      prospectiveHolderChanges: async () => NO_CHANGES,
       eligibleWritersAtRef: async () => ({ roles: ['Sales Lead'], users: [{ name: 'Owner', email: 'owner@x' }] }),
     } as unknown as IAccessControl;
     return { ac, calls };
@@ -4364,7 +4383,7 @@ describe('a write refused for permissions says whether and how to propose it', (
     await fs.writeFile(DENIED, 'old text\n');
     await freeDestinationFor(tool);
     denyWrites();
-    const workflowCalls = workspacePathCalls.length;
+    const versionControlCalls = workspacePathCalls.length;
 
     const { status, json } = await call(base, tool, body);
 
@@ -4387,12 +4406,12 @@ describe('a write refused for permissions says whether and how to propose it', (
     // The read verdict was asked of the repo-relative path.
     expect(calls).toContain('Sales/deal.md');
     // Nothing was created: no workspace was resolved for the DRAFT the answer
-    // suggests, and the context's workflow service is an empty stub, so a
+    // suggests, and the context's version-control service is an empty stub, so a
     // create_branch or change request would have 500d. (The tools that
     // preflight do resolve the CALLER's own workspace on the way — to read
     // the on-disk spelling and refuse links — which is not a draft.)
     const forDraft = workspacePathCalls
-      .slice(workflowCalls)
+      .slice(versionControlCalls)
       .filter((b) => b.includes(draft) || b.includes(encodeURIComponent(draft)));
     expect(forDraft).toEqual([]);
   });
@@ -4503,8 +4522,8 @@ describe('a write refused for permissions says whether and how to propose it', (
     // stated in the handshake instructions and in the managed guide, and in no
     // description. The refusal ITSELF still spells the steps out — that is what
     // the tests above this one assert.
-    const rule = sharedFileRules(testKbContext().layout).find((r) => r.id === 'refused-for-permissions')!;
-    expect(sharedFileRulesSection(testKbContext().layout)).toContain(rule.body);
+    const rule = sharedFileRules(testKbContext().layout, testKbContext().defaultBranch).find((r) => r.id === 'refused-for-permissions')!;
+    expect(sharedFileRulesSection(testKbContext().layout, testKbContext().defaultBranch)).toContain(rule.body);
     for (const def of tools) {
       expect(def.description ?? '', def.name).not.toContain('If this is refused for permissions');
       expect(def.description ?? '', def.name).not.toContain(rule.body);
@@ -5134,7 +5153,7 @@ describe('a move preview judges the destination as it will be', () => {
           ensureRemotesFetched: async () => undefined,
         } as unknown as WorkspaceService,
         KB_DIR,
-        new NodeFs(),
+        realDisk(),
       );
     return {
       canRead: (w: string, u: string, r: string) => fresh().canRead(w, u, r),
@@ -5146,6 +5165,7 @@ describe('a move preview judges the destination as it will be', () => {
       previewAccessAfterRelocation: (
         w: string, u: string, from: string, to: string, opts?: { sourceRemains?: boolean },
       ) => fresh().previewAccessAfterRelocation(w, u, from, to, opts),
+      prospectiveHolderChanges: (w: string, from: string, to: string) => fresh().prospectiveHolderChanges(w, from, to),
     } as unknown as IAccessControl;
   };
 
@@ -5189,6 +5209,8 @@ describe('a move preview judges the destination as it will be', () => {
     expect(dry.body).toMatchObject({ kind: 'folder', accessChanges: false, allowed: true, moved: false });
     expect(dry.body.access.after).toEqual(dry.body.access.before);
     expect(dry.body.access.after.owner).toBe(true);
+    // A rename carries its own rules along: nobody else gains or loses either.
+    expect(dry.body.holderChanges).toBeUndefined();
     // Nothing moved and nothing was written to answer the question.
     expect(await fs.exists(args.dest)).toBe(false);
     expect(await fs.exists(KB('Sales/access.md'))).toBe(true);
@@ -5213,6 +5235,91 @@ describe('a move preview judges the destination as it will be', () => {
     expect(await verbsAt(base, args.dest)).toEqual(dry.body.access.after);
   });
 
+  it('a move that changes only who ELSE may edit it names them, and asks before it moves', async () => {
+    const base = await seeded();
+    // `Ops/` gives the caller what `Sales/` gives, and Ops Lead write as well.
+    await fs.writeFile(
+      KB('Ops/access.md'),
+      rules(`write:\n  - Mover <${MOVER}>\n  - Ops Lead <ops@x.io>\nowner:\n  - Mover <${MOVER}>\n`),
+    );
+    const args = { src: KB('Sales/deal.md'), dest: KB('Ops/deal.md') };
+
+    const dry = await call(base, 'move_file', { ...args, dryRun: true });
+    expect(dry.body).toMatchObject({ accessChanges: false, allowed: true });
+    // Everyone may read on both sides, so the only change is who may edit.
+    expect(dry.body.holderChanges).toEqual({
+      lose: [],
+      gain: [{ kind: 'person', name: 'ops@x.io', email: 'ops@x.io', verb: 'write' }],
+    });
+
+    const unconfirmed = await call(base, 'move_file', args);
+    expect(unconfirmed.body).toMatchObject({ confirmationRequired: true, moved: false });
+    expect(unconfirmed.body.message).toContain('`holderChanges`');
+    expect(await fs.exists(args.src)).toBe(true);
+    expect((await call(base, 'move_file', { ...args, confirm: true })).body).toMatchObject({ moved: true });
+  });
+
+  it('a source the read hook refuses is refused as read_file refuses it: no preview, not even that the move would ask', async () => {
+    const base = await seeded();
+    await fs.writeFile(
+      KB('Ops/access.md'),
+      rules(`write:\n  - Mover <${MOVER}>\n  - Ops Lead <ops@x.io>\nowner:\n  - Mover <${MOVER}>\n`),
+    );
+    const args = { src: KB('Sales/deal.md'), dest: KB('Ops/deal.md'), rewriteLinks: false };
+    // The rules let the caller read it; a deployment's read hook does not. The
+    // hook's refusal is the whole answer: a "this move asks for confirm" would
+    // already say what the comparison found behind the hook.
+    hooks.onAgentRead(async (op) => {
+      if (op.wsPath === args.src) throw new Error('not for agents');
+    });
+    const read = await call(base, 'read_file', { path: args.src });
+    expect(read.status).toBeGreaterThanOrEqual(400);
+    for (const body of [{ ...args, dryRun: true }, args, { ...args, confirm: true }]) {
+      const res = await call(base, 'move_file', body);
+      expect(res.status).toBe(read.status);
+      expect(res.body).toEqual(read.body);
+      expect(JSON.stringify(res.body)).not.toContain('ops@x.io');
+    }
+    expect(await fs.exists(args.src)).toBe(true);
+  });
+
+  it('a caller who reads what moves but not the folder it lands in is refused, on a draft too, and told nothing of the folder', async () => {
+    const base = await seeded();
+    // `Closed/` is somebody else's: its rules are what a move preview would
+    // read back (who it lets in, whom it denies). On a draft no write gate
+    // stands, so the read gate is what refuses — before anything is looked at.
+    await fs.writeFile(
+      KB('Closed/access.md'),
+      rules('read:\n  - Other <other@x.io>\n  - deny everyone\nwrite:\n  - Other <other@x.io>\n'),
+    );
+    await fs.writeFile(KB('Closed/deal.md'), 'taken');
+    const args = { branch: 'someone/draft', src: KB('Sales/deal.md'), dest: KB('Closed/deal.md'), rewriteLinks: false };
+
+    for (const body of [{ ...args, dryRun: true }, args, { ...args, confirm: true }]) {
+      const res = await call(base, 'move_file', body);
+      expect(res.status).toBe(403);
+      expect(res.body.error).toContain(`permission to read "${KB('Closed')}"`);
+      // Neither the folder's rules nor what sits in it: the name clash at
+      // `Closed/deal.md` is never reached.
+      const text = JSON.stringify(res.body);
+      expect(text).not.toContain('other@x.io');
+      expect(text).not.toContain('already exists');
+    }
+    expect(await fs.exists(args.src)).toBe(true);
+    expect(await fs.readFile(KB('Closed/deal.md'), { encoding: 'utf8' })).toBe('taken');
+  });
+
+  it('a move out of a folder names everyone it leaves behind', async () => {
+    const base = await seeded();
+    const args = { src: KB('Work/Notes'), dest: KB('Legal/Notes') };
+    const dry = await call(base, 'move_file', { ...args, dryRun: true });
+    // Everyone may still read it in Legal/: the caller loses editing, not opening.
+    expect(dry.body.holderChanges).toEqual({
+      lose: [{ kind: 'person', name: MOVER, email: MOVER, verb: 'write' }],
+      gain: [],
+    });
+  });
+
   it('what the folder inherited is left behind; what its own access.md gives comes along', async () => {
     const base = await seeded();
     const args = { src: KB('Work/Team'), dest: KB('Legal/Team') };

package/src/modules/workspace/agent-access.gate.ts

@@ -2,7 +2,7 @@
  * Agent access gate — the per-call seam every gated agent tool runs through.
  *
  * It decides nothing of its own. It calls the hooks a DEPLOYMENT registered
- * (`WorkflowHooks`): one before an agent read of a knowledge-base path, one
+ * (`VersionControlHooks`): one before an agent read of a knowledge-base path, one
  * before an agent write. A hook that throws refuses the operation and the
  * caller sees that hook's own message and status. With no hook registered —
  * every core-only deployment — nothing is refused and nothing is recorded, and
@@ -21,7 +21,7 @@
 
 import type { JsonSchema } from '../tool-registry/index.js';
 import type { ToolContext } from '../tool-helpers/index.js';
-import type { WorkflowHooks } from '../workflow/index.js';
+import type { VersionControlHooks } from '../version-control/index.js';
 
 /**
  * What the `sessionId` input says on its own, before any deployment note. The
@@ -32,7 +32,7 @@ import type { WorkflowHooks } from '../workflow/index.js';
  * takes, so a run's reads and its questions share one conversation.
  */
 export const SESSION_ID_DESCRIPTION =
-  "This conversation's id, so the server can tell one run's calls apart. External agents (direct MCP calls and `call_tool_chain` alike): call the `start_session` tool ONCE at the very start of your work to obtain it, then pass that id here — the same id `ask` takes. The in-process agent runtime supplies this automatically (do not set it yourself).";
+  "This conversation's id: call `start_session` once, at the start of your work, and pass its id here, inside `call_tool_chain` too (and to `ask`, where the deployment offers it). The in-process agent runtime sets it itself.";
 
 /**
  * The `sessionId` input every gated tool declares. The description a MOUNTED
@@ -97,11 +97,11 @@ export interface AgentAccessGate {
   /** Lowercased email of the recovery/merge bot, which never reaches the hooks. */
   recoveryBotEmail: string;
   /**
-   * The workflow lifecycle-hook registry holding the BLOCKING `agentRead` and
+   * The version-control lifecycle-hook registry holding the BLOCKING `agentRead` and
    * `preWrite` hooks. Core registers none; a deployment registers against
-   * `workflowService.hooks` — pass that same instance here.
+   * `versionControlService.hooks` — pass that same instance here.
    */
-  hooks: WorkflowHooks;
+  hooks: VersionControlHooks;
   /** The notes a deployment adds to what agents read about these tools. */
   notes: ToolDescriptionNotes;
 }

package/src/modules/workspace/git-internals.middleware.ts

@@ -12,7 +12,7 @@ const GIT_GUARDED_QUERY_KEYS = ['path', 'toDir'] as const;
 const GIT_GUARDED_BODY_KEYS = ['path', 'oldPath', 'newPath', 'destination', 'paths', 'ancestor'] as const;
 /**
  * `from` names a PATH on the prospective-access route (`?from=<file>&toDir=…`)
- * and a BRANCH on the workflow comparison (`?from=<branch>`), so it is judged
+ * and a BRANCH on the version-control comparison (`?from=<branch>`), so it is judged
  * only where it is a path — a branch called after the git folder is refused
  * by the branch-name rule, not by this one.
  */
@@ -49,7 +49,7 @@ export function gitGuardedInputs(req: express.Request): string[] {
  * request must not make the server do.
  *
  * Mounted at the app, ahead of every router under that prefix — the file
- * routes, the review routes, the workflow and access ones, and whatever an
+ * routes, the review routes, the version-control and access ones, and whatever an
  * extension mounts — so a router added later is covered by the fact of its
  * prefix rather than by remembering this. The services underneath refuse
  * again on their own; this is what keeps the refusal ahead of the gates.

package/src/modules/workspace/kb-repository.ts

@@ -76,7 +76,7 @@ const READY_MARKER = 'hexis-repository-ready';
 /** Where a converted clone's stash and other local refs are kept, per workspace (see `importLocalRefs`). */
 export const CONVERTED_REFS = 'refs/kb-converted';
 
-/** Fallback committer identity; every workflow commit overrides it with `--author`. */
+/** Fallback committer identity; every version-control commit overrides it with `--author`. */
 const BOT_NAME = 'Bevel Workflow';
 const BOT_EMAIL = 'bevel-workflow@bevel.software';
 

package/src/modules/workspace/startup/__tests__/kb-startup-runner.degraded.test.ts

@@ -5,7 +5,7 @@ import fs from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 import { KbRemoteUnreachableError } from '../kb-startup-runner.js';
-import { NodeGitRunner } from '../../../workflow/git/node-git-runner.js';
+import { NodeGitRunner } from '../../../version-control/git/node-git-runner.js';
 import { GitRunError, NO_GIT_CREDENTIALS, type IGitRunner } from '../../../../shared/git.contract.js';
 import type { OnServerStart, ServerStartContext, StepResult } from '../on-server-start.js';
 import { newKbStartupRunner } from '../../../../__tests__/workspace-service.js';

package/src/modules/workspace/startup/__tests__/kb-startup-runner.test.ts

@@ -6,7 +6,7 @@ import { promisify } from 'node:util';
 import fs from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
-import { NodeGitRunner } from '../../../workflow/git/node-git-runner.js';
+import { NodeGitRunner } from '../../../version-control/git/node-git-runner.js';
 import { ClassifiedFailure, classifyGitFailure, failureOf } from '../../../../shared/git-failure.js';
 import { GitRunError, gitCredentials } from '../../../../shared/git.contract.js';
 import type { OnServerStart, ServerStartContext, StepResult } from '../on-server-start.js';

package/src/modules/workspace/startup/__tests__/kb-startup-runner.worktrees.test.ts

@@ -5,7 +5,7 @@ import fs from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 import { workingCopyShape } from '../../kb-repository.js';
-import { NodeGitRunner } from '../../../workflow/git/node-git-runner.js';
+import { NodeGitRunner } from '../../../version-control/git/node-git-runner.js';
 import { gitCredentials, type IGitRunner } from '../../../../shared/git.contract.js';
 import type { OnServerStart, ServerStartContext, StepResult } from '../on-server-start.js';
 import { newKbStartupRunner } from '../../../../__tests__/workspace-service.js';