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

package/src/modules/workspace/__tests__/workspace.service.unknown-branch.test.ts

@@ -1,4 +1,5 @@
 import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import fs from 'node:fs/promises';
@@ -63,7 +64,7 @@ describe('WorkspaceService — a branch origin does not have', () => {
   const deleteOnHost = (branch: string): Promise<void> => runGit(upstream, ['branch', '-D', branch]);
 
   const service = (repoUrl = upstream): WorkspaceService =>
-    new WorkspaceService(workspacesRoot, repoUrl, 'knowledge-base', new NodeFs());
+    new WorkspaceService(workspacesRoot, repoUrl, testKbContext(), new NodeFs());
 
   it('a name nothing has ever cloned or listed is a 404 that names only the branch', async () => {
     const svc = service();
@@ -76,6 +77,49 @@ describe('WorkspaceService — a branch origin does not have', () => {
     });
   });
 
+  /**
+   * The second defect on this ticket. A bootstrap that fails to clone used to
+   * leave its workspace directory behind, and a directory named after a branch
+   * is one of the ways the platform remembers having KNOWN a branch. So the
+   * first attempt at a typo answered 404 and then quietly created the evidence
+   * that turned every later attempt into 410 — the reader was told a branch
+   * they had invented "no longer exists on the remote".
+   */
+  it('leaves nothing on disk when the clone fails, so a second attempt is still a 404', async () => {
+    const svc = service();
+
+    await expect(svc.getOrCreateForBranch('nobody/never-made-this')).rejects.toMatchObject({
+      name: 'BranchNotFoundError',
+      status: 404,
+    });
+    // The failed bootstrap rolled back completely — not the clone directory,
+    // not the workspace shell around it.
+    expect(await fs.readdir(workspacesRoot)).toEqual([]);
+
+    // The same name again, on the same instance that has now already failed on
+    // it once. Nothing about the first failure may change this answer.
+    await expect(svc.getOrCreateForBranch('nobody/never-made-this')).rejects.toMatchObject({
+      name: 'BranchNotFoundError',
+      status: 404,
+      message: 'There is no branch named nobody/never-made-this.',
+      payload: { kind: 'branch-not-found', branch: 'nobody/never-made-this' },
+    });
+    expect(await fs.readdir(workspacesRoot)).toEqual([]);
+  });
+
+  it('does not count a bare directory with no clone in it as a branch it knew', async () => {
+    // A shell left by an older process (one that crashed mid-bootstrap, or that
+    // predates the rollback above). The "have I heard of this branch" probe asks
+    // for a COMPLETED clone, so a directory with no `.git` under it is absence:
+    // the honest 404 survives whatever is lying around the workspaces root.
+    await fs.mkdir(path.join(workspacesRoot, workspaceIdForBranch('nobody/never-made-this')), { recursive: true });
+
+    await expect(service().getOrCreateForBranch('nobody/never-made-this')).rejects.toMatchObject({
+      name: 'BranchNotFoundError',
+      status: 404,
+    });
+  });
+
   it('a name a listing showed us, and origin no longer has, stays a 410', async () => {
     const svc = service();
     // What the branch selector saw while the draft still existed.

package/src/modules/workspace/__tests__/workspace.tools.agents-file.test.ts

@@ -2,7 +2,8 @@ import express from 'express';
 import { afterEach, describe, expect, it } from 'vitest';
 import { join } from 'node:path';
 import { tmpdir } from 'node:os';
-import { DEFAULT_KB_LAYOUT, configureKbLayout } from '@bevel-software/platform-shared';
+import { DEFAULT_KB_LAYOUT } from '@bevel-software/platform-shared';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 import { ToolRegistry } from '../../tool-registry/tool-registry.js';
 import { createToolHandlerFactory } from '../../tool-helpers/tool-handler.js';
 import type { ToolAuth } from '../../tool-auth/tool-auth.middleware.js';
@@ -24,6 +25,8 @@ import { registerWorkspaceTools } from '../workspace.tools.js';
  * for it.
  */
 const KB_DIR = 'knowledge-base';
+/** The context the tools read; a case applies a deployment's own names to it. */
+const kb = testKbContext({ kbDirName: KB_DIR });
 
 /** Every workspace tool's description, keyed by name, under the layout in effect. */
 async function descriptions(registry: ToolRegistry = new ToolRegistry()): Promise<Map<string, string>> {
@@ -37,11 +40,11 @@ async function descriptions(registry: ToolRegistry = new ToolRegistry()): Promis
     new SpillStore(join(tmpdir(), 'bevel-test-spills')),
     new DocExtractService(join(tmpdir(), 'bevel-test-doc-extract')),
     {} as unknown as IAccessControl,
-    KB_DIR,
+    kb,
     {
       service: {} as never,
       enabled: false,
-      kbDirName: KB_DIR,
+      kb,
       recoveryBotEmail: 'recovery-bot@bevel.local',
       hooks: new WorkflowHooks(),
     },
@@ -57,7 +60,7 @@ async function listed(registry: ToolRegistry): Promise<Map<string, string>> {
   return new Map(tools.map((t) => [t.name, t.description ?? '']));
 }
 
-afterEach(() => configureKbLayout({ ...DEFAULT_KB_LAYOUT }));
+afterEach(() => kb.applyLayout({ ...DEFAULT_KB_LAYOUT }));
 
 describe('the conventions note every workspace tool carries', () => {
   it('names AGENTS.md, and CLAUDE.md beside it, under the default name', async () => {
@@ -71,7 +74,7 @@ describe('the conventions note every workspace tool carries', () => {
   });
 
   it('names the configured file first and the organisation\'s own AGENTS.md second', async () => {
-    configureKbLayout({ ...DEFAULT_KB_LAYOUT, agentsFile: 'HEXIS.md' });
+    kb.applyLayout({ ...DEFAULT_KB_LAYOUT, agentsFile: 'HEXIS.md' });
     const byName = await descriptions();
     const note = byName.get('grep') ?? '';
     expect(note).toContain('read `HEXIS.md` at the KB root, then `AGENTS.md` if it also exists');
@@ -83,7 +86,7 @@ describe('the conventions note every workspace tool carries', () => {
   });
 
   it('describes the platform files under the configured name, and no longer under AGENTS.md', async () => {
-    configureKbLayout({ ...DEFAULT_KB_LAYOUT, agentsFile: 'HEXIS.md' });
+    kb.applyLayout({ ...DEFAULT_KB_LAYOUT, agentsFile: 'HEXIS.md' });
     const byName = await descriptions();
     const stat = byName.get('file_stat') ?? '';
     expect(stat).toContain('`access.md`, `roles.yaml`, `.bevelignore`, `HEXIS.md`');
@@ -117,7 +120,7 @@ describe('the conventions note every workspace tool carries', () => {
     const atMount = await descriptions(registry);
     expect(atMount.get('grep')).toContain('read `AGENTS.md` at the KB root');
 
-    configureKbLayout({ ...DEFAULT_KB_LAYOUT, agentsFile: 'HEXIS.md' });
+    kb.applyLayout({ ...DEFAULT_KB_LAYOUT, agentsFile: 'HEXIS.md' });
 
     const now = await listed(registry);
     expect(now.get('grep')).toContain('read `HEXIS.md` at the KB root, then `AGENTS.md` if it also exists');

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

@@ -1,11 +1,16 @@
 import type { Server as HttpServer } from 'node:http';
 import { execFile } from 'node:child_process';
-import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { mkdir, mkdtemp, readdir, rm, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { promisify } from 'node:util';
 import express from 'express';
 import { afterEach, describe, expect, it } from 'vitest';
+import '@utcp/http'; // registers the http CallTemplate serializer + protocol
+import { UtcpManualSerializer } from '@utcp/sdk';
+import { HttpCallTemplateSerializer } from '@utcp/http';
+import { CodeModeUtcpClient } from '../../code-mode/index.js';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 import { NodeFs } from '../../kb-fs/node-fs.js';
 import { ToolRegistry } from '../../tool-registry/tool-registry.js';
 import { createToolHandlerFactory } from '../../tool-helpers/tool-handler.js';
@@ -85,7 +90,12 @@ describe('workspace tools — a branch that cannot be opened', () => {
    * real tool-context resolver — so a tool call clones (or fails to clone)
    * exactly as it does in production.
    */
-  async function start(opts: { repoUrl?: 'origin' | 'unreachable' } = {}): Promise<string> {
+  /** The tool defs the mounted registry serves, kept for the sweep below. */
+  let internalTools: { name: string; inputs: unknown }[] = [];
+
+  async function start(
+    opts: { repoUrl?: 'origin' | 'unreachable'; scope?: 'read' | 'write'; source?: 'internal' | 'external' } = {},
+  ): Promise<string> {
     root = await mkdtemp(join(tmpdir(), 'ws-tools-branch-'));
     spillRoot = await mkdtemp(join(tmpdir(), 'ws-tools-spill-'));
     docCacheDir = await mkdtemp(join(tmpdir(), 'ws-tools-doc-'));
@@ -109,7 +119,7 @@ describe('workspace tools — a branch that cannot be opened', () => {
     workspaces = new WorkspaceService(
       workspacesRoot,
       opts.repoUrl === 'unreachable' ? join(root, 'no-such-repo.git') : upstream,
-      KB_DIR,
+      testKbContext({ kbDirName: KB_DIR }),
       new NodeFs(),
     );
 
@@ -127,22 +137,44 @@ describe('workspace tools — a branch that cannot be opened', () => {
     const app = express();
     app.use(express.json());
     const router = express.Router();
+    const registry = new ToolRegistry();
+    // The internal discovery endpoint, exactly as `manual.routes` serves it —
+    // what a real `CodeModeUtcpClient` reads to learn the tools it can call
+    // from inside a chain. Served here so the chain test below drives the SAME
+    // routes as every direct call in this file.
+    router.get('/agent/internal/utcp', async (_req, res) => {
+      res.json(
+        new UtcpManualSerializer().validateDict({
+          utcp_version: '1.1.0',
+          manual_version: '1.0.0',
+          tools: await registry.listInternal(),
+        }),
+      );
+    });
     registerWorkspaceTools(
-      new ToolRegistry(),
+      registry,
       router,
       (req: express.Request, _res: express.Response, next: express.NextFunction) => {
-        req.toolAuth = { source: 'external', userId: 'u', scope: 'read' } as ToolAuth;
+        req.toolAuth = {
+          // The sweep below asks for `internal` + `write`, which is what reaches
+          // the internal-only tools and gets past the write-scope refusal that
+          // sits in FRONT of every handler. Everything else in this file stays
+          // on the external read surface the bug was reported from.
+          source: opts.source ?? 'external',
+          userId: 'u',
+          scope: opts.scope ?? 'read',
+        } as ToolAuth;
         next();
       },
       createToolHandlerFactory(resolve),
       new SpillStore(spillRoot),
       new DocExtractService(docCacheDir),
       allowAll,
-      KB_DIR,
+      testKbContext({ kbDirName: KB_DIR }),
       {
         service: {} as never,
         enabled: false,
-        kbDirName: KB_DIR,
+        kb: testKbContext({ kbDirName: KB_DIR }),
         recoveryBotEmail: 'recovery-bot@bevel.local',
         hooks: new WorkflowHooks(),
       },
@@ -150,21 +182,34 @@ describe('workspace tools — a branch that cannot be opened', () => {
       {} as never,
     );
     app.use('/api', router);
+    internalTools = (await registry.listInternal()) as unknown as { name: string; inputs: unknown }[];
     httpServer = await new Promise<HttpServer>((r) => {
       const s = app.listen(0, () => r(s));
     });
     return `http://127.0.0.1:${(httpServer.address() as { port: number }).port}`;
   }
 
-  const listFiles = async (base: string, branch: string): Promise<{ status: number; body: Record<string, unknown> }> => {
-    const res = await fetch(`${base}/api/agent/tools/list_files`, {
+  /** Call a tool with an arbitrary body — including one that omits `branch`. */
+  const callTool = async (
+    base: string,
+    tool: string,
+    body: unknown,
+  ): Promise<{ status: number; body: Record<string, unknown> }> => {
+    const res = await fetch(`${base}/api/agent/tools/${tool}`, {
       method: 'POST',
       headers: { 'content-type': 'application/json', authorization: 'Bearer x' },
-      body: JSON.stringify({ branch, path: '' }),
+      body: JSON.stringify(body),
     });
     return { status: res.status, body: (await res.json()) as Record<string, unknown> };
   };
 
+  const listFiles = async (base: string, branch: string): Promise<{ status: number; body: Record<string, unknown> }> =>
+    callTool(base, 'list_files', { branch, path: '' });
+
+  /** Every entry currently under the workspaces root. */
+  const workspaceDirs = async (): Promise<string[]> =>
+    (await readdir(join(root, 'workspaces'))).sort();
+
   const deleteOnHost = (branch: string): Promise<void> =>
     runGit(join(root, 'upstream.git'), ['branch', '-D', branch]);
 
@@ -181,6 +226,188 @@ describe('workspace tools — a branch that cannot be opened', () => {
     });
   });
 
+  /**
+   * The reported bug, from the outside: every tool call made without a
+   * `branch` answered `Branch "undefined" no longer exists on the remote.` —
+   * the missing input was carried all the way down, turned into a workspace
+   * directory named `undefined`, and the failed clone of that "branch" was
+   * then explained as a branch that had been deleted.
+   *
+   * The input is refused BY NAME instead, at the boundary, before any of that
+   * can happen. `list_files` stands in for every knowledge-base tool here
+   * because they share the one choke point (`getFilesystem`) — the refusal is
+   * the context resolver's, not this tool's.
+   */
+  describe('a call that names no branch', () => {
+    // Every shape of "the caller sent no branch". The literals are in here
+    // because a client that interpolates a variable it never set sends the
+    // STRING "undefined" — indistinguishable, in intent, from omitting it, and
+    // the one value that must never reach a clone.
+    const absent: Array<[label: string, body: Record<string, unknown>]> = [
+      ['the field is missing entirely', { path: '' }],
+      ['the field is empty', { branch: '', path: '' }],
+      ['the field is null', { branch: null, path: '' }],
+      ['the field is a number', { branch: 42, path: '' }],
+      ['the field is an object', { branch: { name: 'main' }, path: '' }],
+      ['the field is an array', { branch: ['main'], path: '' }],
+      ['the field is the literal "undefined"', { branch: 'undefined', path: '' }],
+      ['the field is the literal "null"', { branch: 'null', path: '' }],
+    ];
+
+    for (const [label, body] of absent) {
+      it(`400s branch-required when ${label}`, async () => {
+        const base = await start();
+
+        const res = await callTool(base, 'list_files', body);
+
+        expect(res.status).toBe(400);
+        expect(res.body).toEqual({
+          kind: 'branch-required',
+          error: '`branch` is required: pass the branch (draft) you are working on.',
+        });
+        // The refusal is the whole story: nothing was created and nothing was
+        // cloned. An empty workspaces root is the strongest form of that
+        // claim — there is no directory named for any branch, least of all one
+        // named `undefined`.
+        expect(await workspaceDirs()).toEqual([]);
+      });
+    }
+
+    it('never writes `undefined` or `null` as a branch name into the answer', async () => {
+      const base = await start();
+
+      const res = await callTool(base, 'list_files', { path: '' });
+
+      // AC3, checked against the whole response rather than one field: the
+      // message names the INPUT and what to pass, never a stringified value of
+      // what was missing. `Branch "undefined" no longer exists` is exactly the
+      // sentence this must never produce again.
+      const serialized = JSON.stringify(res.body);
+      expect(serialized).not.toContain('undefined');
+      expect(serialized).not.toContain('null');
+    });
+
+    /**
+     * `call_tool_chain` is the other way every one of these tools gets called,
+     * and it is where the bug was reported from just as often. It is not a
+     * second implementation to guard: the chain's UTCP http transport POSTs to
+     * the SAME `/agent/tools/...` route this file has been calling directly, so
+     * the one refusal covers both. This test is what proves that claim rather
+     * than assuming it — with a real `CodeModeUtcpClient` reading a real
+     * manual and running real JavaScript.
+     */
+    it('400s branch-required from inside call_tool_chain, and creates no workspace', async () => {
+      const base = await start();
+      const client = await CodeModeUtcpClient.create(process.cwd(), {
+        variables: { bevel_API_URL: base, bevel_CONNECTION_KEY: 'internal-token' },
+      } as never);
+      await client.registerManual(
+        new HttpCallTemplateSerializer().validateDict({
+          name: 'bevel',
+          call_template_type: 'http',
+          http_method: 'GET',
+          url: '${API_URL}/api/agent/internal/utcp',
+          content_type: 'application/json',
+          headers: { Authorization: 'Bearer ${CONNECTION_KEY}' },
+        }),
+      );
+
+      // The exact call from the specification: a chain that names the path and
+      // forgets the branch. The tool THROWS inside the chain, so the failure is
+      // caught and its message returned — the runtime's own contract for
+      // surfacing a tool error to the model.
+      const { result } = await client.callToolChain(
+        `try { return { ok: bevel.list_files({ body: { path: 'knowledge-base' } }) }; }
+         catch (err) { return { failed: err.message }; }`,
+        30_000,
+      );
+
+      // The tool did not run.
+      expect(result.ok).toBeUndefined();
+      // The message the chain hands the model carries the whole refusal: the
+      // status, the sentence, and the `kind` the direct caller switches on.
+      // (The status and payload are IN the message rather than on the thrown
+      // object — the sandboxed error exposes no own properties — which is why
+      // this asserts on the text the model actually reads.)
+      expect(result.failed).toContain('HTTP 400');
+      expect(result.failed).toContain('`branch` is required: pass the branch (draft) you are working on.');
+      expect(result.failed).toContain('"kind":"branch-required"');
+      // Not the sentence the bug produced — and no invented branch name in it.
+      expect(result.failed).not.toContain('no longer exists');
+      expect(result.failed).not.toContain('undefined');
+      // And the chain path refuses just as early: nothing was cloned.
+      expect(await workspaceDirs()).toEqual([]);
+    });
+
+    /**
+     * AC1 says "any knowledge-base tool", so this asserts it of EVERY tool the
+     * module mounts rather than of the one this file otherwise drives. The list
+     * comes from the registry, so a tool added later is swept in automatically
+     * and cannot quietly reintroduce the bug on its own route. The guard runs
+     * ahead of every other check, which is what lets one empty body stand in
+     * for a valid call to each of them.
+     */
+    it('400s branch-required on every mounted tool that declares `branch`', async () => {
+      const base = await start({ source: 'internal', scope: 'write' });
+      const declaresBranch = internalTools
+        .filter((t) => {
+          const body = (t.inputs as { properties?: { body?: { required?: string[] } } }).properties?.body;
+          return (body?.required ?? []).includes('branch');
+        })
+        .map((t) => t.name);
+
+      // The whole branch-taking surface, not a sample of it.
+      expect(declaresBranch.length).toBeGreaterThan(10);
+
+      for (const tool of declaresBranch) {
+        const res = await callTool(base, tool, {});
+        expect(res.status, `${tool} must 400 on a branch-less call`).toBe(400);
+        expect(res.body.kind, `${tool} must answer kind branch-required`).toBe('branch-required');
+        // No tool's refusal may name the value it did not get.
+        expect(JSON.stringify(res.body), `${tool} must not echo an absent value`).not.toContain('undefined');
+      }
+      expect(await workspaceDirs()).toEqual([]);
+    });
+
+    it('still serves the same tool once a branch is named', async () => {
+      const base = await start();
+      // The guard refuses an absent input, not the tool: the same call with a
+      // real branch works, so the refusal cannot be a tool that simply broke.
+      expect((await callTool(base, 'list_files', { path: '' })).status).toBe(400);
+
+      const { status, body } = await listFiles(base, 'alice/draft');
+
+      expect(status).toBe(200);
+      expect((body.entries as { name: string }[]).map((e) => e.name)).toContain(KB_DIR);
+    });
+  });
+
+  /**
+   * The second half of the bug: a bootstrap that failed to clone used to leave
+   * a directory behind, and a directory named after a branch is how the
+   * platform remembers having known one. The first attempt's leftovers turned
+   * the second attempt's honest "no such branch" into "it was deleted".
+   */
+  it('answers 404 again on a second attempt at a name that never existed', async () => {
+    const base = await start();
+
+    const first = await listFiles(base, 'nobody/never-made-this');
+    expect(first.status).toBe(404);
+    // Nothing survived the failed clone — not the repo directory, not the
+    // workspace shell around it. This is what keeps the next attempt honest.
+    expect(await workspaceDirs()).toEqual([]);
+
+    const second = await listFiles(base, 'nobody/never-made-this');
+
+    expect(second.status).toBe(404);
+    expect(second.body).toEqual({
+      kind: 'branch-not-found',
+      branch: 'nobody/never-made-this',
+      error: 'There is no branch named nobody/never-made-this.',
+    });
+    expect(await workspaceDirs()).toEqual([]);
+  });
+
   it('410s a branch a listing showed us and origin no longer has', async () => {
     const base = await start();
     workspaces!.noteBranchesListed(['target-company-state', 'alice/draft']);

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

@@ -7,6 +7,7 @@ import { promisify } from 'node:util';
 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 { LocalFilesystem } from '@mastra/core/workspace';
 import { ToolRegistry } from '../../tool-registry/tool-registry.js';
 import { createToolHandlerFactory } from '../../tool-helpers/tool-handler.js';
@@ -218,10 +219,10 @@ async function start(
   const app = express();
   app.use(express.json());
   const router = express.Router();
-  registerWorkspaceTools(registry, router, fakeAuth, toolHandler, new SpillStore(join(tmpdir(), 'bevel-test-spills')), new DocExtractService(docCacheDir), access, KB_DIR, {
+  registerWorkspaceTools(registry, router, fakeAuth, toolHandler, new SpillStore(join(tmpdir(), 'bevel-test-spills')), new DocExtractService(docCacheDir), access, testKbContext({ kbDirName: KB_DIR }), {
     service: {} as never,
     enabled: false, // these tests predate and don't exercise the ontology boundary
-    kbDirName: KB_DIR,
+    kb: testKbContext({ kbDirName: KB_DIR }),
     recoveryBotEmail: 'recovery-bot@bevel.local',
     hooks: new WorkflowHooks(),
   }, writePolicy, {} as never /* sessionSink — start_session not exercised here */);
@@ -232,9 +233,24 @@ async function start(
   return `http://127.0.0.1:${(httpServer.address() as { port: number }).port}`;
 }
 
-const post = (url: string, body: unknown = {}) =>
+/** POST a body EXACTLY as given — for the tests about a malformed call. */
+const postRaw = (url: string, body: unknown = {}) =>
   fetch(url, { method: 'POST', headers: { 'content-type': 'application/json', authorization: 'Bearer x' }, body: JSON.stringify(body) });
 
+/**
+ * POST a well-formed call. Every KB tool requires `branch` — a call that names
+ * none is refused at the mount with 400 `branch-required` — so this names one
+ * unless the test already did. A test ABOUT the missing input uses `postRaw`,
+ * so the thing under test is never papered over by the helper.
+ */
+const post = (url: string, body: unknown = {}) =>
+  postRaw(
+    url,
+    body !== null && typeof body === 'object' && !Array.isArray(body) && !('branch' in body)
+      ? { branch: 'main', ...body }
+      : body,
+  );
+
 beforeEach(() => {
   /* fresh per test via start() */
 });
@@ -455,7 +471,8 @@ describe('workspace file primitives', () => {
     // named "undefined" — it fails closed with a clear 4xx naming the missing
     // branch context, BEFORE any workspace resolve.
     expect(focusedBranch).toBeUndefined();
-    const res = await post(`${base}/api/agent/tools/execute_command`, { command: 'echo should-not-run' });
+    // `postRaw`: the absent field IS the test here, so the body goes as written.
+    const res = await postRaw(`${base}/api/agent/tools/execute_command`, { command: 'echo should-not-run' });
     expect(res.status).toBe(400);
     expect((await res.json()).error).toMatch(/branch/i);
     // The guard runs before `getOrCreateForBranch`, so no workspace (least of all
@@ -470,7 +487,7 @@ describe('workspace file primitives', () => {
     // against that branch's workspace and returns output end to end (AC2) —
     // rather than failing closed the way a context-less external call does.
     focusedBranch = 'main';
-    const res = (await (await post(`${base}/api/agent/tools/execute_command`, { command: 'echo hello-exec' })).json()) as { stdout: string; exitCode: number };
+    const res = (await (await postRaw(`${base}/api/agent/tools/execute_command`, { command: 'echo hello-exec' })).json()) as { stdout: string; exitCode: number };
     expect(res.exitCode).toBe(0);
     expect(res.stdout).toContain('hello-exec');
     // Resolved against the focused branch — never an "undefined" workspace.
@@ -554,6 +571,20 @@ describe('workspace file primitives', () => {
     expect(workspacePathCalls).toEqual([]);
   });
 
+  it('answers a branch-less call with the same kind every other KB tool uses', async () => {
+    const base = await start();
+    // The MESSAGE here is this tool's own — only `execute_command` has a
+    // focused-branch fallback to explain. The DISCRIMINATOR is shared, so a
+    // client switches on one kind across the whole surface instead of matching
+    // prose per tool.
+    for (const body of [{ command: 'x' }, { branch: '', command: 'x' }, { branch: 'undefined', command: 'x' }]) {
+      const res = await postRaw(`${base}/api/agent/tools/execute_command`, body);
+      expect(res.status).toBe(400);
+      expect((await res.json()).kind).toBe('branch-required');
+    }
+    expect(workspacePathCalls).toEqual([]);
+  });
+
   it('execute_command validates the branch BEFORE the write-policy gate', async () => {
     const base = await start();
     // A routine-restricted session is refused by `assertUnrestricted` with 403.
@@ -1831,8 +1862,8 @@ describe('start_session', () => {
     const router = express.Router();
     registerWorkspaceTools(
       registry, router, auth, toolHandler,
-      new SpillStore(join(tmpdir(), 'bevel-test-spills')), new DocExtractService(join(tmpdir(), 'bevel-test-doc-extract')), allowAll, KB_DIR,
-      { service: {} as never, enabled: false, kbDirName: KB_DIR, recoveryBotEmail: 'recovery-bot@bevel.local', hooks: new WorkflowHooks() },
+      new SpillStore(join(tmpdir(), 'bevel-test-spills')), new DocExtractService(join(tmpdir(), 'bevel-test-doc-extract')), allowAll, testKbContext({ kbDirName: KB_DIR }),
+      { service: {} as never, enabled: false, kb: testKbContext({ kbDirName: KB_DIR }), recoveryBotEmail: 'recovery-bot@bevel.local', hooks: new WorkflowHooks() },
       new RoutineWritePolicyService(),
       sink ?? fakeSessionSink,
     );
@@ -1956,8 +1987,8 @@ describe('start_session', () => {
     const noopAuth: express.RequestHandler = (_req, _res, next) => next();
     registerWorkspaceTools(
       registry, router, noopAuth, (() => () => {}) as never,
-      new SpillStore(join(tmpdir(), 'bevel-test-spills')), new DocExtractService(join(tmpdir(), 'bevel-test-doc-extract')), allowAll, KB_DIR,
-      { service: {} as never, enabled: false, kbDirName: KB_DIR, recoveryBotEmail: 'recovery-bot@bevel.local', hooks: new WorkflowHooks() },
+      new SpillStore(join(tmpdir(), 'bevel-test-spills')), new DocExtractService(join(tmpdir(), 'bevel-test-doc-extract')), allowAll, testKbContext({ kbDirName: KB_DIR }),
+      { service: {} as never, enabled: false, kb: testKbContext({ kbDirName: KB_DIR }), recoveryBotEmail: 'recovery-bot@bevel.local', hooks: new WorkflowHooks() },
       new RoutineWritePolicyService(),
       {} as never,
     );
@@ -1998,8 +2029,8 @@ describe('branch is a required parameter in the tool contract', () => {
       new SpillStore(join(tmpdir(), 'bevel-test-spills')),
       new DocExtractService(join(tmpdir(), 'bevel-test-doc-extract')),
       allowAll,
-      KB_DIR,
-      { service: {} as never, enabled: false, kbDirName: KB_DIR, recoveryBotEmail: 'recovery-bot@bevel.local', hooks: new WorkflowHooks() },
+      testKbContext({ kbDirName: KB_DIR }),
+      { service: {} as never, enabled: false, kb: testKbContext({ kbDirName: KB_DIR }), recoveryBotEmail: 'recovery-bot@bevel.local', hooks: new WorkflowHooks() },
       new RoutineWritePolicyService(),
       {} as never,
     );
@@ -2265,6 +2296,8 @@ describe('the tools place an unprefixed path inside the repository', () => {
 describe('folders never vanish', () => {
   const KB = (p: string) => `${KB_DIR}/${p}`;
   const tool = async (base: string, name: string, body: Record<string, unknown>) => {
+    // `post` names the branch every KB tool requires; these tests are about
+    // folders, not about the branch input.
     const res = await post(`${base}/api/agent/tools/${name}`, body);
     return { status: res.status, body: (await res.json()) as Record<string, unknown> };
   };

package/src/modules/workspace/__tests__/write-denial.test.ts

@@ -1,4 +1,5 @@
 import { describe, it, expect, vi } from 'vitest';
+import { testKbContext } from '../../../__tests__/kb-context.js';
 import { writeDenial } from '../write-denial.js';
 import { AccessDeniedError } from '../../access-model/access-errors.js';
 import type { ChangeReadVerdict, IChangeReadGate } from '../../access-model/change-gate.js';
@@ -34,7 +35,7 @@ describe('writeDenial asks the read gate about the refused path as the refuser s
       eligibleUsers: [],
       targetKind: 'dir',
     });
-    const out = await writeDenial(err, INPUT, noAccess, KB, gate);
+    const out = await writeDenial(err, INPUT, noAccess, testKbContext({ kbDirName: KB }), gate);
     expect(judge).toHaveBeenCalledWith(
       'target-company-state',
       'alice@example.com',
@@ -48,7 +49,7 @@ describe('writeDenial asks the read gate about the refused path as the refuser s
   it('a refusal that says nothing about its kind is judged as a file', async () => {
     const { gate, judge } = gateThat({ allowed: false, unreadable: 'KnowledgeBase' });
     const err = new AccessDeniedError({ path: `${KB}/KnowledgeBase/loose.md`, eligibleRoles: [], eligibleUsers: [] });
-    const out = await writeDenial(err, INPUT, noAccess, KB, gate);
+    const out = await writeDenial(err, INPUT, noAccess, testKbContext({ kbDirName: KB }), gate);
     expect(judge).toHaveBeenCalledWith(expect.any(String), 'alice@example.com', `${KB}/KnowledgeBase/loose.md`, 'file');
     expect(out.details).toMatchObject({
       kind: 'write-denied',
@@ -60,7 +61,7 @@ describe('writeDenial asks the read gate about the refused path as the refuser s
   it('without a gate the read verdict alone decides, as before', async () => {
     const accessControl = { canRead: vi.fn(async () => true) } as unknown as IAccessControl;
     const err = new AccessDeniedError({ path: `${KB}/KnowledgeBase/Sales/deal.md`, eligibleRoles: [], eligibleUsers: [] });
-    const out = await writeDenial(err, INPUT, accessControl, KB);
+    const out = await writeDenial(err, INPUT, accessControl, testKbContext({ kbDirName: KB }));
     expect(accessControl.canRead).toHaveBeenCalledWith('target-company-state', 'alice@example.com', 'KnowledgeBase/Sales/deal.md');
     expect(out.details).toMatchObject({ kind: 'write-denied', canPropose: true });
   });
@@ -68,7 +69,7 @@ describe('writeDenial asks the read gate about the refused path as the refuser s
   it('a gate that cannot answer refuses to offer the route', async () => {
     const gate: IChangeReadGate = { judge: vi.fn(async () => { throw new Error('git down'); }), assertMayChange: vi.fn() };
     const err = new AccessDeniedError({ path: `${KB}/KnowledgeBase/Sales/deal.md`, eligibleRoles: [], eligibleUsers: [] });
-    const out = await writeDenial(err, INPUT, noAccess, KB, gate);
+    const out = await writeDenial(err, INPUT, noAccess, testKbContext({ kbDirName: KB }), gate);
     expect(out.details).toMatchObject({ canPropose: false });
     expect(out.details?.cannotProposeReason).toContain('could not be determined');
   });