@bevel-software/platform-core-backend 0.29.0 → 0.31.0

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

@@ -1,9 +1,13 @@
 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 { ToolError, hasHttpStatus, type ToolContext, type ToolHandler } from '../../tool-helpers/tool.contract.js';
+import { isCommitSha } from '../../../shared/git.contract.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 { IAccessControl } from '../../access/access-control.interface.js';
+import { assertAgentWriteAllowed, notifyAgentRead, SESSION_ID_INPUT, type AgentAccessGate } from '../../workspace/index.js';
+import { readablePathsAt, readableAtCommits, assertReadableAtCommits } from '../read-on-branch.js';
 import type { KbContext } from '../../../shared/kb-context.js';
 import { workspaceIdForBranch } from '../../../shared/workspace-id.js';
 import { assertInsideRepo, normalizePathArgs } from '../../kb-fs/repo-path.js';
@@ -176,6 +180,21 @@ export function registerWorkflowTools(
    * nor links a request it answers no for.
    */
   maySeeChangeRequest: (ctx: ToolContext, number: number) => Promise<boolean>,
+  /**
+   * The per-file read gate the history tools apply: a file's past is the
+   * file, so a history read takes the read the file itself takes — on the
+   * workspace for its own branch's history (`canRead`), at the commit
+   * another branch's content was served from (`canReadAtRef`, through
+   * `readableAtCommits`, the compare route's own rule), and in batches for
+   * the path lists `branch_status` shows.
+   */
+  accessControl: Pick<IAccessControl, 'canRead' | 'canReadAtRef' | 'canReadBatch' | 'canReadBatchAtRef'>,
+  /**
+   * The deployment's blocking read hook, told of every file content a history
+   * tool serves, as `read_file` tells it — a hook that refuses the read
+   * refuses the history too.
+   */
+  agentAccessGate: AgentAccessGate,
 ): void {
   const { kbDirName } = kb;
   const mount = (spec: {
@@ -748,4 +767,446 @@ export function registerWorkflowTools(
       };
     },
   });
