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

package/src/modules/workflow/agent-tools/change-request-summary.ts

@@ -0,0 +1,182 @@
+import type {
+  ChangeRequestDetail,
+  ChangeRequestState,
+  ChangedFile,
+  FileApproval,
+  PrFileStatus,
+} from '@bevel-software/platform-shared';
+
+/**
+ * What `open_change_request` answers, and why it is not the detail the app's
+ * dialog reads.
+ *
+ * The dialog renders every file's diff, so its detail carries every patch. An
+ * agent that opens a change request needs none of that: it needs the link to
+ * hand the user, and enough of the request to confirm it carries the files it
+ * meant to propose and to say what the request is now waiting on. Handing it
+ * the dialog's detail cost ~445,000 characters for 27 files of 15 KB — past
+ * every tool-result limit, so the one field the agent actually needed (the
+ * link) could not be read at all.
+ *
+ * So this is a purpose-made answer: the link first, the request's identity,
+ * who must approve each path, what blocks the merge verbatim from the detail,
+ * and the changed paths with their kind of change — no patch, no file content.
+ * An agent that wants more asks for it by name through `include`.
+ */
+
+/** What `include` accepts. */
+export type ChangeRequestInclude = 'patches' | 'all-paths';
+
+/** The two `include` values, for the tool's input schema and its validation. */
+export const CHANGE_REQUEST_INCLUDES: readonly ChangeRequestInclude[] = ['patches', 'all-paths'];
+
+/** How many paths the answer lists before it cuts; `all-paths` lifts the cut. */
+export const CHANGE_REQUEST_PATH_LIMIT = 25;
+
+/**
+ * The kind of change to one path, in the four words the answer speaks. Git's
+ * own statuses are finer (`modified` vs `changed`, `renamed` vs `copied`) in
+ * ways nothing downstream acts on.
+ */
+export type ChangeKind = 'added' | 'changed' | 'deleted' | 'moved';
+
+/** One changed path. `previousPath` is where a `moved` one came from. */
+export interface ChangeRequestSummaryFile {
+  path: string;
+  change: ChangeKind;
+  previousPath?: string;
+  /** Unified diff. Only with `include: ["patches"]`, and absent for a binary or oversized file. */
+  patch?: string;
+}
+
+/**
+ * Who must approve one path, at the same per-path granularity the detail
+ * carries (the access tree resolves a role per file or per folder; this says
+ * what it resolved to for this file).
+ *
+ * The detail's own entry is the dialog's: it also carries each approver's
+ * email, the viewer's own eligibility, and every approval's timestamp and
+ * staleness. Repeated over 25 files that is ~4,500 characters an agent cannot
+ * act on — it may not approve anything — and it is what would push the
+ * 27-file answer back over the limit this ticket exists to get under. So the
+ * answer keeps what "who must approve" means and nothing else.
+ */
+export interface ChangeRequestApprovers {
+  path: string;
+  /** Roles that confer approval here. `everyone` means any signed-in approver. */
+  roles: string[];
+  /** Approvers named directly, by display name. */
+  users: string[];
+  /** True once an eligible approver has approved at the request's current head. */
+  approved: boolean;
+  /** False when the merge gate does not bind this path — then nobody has to approve it. */
+  inMergeGate: boolean;
+  /**
+   * Present when the access tree could not be resolved for this path — which
+   * includes a detail that carries no verdict at all. Then empty
+   * `roles`/`users` means "not known", NOT "nobody has to approve".
+   */
+  approversUnknown?: true;
+}
+
+export interface ChangeRequestSummary {
+  /** First field on purpose: it is the one an agent must hand the user. */
+  url: string;
+  urlNote?: string;
+  number: number;
+  title: string;
+  state: ChangeRequestState;
+  sourceBranch: string;
+  targetBranch: string;
+  /** Who must approve, one entry per listed path. */
+  approvals: ChangeRequestApprovers[];
+  /** What blocks the merge — verbatim from the detail. Empty when nothing does. */
+  mergeBlockedReasons: string[];
+  /** The changed paths, cut to {@link CHANGE_REQUEST_PATH_LIMIT} unless `all-paths` was asked for. */
+  files: ChangeRequestSummaryFile[];
+  /** How many files the request changes in total, cut or not. */
+  totalFiles: number;
+}
+
+/**
+ * A copy and a rename both carry `previousPath`, and the one thing a reader
+ * does with either is look at where the text came from — so both read `moved`.
+ * `unchanged` is a file the request lists without changing (git reports it on
+ * a mode-only change); `changed` is the honest word for it among these four.
+ */
+function changeKindOf(status: PrFileStatus | undefined): ChangeKind {
+  switch (status) {
+    case 'added':
+      return 'added';
+    case 'removed':
+      return 'deleted';
+    case 'renamed':
+    case 'copied':
+      return 'moved';
+    default:
+      return 'changed';
+  }
+}
+
+function approversOf(approval: FileApproval): ChangeRequestApprovers {
+  const eligible = approval.eligibleApprovers ?? { roles: [], users: [] };
+  return {
+    path: approval.path,
+    roles: eligible.roles ?? [],
+    users: (eligible.users ?? []).map((u) => u.name),
+    approved: approval.isApproved,
+    inMergeGate: approval.inMergeGate,
+    // Anything but an explicit `true` is unresolved — a detail built before
+    // the flag existed carries no flag at all, and reading that as "resolved"
+    // would turn an empty approver set into "nobody must approve". Same
+    // fail-closed reading as `computeViewerCanUpdate`.
+    ...(approval.eligibilityResolved !== true ? { approversUnknown: true as const } : {}),
+  };
+}
+
+function summaryFileOf(file: ChangedFile, withPatch: boolean): ChangeRequestSummaryFile {
+  return {
+    path: file.path,
+    change: changeKindOf(file.status),
+    ...(file.previousPath ? { previousPath: file.previousPath } : {}),
+    ...(withPatch && file.patch ? { patch: file.patch } : {}),
+  };
+}
+
+/**
+ * Shape the tool's answer out of the detail the service already returns. Pure:
+ * the service and the app's routes are untouched, and the detail they serve is
+ * exactly what it was.
+ *
+ * `approvals` is narrowed to the paths the answer lists, because the detail's
+ * contract is one entry per listed file. Nothing about the merge gate is lost
+ * by that: `mergeBlockedReasons` names every missing approval, cut or not.
+ */
+export function summarizeChangeRequest(
+  detail: ChangeRequestDetail,
+  include: readonly ChangeRequestInclude[] = [],
+): ChangeRequestSummary {
+  const all = detail.files ?? [];
+  const withPatch = include.includes('patches');
+  const listed = include.includes('all-paths') ? all : all.slice(0, CHANGE_REQUEST_PATH_LIMIT);
+  const listedPaths = new Set(listed.map((f) => f.path));
+  return {
+    url: detail.url,
+    ...(detail.urlNote ? { urlNote: detail.urlNote } : {}),
+    number: detail.number,
+    title: detail.title,
+    state: detail.state,
+    sourceBranch: detail.branch,
+    targetBranch: detail.base,
+    approvals: (detail.approvals ?? []).filter((a) => listedPaths.has(a.path)).map(approversOf),
+    mergeBlockedReasons: detail.mergeBlockedReasons ?? [],
+    files: listed.map((f) => summaryFileOf(f, withPatch)),
+    totalFiles: all.length,
+  };
+}
+
+/** The `include` values off a tool call's arguments; anything else is ignored. */
+export function parseInclude(raw: unknown): ChangeRequestInclude[] {
+  if (!Array.isArray(raw)) return [];
+  return CHANGE_REQUEST_INCLUDES.filter((v) => raw.includes(v));
+}

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

@@ -9,6 +9,12 @@ 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 {
@@ -47,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 = {
@@ -99,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'],
 };
 
 /**
@@ -399,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',
@@ -407,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',
+    );
+  });
+});