@bevel-software/platform-core-backend 0.21.0 → 0.23.0

package/src/modules/workflow/agent-tools/workflow.tools.ts

@@ -5,9 +5,16 @@ import { toolDef, withBranchInput } from '../../tool-helpers/tool-def.js';
 import type { ToolHandlerFactory } from '../../tool-helpers/tool-handler.js';
 import { requireInternalSource } from '../../tool-auth/tool-auth.middleware.js';
 import type { KbContext } from '../../../shared/kb-context.js';
+import { assertBranchProvided } from '../../../shared/domain-errors.js';
 import { workspaceIdForBranch } from '../../../shared/workspace-id.js';
 import { assertInsideRepo, normalizePathArgs } from '../../kb-fs/repo-path.js';
 import { RETIRED_TOOL_MESSAGES } from '@bevel-software/platform-mcp-core';
+import {
+  CHANGE_REQUEST_INCLUDES,
+  CHANGE_REQUEST_PATH_LIMIT,
+  parseInclude,
+  summarizeChangeRequest,
+} from './change-request-summary.js';
 
 /** `knowledge-base/KnowledgeBase/x.md` → `KnowledgeBase/x.md`; anything else unchanged. */
 function stripKbDir(path: string, kbDirName: string): string {
@@ -46,20 +53,31 @@ const commitSchema: JsonSchema = {
   required: ['authorName', 'authorEmail', 'sha', 'subject', 'committedAt'],
 };
 
-const changeRequestFileSchema: JsonSchema = {
+const changeRequestSummaryFileSchema: JsonSchema = {
   type: 'object',
   properties: {
     path: { type: 'string' },
-    previousPath: { type: 'string', description: 'Set for renames/copies.' },
-    status: { type: 'string', description: '`added` | `modified` | `removed` | `renamed` | `copied` | `changed` | `unchanged`.' },
-    additions: { type: 'integer' },
-    deletions: { type: 'integer' },
-    patch: { type: 'string', description: 'Unified diff; absent for binary or oversized files.' },
-    isBinary: { type: 'boolean' },
-    sha: { type: 'string', description: 'Blob SHA at the change-request head.' },
-    rawUrl: { type: 'string' },
+    change: { type: 'string', description: '`added` | `changed` | `deleted` | `moved`.' },
+    previousPath: { type: 'string', description: 'Where a `moved` file came from.' },
+    patch: {
+      type: 'string',
+      description: 'Unified diff. Only with `include: ["patches"]`, and absent for a binary or oversized file.',
+    },
+  },
+  required: ['path', 'change'],
+};
+
+const changeRequestApproversSchema: JsonSchema = {
+  type: 'object',
+  properties: {
+    path: { type: 'string' },
+    roles: { type: 'array', items: { type: 'string' }, description: 'Roles that confer approval here; `everyone` means any signed-in approver.' },
+    users: { type: 'array', items: { type: 'string' }, description: 'Approvers named directly, by display name.' },
+    approved: { type: 'boolean', description: 'True once an eligible approver has approved at the current head.' },
+    inMergeGate: { type: 'boolean', description: 'False when the merge gate does not bind this path — then nobody has to approve it.' },
+    approversUnknown: { type: 'boolean', description: 'Present when the access tree could not be resolved: empty `roles`/`users` means unknown, not nobody.' },
   },
-  required: ['path', 'status', 'additions', 'deletions', 'isBinary', 'sha', 'rawUrl'],
+  required: ['path', 'roles', 'users', 'approved', 'inMergeGate'],
 };
 
 const commentSchema: JsonSchema = {
@@ -98,24 +116,43 @@ function linkOf(cr: { number: number; url: string; urlNote?: string }): { number
   return { number: cr.number, url: cr.url, ...(cr.urlNote ? { urlNote: cr.urlNote } : {}) };
 }
 
-const changeRequestDetailSchema: JsonSchema = {
+/**
+ * What `open_change_request` answers: a summary, `url` first, with no patch and
+ * no file content. The app's dialog reads the full detail from its own route;
+ * handing that to an agent cost ~445,000 characters for 27 files of 15 KB and
+ * overflowed every tool-result limit. Built by `summarizeChangeRequest`.
+ *
+ * Property order is the answer's field order, and `url` leads it: the link is
+ * the one field the agent must hand the user, so it must survive any truncation.
+ */
+const changeRequestSummarySchema: JsonSchema = {
   type: 'object',
-  description: 'Full change-request detail (aliased from the underlying pull request).',
   properties: {
-    number: { type: 'integer' },
     url: changeRequestUrlSchema,
     urlNote: changeRequestUrlNoteSchema,
+    number: { type: 'integer' },
     title: { type: 'string' },
-    body: { type: 'string' },
-    author: { type: 'object', properties: { login: { type: 'string' }, name: { type: 'string' } }, required: ['login'] },
-    headSha: { type: 'string' },
-    baseSha: { type: 'string' },
-    files: { type: 'array', items: changeRequestFileSchema },
-    comments: { type: 'array', items: commentSchema },
-    approvals: { type: 'array', items: { type: 'object', additionalProperties: true }, description: 'Per-file approval state, one entry per file in `files`.' },
+    state: { type: 'string', description: '`open` | `merged` | `closed`.' },
+    sourceBranch: { type: 'string', description: 'The draft branch carrying the changes.' },
+    targetBranch: { type: 'string', description: 'The branch the changes apply to.' },
+    approvals: {
+      type: 'array',
+      items: changeRequestApproversSchema,
+      description: 'Who must approve, one entry per listed file. A file nobody can approve (`inMergeGate: false`) blocks nothing.',
+    },
+    mergeBlockedReasons: {
+      type: 'array',
+      items: { type: 'string' },
+      description: 'What blocks the merge — every missing approval, whether its file is listed or cut. Empty when nothing blocks.',
+    },
+    files: {
+      type: 'array',
+      items: changeRequestSummaryFileSchema,
+      description: `The changed paths with their kind of change, cut to ${CHANGE_REQUEST_PATH_LIMIT}; \`include: ["all-paths"]\` lists them all.`,
+    },
+    totalFiles: { type: 'integer', description: 'How many files the request changes in total, cut or not.' },
   },
-  required: ['number', 'url', 'title', 'body', 'headSha', 'baseSha', 'files', 'comments', 'approvals'],
-  additionalProperties: true,
+  required: ['url', 'number', 'title', 'state', 'sourceBranch', 'targetBranch', 'approvals', 'mergeBlockedReasons', 'files', 'totalFiles'],
 };
 
 /**
@@ -144,16 +181,30 @@ export function registerWorkflowTools(
     write: boolean;
     /** Register on the internal catalog only (e.g. agent-control tools that make no sense to a remote caller). */
     internalOnly?: boolean;
-    /** Skip the auto-injected `branch` input — for a tool that already declares its own `branch` (switch_branch). */
+    /**
+     * Skip the auto-injected `branch` input — for a tool that declares its own
+     * `branch` with its own meaning (`create_branch`'s fork base,
+     * `switch_branch`'s target draft) or none at all (`merge_branch`,
+     * `open_change_request`, the repo-global reads). It says NOTHING about
+     * whether the tool requires a branch: that is read off the declared schema
+     * below, because reading it off this flag is what let `create_branch` opt
+     * out of the check while still demanding the input.
+     */
     skipBranch?: boolean;
     handler: ToolHandler;
   }): void => {
     const path = `/api/agent/tools/${spec.name}`;
+    const inputs = spec.skipBranch ? spec.inputs : withBranchInput(spec.inputs);
+    // The tool's OWN declaration is the only honest answer to "must this call
+    // name a branch": the injected input and a hand-declared one (the fork
+    // base, the draft to switch to) are equally required, and a tool that adds
+    // or drops the input later moves this with it.
+    const requiresBranch = ((inputs as { required?: string[] }).required ?? []).includes('branch');
     const def = toolDef({
       name: spec.name,
       description: spec.description,
       path,
-      inputs: spec.skipBranch ? spec.inputs : withBranchInput(spec.inputs),
+      inputs,
       outputs: spec.outputs,
       tags: spec.write ? ['workflow', 'write'] : ['workflow'],
     });
@@ -171,7 +222,27 @@ export function registerWorkflowTools(
       // normaliser: the root-anchored `/<kbDirName>/…` form names the same
       // workspace path, and a path with no prefix is placed under
       // `<kbDirName>/` rather than refused.
-      toolHandler((args, ctx) => spec.handler(normalizePathArgs(args, kbDirName), ctx), { write: spec.write }),
+      toolHandler(
+        (args, ctx) => {
+          // These tools hand `branch` STRAIGHT to `workspaceIdForBranch` —
+          // they address a workspace by id rather than going through
+          // `getFilesystem`, so the choke point that guards the file tools
+          // never sees them. Without this, a branch-less `commit_change`
+          // commits to a workspace id literally named "undefined", and a
+          // branch-less `create_branch` forks from one: it clones a branch of
+          // that name, fails, and answers `There is no branch named undefined.`
+          //
+          // Keyed on whether the SCHEMA requires `branch`, not on whether the
+          // input was injected. `create_branch` and `switch_branch` declare
+          // their own required `branch`; a check keyed on the injection skipped
+          // exactly those two, which is how the reported bug survived on
+          // `create_branch` — the one tool whose `branch` is a branch the
+          // caller must already have.
+          if (requiresBranch) assertBranchProvided(args.branch);
+          return spec.handler(normalizePathArgs(args, kbDirName), ctx);
+        },
+        { write: spec.write },
+      ),
     );
   };
 
@@ -330,6 +401,17 @@ export function registerWorkflowTools(
     handler: async (args, ctx: ToolContext) => {
       const name = args.name as string;
       const base = args.branch as string;
+      // `name` is declared required too, and the same-name refusal below quotes
+      // it. With nothing enforcing it, a call that named neither input compared
+      // undefined to undefined, matched, and answered "not 'undefined', the
+      // draft being created" — an absent value presented as a draft name, the
+      // very sentence this ticket exists to stop. Refused by name instead,
+      // without echoing what was not sent.
+      if (typeof name !== 'string' || name.length === 0) {
+        throw new ToolError('`name` is required: pass the name of the draft to create.', 400, {
+          kind: 'name-required',
+        });
+      }
       // The git op runs in the base's workspace, whose clone has the base
       // checked out — the new draft forks from its HEAD. Resolving a workspace
       // lazily clones its branch from origin, so a `branch` naming the
@@ -353,6 +435,12 @@ export function registerWorkflowTools(
       'Open a change request from a draft branch into a target branch. Auto-merges the latest target ' +
       'into the source first, pushes, then creates the CR. On conflicts returns a ' +
       '`change-request-conflicts` error with affected paths. The author marker is injected server-side. ' +
+      'Answers a SUMMARY, not the request\'s content: `url` first (hand it to the user), then `number`, ' +
+      '`title`, `state`, `sourceBranch`, `targetBranch`, `approvals` (who must approve each file), ' +
+      '`mergeBlockedReasons` (what blocks the merge), and `files` — the changed paths with their kind of ' +
+      `change (\`added\` / \`changed\` / \`deleted\` / \`moved\`), cut to ${CHANGE_REQUEST_PATH_LIMIT} of \`totalFiles\`. ` +
+      'No patches and no file content: ask for the diffs with `include: ["patches"]` and for every path ' +
+      'with `include: ["all-paths"]`. ' +
       'An agent proposes; a person reviews and merges the request in the app — hand the user its `url`.',
     inputs: {
       type: 'object',
@@ -361,28 +449,37 @@ export function registerWorkflowTools(
         targetBranch: { type: 'string', minLength: 1, description: `The branch to apply to (e.g. '${kb.defaultBranch}').` },
         title: { type: 'string', minLength: 1, maxLength: 256, description: 'Short imperative title (≤256 chars).' },
         description: { type: 'string', description: 'Optional markdown body shown verbatim to reviewers.' },
+        include: {
+          type: 'array',
+          items: { type: 'string', enum: [...CHANGE_REQUEST_INCLUDES] },
+          description:
+            'Add to the default answer, which carries neither: `patches` gives each listed file its unified diff, ' +
+            `\`all-paths\` lists every changed path instead of the first ${CHANGE_REQUEST_PATH_LIMIT}. Both may be given. ` +
+            'Patches of a large request run to hundreds of thousands of characters — ask for them only when you will read them.',
+        },
       },
       required: ['sourceBranch', 'targetBranch', 'title'],
       additionalProperties: false,
     },
-    outputs: {
-      type: 'object',
-      properties: { changeRequest: changeRequestDetailSchema },
-      required: ['changeRequest'],
-    },
+    outputs: changeRequestSummarySchema,
     write: true,
     // The workspace this acts on is the SOURCE draft's — `sourceBranch` already
     // names it, so skip the auto-injected (and here redundant) `branch` input
     // rather than asking the model for both and reading the wrong one.
     skipBranch: true,
-    handler: async (args, ctx: ToolContext) => ({
-      changeRequest: await ctx.workflowService.openChangeRequest(workspaceIdForBranch(args.sourceBranch as string), ctx.user, {
-        sourceBranch: args.sourceBranch as string,
-        targetBranch: args.targetBranch as string,
-        title: args.title as string,
-        description: typeof args.description === 'string' ? args.description : undefined,
-      }),
-    }),
+    // The service still returns the full detail — the app's routes serve the
+    // same call and must keep getting it. The shaping happens here, in the
+    // answer, so nothing below the tool changes.
+    handler: async (args, ctx: ToolContext) =>
+      summarizeChangeRequest(
+        await ctx.workflowService.openChangeRequest(workspaceIdForBranch(args.sourceBranch as string), ctx.user, {
+          sourceBranch: args.sourceBranch as string,
+          targetBranch: args.targetBranch as string,
+          title: args.title as string,
+          description: typeof args.description === 'string' ? args.description : undefined,
+        }),
+        parseInclude(args.include),
+      ),
   });
 
   mount({

package/src/modules/workflow/file-lock.service.ts

@@ -305,6 +305,37 @@ export class FileLockService {
     return rowToFileLock(row);
   }
 
+  /**
+   * Drop every lock held on `branch`, whoever holds it and whichever
+   * workspace it sits in, and answer how many rows went.
+   *
+   * The one caller is a change request being closed because the
+   * knowledge-base repository was REPLACED: the branch the lock names belongs
+   * to a repository this deployment no longer has, so the holder can neither
+   * publish their bytes nor release the lock themselves — and the row would
+   * otherwise sit there refusing the path to everyone until its TTL ran out
+   * on every heartbeat a still-connected client keeps sending.
+   *
+   * Expired rows go too: they are already nobody's lock, and leaving them for
+   * the lazy sweep would only make this answer harder to read.
+   *
+   * Deliberately NOT a release in the ordinary sense — nothing is committed
+   * and nothing is enqueued. The bytes belonged to a repository that is gone.
+   *
+   * What an ORDINARY release already enqueued is a different matter, and not
+   * this method's to fix: a release queues the bytes and only then drops its
+   * lock, so rows can be waiting for a branch whose locks this deletes. The
+   * caller takes those out of the worker's reach in the same breath — see
+   * `PendingCommitsService.markNeedsAttentionOnBranch`.
+   */
+  async releaseAllOnBranch(branch: string): Promise<number> {
+    const gone = await this.db
+      .delete(fileLocks)
+      .where(eq(fileLocks.branch, branch))
+      .returning({ path: fileLocks.path });
+    return gone.length;
+  }
+
   /**
    * Is ANY unexpired lock held anywhere in this workspace? Feeds the git
    * status sanity check: a held lock means a mutation is mid-flight — the

package/src/modules/workflow/git/__tests__/git.service.fileBytesAtCommit.test.ts

@@ -0,0 +1,260 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { testKbContext } from '../../../../__tests__/kb-context.js';
+import { GitService } from '../git.service.js';
+import {
+  VersionNotOnBranchError,
+  VERSION_NOT_ON_BRANCH_MESSAGE,
+  WorkflowValidationError,
+} from '../../../../shared/domain-errors.js';
+import { GitRunError, assertOneSpecPerLine } from '../../../../shared/git.contract.js';
+import { runGit, gitOut, stubWorkflowHooks, stubWorkspaceService } from './git-test-helpers.js';
+
+/**
+ * A past version has to come back BYTE FOR BYTE, and only for saves on the
+ * branch being viewed.
+ *
+ * `readFileAtRef` decodes git's stdout as UTF-8, which is why a binary could
+ * not be served through it at all: every byte sequence that is not valid UTF-8
+ * comes back as U+FFFD, so a PNG downloaded from history would not open. The
+ * suite pins the round trip on bytes that would not survive that (everything
+ * from 0x00 to 0xff, NUL included), the two sides of a save, and the branch
+ * rule that decides who may ask at all.
+ */
+
+/** Every byte value, so any decode-and-re-encode step is visible as a failure. */
+const ALL_BYTES = Buffer.from(Array.from({ length: 256 }, (_, i) => i));
+const PNG_HEADER = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+const V1 = Buffer.concat([PNG_HEADER, ALL_BYTES, Buffer.from('v1')]);
+const V2 = Buffer.concat([PNG_HEADER, ALL_BYTES.subarray(0, 128), Buffer.from('v2\0tail')]);
+
+describe('GitService.fileBytesAtCommit', () => {
+  let root: string;
+  let repo: string;
+  let svc: GitService;
+  const workspaceId = 'target-company-state';
+  /** The save that ADDED logo.png (V1), the save that REPLACED it (V2). */
+  let addSha: string;
+  let replaceSha: string;
+
+  beforeEach(async () => {
+    root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-bytes-at-ref-'));
+    const workspaceDir = path.join(root, workspaceId);
+    repo = path.join(workspaceDir, 'knowledge-base');
+    await fs.mkdir(repo, { recursive: true });
+    await runGit(root, ['init', '-b', 'target-company-state', repo]);
+    await runGit(repo, ['config', 'user.email', 'workspace@bevel.test']);
+    await runGit(repo, ['config', 'user.name', 'bevel Workspace']);
+
+    await fs.writeFile(path.join(repo, 'logo.png'), V1);
+    await fs.mkdir(path.join(repo, 'docs'));
+    await fs.writeFile(path.join(repo, 'docs', 'child.md'), 'child\n');
+    await runGit(repo, ['add', '.']);
+    await runGit(repo, ['commit', '-m', 'add logo']);
+    addSha = await gitOut(repo, ['rev-parse', 'HEAD']);
+
+    await fs.writeFile(path.join(repo, 'logo.png'), V2);
+    await runGit(repo, ['add', '.']);
+    await runGit(repo, ['commit', '-m', 'replace logo']);
+    replaceSha = await gitOut(repo, ['rev-parse', 'HEAD']);
+
+    svc = new GitService(
+      stubWorkspaceService({ [workspaceId]: workspaceDir }),
+      stubWorkflowHooks(),
+      testKbContext(),
+    );
+  });
+
+  afterEach(async () => {
+    await fs.rm(root, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 });
+  });
+
+  it('returns the exact bytes of each save, on both sides of it', async () => {
+    const atAdd = await svc.fileBytesAtCommit(workspaceId, 'knowledge-base/logo.png', addSha, 'after');
+    expect(atAdd).not.toBeNull();
+    expect(atAdd!.bytes.equals(V1)).toBe(true);
+    expect(atAdd!.blobId).toMatch(/^[0-9a-f]{40}$/);
+
+    const atReplace = await svc.fileBytesAtCommit(
+      workspaceId,
+      'knowledge-base/logo.png',
+      replaceSha,
+      'after',
+    );
+    expect(atReplace!.bytes.equals(V2)).toBe(true);
+
+    // The `before` side of the replacing save IS the original upload — which
+    // is what makes "download the version this save replaced" possible.
+    const before = await svc.fileBytesAtCommit(
+      workspaceId,
+      'knowledge-base/logo.png',
+      replaceSha,
+      'before',
+    );
+    expect(before!.bytes.equals(V1)).toBe(true);
+    // Different content, therefore a different ETag: the blob id IS the hash.
+    expect(atReplace!.blobId).not.toBe(before!.blobId);
+  });
+
+  it('accepts the repo-relative spelling of the path too', async () => {
+    const at = await svc.fileBytesAtCommit(workspaceId, 'logo.png', addSha, 'after');
+    expect(at!.bytes.equals(V1)).toBe(true);
+  });
+
+  it('serves the version just before the save that DELETED the file', async () => {
+    await fs.rm(path.join(repo, 'logo.png'));
+    await runGit(repo, ['add', '-A']);
+    await runGit(repo, ['commit', '-m', 'remove logo']);
+    const delSha = await gitOut(repo, ['rev-parse', 'HEAD']);
+
+    // Nothing at the path after the save…
+    expect(
+      await svc.fileBytesAtCommit(workspaceId, 'knowledge-base/logo.png', delSha, 'after'),
+    ).toBeNull();
+    // …and the bytes as they were just before it.
+    const before = await svc.fileBytesAtCommit(
+      workspaceId,
+      'knowledge-base/logo.png',
+      delSha,
+      'before',
+    );
+    expect(before!.bytes.equals(V2)).toBe(true);
+  });
+
+  it('returns null for a path the save did not have', async () => {
+    expect(
+      await svc.fileBytesAtCommit(workspaceId, 'knowledge-base/never.png', addSha, 'after'),
+    ).toBeNull();
+    // The root commit has no parent, so it has no `before` side either.
+    expect(
+      await svc.fileBytesAtCommit(workspaceId, 'knowledge-base/logo.png', addSha, 'before'),
+    ).toBeNull();
+  });
+
+  it('refuses a directory at the ref — history is served per file', async () => {
+    await expect(
+      svc.fileBytesAtCommit(workspaceId, 'knowledge-base/docs', addSha, 'after'),
+    ).rejects.toThrow(/history is served per file/);
+  });
+
+  it('refuses a path carrying a LINE BREAK, which git would read as two object names', async () => {
+    // `cat-file --batch` takes one `<ref>:<path>` spec per LINE. Before the
+    // path validator refused control characters, `docs/child.md\nzzz` reached
+    // it as two specs: git answered about `docs/child.md` and those bytes came
+    // back as this path's — under the access gates of a name that exists
+    // nowhere, so the file's own rules were never the ones consulted. Verified
+    // against real git here, not a stub: the call must fail, and nothing of
+    // `child.md` may come back under the longer name.
+    for (const injected of [
+      'knowledge-base/docs/child.md\nzzz',
+      'knowledge-base/docs/child.md\rzzz',
+      'knowledge-base/docs/child.md\nknowledge-base/logo.png',
+    ]) {
+      // Both the TYPE and the sentence. Two different validators are called
+      // `assertValidRelativePath` — the shared one in
+      // `packages/shared/src/workspace/filename.ts`, which throws a plain
+      // `Error('Invalid path: …')`, and the kb-fs one in
+      // `modules/kb-fs/branch-name.ts`, which throws `WorkflowValidationError`
+      // (status 400). `GitService` imports the kb-fs one, and the 400 is what
+      // makes the route answer 400 rather than 500, so the type is asserted
+      // here deliberately and the message pins which of the two ran.
+      await expect(
+        svc.fileBytesAtCommit(workspaceId, injected, addSha, 'after'),
+      ).rejects.toThrow(WorkflowValidationError);
+      await expect(
+        svc.fileBytesAtCommit(workspaceId, injected, addSha, 'after'),
+      ).rejects.toThrow(/control character/);
+      await expect(
+        svc.fileBytesAtCommit(workspaceId, injected, addSha, 'after'),
+      ).rejects.toMatchObject({ status: 400 });
+    }
+    // The refusal is the PATH's, decided before the sha is resolved or the
+    // workspace's git turn is taken — so a caller cannot reach git with one.
+    await expect(
+      svc.fileBytesAtCommit(workspaceId, 'knowledge-base/docs/child.md\nzzz', 'HEAD', 'after'),
+    ).rejects.toThrow(/control character/);
+  });
+
+  it('fences the batch protocol itself against a spec that is not one line', () => {
+    // The fence under `blobAtRef` and under the access resolver's batch read,
+    // for a spec assembled from somewhere the path validator does not cover.
+    expect(() => assertOneSpecPerLine([`${addSha}:logo.png`])).not.toThrow();
+    expect(() => assertOneSpecPerLine([`${addSha}:docs/child.md\nzzz`])).toThrow(/line break/);
+    expect(() => assertOneSpecPerLine(['a:b', 'c:d\re'])).toThrow(/line break/);
+  });
+
+  it('refuses a sha that is not a sha', async () => {
+    await expect(
+      svc.fileBytesAtCommit(workspaceId, 'knowledge-base/logo.png', 'HEAD', 'after'),
+    ).rejects.toThrow(WorkflowValidationError);
+  });
+
+  it('refuses a save that is not in this branch\'s history, and a made-up one, alike', async () => {
+    // A save that exists — on another branch this workspace is not viewing.
+    await runGit(repo, ['checkout', '-b', 'someone-else']);
+    await fs.writeFile(path.join(repo, 'logo.png'), Buffer.from('elsewhere'));
+    await runGit(repo, ['add', '-A']);
+    await runGit(repo, ['commit', '-m', 'elsewhere']);
+    const otherSha = await gitOut(repo, ['rev-parse', 'HEAD']);
+    await runGit(repo, ['checkout', 'target-company-state']);
+
+    for (const sha of [otherSha, 'a'.repeat(40)]) {
+      const read = svc.fileBytesAtCommit(workspaceId, 'knowledge-base/logo.png', sha, 'after');
+      await expect(read).rejects.toThrow(VersionNotOnBranchError);
+      await expect(read).rejects.toThrow(VERSION_NOT_ON_BRANCH_MESSAGE);
+    }
+
+    // …and every save the panel LISTS is accepted, which is the other half of
+    // the rule: `logForFile` walks HEAD, so anything it returns is an ancestor.
+    // Asserted through the read itself rather than a boolean helper, so what is
+    // pinned is the thing the route calls.
+    for (const listed of await svc.logForFile(workspaceId, 'knowledge-base/logo.png')) {
+      await expect(
+        svc.fileBytesAtCommit(workspaceId, 'knowledge-base/logo.png', listed.sha, 'after'),
+      ).resolves.not.toBeNull();
+    }
+  });
+
+  it('propagates a repository failure rather than calling it a version off the branch', async () => {
+    // An UNBORN HEAD: the sha resolves perfectly well and git's complaint is
+    // about the other argument ('ambiguous argument HEAD'). Folded into
+    // `VersionNotOnBranchError` it would tell a reader the save they can see
+    // listed is not in their history — a broken workspace dressed up as an
+    // answer about access, and one 'Try again' can never get past.
+    await runGit(repo, ['checkout', '--orphan', 'nothing-committed-yet']);
+    const err: unknown = await svc
+      .fileBytesAtCommit(workspaceId, 'knowledge-base/logo.png', addSha, 'after')
+      .catch((e: unknown) => e);
+    // `GitRunError` specifically, not just `Error`: the route reads the error's
+    // TYPE to decide its status, so a future re-wrap into
+    // `WorkflowValidationError` would turn this into a 400 about the caller's
+    // request rather than the logged 500 a broken repository earns, and a bare
+    // `toBeInstanceOf(Error)` would not notice.
+    expect(err).toBeInstanceOf(GitRunError);
+    expect(err).not.toBeInstanceOf(VersionNotOnBranchError);
+  });
+
+  it('applies the same branch rule to the existing text-history reads', async () => {
+    await runGit(repo, ['checkout', '-b', 'someone-else']);
+    await fs.writeFile(path.join(repo, 'logo.png'), Buffer.from('elsewhere'));
+    await runGit(repo, ['add', '-A']);
+    await runGit(repo, ['commit', '-m', 'elsewhere']);
+    const otherSha = await gitOut(repo, ['rev-parse', 'HEAD']);
+    await runGit(repo, ['checkout', 'target-company-state']);
+
+    // Otherwise the bytes route's rule could simply be read around: the patch
+    // and the full before/after text are past versions too.
+    await expect(
+      svc.diffFileAtCommit(workspaceId, 'knowledge-base/logo.png', otherSha),
+    ).rejects.toThrow(VERSION_NOT_ON_BRANCH_MESSAGE);
+    await expect(
+      svc.fileContentsAtCommit(workspaceId, 'knowledge-base/logo.png', otherSha),
+    ).rejects.toThrow(VERSION_NOT_ON_BRANCH_MESSAGE);
+    // The on-branch saves still work.
+    expect(await svc.diffFileAtCommit(workspaceId, 'knowledge-base/logo.png', replaceSha)).toContain(
+      'logo.png',
+    );
+  });
+});