@bevel-software/platform-core-backend 0.25.2 → 0.27.0

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

@@ -103,8 +103,12 @@ export interface ChangeRequestSummary {
  * 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.
+ *
+ * Exported because `list_change_request_files` answers `change` under this same
+ * name: an agent that opens a request and reads its files back must not be told
+ * `moved` by one tool and `renamed` by the other.
  */
-function changeKindOf(status: PrFileStatus | undefined): ChangeKind {
+export function changeKindOf(status: PrFileStatus | undefined): ChangeKind {
   switch (status) {
     case 'added':
       return 'added';

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

@@ -1,11 +1,10 @@
 import type { Router, RequestHandler } from 'express';
 import type { IToolRegistry, JsonSchema } from '../../tool-registry/tool.contract.js';
 import { ToolError, type ToolContext, type ToolHandler } from '../../tool-helpers/tool.contract.js';
-import { toolDef, withBranchInput } from '../../tool-helpers/tool-def.js';
+import { toolDef } 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';
@@ -171,6 +170,12 @@ export function registerWorkflowTools(
   toolHandler: ToolHandlerFactory,
   /** The clone folder at the workspace root (`save_file` refuses a path outside it) and the branch model. */
   kb: Pick<KbContext, 'kbDirName' | 'defaultBranch' | 'defaultWorkspaceId' | 'protectedBranches'>,
+  /**
+   * Whether the caller may see change request `number` — `get_change_request`'s
+   * own gate (`changeRequestScope(...).maySee`). `delete_branch` neither names
+   * nor links a request it answers no for.
+   */
+  maySeeChangeRequest: (ctx: ToolContext, number: number) => Promise<boolean>,
 ): void {
   const { kbDirName } = kb;
   const mount = (spec: {
@@ -191,21 +196,24 @@ export function registerWorkflowTools(
      * out of the check while still demanding the input.
      */
     skipBranch?: boolean;
+    /** Arguments this tool's handler refuses by name itself (see `ToolDefSpec`). */
+    refusesItself?: string[];
     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');
+    // Every workflow tool that takes a branch REQUIRES it — the injected input
+    // and a hand-declared one (the fork base, the draft to switch to) alike.
+    // A hand-declared one is required by its own schema, which `toolDef`
+    // reads as `required` too; the tool handler refuses a call without it.
     const def = toolDef({
       name: spec.name,
       description: spec.description,
       path,
-      inputs,
+      inputs: spec.inputs,
+      branch: spec.skipBranch ? undefined : 'required',
+      write: spec.write,
       outputs: spec.outputs,
+      refusesItself: spec.refusesItself,
       tags: spec.write ? ['workflow', 'write'] : ['workflow'],
     });
     registry.registerInternalTool(def);
@@ -223,24 +231,12 @@ export function registerWorkflowTools(
       // workspace path, and a path with no prefix is placed under
       // `<kbDirName>/` rather than refused.
       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);
-        },
+        // These tools hand `branch` STRAIGHT to `workspaceIdForBranch` —
+        // they address a workspace by id rather than going through
+        // `getFilesystem` — so the branch-less call the tool handler refuses
+        // before this runs would otherwise commit to, or fork from, a
+        // workspace literally named "undefined".
+        (args, ctx) => spec.handler(normalizePathArgs(args, kbDirName), ctx),
         { write: spec.write },
       ),
     );
@@ -383,6 +379,9 @@ export function registerWorkflowTools(
     // workspace-`branch` injection ("the branch you are currently working on"),
     // whose wording invites filling in the draft being created instead.
     skipBranch: true,
+    // The handler refuses a missing `name` with a message that says what the
+    // name is for (`name-required`); the generic check leaves it to that.
+    refusesItself: ['name'],
     inputs: {
       type: 'object',
       properties: {
@@ -528,6 +527,14 @@ export function registerWorkflowTools(
       });
       if (!detail) {        throw new ToolError(`Change request #${number} not found.`, 404);
       }
+      // A comment anchors to a commit, and a DECLINED request has none to anchor
+      // to: nothing durable records what it proposed, so its detail carries no
+      // head (see `changeSourceFor`). Say that, rather than letting the service's
+      // `head sha is required` surface as a 400 about an argument the caller
+      // never passed. An APPLIED request still takes comments — its head is the
+      // source tip its merge commit recorded.
+      if (!detail.headSha) {        throw new ToolError(`Change request #${number} is ${detail.state} and has no commit to anchor a comment to.`, 409);
+      }
       const comment = await ctx.workflowService.postComment(
         number,
         ctx.user,
@@ -542,13 +549,16 @@ export function registerWorkflowTools(
     name: 'merge_branch',
     description:
       'Merge branch `source` into branch `target` as you, and publish `target`. An agent proposes and syncs; ' +
-      'a person merges: this tool never lands a change request. It refuses when a change request from `source` ' +
-      'into `target` is open (naming it) — ask the user to review that request in the app instead. It refuses ' +
+      'a person merges: this tool never lands a change request. It refuses while a change request from `source` ' +
+      'into `target` is open (naming it): ask the user to review it in the app. It refuses ' +
       'when `target` is a protected branch unless you could commit every changed file directly to it. ' +
       'SYNC: merging the target into your draft (`source` = the change request\'s target, `target` = your draft) ' +
-      'is always allowed, even with that draft\'s request open — use it to bring a draft up to date. ' +
-      'Returns `merged` with the merge commit, or `conflicts-need-resolution` with the conflicting paths ' +
-      '(nothing is written; resolve them on `source` and merge again).',
+      'is always allowed, even with the draft\'s request open. ' +
+      'Writes are committed asynchronously; the merge first waits up to 20s for those on `source`. ' +
+      'Returns `merged` with the merge commit; `nothing-to-merge` with `target`\'s tip when it already holds ' +
+      'all of `source`; `pending-commits` (nothing merged) when writes are still committing — retry shortly — ' +
+      'or one failed (`needsAttention`: tell the user); or `conflicts-need-resolution` with the conflicting ' +
+      'paths (nothing is written; resolve them on `source` and merge again).',
     // Names both branches itself; the merge runs in `target`'s workspace.
     skipBranch: true,
     inputs: {
@@ -565,11 +575,28 @@ export function registerWorkflowTools(
       properties: {
         outcome: {
           type: 'object',
-          description: 'Either a completed merge or a signal that conflicts must be resolved first.',
+          description:
+            'A completed merge, a merge with nothing to do, writes on `source` not committed yet ' +
+            '(writes are committed asynchronously and the merge waits up to 20 seconds for them), ' +
+            'or a signal that conflicts must be resolved first.',
           properties: {
-            kind: { type: 'string', enum: ['merged', 'conflicts-need-resolution'] },
-            sha: { type: 'string', description: 'Present when `kind` is `merged` — the tip of `target` after the merge.' },
+            kind: { type: 'string', enum: ['merged', 'nothing-to-merge', 'pending-commits', 'conflicts-need-resolution'] },
+            sha: {
+              type: 'string',
+              description:
+                'Present when `kind` is `merged` (the merge commit, now the tip of `target`) or `nothing-to-merge` ' +
+                '(the unchanged tip of `target`, which already held everything on `source`).',
+            },
             conflictedPaths: { type: 'array', items: { type: 'string' }, description: 'Present when `kind` is `conflicts-need-resolution`.' },
+            branch: { type: 'string', description: 'Present when `kind` is `pending-commits` — the branch whose writes are not committed yet.' },
+            pending: { type: 'integer', description: 'Present when `kind` is `pending-commits` — how many commits on that branch are still queued, plus those that failed when `needsAttention` is present.' },
+            needsAttention: {
+              type: 'string',
+              description:
+                'Present when `kind` is `pending-commits` and a queued commit failed: the worker\'s message. ' +
+                'Waiting will not help; tell the user.',
+            },
+            message: { type: 'string', description: 'Present when `kind` is `pending-commits` — what to do next.' },
           },
           required: ['kind'],
         },
@@ -587,6 +614,81 @@ export function registerWorkflowTools(
     },
   });
 
+  mount({
+    name: 'delete_branch',
+    description:
+      'Delete branch `name` from the shared repository and the server. Allowed for the ' +
+      'branch\'s author (`<email-localpart>/…`, or your own `suggestions/…` bundle) or an Admin. Refuses a ' +
+      'protected branch, a name that is not a branch, a branch with saves still landing or a file held ' +
+      '(retry once they land). An open change request from or into it that proposes nothing is closed and the ' +
+      'delete goes ahead; one that still proposes something refuses it, naming and linking it: its author ' +
+      'withdraws it or an Admin declines it, in the app (one you cannot see is not named, nor in a preview). ' +
+      'Refuses a branch holding commits that are not on the ' +
+      'default branch, saying how many; `discardUnmerged: true` deletes it anyway and reports them as ' +
+      '`discardedCommits`. Refuses if the shared repository is unreachable. Preview with ' +
+      '`dryRun: true`: it changes nothing and answers `exists`, `canDelete`, `refusals`, `unmergedCommits`, ' +
+      '`openChangeRequests` and `lastCommit`. A preview grants nothing; checks rerun on delete. ' +
+      'Answers the deleted branch\'s `lastCommit`.',
+    // Names its branch itself; the deletion runs in the default branch's workspace.
+    skipBranch: true,
+    refusesItself: ['name'],
+    inputs: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', minLength: 1, description: 'The branch to delete.' },
+        dryRun: { type: 'boolean', description: 'Report what deleting would do, and change nothing.' },
+        discardUnmerged: {
+          type: 'boolean',
+          description: 'Delete even though the branch holds commits that are not on the default branch. They are lost.',
+        },
+      },
+      required: ['name'],
+      additionalProperties: false,
+    },
+    outputs: {
+      type: 'object',
+      properties: {
+        kind: { type: 'string', enum: ['preview', 'deleted'] },
+        branch: { type: 'string' },
+        lastCommit: { type: ['string', 'null'], description: 'The branch\'s tip — what a restore starts from. Null in a preview of a branch that does not exist.' },
+        discardedCommits: { type: 'integer', description: 'When `kind` is `deleted`: commits not on the default branch that went with it.' },
+        exists: { type: 'boolean', description: 'When `kind` is `preview`.' },
+        canDelete: { type: 'boolean', description: 'When `kind` is `preview`: whether a delete asked for now would go through.' },
+        refusals: { type: 'array', items: { type: 'string' }, description: 'When `kind` is `preview`: why it would not.' },
+        unmergedCommits: { type: 'integer', description: 'When `kind` is `preview`: commits not on the default branch.' },
+        openChangeRequests: {
+          type: 'array',
+          description: 'When `kind` is `preview`: open change requests from (`source`) or into (`target`) the branch that you can see.',
+          items: {
+            type: 'object',
+            properties: {
+              number: { type: 'integer' },
+              end: { type: 'string', enum: ['source', 'target'] },
+              url: { type: 'string', description: 'Link to the request in the app.' },
+              proposesNothing: { type: 'boolean', description: 'True when the delete would close it rather than be refused by it.' },
+            },
+            required: ['number', 'end', 'url', 'proposesNothing'],
+          },
+        },
+      },
+      required: ['kind', 'branch', 'lastCommit'],
+    },
+    write: true,
+    handler: async (args, ctx: ToolContext) => {
+      const name = args.name;
+      if (typeof name !== 'string' || name.length === 0) {
+        throw new ToolError('`name` is required: pass the name of the branch to delete.', 400, {
+          kind: 'name-required',
+        });
+      }
+      return ctx.workflowService.deleteBranchChecked(ctx.user, name, {
+        dryRun: args.dryRun === true,
+        discardUnmerged: args.discardUnmerged === true,
+        maySee: (number) => maySeeChangeRequest(ctx, number),
+      });
+    },
+  });
+
   // `merge_change_request` is retired: a change request is merged by a person
   // in the app. It is in no catalog, but a caller holding an old manual still
   // posts to its path — answer with who merges now, not a bare 404.

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

@@ -69,17 +69,52 @@ function rowToFileLock(row: typeof fileLocks.$inferSelect): FileLock {
 export class FileLockService {
   constructor(private readonly db: Database) {}
 
+  /**
+   * Branches being deleted right now, with how many deletions hold each. No
+   * lock is granted on them: a deletion checks that no save is landing and
+   * then removes the branch, and a save that took its lock in between would
+   * be lost with the checkout. See `whileNoneAcquired`.
+   */
+  private readonly closing = new Map<string, number>();
+
+  /**
+   * Acquires on each branch that passed the `closing` check and have not
+   * settled yet. `whileNoneAcquired` waits for them: one whose row is still
+   * being written when a deletion starts would otherwise land after the
+   * deletion's last check.
+   */
+  private readonly acquiring = new Map<string, Set<Promise<unknown>>>();
+
+  /**
+   * Run `fn` while no lock can be acquired on `branch`, once every acquire
+   * already under way on it has settled. The deletion paths re-check for
+   * saves landing inside it, so that check sees every lock granted before it,
+   * and the deletion meets no save that started in between.
+   */
+  async whileNoneAcquired<T>(branch: string, fn: () => Promise<T>): Promise<T> {
+    this.closing.set(branch, (this.closing.get(branch) ?? 0) + 1);
+    try {
+      await Promise.allSettled([...(this.acquiring.get(branch) ?? [])]);
+      return await fn();
+    } finally {
+      const n = (this.closing.get(branch) ?? 1) - 1;
+      if (n > 0) this.closing.set(branch, n);
+      else this.closing.delete(branch);
+    }
+  }
+
   /**
    * Acquire a lock for `(workspaceId, branch, path)` on behalf of `user`.
    *
    * Three outcomes folded into the same return shape:
    *   - No existing row: insert + return `{ acquired: true, lock }`.
    *   - Existing row, expired: take it over (update) + `{ acquired: true }`.
-   *   - Existing row, live, different user: return `{ acquired: false }`
-   *     with the current holder's lock state so the UI can render
-   *     "Locked by X" without a follow-up call.
-   *   - Existing row, live, same user: refresh TTL + `{ acquired: true }`
-   *     so re-acquiring your own lock is idempotent.
+   *   - Existing row, live — ANY user, the holder included: return
+   *     `{ acquired: false }` with the current holder's lock state so the UI
+   *     can render "Locked by X" without a follow-up call. Re-acquiring your
+   *     own live lock is refused on purpose (see the comment in the body):
+   *     refresh a held lock with `heartbeat()`, and ask "do I already hold
+   *     it?" with `get()`.
    *
    * `opts.coordination` stamps the row's `mode` as `'coordination'` — a
    * pure-mutex hold that grants no write authority (see
@@ -97,6 +132,33 @@ export class FileLockService {
     opts?: { coordination?: boolean },
   ): Promise<AcquireLockResult> {
     const targetPath = canonicalFileIdentity(rawPath);
+    if (this.closing.has(branch)) {
+      throw new WorkflowValidationError(`"${branch}" is being deleted, so "${targetPath}" cannot be held for editing.`, {
+        kind: 'branch-being-deleted',
+        branch,
+        path: targetPath,
+      });
+    }
+    const pending = this.acquireUnchecked(workspaceId, branch, targetPath, user, opts);
+    const inFlight = this.acquiring.get(branch) ?? new Set<Promise<unknown>>();
+    inFlight.add(pending);
+    this.acquiring.set(branch, inFlight);
+    try {
+      return await pending;
+    } finally {
+      inFlight.delete(pending);
+      if (inFlight.size === 0 && this.acquiring.get(branch) === inFlight) this.acquiring.delete(branch);
+    }
+  }
+
+  /** `acquire` past the deletion gate. */
+  private async acquireUnchecked(
+    workspaceId: string,
+    branch: string,
+    targetPath: string,
+    user: AuthUser,
+    opts?: { coordination?: boolean },
+  ): Promise<AcquireLockResult> {
     const now = new Date();
     const expiresAt = new Date(now.getTime() + LOCK_TTL_MS);
 

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

@@ -0,0 +1,285 @@
+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 { WorkflowHooks } from '../../workflow-hooks.js';
+import { GitService } from '../git.service.js';
+import { WorkflowValidationError } from '../../../../shared/domain-errors.js';
+import { mergeCommitSubject } from '../merge-commit.js';
+import { runGit, gitOut, stubWorkspaceService } from './git-test-helpers.js';
+
+/**
+ * Reading an APPLIED change request back from its merge commit — the three
+ * methods behind Razvan's 2026-10-02 decision, against a real git.
+ *
+ * Why they exist at all: merging a change request retires its source branch, so
+ * the branch pair every other diff method takes no longer resolves. Before this,
+ * a merged request answered no files — and since an empty file set proves no read
+ * access, that left every applied request readable by its author alone. The merge
+ * commit is what is left of the change, it is local, and it cannot move.
+ *
+ * The fixture is the merge `mergeChangeRequest` makes: `--no-ff`, on the target,
+ * so the commit has the target as its first parent and the source tip as its
+ * second.
+ */
+describe('GitService reading an applied change from its merge commit', () => {
+  const workspaceId = 'ws-applied';
+  /** The change request the fixture's merge commit belongs to. */
+  const CR = 42;
+  let root: string;
+  let repo: string;
+  let git: GitService;
+
+  /** One clone with a merge commit on `main`, and the shas that went into it. */
+  async function seedMerged(): Promise<{
+    mergeSha: string;
+    targetBefore: string;
+    sourceTip: string;
+  }> {
+    repo = path.join(root, workspaceId, 'knowledge-base');
+    await fs.mkdir(repo, { recursive: true });
+    await runGit(path.dirname(repo), ['init', '-b', 'main', 'knowledge-base']);
+    await runGit(repo, ['config', 'user.email', 'test@bevel.local']);
+    await runGit(repo, ['config', 'user.name', 'Test Runner']);
+
+    await fs.writeFile(path.join(repo, 'base.md'), 'base\n');
+    await fs.mkdir(path.join(repo, 'Payroll'), { recursive: true });
+    await fs.writeFile(path.join(repo, 'Payroll', 'Rates.md'), 'bands\n');
+    await runGit(repo, ['add', '-A']);
+    await runGit(repo, ['commit', '-m', 'init']);
+
+    // The proposal: an add, an edit, a delete and a move out of Payroll.
+    await runGit(repo, ['checkout', '-b', 'juan/proposal']);
+    await fs.writeFile(path.join(repo, 'Added.md'), 'new\n');
+    await fs.writeFile(path.join(repo, 'base.md'), 'base\nmore\n');
+    await fs.mkdir(path.join(repo, 'Knowledge'), { recursive: true });
+    await fs.rename(path.join(repo, 'Payroll', 'Rates.md'), path.join(repo, 'Knowledge', 'Open.md'));
+    await runGit(repo, ['add', '-A']);
+    await runGit(repo, ['commit', '-m', 'the proposal']);
+    const sourceTip = await gitOut(repo, ['rev-parse', 'HEAD']);
+
+    // The target moves on while the proposal waits, so a three-dot read of the
+    // merge commit would report this commit's file too — and must not.
+    await runGit(repo, ['checkout', 'main']);
+    await fs.writeFile(path.join(repo, 'OnTarget.md'), 'meanwhile\n');
+    await runGit(repo, ['add', '-A']);
+    await runGit(repo, ['commit', '-m', 'unrelated work on the target']);
+    const targetBefore = await gitOut(repo, ['rev-parse', 'HEAD']);
+
+    // The subject `mergePr` writes — the reader verifies it, so the fixture must
+    // produce it the same way rather than spelling it out.
+    await runGit(repo, [
+      'merge', '--no-ff', '-m', mergeCommitSubject('Rework the onboarding note', CR), 'juan/proposal',
+    ]);
+    const mergeSha = await gitOut(repo, ['rev-parse', 'HEAD']);
+    // Applied: the source branch goes, as `mergeChangeRequest` retires it.
+    await runGit(repo, ['branch', '-D', 'juan/proposal']);
+
+    git = new GitService(
+      stubWorkspaceService({ [workspaceId]: path.dirname(repo) }),
+      new WorkflowHooks(),
+      testKbContext(),
+    );
+    return { mergeSha, targetBefore, sourceTip };
+  }
+
+  /** The row's pointer at its merge commit: the sha AND the number that proves it. */
+  const ref = (mergeSha: string, number = CR) => ({ number, mergeSha });
+
+  beforeEach(async () => {
+    root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-applied-'));
+  });
+  afterEach(async () => {
+    await fs.rm(root, { recursive: true, force: true }).catch(() => {});
+  });
+
+  it('answers the files the request applied, with their statuses and counts', async () => {
+    const { mergeSha } = await seedMerged();
+    const files = await git.changedFilesOfAppliedChange(workspaceId, ref(mergeSha));
+    const byPath = Object.fromEntries(files.map((f) => [f.path, f]));
+    expect(Object.keys(byPath).sort()).toEqual(['Added.md', 'Knowledge/Open.md', 'base.md']);
+    expect(byPath['Added.md'].status).toBe('added');
+    expect(byPath['base.md'].status).toBe('modified');
+    expect(byPath['base.md'].additions).toBe(1);
+    // The move is reported as one file with both of its names — which is what
+    // the read gate needs to judge it on the folder it LEFT as well.
+    expect(byPath['Knowledge/Open.md'].status).toBe('renamed');
+    expect(byPath['Knowledge/Open.md'].previousPath).toBe('Payroll/Rates.md');
+  });
+
+  // The reason the range is two-dot from the FIRST parent. A three-dot diff
+  // would be read from the merge base of the two parents, so it would re-report
+  // everything that landed on the target while the proposal waited.
+  it('reports nothing the target did on its own while the request waited', async () => {
+    const { mergeSha } = await seedMerged();
+    const files = await git.changedFilesOfAppliedChange(workspaceId, ref(mergeSha));
+    expect(files.map((f) => f.path)).not.toContain('OnTarget.md');
+  });
+
+  it('generates the patches, and skips them entirely at patchCap 0', async () => {
+    const { mergeSha } = await seedMerged();
+    const withPatches = await git.changedFilesOfAppliedChange(workspaceId, ref(mergeSha));
+    expect(withPatches.find((f) => f.path === 'base.md')?.patch).toContain('+more');
+    const without = await git.changedFilesOfAppliedChange(workspaceId, ref(mergeSha), { patchCap: 0 });
+    expect(without.every((f) => f.patch === undefined)).toBe(true);
+  });
+
+  it('answers the same change as the two path views a summary needs', async () => {
+    const { mergeSha } = await seedMerged();
+    const { paths, pairs } = await git.changedPathsAndPairsOfAppliedChange(workspaceId, ref(mergeSha));
+    // The flat list offers both sides of the move for an access lookup; the pairs
+    // say which old name belongs to which file. The file list above and these
+    // pairs must agree, or the list of requests and the detail of one would
+    // disagree about what is readable.
+    expect(paths.sort()).toEqual(['Added.md', 'Knowledge/Open.md', 'base.md']);
+    expect(pairs).toEqual(
+      expect.arrayContaining([
+        { path: 'Knowledge/Open.md', previousPath: 'Payroll/Rates.md' },
+        { path: 'Added.md' },
+        { path: 'base.md' },
+      ]),
+    );
+    const files = await git.changedFilesOfAppliedChange(workspaceId, ref(mergeSha), { patchCap: 0 });
+    expect(pairs.map((p) => p.path).sort()).toEqual(files.map((f) => f.path).sort());
+  });
+
+  it("answers the merge commit's two parents as the request's base and head", async () => {
+    const { mergeSha, targetBefore, sourceTip } = await seedMerged();
+    expect(await git.appliedChangeShas(workspaceId, ref(mergeSha))).toEqual({
+      baseSha: targetBefore,
+      headSha: sourceTip,
+    });
+  });
+
+  // cubic P1 on #347, and the case that makes the whole verification necessary.
+  // When the target already contains the source there is nothing to merge, so the
+  // merge writes NO commit and reports the target tip. A row that recorded that
+  // tip points at an ordinary commit — whatever landed on the target last — and
+  // reading its own change would answer with THAT change's files under this
+  // request's number. Refused, so the request falls back to author-only.
+  it('refuses a commit with no second parent, which no merge of this request wrote', async () => {
+    await seedMerged();
+    await fs.writeFile(path.join(repo, 'SomebodyElse.md'), 'unrelated work\n');
+    await runGit(repo, ['add', '-A']);
+    await runGit(repo, ['commit', '-m', 'unrelated work on the target']);
+    const tip = await gitOut(repo, ['rev-parse', 'HEAD']);
+    for (const call of [
+      () => git.appliedChangeShas(workspaceId, ref(tip)),
+      () => git.changedFilesOfAppliedChange(workspaceId, ref(tip)),
+      () => git.changedPathsAndPairsOfAppliedChange(workspaceId, ref(tip)),
+    ]) {
+      await expect(call()).rejects.toThrow(/is not a merge commit/);
+    }
+  });
+
+  it('tells a commit the clone does not hold apart from one that is not a merge: the first may arrive, the second never will', async () => {
+    await seedMerged();
+    const unknown = 'f'.repeat(40);
+    await expect(git.appliedChangeShas(workspaceId, ref(unknown))).rejects.toThrow(/is not in this clone/);
+    await expect(git.appliedChangeShas(workspaceId, ref(unknown))).rejects.not.toThrow(/is not a merge commit/);
+  });
+
+  // The residual of the same P1, and the reason the NUMBER travels with the sha.
+  // An empty request merged while the target tip was ANOTHER request's merge
+  // commit recorded a sha that is a merge commit — just not this request's. Two
+  // parents alone would accept it and publish the other request's files.
+  it('refuses a merge commit whose subject names a different request', async () => {
+    const { mergeSha } = await seedMerged();
+    for (const call of [
+      () => git.appliedChangeShas(workspaceId, ref(mergeSha, CR + 1)),
+      () => git.changedFilesOfAppliedChange(workspaceId, ref(mergeSha, CR + 1)),
+      () => git.changedPathsAndPairsOfAppliedChange(workspaceId, ref(mergeSha, CR + 1)),
+    ]) {
+      await expect(call()).rejects.toThrow(/is not the merge commit of change request #43/);
+    }
+    // The same commit under its OWN number still reads, so what guards is the
+    // number and not a blanket refusal.
+    expect(
+      (await git.changedFilesOfAppliedChange(workspaceId, ref(mergeSha), { patchCap: 0 })).length,
+    ).toBe(3);
+  });
+
+  // The number is matched at the END of the subject, where `mergeCommitSubject`
+  // puts it, so a title that happens to contain another request's number is not
+  // mistaken for that request's merge commit.
+  it('matches the number at the end, not anywhere in the title', async () => {
+    await seedMerged();
+    await runGit(repo, ['checkout', '-b', 'juan/third']);
+    await fs.writeFile(path.join(repo, 'Third.md'), 'x\n');
+    await runGit(repo, ['add', '-A']);
+    await runGit(repo, ['commit', '-m', 'third']);
+    await runGit(repo, ['checkout', 'main']);
+    await runGit(repo, [
+      'merge', '--no-ff', '-m', mergeCommitSubject('Follow-up to (#99)', 7), 'juan/third',
+    ]);
+    const sha = await gitOut(repo, ['rev-parse', 'HEAD']);
+    await expect(git.appliedChangeShas(workspaceId, ref(sha, 99))).rejects.toThrow(
+      /is not the merge commit of change request #99/,
+    );
+    expect(await git.appliedChangeShas(workspaceId, ref(sha, 7))).toMatchObject({
+      baseSha: expect.any(String),
+    });
+  });
+
+  // Fail-closed, and this is the case it protects: a clone that has not fetched
+  // the merge yet must answer no files, never somebody else's. Every caller reads
+  // the rejection as "the file set could not be resolved" and leaves the request
+  // to its author.
+  it('refuses a commit this clone does not hold, rather than reaching for it', async () => {
+    await seedMerged();
+    const absent = 'f'.repeat(40);
+    for (const call of [
+      () => git.changedFilesOfAppliedChange(workspaceId, ref(absent)),
+      () => git.changedPathsAndPairsOfAppliedChange(workspaceId, ref(absent)),
+      () => git.appliedChangeShas(workspaceId, ref(absent)),
+    ]) {
+      await expect(call()).rejects.toThrow(WorkflowValidationError);
+    }
+  });
+
+  it('refuses anything that is not a sha, so no ref name can be smuggled in', async () => {
+    await seedMerged();
+    for (const bad of ['main', 'HEAD', '', 'main; rm -rf /', '../../etc/passwd', 'abc']) {
+      await expect(
+        git.changedFilesOfAppliedChange(workspaceId, ref(bad)),
+      ).rejects.toThrow(/invalid commit sha/);
+    }
+  });
+
+  it('refuses a root commit, which has no parent to read the change against', async () => {
+    await seedMerged();
+    const rootCommit = await gitOut(repo, ['rev-list', '--max-parents=0', 'HEAD']);
+    await expect(
+      git.changedFilesOfAppliedChange(workspaceId, ref(rootCommit)),
+    ).rejects.toThrow(/is not a merge commit/);
+  });
+
+  it('filters roles.yaml and the folder placeholder, as the branch-pair diff does', async () => {
+    await seedMerged();
+    // A request that touches roles.yaml and creates an empty folder: neither is
+    // content to review, and a merged request must not start listing them when an
+    // open one does not.
+    await runGit(repo, ['checkout', '-b', 'juan/second']);
+    await fs.writeFile(path.join(repo, 'roles.yaml'), 'Admin: [a@b.c]\n');
+    await fs.mkdir(path.join(repo, 'Empty'), { recursive: true });
+    await fs.writeFile(path.join(repo, 'Empty', '.gitkeep'), '');
+    await fs.writeFile(path.join(repo, 'Real.md'), 'content\n');
+    await runGit(repo, ['add', '-A']);
+    await runGit(repo, ['commit', '-m', 'second proposal']);
+    await runGit(repo, ['checkout', 'main']);
+    await runGit(repo, [
+      'merge', '--no-ff', '-m', mergeCommitSubject('The second proposal', 43), 'juan/second',
+    ]);
+    const sha = await gitOut(repo, ['rev-parse', 'HEAD']);
+
+    const files = await git.changedFilesOfAppliedChange(workspaceId, ref(sha, 43), { patchCap: 0 });
+    expect(files.map((f) => f.path)).toEqual(['Real.md']);
+    // The paths view keeps the placeholder (a folder-only request must still
+    // reach the folder's owners) and drops roles.yaml, exactly as the
+    // branch-pair diff does.
+    const { paths, pairs } = await git.changedPathsAndPairsOfAppliedChange(workspaceId, ref(sha, 43));
+    expect(paths.sort()).toEqual(['Empty/.gitkeep', 'Real.md']);
+    expect(pairs.map((p) => p.path)).toEqual(['Real.md']);
+  });
+});