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

package/src/modules/workflow/__tests__/workflow.service.update-from-target.test.ts

@@ -11,9 +11,11 @@ import type { PendingCommitsService } from '../pending-commits.service.js';
 import type { Database } from '../../database/connection.js';
 import { WorkflowService } from '../workflow.service.js';
 import { openChangeGate } from '../../../__tests__/open-change-gate.js';
+import type { WorkflowEventBus } from '../event-bus.js';
 import {
   ChangeRequestConflictsError,
   PullRebaseConflictError,
+  PushNeedsAgentResolutionError,
   WorkflowDomainError,
 } from '../../../shared/domain-errors.js';
 
@@ -76,6 +78,8 @@ function harness(opts: {
   /** Does the clone hold commits origin has not seen? */
   unpushed?: boolean;
   unpushedError?: Error;
+  /** Each push answers the next of these in turn: an Error rejects, undefined lands. */
+  pushes?: Array<Error | undefined>;
 }) {
   // Two resolves per update: once after the pull (where the branch IS), once
   // after the merge (where it ended up). One mock that answers in order, so a
@@ -93,7 +97,10 @@ function harness(opts: {
       ? vi.fn().mockRejectedValue(opts.pullError)
       : vi.fn().mockResolvedValue({ treeChanged: false }),
     mergeFromOrigin: vi.fn().mockResolvedValue(opts.merge ?? { kind: 'clean', alreadyUpToDate: false }),
-    push: vi.fn().mockResolvedValue(undefined),
+    push: (opts.pushes ?? []).reduce(
+      (fn, outcome) => (outcome ? fn.mockRejectedValueOnce(outcome) : fn.mockResolvedValueOnce(undefined)),
+      vi.fn().mockResolvedValue(undefined),
+    ),
     hasUnpushedCommits: opts.unpushedError
       ? vi.fn().mockRejectedValue(opts.unpushedError)
       : vi.fn().mockResolvedValue(opts.unpushed ?? true),
@@ -114,6 +121,7 @@ function harness(opts: {
   const reviewWorkflow = {
     carryApprovalsForward: vi.fn().mockResolvedValue(opts.carried ?? 0),
   };
+  const emit = vi.fn();
   const svc = new WorkflowService(
     {} as unknown as Database,
     git as unknown as GitService,
@@ -125,8 +133,9 @@ function harness(opts: {
     pendingCommits as unknown as PendingCommitsService,
     testKbContext(),
     openChangeGate(),
+    { emit } as unknown as WorkflowEventBus,
   );
-  return { svc, git, prs, pendingCommits, reviewWorkflow, refreshed };
+  return { svc, git, prs, pendingCommits, reviewWorkflow, refreshed, emit };
 }
 
 describe('WorkflowService.updateFromTarget', () => {
@@ -385,4 +394,47 @@ describe('WorkflowService.updateFromTarget: the approvals the merge did not touc
     // slow beats a dialog that goes on presenting pre-merge text as current.
     expect(result.updatedPaths).toEqual(['Sales/Deal.md']);
   });
+
+  describe('when the repository host refuses the push', () => {
+    const REFUSED = new Error('git push failed: remote: Internal Server Error');
+
+    it('keeps the merge applied locally and answers 409 with the saved-locally sentence and the banner', async () => {
+      const h = harness({ changedPaths: ['Sales/Deal.md'], pushes: [REFUSED] });
+      const err = await h.svc.updateFromTarget(WS, USER, 7).catch((e: unknown) => e);
+
+      expect(err).toBeInstanceOf(PushNeedsAgentResolutionError);
+      expect((err as PushNeedsAgentResolutionError).status).toBe(409);
+      expect((err as Error).message).toContain('Saved locally on "alice/deal"');
+      expect(JSON.stringify((err as PushNeedsAgentResolutionError).payload)).not.toContain('Internal Server Error');
+      // One attempt: a refusal is not a divergence, so nothing is retried.
+      expect(h.git.push).toHaveBeenCalledTimes(1);
+      // The merge ran and stays in the clone — the next push carries it.
+      expect(h.git.mergeFromOrigin).toHaveBeenCalledTimes(1);
+      expect(h.emit).toHaveBeenCalledWith(
+        expect.objectContaining({ kind: 'git-sync-failed', workspaceId: 'alice/deal', branch: 'alice/deal' }),
+      );
+    });
+
+    it('the next update pushes what is still unpushed, and the banner clears', async () => {
+      const h = harness({
+        changedPaths: ['Sales/Deal.md'],
+        unpushed: true,
+        pushes: [REFUSED, undefined],
+      });
+      await expect(h.svc.updateFromTarget(WS, USER, 7)).rejects.toBeInstanceOf(PushNeedsAgentResolutionError);
+      await h.svc.updateFromTarget(WS, USER, 7);
+      const kinds = h.emit.mock.calls.map((c) => (c[0] as { kind: string }).kind).filter((k) => k.startsWith('git-sync-'));
+      expect(kinds).toEqual(['git-sync-failed', 'git-sync-recovered']);
+    });
+
+    it('a non-fast-forward recovers with a merge-preserving pull, so the merge stays a merge', async () => {
+      const h = harness({
+        changedPaths: ['Sales/Deal.md'],
+        pushes: [new Error('! [rejected] alice/deal -> alice/deal (non-fast-forward)'), undefined],
+      });
+      await h.svc.updateFromTarget(WS, USER, 7);
+      expect(h.git.push).toHaveBeenCalledTimes(2);
+      expect(h.git.pull).toHaveBeenLastCalledWith(WS, { preserveMerges: true });
+    });
+  });
 });

package/src/modules/workflow/agent-tools/__tests__/change-request-read.tools.test.ts

@@ -383,6 +383,25 @@ describe('list_change_requests', () => {
     expect(calls).toContainEqual(['listChangeRequestsByState', ['closed', 'merged', 'open']]);
   });
 
+  it('refuses a `state` it does not know instead of answering the open ones', async () => {
+    const base = await start();
+    // `merged` is what the ANSWER says for an applied request, so it is the
+    // word an agent is most likely to feed back in; a typo is refused too.
+    // The route's argument check answers first — the schema pins `state` to
+    // its three values — and names them in its refusal; the handler's own
+    // check beneath it is the floor for a caller that reaches it another way.
+    for (const state of ['merged', 'applied', 'OPEN', '', 7, null]) {
+      calls = [];
+      const { status, json } = await call(base, 'list_change_requests', { state });
+      expect(status, JSON.stringify(state)).toBe(400);
+      expect((json as { kind?: string }).kind, JSON.stringify(state)).toBe('arguments-do-not-match');
+      // The three values are named either in the mismatch line (a wrong
+      // string) or in the interface the refusal carries (a wrong type).
+      expect(JSON.stringify(json), JSON.stringify(state)).toMatch(/open.*closed.*all/);
+      expect(calls, JSON.stringify(state)).toEqual([]);
+    }
+  });
+
   it('filters by target branch and by author', async () => {
     const base = await start();
     summaries = [
@@ -619,6 +638,19 @@ describe('get_change_request', () => {
     expect(absent.json.error).toBe('Change request #99 not found.');
   });
 
+  // An OPEN request that proposes nothing, before the background sweep has
+  // closed it: still "not found" to an agent that is not its author. Closing
+  // empty requests changed nothing about what agents may see.
+  it('answers not found for an open request with no files to an agent that is not its author', async () => {
+    const base = await start();
+    details.set(12, detail({ state: 'open', files: [], approvals: [] }));
+    const { status, json } = await call(base, 'get_change_request', { number: 12 });
+    expect(status).toBe(404);
+    expect(json.error).toBe('Change request #12 not found.');
+    callerEmail = AUTHOR;
+    expect((await call(base, 'get_change_request', { number: 12 })).status).toBe(200);
+  });
+
   it('answers not found when the access tree at the target cannot be resolved', async () => {
     const base = await start();
     readable = null;
@@ -1033,11 +1065,15 @@ describe('a mixed-access caller is never handed a path they may not read', () =>
     mixedAccessRequest();
     summaries = [details.get(1)!];
     for (const tool of TOOLS) {
-      const { status, json } = await call(
-        base,
-        tool,
-        tool === 'list_change_requests' ? {} : { number: 1, include: ['patches'] },
-      );
+      // `include` only where the tool declares it: a call naming an argument
+      // its tool does not have is refused before it runs.
+      const args =
+        tool === 'list_change_requests'
+          ? {}
+          : tool === 'list_change_request_files'
+            ? { number: 1, include: ['patches'] }
+            : { number: 1 };
+      const { status, json } = await call(base, tool, args);
       expect(status, tool).toBe(200);
       const whole = JSON.stringify(json);
       expect(whole, tool).not.toContain('Avi-Checkin');

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

@@ -9,7 +9,13 @@ import { createToolContextResolver } from '../../../tool-helpers/tool-context.js
 import { createToolHandlerFactory } from '../../../tool-helpers/tool-handler.js';
 import { createManualRoutes } from '../../../tool-registry/manual.routes.js';
 import { registerWorkflowTools } from '../workflow.tools.js';
-import { ChangeRequestConflictsError, OpenChangeRequestBlocksMergeError } from '../../../../shared/domain-errors.js';
+import {
+  BranchAuthorshipError,
+  BranchDeleteBlockedError,
+  BranchNotFoundError,
+  ChangeRequestConflictsError,
+  OpenChangeRequestBlocksMergeError,
+} from '../../../../shared/domain-errors.js';
 
 const WS = 'target-company-state';
 
@@ -144,6 +150,34 @@ const workflowService = {
     }
     return { kind: 'merged', sha: 'merge-sha' };
   },
+  deleteBranchChecked: async (
+    user: { id: string },
+    name: string,
+    { maySee, ...opts }: { dryRun?: boolean; discardUnmerged?: boolean; maySee?: (n: number) => Promise<boolean> },
+  ) => {
+    calls.push(['deleteBranchChecked', user.id, name, opts]);
+    if (maySee) calls.push(['maySee', 12, await maySee(12)], ['maySee', 13, await maySee(13)]);
+    if (name === 'me/missing') throw new BranchNotFoundError(name);
+    if (name === 'ali/theirs') throw new BranchAuthorshipError(name);
+    if (name === 'me/proposed') {
+      throw new BranchDeleteBlockedError(
+        'open-change-request',
+        name,
+        'Change request #12 is open from "me/proposed". Ask the user to withdraw or decline it in the app; then the branch can be deleted.',
+        { number: 12 },
+      );
+    }
+    if (name === 'me/unmerged' && !(opts as { discardUnmerged?: boolean }).discardUnmerged) {
+      throw new BranchDeleteBlockedError('unmerged-commits', name, '"me/unmerged" holds 3 commits…', { unmergedCommits: 3 });
+    }
+    if (name === 'me/offline') {
+      throw new BranchDeleteBlockedError('state-unconfirmed', name, 'Could not reach the shared repository…');
+    }
+    if ((opts as { dryRun?: boolean }).dryRun) {
+      return { kind: 'preview', branch: name, exists: true, canDelete: true, refusals: [], unmergedCommits: 0, openChangeRequests: [], lastCommit: 'tip-1' };
+    }
+    return { kind: 'deleted', branch: name, lastCommit: 'tip-1', discardedCommits: name === 'me/unmerged' ? 3 : 0 };
+  },
   postComment: async (number: number, _user: unknown, input: { path?: string }) => {
     calls.push(['postComment', number, input.path]);
     return { id: 'c-1' };
@@ -169,7 +203,11 @@ async function start(): Promise<string> {
   const toolHandler = createToolHandlerFactory(resolve);
 
   const router = express.Router();
-  registerWorkflowTools(registry, router, toolAuth, toolHandler, testKbContext());
+  // Request #13 is one the caller may not see.
+  registerWorkflowTools(registry, router, toolAuth, toolHandler, testKbContext(), async (ctx, number) => {
+    calls.push(['maySeeAs', ctx.user.id, number]);
+    return number !== 13;
+  });
   router.use(createManualRoutes(registry, toolAuth));
 
   const app = express();
@@ -250,6 +288,80 @@ describe('registerWorkflowTools', () => {
     expect(calls.some((c) => c[0] === 'postComment')).toBe(false);
   });
 
+  describe('delete_branch', () => {
+    it('is on both catalogs, takes name, dryRun and discardUnmerged, and is a write tool', async () => {
+      await start();
+      for (const tools of [await registryRef!.listInternal(), await registryRef!.listExternal()]) {
+        const tool = tools.find((t) => t.name === 'delete_branch');
+        expect(tool).toBeDefined();
+        // `toolDef` wraps a tool's own inputs under `body`.
+        const inputs = (tool!.inputs as { properties: { body: { properties: Record<string, unknown>; required: string[] } } })
+          .properties.body;
+        expect(Object.keys(inputs.properties).sort()).toEqual(['discardUnmerged', 'dryRun', 'name']);
+        expect(inputs.required).toEqual(['name']);
+        expect(tool!.tags).toContain('write');
+        // An empty request is closed by the delete; a live one refuses it, linked.
+        expect(tool!.description).toContain('proposes nothing is closed');
+        expect(tool!.description).toContain('its author withdraws it or an Admin declines it');
+      }
+    });
+
+    it('deletes as the caller and answers the last commit', async () => {
+      const base = await start();
+      const res = await post(`${base}/api/agent/tools/delete_branch`, writeTok(), { name: 'me/draft' });
+      expect(res.status).toBe(200);
+      expect(await res.json()).toEqual({ kind: 'deleted', branch: 'me/draft', lastCommit: 'tip-1', discardedCommits: 0 });
+      expect(calls).toContainEqual(['deleteBranchChecked', 'user-A', 'me/draft', { dryRun: false, discardUnmerged: false }]);
+    });
+
+    it('passes dryRun and discardUnmerged through', async () => {
+      const base = await start();
+      const preview = await post(`${base}/api/agent/tools/delete_branch`, writeTok(), { name: 'me/draft', dryRun: true });
+      expect(await preview.json()).toMatchObject({ kind: 'preview', canDelete: true, lastCommit: 'tip-1' });
+      const discarded = await post(`${base}/api/agent/tools/delete_branch`, writeTok(), { name: 'me/unmerged', discardUnmerged: true });
+      expect(await discarded.json()).toMatchObject({ kind: 'deleted', discardedCommits: 3 });
+      expect(calls).toContainEqual(['deleteBranchChecked', 'user-A', 'me/draft', { dryRun: true, discardUnmerged: false }]);
+      expect(calls).toContainEqual(['deleteBranchChecked', 'user-A', 'me/unmerged', { dryRun: false, discardUnmerged: true }]);
+    });
+
+    it('answers each refusal with its status and message', async () => {
+      const base = await start();
+      const ask = async (name: string) => {
+        const res = await post(`${base}/api/agent/tools/delete_branch`, writeTok(), { name });
+        return { status: res.status, body: (await res.json()) as Record<string, unknown> };
+      };
+      const missing = await ask('me/missing');
+      expect(missing.status).toBe(404);
+      expect(missing.body.error).toMatch(/no branch named me\/missing/);
+      const theirs = await ask('ali/theirs');
+      expect(theirs.status).toBe(403);
+      expect(theirs.body.error).toBe('Only the author of "ali/theirs" can delete it.');
+      const proposed = await ask('me/proposed');
+      expect(proposed.status).toBe(409);
+      expect(proposed.body).toMatchObject({ reason: 'open-change-request', number: 12 });
+      expect(proposed.body.error).toMatch(/#12.*withdraw or decline it in the app/);
+      const unmerged = await ask('me/unmerged');
+      expect(unmerged.status).toBe(409);
+      expect(unmerged.body).toMatchObject({ reason: 'unmerged-commits', unmergedCommits: 3 });
+      expect((await ask('me/offline')).status).toBe(503);
+    });
+
+    it('requires a name', async () => {
+      const base = await start();
+      const res = await post(`${base}/api/agent/tools/delete_branch`, writeTok(), {});
+      expect(res.status).toBe(400);
+      expect(calls.some((c) => c[0] === 'deleteBranchChecked')).toBe(false);
+    });
+
+    it("hands the service the caller's view of change requests, as get_change_request gates it", async () => {
+      const base = await start();
+      await post(`${base}/api/agent/tools/delete_branch`, writeTok(), { name: 'me/draft', dryRun: true });
+      expect(calls).toContainEqual(['maySeeAs', 'user-A', 12]);
+      expect(calls).toContainEqual(['maySee', 12, true]);
+      expect(calls).toContainEqual(['maySee', 13, false]);
+    });
+  });
+
   // An agent proposes and syncs; a person merges.
   describe('merging', () => {
     it('merge_change_request is gone: its old path answers who merges now, and never merges', async () => {
@@ -304,6 +416,19 @@ describe('registerWorkflowTools', () => {
         const mergeBranch = tools.find((t) => t.name === 'merge_branch')!;
         expect(mergeBranch.description).toMatch(/a person merges/);
         expect(mergeBranch.description).toMatch(/SYNC/);
+        // Every outcome is named, and the asynchronous commit the merge waits for.
+        for (const kind of ['merged', 'nothing-to-merge', 'pending-commits', 'conflicts-need-resolution']) {
+          expect(mergeBranch.description, kind).toContain(`\`${kind}\``);
+        }
+        expect(mergeBranch.description).toMatch(/committed asynchronously/);
+        expect(mergeBranch.description).toMatch(/waits up to 20s/);
+        const outcome = (mergeBranch.outputs as { properties: { outcome: { description: string; properties: Record<string, { enum?: string[] }> } } })
+          .properties.outcome;
+        expect(outcome.properties.kind.enum).toEqual(['merged', 'nothing-to-merge', 'pending-commits', 'conflicts-need-resolution']);
+        expect(Object.keys(outcome.properties)).toEqual(
+          expect.arrayContaining(['sha', 'conflictedPaths', 'branch', 'pending', 'needsAttention', 'message']),
+        );
+        expect(outcome.description).toMatch(/committed asynchronously and the merge waits/);
       }
     });
   });

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

@@ -133,14 +133,6 @@ export function registerChangeRequestReadTools(
     router.post(path.slice('/api'.length), toolAuth, toolHandler(spec.handler, { write: false }));
   };
 
-  /**
-   * A clone to resolve access verdicts in. All clones track the same origin and
-   * every verdict here is read at `origin/<base>`, so any existing one answers
-   * identically — reusing one avoids cloning a branch just to read a ref.
-   */
-  const repoGlobalWorkspaceId = async (ctx: ToolContext): Promise<string> =>
-    (await ctx.workspaceService.findAnyWorkspaceId()) ?? kb.defaultWorkspaceId();
-
   /** A change-request number as the tools accept it. */
   const numberArg = (args: Record<string, unknown>): number => {
     const n = args.number;
@@ -153,119 +145,7 @@ export function registerChangeRequestReadTools(
     return n;
   };
 
-  /**
-   * Read verdicts for `paths` at `origin/<base>`, as a membership set of what
-   * the caller MAY read. A null answer (the ref or its `roles.yaml` does not
-   * resolve) withholds everything, which is the same reading the app's
-   * fork-point route gives it.
-   */
-  const readablePaths = async (
-    ctx: ToolContext,
-    workspaceId: string,
-    base: string,
-    paths: string[],
-  ): Promise<Set<string>> => {
-    if (paths.length === 0) return new Set();
-    const verdicts = await accessControl.canReadBatchAtRef(
-      workspaceId,
-      `origin/${base}`,
-      ctx.user.email,
-      [...new Set(paths)],
-    );
-    if (!verdicts) return new Set();
-    return new Set([...verdicts].filter(([, allowed]) => allowed).map(([p]) => p));
-  };
-
-  /**
-   * The detail of request `number` with the access filter applied, or a 404 —
-   * the one place the four by-number tools get their data, so they cannot
-   * drift on who may see what.
-   */
-  interface ScopedDetail {
-    detail: ChangeRequestDetail;
-    /**
-     * Whether the caller may read one path of this request — the raw per-path
-     * verdict, as the access tree gives it at `origin/<base>`.
-     */
-    mayRead: (path: string) => boolean;
-    /**
-     * Whether this request may NAME `path` to the caller — `mayRead`, minus
-     * every name a withheld file goes by. The ONE verdict the tools below ask
-     * about a path, so none of them can decide it a second way.
-     *
-     * The two differ on exactly one shape, and it is the shape that leaks: a
-     * file moved out of a folder the caller may not read is readable under
-     * its NEW name, yet `fileIsReadable` withholds it whole (its diff shows the
-     * old path's content). Anything keyed on that new path — an approval, a
-     * comment anchored to it — would otherwise say the request touches a file
-     * the file tool refuses to list, under a name it refuses to print.
-     */
-    mayShow: (path: string) => boolean;
-    /** The request's files the caller may read, in the request's own order. */
-    readableFiles: ChangeRequestDetail['files'];
-    /**
-     * Every name the withheld files go by — for filtering the gate blockers and
-     * for deciding `mayShow`. NEVER answered: use `withheldFileCount` to report
-     * them.
-     */
-    withheldFilePaths: string[];
-    /** How many files are withheld. One per file, whatever its move names. */
-    withheldFileCount: number;
-    viewerIsAuthor: boolean;
-  }
-
-  const scopedDetail = async (
-    ctx: ToolContext,
-    number: number,
-    opts: { patches: boolean },
-  ): Promise<ScopedDetail> => {
-    const workspaceId = await repoGlobalWorkspaceId(ctx);
-    const detail = await ctx.workflowService.getChangeRequestDetail(number, {
-      workspaceId,
-      viewerEmail: ctx.user.email,
-      patches: opts.patches,
-    });
-    if (!detail) throw notFound(number);
-    const viewerIsAuthor = isAuthor(detail, ctx.user.email);
-    // Comment paths join the batch: a comment may name a file the request no
-    // longer changes, and without a verdict of its own it would be withheld
-    // from a caller who can read it perfectly well.
-    const commentPaths = detail.comments.map((c) => c.path).filter((p): p is string => !!p);
-    // BOTH names of every file: a move is judged on its old path as well as
-    // its new one, because the diff of a move shows what was at the old one.
-    const readable = await readablePaths(ctx, workspaceId, detail.base, [
-      ...detail.files.flatMap(pathsOf),
-      ...commentPaths,
-    ]);
-    const mayRead = (path: string) => readable.has(path);
-    const readableFiles = detail.files.filter((f) => fileIsReadable(f, mayRead));
-    if (!maySeeChangeRequest({ readableFiles: readableFiles.length, isAuthor: viewerIsAuthor })) {
-      throw notFound(number);
-    }
-    // Every name a withheld file goes by, so a gate warning quoting either
-    // spelling is caught by the blocker filter — and so `mayShow` catches
-    // whichever spelling an approval or a comment happens to use.
-    const withheldFilePaths = detail.files
-      .filter((f) => !fileIsReadable(f, mayRead))
-      .flatMap(pathsOf);
-    const withheldNames = new Set(withheldFilePaths);
-    return {
-      detail,
-      mayRead,
-      mayShow: (path: string) => mayRead(path) && !withheldNames.has(path),
-      readableFiles,
-      withheldFilePaths,
-      withheldFileCount: detail.files.length - readableFiles.length,
-      viewerIsAuthor,
-    };
-  };
-
-  /**
-   * The same answer for a number that was never issued and for one the caller
-   * may not see — requirement 7. Says nothing a probe could tell apart.
-   */
-  const notFound = (number: number): ToolError =>
-    new ToolError(`Change request #${number} not found.`, 404);
+  const { repoGlobalWorkspaceId, readablePaths, scopedDetail } = changeRequestScope(accessControl, kb);
 
   /**
    * The changed files of a SUMMARY, as the pairs a read gate decides over.
@@ -374,7 +254,18 @@ export function registerChangeRequestReadTools(
       required: ['changeRequests', ...pagingRequired],
     },
     handler: async (args, ctx: ToolContext) => {
-      const state = args.state === 'closed' || args.state === 'all' ? args.state : 'open';
+      // The answer spells a merged request `state: merged`, so an agent that
+      // copies that word back into the filter is asking for the applied
+      // ones. Quietly answering the open ones instead reads as "there are no
+      // merged requests" — refuse, and name the filter's own vocabulary.
+      const state = args.state === undefined ? 'open' : args.state;
+      if (state !== 'open' && state !== 'closed' && state !== 'all') {
+        throw new ToolError(
+          `Unknown \`state\` ${JSON.stringify(state)}. Use \`open\` (the default), \`closed\` ` +
+            '(applied and declined alike) or `all`; the answer then says `merged` or `closed` for each.',
+          400,
+        );
+      }
       const head = typeof args.head === 'string' ? args.head : undefined;
       const base = typeof args.base === 'string' ? args.base : undefined;
       const author = typeof args.author === 'string' ? args.author : undefined;
@@ -722,3 +613,147 @@ export function registerChangeRequestReadTools(
   });
 }
 
+/**
+ * The detail of request `number` with the access filter applied, or a 404 —
+ * the one place the four by-number tools get their data, so they cannot
+ * drift on who may see what.
+ */
+export interface ScopedDetail {
+  detail: ChangeRequestDetail;
+  /**
+   * Whether the caller may read one path of this request — the raw per-path
+   * verdict, as the access tree gives it at `origin/<base>`.
+   */
+  mayRead: (path: string) => boolean;
+  /**
+   * Whether this request may NAME `path` to the caller — `mayRead`, minus
+   * every name a withheld file goes by. The ONE verdict the tools below ask
+   * about a path, so none of them can decide it a second way.
+   *
+   * The two differ on exactly one shape, and it is the shape that leaks: a
+   * file moved out of a folder the caller may not read is readable under
+   * its NEW name, yet `fileIsReadable` withholds it whole (its diff shows the
+   * old path's content). Anything keyed on that new path — an approval, a
+   * comment anchored to it — would otherwise say the request touches a file
+   * the file tool refuses to list, under a name it refuses to print.
+   */
+  mayShow: (path: string) => boolean;
+  /** The request's files the caller may read, in the request's own order. */
+  readableFiles: ChangeRequestDetail['files'];
+  /**
+   * Every name the withheld files go by — for filtering the gate blockers and
+   * for deciding `mayShow`. NEVER answered: use `withheldFileCount` to report
+   * them.
+   */
+  withheldFilePaths: string[];
+  /** How many files are withheld. One per file, whatever its move names. */
+  withheldFileCount: number;
+  viewerIsAuthor: boolean;
+}
+
+/**
+ * The access scope of one change request, as every by-number read tool sees
+ * it — and as `delete_branch` does, so a deletion's preview or refusal never
+ * names a request `get_change_request` answers as not found.
+ */
+export function changeRequestScope(
+  accessControl: Pick<IAccessControl, 'canReadBatchAtRef'>,
+  kb: Pick<KbContext, 'defaultWorkspaceId'>,
+) {
+  /**
+   * A clone to resolve access verdicts in. All clones track the same origin and
+   * every verdict here is read at `origin/<base>`, so any existing one answers
+   * identically — reusing one avoids cloning a branch just to read a ref.
+   */
+  const repoGlobalWorkspaceId = async (ctx: ToolContext): Promise<string> =>
+    (await ctx.workspaceService.findAnyWorkspaceId()) ?? kb.defaultWorkspaceId();
+
+  /**
+   * Read verdicts for `paths` at `origin/<base>`, as a membership set of what
+   * the caller MAY read. A null answer (the ref or its `roles.yaml` does not
+   * resolve) withholds everything, which is the same reading the app's
+   * fork-point route gives it.
+   */
+  const readablePaths = async (
+    ctx: ToolContext,
+    workspaceId: string,
+    base: string,
+    paths: string[],
+  ): Promise<Set<string>> => {
+    if (paths.length === 0) return new Set();
+    const verdicts = await accessControl.canReadBatchAtRef(
+      workspaceId,
+      `origin/${base}`,
+      ctx.user.email,
+      [...new Set(paths)],
+    );
+    if (!verdicts) return new Set();
+    return new Set([...verdicts].filter(([, allowed]) => allowed).map(([p]) => p));
+  };
+
+  const scopedDetail = async (
+    ctx: ToolContext,
+    number: number,
+    opts: { patches: boolean },
+  ): Promise<ScopedDetail> => {
+    const workspaceId = await repoGlobalWorkspaceId(ctx);
+    const detail = await ctx.workflowService.getChangeRequestDetail(number, {
+      workspaceId,
+      viewerEmail: ctx.user.email,
+      patches: opts.patches,
+    });
+    if (!detail) throw notFound(number);
+    const viewerIsAuthor = isAuthor(detail, ctx.user.email);
+    // Comment paths join the batch: a comment may name a file the request no
+    // longer changes, and without a verdict of its own it would be withheld
+    // from a caller who can read it perfectly well.
+    const commentPaths = detail.comments.map((c) => c.path).filter((p): p is string => !!p);
+    // BOTH names of every file: a move is judged on its old path as well as
+    // its new one, because the diff of a move shows what was at the old one.
+    const readable = await readablePaths(ctx, workspaceId, detail.base, [
+      ...detail.files.flatMap(pathsOf),
+      ...commentPaths,
+    ]);
+    const mayRead = (path: string) => readable.has(path);
+    const readableFiles = detail.files.filter((f) => fileIsReadable(f, mayRead));
+    if (!maySeeChangeRequest({ readableFiles: readableFiles.length, isAuthor: viewerIsAuthor })) {
+      throw notFound(number);
+    }
+    // Every name a withheld file goes by, so a gate warning quoting either
+    // spelling is caught by the blocker filter — and so `mayShow` catches
+    // whichever spelling an approval or a comment happens to use.
+    const withheldFilePaths = detail.files
+      .filter((f) => !fileIsReadable(f, mayRead))
+      .flatMap(pathsOf);
+    const withheldNames = new Set(withheldFilePaths);
+    return {
+      detail,
+      mayRead,
+      mayShow: (path: string) => mayRead(path) && !withheldNames.has(path),
+      readableFiles,
+      withheldFilePaths,
+      withheldFileCount: detail.files.length - readableFiles.length,
+      viewerIsAuthor,
+    };
+  };
+
+  /**
+   * The same answer for a number that was never issued and for one the caller
+   * may not see — requirement 7. Says nothing a probe could tell apart.
+   */
+  const notFound = (number: number): ToolError =>
+    new ToolError(`Change request #${number} not found.`, 404);
+
+  /** Whether the caller may see request `number` at all: what `scopedDetail` answers 404 for, as a no. */
+  const maySee = async (ctx: ToolContext, number: number): Promise<boolean> => {
+    try {
+      await scopedDetail(ctx, number, { patches: false });
+      return true;
+    } catch (err) {
+      if (err instanceof ToolError && err.status === 404) return false;
+      throw err;
+    }
+  };
+
+  return { repoGlobalWorkspaceId, readablePaths, scopedDetail, notFound, maySee };
+}