+
+  // ── History and syncing ────────────────────────────────────────────────────
+  //
+  // What the app's History tab, compare view and "update from target" do,
+  // as tools: the agent never runs git itself. Each reads through the
+  // workflow service's gated methods and takes the per-file read the file
+  // itself takes.
+
+  /** The branch's workspace, made when it is not on disk yet, and its id. */
+  const workspaceOf = async (ctx: ToolContext, branch: string): Promise<string> => {
+    await ctx.workspaceService.getOrCreateForBranch(branch);
+    return workspaceIdForBranch(branch);
+  };
+
+  /**
+   * The per-file read gate on the workspace's own branch, and the
+   * deployment's read hook told of the read (as `read_file` tells it);
+   * answers the repository-relative path.
+   */
+  const requireRead = async (ctx: ToolContext, branch: string, workspaceId: string, path: string): Promise<string> => {
+    const rel = stripKbDir(path, kbDirName);
+    await notifyAgentRead(agentAccessGate, ctx, branch, path);
+    if (!(await accessControl.canRead(workspaceId, ctx.user.email, rel))) {
+      throw new ToolError(`You don't have permission to read "${rel}".`, 403, { kind: 'read-denied', path: rel });
+    }
+    return rel;
+  };
+
+  /**
+   * The per-file read gate for content served from ANOTHER branch — the
+   * compare route's rule: at every commit the branch resolves to (the one
+   * the service serves it from, and its other tip when the local head and
+   * the published tip differ), all of which must grant, asked by the
+   * service inside its reservation before anything is said about the path
+   * there.
+   */
+  const requireReadAtCommits = (ctx: ToolContext, workspaceId: string, rel: string, commits: readonly string[], branch: string): Promise<void> =>
+    assertReadableAtCommits(accessControl, workspaceId, ctx.user.email, rel, commits, branch);
+
+  /** Which of `paths` the caller may read at `origin/<base>` — the change-request reads' rule, `readablePathsAt`. */
+  const readableAt = (ctx: ToolContext, workspaceId: string, base: string, paths: string[]): Promise<Set<string>> =>
+    readablePathsAt(accessControl, workspaceId, ctx.user.email, base, paths);
+
+
+  mount({
+    name: 'list_file_changes',
+    description:
+      'The history of one file on `branch`: its commits, newest first — who made each, when, and its ' +
+      'subject — as the app\'s History tab shows them. `limit` caps the list (default 20, at most 100). ' +
+      'Read a version with `read_file_at` and its diff with `compare_file`. Takes the read the file itself ' +
+      'takes; a folder has no history of its own (ask per file).',
+    inputs: {
+      type: 'object',
+      properties: {
+        path: { type: 'string', minLength: 1, description: 'The file, workspace-relative (as `read_file` takes it).' },
+        limit: { type: 'integer', minimum: 1, maximum: 100, description: 'How many commits at most (default 20).' },
+        sessionId: SESSION_ID_INPUT,
+      },
+      required: ['path'],
+      additionalProperties: false,
+    },
+    outputs: {
+      type: 'object',
+      properties: {
+        path: { type: 'string', description: 'The file, repository-relative.' },
+        changes: { type: 'array', items: commitSchema, description: 'Newest first.' },
+      },
+      required: ['path', 'changes'],
+    },
+    write: false,
+    handler: async (args, ctx: ToolContext) => {
+      const branch = args.branch as string;
+      const path = args.path;
+      if (typeof path !== 'string' || path.length === 0) throw new ToolError('`path` is required.', 400);
+      const workspaceId = await workspaceOf(ctx, branch);
+      const rel = await requireRead(ctx, branch, workspaceId, path);
+      const limit = typeof args.limit === 'number' ? args.limit : undefined;
+      const changes = await ctx.workflowService.listChangesForFile(workspaceId, path, limit);
+      return { path: rel, changes };
+    },
+  });
+
+  mount({
+    name: 'read_file_at',
+    description:
+      'One file as it was at a point in history: `at` is a commit (from `list_file_changes`, on `branch`\'s ' +
+      'own history) or the name of another branch (its published tip). Answers `content` (null when the ' +
+      'file was not there) and `sha`, the commit it was read at; for a commit, also `before`, the file ' +
+      'just before that commit. To put an earlier version back, write it with `write_file`. Takes the read ' +
+      'the file takes at that point.',
+    inputs: {
+      type: 'object',
+      properties: {
+        path: { type: 'string', minLength: 1, description: 'The file, workspace-relative.' },
+        at: { type: 'string', minLength: 1, description: 'A commit sha, or a branch name.' },
+        sessionId: SESSION_ID_INPUT,
+      },
+      required: ['path', 'at'],
+      additionalProperties: false,
+    },
+    outputs: {
+      type: 'object',
+      properties: {
+        path: { type: 'string', description: 'The file, repository-relative.' },
+        at: { type: 'string', description: 'What was asked for.' },
+        kind: { type: 'string', enum: ['commit', 'branch'] },
+        sha: { type: 'string', description: 'The commit the content was read at.' },
+        content: { type: ['string', 'null'], description: 'The file at that commit; null when it was not there.' },
+        before: { type: ['string', 'null'], description: 'For a commit: the file just before it; null when it was not there (or the commit is the first).' },
+      },
+      required: ['path', 'at', 'kind', 'sha', 'content'],
+    },
+    write: false,
+    handler: async (args, ctx: ToolContext) => {
+      const branch = args.branch as string;
+      const path = args.path;
+      const at = args.at;
+      if (typeof path !== 'string' || path.length === 0) throw new ToolError('`path` is required.', 400);
+      if (typeof at !== 'string' || at.length === 0) throw new ToolError('`at` is required: a commit sha or a branch name.', 400);
+      const workspaceId = await workspaceOf(ctx, branch);
+      // The hook and the workspace gate first, whichever point in history is
+      // read: the file is this workspace's file.
+      const rel = await requireRead(ctx, branch, workspaceId, path);
+      if (isCommitSha(at)) {
+        const { baseline, current } = await ctx.workflowService.fileAtChange(workspaceId, path, at);
+        return { path: rel, at, kind: 'commit', sha: at, content: current, before: baseline };
+      }
+      // Read at the branch's published tip, authorized at that very commit
+      // inside the read — before anything is said about the path there,
+      // the folder refusal included: the ref is a name a fetch may move
+      // between a verdict and a read; the commit is not.
+      const read = await ctx.workflowService.fileAtBranch(workspaceId, path, at, (commits) => requireReadAtCommits(ctx, workspaceId, rel, commits, at));
+      return { path: rel, at, kind: 'branch', sha: read.sha, content: read.content };
+    },
+  });
+
+  mount({
+    name: 'compare_file',
+    description:
+      'The unified diff of one file: between two branches (`from`, `to`; either may be `branch` itself), ' +
+      'or of one commit on `branch` (`at`: what that commit changed in the file). Empty when identical. ' +
+      'Takes the read the file takes on each side.',
+    inputs: {
+      type: 'object',
+      properties: {
+        path: { type: 'string', minLength: 1, description: 'The file, workspace-relative.' },
+        from: { type: 'string', minLength: 1, description: 'A branch: the diff\'s left side.' },
+        to: { type: 'string', minLength: 1, description: 'A branch: the diff\'s right side.' },
+        at: { type: 'string', minLength: 1, description: 'A commit sha on `branch`: the diff that commit made in the file.' },
+        sessionId: SESSION_ID_INPUT,
+      },
+      required: ['path'],
+      additionalProperties: false,
+    },
+    outputs: {
+      type: 'object',
+      properties: {
+        path: { type: 'string', description: 'The file, repository-relative.' },
+        diff: { type: 'string', description: 'A unified diff; empty when the two sides are identical.' },
+      },
+      required: ['path', 'diff'],
+    },
+    write: false,
+    handler: async (args, ctx: ToolContext) => {
+      const branch = args.branch as string;
+      const path = args.path;
+      if (typeof path !== 'string' || path.length === 0) throw new ToolError('`path` is required.', 400);
+      const workspaceId = await workspaceOf(ctx, branch);
+      // As the compare route: the workspace's own gate on the path (the
+      // checked-out side can be served from the working tree), then each
+      // compared side at the commit it was served from.
+      const rel = await requireRead(ctx, branch, workspaceId, path);
+      if (typeof args.at === 'string' && args.at.length > 0) {
+        if (!isCommitSha(args.at)) throw new ToolError('`at` must be a full commit sha.', 400);
+        return { path: rel, diff: await ctx.workflowService.showFileAtChange(workspaceId, path, args.at) };
+      }
+      const from = args.from;
+      const to = args.to;
+      if (typeof from !== 'string' || from.length === 0 || typeof to !== 'string' || to.length === 0) {
+        throw new ToolError('Give `from` and `to` (two branches), or `at` (one commit).', 400);
+      }
+      const compared = await ctx.workflowService.compareFile(workspaceId, path, from, to, async (sides) => {
+        await requireReadAtCommits(ctx, workspaceId, rel, sides.from, from);
+        await requireReadAtCommits(ctx, workspaceId, rel, sides.to, to);
+      });
+      return { path: rel, diff: compared.diff };
+    },
+  });
+
+  mount({
+    name: 'branch_status',
+    description:
+      'Where `branch` stands, before proposing or syncing a draft. Answers whether it is on the shared ' +
+      'repository, how far ahead of and behind its upstream it is, whether the shared branch has commits this ' +
+      'workspace lacks (`behindRemote`: `update_branch` brings them in), the files written but not committed ' +
+      'yet, the protected branch it was forked from (`forkBase`), and `changedPaths`: what it changes against ' +
+      '`base` (default: the fork base) — the files a change request into it would carry.',
+    inputs: {
+      type: 'object',
+      properties: {
+        base: { type: 'string', minLength: 1, description: 'The branch to compare against (default: the fork base).' },
+        sessionId: SESSION_ID_INPUT,
+      },
+      additionalProperties: false,
+    },
+    outputs: {
+      type: 'object',
+      properties: {
+        branch: { type: 'string' },
+        isProtected: { type: 'boolean' },
+        hasRemote: { type: 'boolean', description: 'True when the shared repository has the branch.' },
+        ahead: { type: ['integer', 'null'], description: 'Commits ahead of the upstream (or the fork base); null when unresolved.' },
+        behind: { type: ['integer', 'null'], description: 'Commits behind; null when unresolved.' },
+        behindRemote: { type: 'boolean', description: 'The shared branch has commits this workspace has not merged yet.' },
+        uncommittedPaths: { type: 'array', items: { type: 'string' }, description: 'Written but not committed yet (saves still landing).' },
+        forkBase: { type: ['string', 'null'], description: 'The protected branch this one was forked from; null when none can be reached.' },
+        base: { type: ['string', 'null'], description: 'What `changedPaths` is against.' },
+        changedPaths: { type: 'array', items: { type: 'string' }, description: 'Repository-relative; rename-aware; only the paths you may read. Empty when `base` is null.' },
+        withheldPaths: { type: 'integer', description: 'How many changed or uncommitted paths were left out because you may not read them.' },
+      },
+      required: ['branch', 'isProtected', 'hasRemote', 'ahead', 'behind', 'behindRemote', 'uncommittedPaths', 'forkBase', 'base', 'changedPaths', 'withheldPaths'],
+    },
+    write: false,
+    handler: async (args, ctx: ToolContext) => {
+      const branch = args.branch as string;
+      const workspaceId = await workspaceOf(ctx, branch);
+      // Each read below takes the workspace's reservation on its own: this
+      // is a REPORT of independent facts, not a range measured across steps,
+      // and a save or sync landing between two of them is tolerated — the
+      // next call reports it. (The one answer that must be exact, what a
+      // merge is of, is taken under one reservation by `update_branch`.)
+      const [status, branches, pending, forkBase] = await Promise.all([
+        ctx.workflowService.branchStatus(workspaceId),
+        ctx.workflowService.listBranches(workspaceId),
+        ctx.workflowService.listPendingChangePaths(workspaceId),
+        ctx.workflowService.resolveForkBase(workspaceId, branch),
+      ]);
+      const info = branches.find((b) => b.name === branch);
+      const base = typeof args.base === 'string' && args.base.length > 0 ? args.base : forkBase;
+      // A path's name is information too: the changed paths are shown as the
+      // change-request reads show them (readable at `origin/<base>`), the
+      // uncommitted ones as the workspace's own listing would.
+      const changedAll =
+        base && base !== branch ? await ctx.workflowService.changedPathsBetweenBranches(workspaceId, base, branch) : [];
+      const readableChanged = base ? await readableAt(ctx, workspaceId, base, changedAll) : new Set<string>();
+      const changedPaths = changedAll.filter((p) => readableChanged.has(p));
+      const pendingRel = pending.map((p) => stripKbDir(p, kbDirName));
+      const pendingVerdicts = pendingRel.length > 0 ? await accessControl.canReadBatch(workspaceId, ctx.user.email, pendingRel) : new Map<string, boolean>();
+      const uncommittedPaths = pendingRel.filter((p) => pendingVerdicts.get(p) === true);
+      return {
+        branch,
+        isProtected: info?.isProtected ?? kb.protectedBranches.has(branch),
+        hasRemote: info?.hasRemote ?? status.hasUpstream,
+        ahead: info?.ahead ?? null,
+        behind: info?.behind ?? null,
+        behindRemote: status.unmergedFromUpstream,
+        uncommittedPaths,
+        forkBase,
+        base: base && base !== branch ? base : null,
+        changedPaths,
+        withheldPaths: changedAll.length - changedPaths.length + (pendingRel.length - uncommittedPaths.length),
+      };
+    },
+  });
+
+  mount({
+    name: 'update_branch',
+    description:
+      'Bring another branch into `branch` as a merge commit by you, and publish it: `from` (a draft\'s ' +
+      'target, to refresh the draft), or left out, the branch\'s own shared state when it moved while this ' +
+      'workspace held commits (`branch_status` says `behindRemote`). Never a protected branch. CONFLICTS: ' +
+      'the first call answers `conflicts` naming every conflicted path with the file at the merge base, on ' +
+      'each side (`ours` = `branch`, `theirs` = `from`) and the working copy with git\'s markers, and leaves ' +
+      'the branch as it was. Decide each file (keep both sides\' information unless one is clearly stale; ' +
+      '`list_file_changes` shows intent), then call again with `resolutions`, one per conflicted path: ' +
+      '`content` (the resolved text) or `choose` (`ours`, `theirs`, `delete`). Only conflicted paths are ' +
+      'written here; other edits go through the file tools. Answers `merged`, `nothing-to-merge`, ' +
+      '`conflicts` again (something changed meanwhile), or `pending-commits` (writes still landing: retry).',
+    inputs: {
+      type: 'object',
+      properties: {
+        from: { type: 'string', minLength: 1, description: 'The branch to bring in (default: this branch\'s own shared state).' },
+        sessionId: SESSION_ID_INPUT,
+        resolutions: {
+          type: 'array',
+          description: 'One per conflicted path, from a previous `conflicts` answer.',
+          items: {
+            type: 'object',
+            properties: {
+              path: { type: 'string', minLength: 1, description: 'The conflicted path, as the answer named it.' },
+              content: { type: 'string', description: 'The resolved text of the file.' },
+              choose: { type: 'string', enum: ['ours', 'theirs', 'delete'], description: 'Keep one side whole, or drop the file.' },
+            },
+            required: ['path'],
+            additionalProperties: false,
+          },
+        },
+      },
+      additionalProperties: false,
+    },
+    outputs: {
+      type: 'object',
+      properties: {
+        kind: { type: 'string', enum: ['merged', 'nothing-to-merge', 'conflicts', 'pending-commits'] },
+        from: { type: 'string', description: 'The branch brought in.' },
+        sha: { type: 'string', description: '`merged`: the merge commit, now the tip of `branch`, published; `nothing-to-merge`: the unchanged tip.' },
+        resolvedPaths: { type: 'array', items: { type: 'string' }, description: '`merged`: the conflicts the resolutions settled.' },
+        mergeBase: { type: ['string', 'null'], description: '`conflicts`: the common ancestor; null when the histories are unrelated.' },
+        ours: { type: 'string', description: '`conflicts`: the tip of `branch`.' },
+        theirs: { type: 'string', description: '`conflicts`: the tip of `from`.' },
+        files: {
+          type: 'array',
+          description:
+            '`conflicts`: every conflicted path you may read, with the file at the base, on each side, and the marked-up ' +
+            'working copy. A side is null when that side has no file — or when `truncated` names it (too large or not ' +
+            'text): then read `ours` with `read_file`, `theirs` with `read_file_at` at `from`, `base` with `read_file_at` ' +
+            'at `mergeBase`.',
+          items: {
+            type: 'object',
+            properties: {
+              path: { type: 'string' },
+              base: { type: ['string', 'null'] },
+              ours: { type: ['string', 'null'] },
+              theirs: { type: ['string', 'null'] },
+              merged: { type: ['string', 'null'] },
+              truncated: { type: 'array', items: { type: 'string', enum: ['base', 'ours', 'theirs', 'merged'] } },
+            },
+            required: ['path', 'base', 'ours', 'theirs', 'merged'],
+          },
+        },
+        unresolved: { type: 'array', items: { type: 'string' }, description: '`conflicts`: the paths you may read that no resolution covered.' },
+        withheldConflicts: {
+          type: 'integer',
+          description:
+            '`conflicts`: how many conflicted files were left out because you may not read them on one of the two branches. ' +
+            'They are not yours to settle: ask a person who can read them to update the draft in the app.',
+        },
+        branch: { type: 'string', description: '`pending-commits`: the branch whose writes are not committed yet.' },
+        pending: { type: 'integer', description: '`pending-commits`: how many.' },
+        needsAttention: { type: 'string', description: '`pending-commits`: a queued commit failed; the worker\'s message. Tell the user.' },
+        message: { type: 'string', description: '`pending-commits`: what to do next.' },
+      },
+      required: ['kind'],
+    },
+    write: true,
+    handler: async (args, ctx: ToolContext) => {
+      const branch = args.branch as string;
+      const from = args.from;
+      if (from !== undefined && (typeof from !== 'string' || from.length === 0)) {
+        throw new ToolError('`from` must be a branch name.', 400);
+      }
+      let resolutions: { path: string; content?: string; choose?: 'ours' | 'theirs' | 'delete' }[] | undefined;
+      if (args.resolutions !== undefined) {
+        if (!Array.isArray(args.resolutions)) throw new ToolError('`resolutions` must be a list.', 400);
+        resolutions = args.resolutions.map((r: unknown, i: number) => {
+          const entry = r as Record<string, unknown>;
+          if (!entry || typeof entry.path !== 'string' || entry.path.length === 0) {
+            throw new ToolError(`resolutions[${i}]: \`path\` is required.`, 400);
+          }
+          const out: { path: string; content?: string; choose?: 'ours' | 'theirs' | 'delete' } = { path: entry.path };
+          if (entry.content !== undefined) {
+            if (typeof entry.content !== 'string') throw new ToolError(`resolutions[${i}]: \`content\` must be text.`, 400);
+            out.content = entry.content;
+          }
+          if (entry.choose !== undefined) {
+            if (entry.choose !== 'ours' && entry.choose !== 'theirs' && entry.choose !== 'delete') {
+              throw new ToolError(`resolutions[${i}]: \`choose\` is \`ours\`, \`theirs\` or \`delete\`.`, 400);
+            }
+            out.choose = entry.choose;
+          }
+          return out;
+        });
+      }
+      const workspaceId = await workspaceOf(ctx, branch);
+      /**
+       * Whether the caller may read `rel` on both sides of this merge — at
+       * the two COMMITS the answer says the merge was of, which is what its
+       * bytes are from, never at a branch ref that may have moved since the
+       * reservation was released — with the deployment's read hook told of
+       * the read, as every history read tells it: a hook that refuses makes
+       * the file one the caller may not read; a hook that fails is not an
+       * answer and propagates.
+       */
+      const mayReadBothSides = async (rel: string, at: { ours: string; theirs: string }): Promise<boolean> => {
+        try {
+          await notifyAgentRead(agentAccessGate, ctx, branch, `${kbDirName}/${rel}`);
+        } catch (err) {
+          // A hook's own refusal carries a status; anything else is a failure of the hook, not an answer.
+          if (hasHttpStatus(err)) return false;
+          throw err;
+        }
+        return readableAtCommits(accessControl, workspaceId, ctx.user.email, rel, [at.ours, at.theirs]);
+      };
+      // A resolution reads a file on both branches and writes it on the
+      // draft, so the deployment's hooks are asked as they are for any read
+      // and any write. The access model's own verdicts — may the caller read
+      // the file on both branches, may they change it on the draft — are the
+      // service's, asked inside the merge against the source commit as
+      // fetched (`updateBranch`), so a rule that changed with the source
+      // cannot be outrun by a check made before it was fetched.
+      for (const r of resolutions ?? []) {
+        const wsPath = `${kbDirName}/${stripKbDir(r.path, kbDirName)}`;
+        try {
+          await notifyAgentRead(agentAccessGate, ctx, branch, wsPath);
+        } catch (err) {
+          if (hasHttpStatus(err)) {
+            throw new ToolError(`You may not read "${stripKbDir(r.path, kbDirName)}" here, so it is not yours to settle.`, 403, {
+              kind: 'read-denied',
+              path: stripKbDir(r.path, kbDirName),
+            });
+          }
+          throw err;
+        }
+        await assertAgentWriteAllowed(agentAccessGate, ctx, branch, wsPath);
+      }
+      // A resolution's content lands on the draft by the merge, not by the
+      // file tools' filesystem: it takes the same pre-disk gate that
+      // filesystem runs (`roles.yaml` must parse, no new role, no unknown
+      // group), handed to the service to ask before the merge.
+      const outcome =
+        resolutions !== undefined
+          ? await ctx.workflowService.updateBranch(workspaceId, ctx.user, {
+              ...(from !== undefined ? { from } : {}),
+              resolutions,
+              validateWrite: await ctx.getWriteValidator(branch),
+            })
+          : await ctx.workflowService.updateBranch(workspaceId, ctx.user, from !== undefined ? { from } : {});
+      if (outcome.kind !== 'conflicts') return outcome;
+      // A conflict answer carries the file on both branches, and a path's
+      // name is information too: a file the caller may not read on both is
+      // left out of `files` and `unresolved` alike and only counted.
+      const files = [];
+      for (const f of outcome.files) if (await mayReadBothSides(f.path, outcome)) files.push(f);
+      const shown = new Set(files.map((f) => f.path));
+      return {
+        ...outcome,
+        files,
+        unresolved: outcome.unresolved.filter((p) => shown.has(p)),
+        withheldConflicts: outcome.files.length - files.length,
+      };
+    },
+  });
 }

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

@@ -0,0 +1,175 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { testKbContext } from '../../../../__tests__/kb-context.js';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import type { WorkspaceService } from '../../../workspace/workspace.service.js';
+import { WorkflowHooks } from '../../workflow-hooks.js';
+import { GitService } from '../git.service.js';
+import { WorkspaceMutex } from '../../../kb-fs/mutex.js';
+
+/**
+ * Every git process the service starts, by argv, so a test can say what a
+ * change-request read is allowed to cost. The fixture's own git runs through
+ * `execFile` and is not logged.
+ */
+const { spawnLog } = vi.hoisted(() => ({ spawnLog: [] as string[][] }));
+
+vi.mock('node:child_process', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('node:child_process')>();
+  const spawn = ((file: string, args: string[], options: unknown) => {
+    if (file === 'git') spawnLog.push(args ?? []);
+    return (actual.spawn as unknown as (...a: unknown[]) => unknown)(file, args, options);
+  }) as unknown as typeof actual.spawn;
+  return { ...actual, spawn };
+});
+
+const execFileAsync = promisify(execFile);
+
+async function runGit(cwd: string, args: string[]): Promise<void> {
+  await execFileAsync('git', args, {
+    cwd,
+    env: {
+      ...process.env,
+      GIT_AUTHOR_NAME: 'Test',
+      GIT_AUTHOR_EMAIL: 't@x.com',
+      GIT_COMMITTER_NAME: 'Test',
+      GIT_COMMITTER_EMAIL: 't@x.com',
+    },
+  });
+}
+
+const spawnsOf = (subcommand: string) => spawnLog.filter((argv) => argv.includes(subcommand)).length;
+
+/**
+ * What a change request's changed paths cost: the tips come from the ref
+ * files and the diff is read from git ONCE per pair of commits. A listing
+ * that nothing has moved under asks git for nothing; a push moves a tip,
+ * and that request alone is diffed again.
+ */
+describe('a change request is diffed once per pair of commits', () => {
+  let root: string;
+  let upstream: string;
+  let repo: string;
+  let other: string;
+  let svc: GitService;
+  const workspaceId = 'ws-main';
+  const secondWorkspaceId = 'ws-two';
+
+  beforeEach(async () => {
+    root = await fs.mkdtemp(path.join(os.tmpdir(), 'bevel-changed-memo-'));
+    upstream = path.join(root, 'upstream.git');
+    await runGit(root, ['init', '--bare', '-b', 'main', upstream]);
+    const seed = path.join(root, '.seed');
+    await fs.mkdir(seed);
+    await runGit(seed, ['init', '-b', 'main']);
+    await runGit(seed, ['remote', 'add', 'origin', upstream]);
+    await fs.writeFile(path.join(seed, 'base.md'), 'base\n');
+    await runGit(seed, ['add', '-A']);
+    await runGit(seed, ['commit', '-m', 'init']);
+    await runGit(seed, ['checkout', '-b', 'feature']);
+    await fs.writeFile(path.join(seed, 'one.md'), 'one\n');
+    await runGit(seed, ['add', '-A']);
+    await runGit(seed, ['commit', '-m', 'one']);
+    await runGit(seed, ['push', 'origin', 'main', 'feature']);
+    const workspaceDir = path.join(root, workspaceId);
+    repo = path.join(workspaceDir, 'knowledge-base');
+    await fs.mkdir(workspaceDir, { recursive: true });
+    await runGit(root, ['clone', upstream, repo]);
+    other = path.join(root, 'other');
+    await runGit(root, ['clone', upstream, other]);
+    // A second workspace of the same knowledge base, with its own reservation.
+    const secondDir = path.join(root, secondWorkspaceId);
+    await fs.mkdir(secondDir, { recursive: true });
+    await runGit(root, ['clone', upstream, path.join(secondDir, 'knowledge-base')]);
+    const workspace = {
+      getWorkspacePath: async (id: string) => {
+        if (id === workspaceId) return workspaceDir;
+        if (id === secondWorkspaceId) return secondDir;
+        throw new Error(`unexpected workspace ${id}`);
+      },
+    } as unknown as WorkspaceService;
+    svc = new GitService(
+      workspace,
+      new WorkflowHooks(),
+      testKbContext({ branchModel: { defaultBranch: 'main', protectedBranches: ['main'] } }),
+      new WorkspaceMutex(),
+    );
+    spawnLog.length = 0;
+  });
+
+  afterEach(async () => {
+    await fs.rm(root, { recursive: true, force: true });
+  });
+
+  it('reads the tips from the ref files, diffs once, and asks git nothing the second time', async () => {
+    const first = await svc.changedPathsAndPairsForPr(workspaceId, 'main', 'feature', { fetch: false });
+    expect(first.paths).toEqual(['one.md']);
+    expect(first.pairs).toEqual([{ path: 'one.md' }]);
+    expect(spawnsOf('diff')).toBe(1);
+    expect(spawnsOf('rev-parse')).toBe(0);
+
+    spawnLog.length = 0;
+    const second = await svc.changedPathsAndPairsForPr(workspaceId, 'main', 'feature', { fetch: false });
+    expect(second).toEqual(first);
+    expect(spawnLog).toEqual([]);
+
+    // The access-check flavour reads the same pair: the memo answers it too.
+    spawnLog.length = 0;
+    expect(await svc.changedPathsForPr(workspaceId, 'main', 'feature', { fetch: false, forAccessCheck: true })).toEqual(['one.md']);
+    expect(spawnLog).toEqual([]);
+  });
+
+  it('diffs again, once, when a push moves a tip', async () => {
+    await svc.changedPathsAndPairsForPr(workspaceId, 'main', 'feature', { fetch: false });
+    // Someone else pushes to feature; the workspace fetches as a listing's
+    // whole-clone refresh does, which rewrites the ref file.
+    await runGit(other, ['checkout', 'feature']);
+    await fs.writeFile(path.join(other, 'two.md'), 'two\n');
+    await runGit(other, ['add', '-A']);
+    await runGit(other, ['commit', '-m', 'two']);
+    await runGit(other, ['push', 'origin', 'feature']);
+    await runGit(repo, ['fetch', 'origin']);
+
+    spawnLog.length = 0;
+    const after = await svc.changedPathsAndPairsForPr(workspaceId, 'main', 'feature', { fetch: false });
+    expect(after.paths.sort()).toEqual(['one.md', 'two.md']);
+    expect(spawnsOf('diff')).toBe(1);
+    expect(spawnsOf('rev-parse')).toBe(0);
+
+    spawnLog.length = 0;
+    expect(await svc.changedPathsAndPairsForPr(workspaceId, 'main', 'feature', { fetch: false })).toEqual(after);
+    expect(spawnLog).toEqual([]);
+  });
+
+  it('shares one diff between concurrent reads of a pair nobody has seen, even from two workspaces', async () => {
+    // Two workspaces take two reservations, so nothing serialises the two
+    // reads but the in-flight diff itself: both answer, one `diff` runs.
+    const [a, b] = await Promise.all([
+      svc.changedPathsAndPairsForPr(workspaceId, 'main', 'feature', { fetch: false }),
+      svc.changedPathsAndPairsForPr(secondWorkspaceId, 'main', 'feature', { fetch: false }),
+    ]);
+    expect(a).toEqual(b);
+    expect(a.paths).toEqual(['one.md']);
+    expect(spawnsOf('diff')).toBe(1);
+  });
+
+  it('still asks git about a branch the ref files do not hold, and answers as before', async () => {
+    // A branch this clone has never fetched: the files say missing for both
+    // of its names, which is rev-parse's answer too — and `fetch: false`
+    // then turns into the per-request fetch the caller was promised.
+    await runGit(other, ['checkout', '-b', 'later']);
+    await fs.writeFile(path.join(other, 'three.md'), 'three\n');
+    await runGit(other, ['add', '-A']);
+    await runGit(other, ['commit', '-m', 'three']);
+    await runGit(other, ['push', 'origin', 'later']);
+
+    spawnLog.length = 0;
+    const got = await svc.changedPathsAndPairsForPr(workspaceId, 'main', 'later', { fetch: false });
+    expect(got.paths).toEqual(['three.md']);
+    expect(spawnsOf('fetch')).toBe(1);
+    expect(spawnsOf('diff')).toBe(1);
+  });
+});