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

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

@@ -3,7 +3,6 @@ import express from 'express';
 import { afterEach, beforeEach, describe, expect, it } from 'vitest';
 import type {
   ChangeRequest,
-  ChangeRequestComment,
   ChangeRequestDetail,
   ChangeRequestState,
   ChangedFile,
@@ -28,7 +27,6 @@ const TOOLS = [
   'get_change_request',
   'list_change_request_files',
   'list_change_request_reviews',
-  'list_change_request_comments',
 ] as const;
 
 // ── The world each test sets up ─────────────────────────────────────────────
@@ -69,18 +67,6 @@ function approval(path: string, over: Partial<FileApproval> = {}): FileApproval
   };
 }
 
-/** A comment as the detail carries one. Module-level: the rename suite needs it too. */
-function comment(over: Partial<ChangeRequestComment>): ChangeRequestComment {
-  return {
-    id: 'c-1',
-    author: { email: VIEWER, name: 'Mia' },
-    body: 'This line is out of date.',
-    headSha: 'head-1',
-    createdAt: '2026-09-29T08:00:00.000Z',
-    ...over,
-  };
-}
-
 function approvedBy(email: string, name: string, at: string, isStale = false) {
   return { email, name, approvedAt: at, isStale, isSelfApproval: false };
 }
@@ -126,7 +112,6 @@ function detail(over: Partial<ChangeRequestDetail> = {}): ChangeRequestDetail {
     headSha: 'head-1',
     baseSha: 'base-1',
     files,
-    comments: [],
     approvals: files.map((f) => approval(f.path)),
     mergeableInBevel: false,
     mergeBlockedReasons: [],
@@ -274,7 +259,7 @@ afterEach(async () => {
 
 // ── The catalog ─────────────────────────────────────────────────────────────
 
-describe('the five read tools', () => {
+describe('the four read tools', () => {
   it('are all registered, on both surfaces, by their GitHub-counterpart names', async () => {
     await start();
     const internal = (await registryRef!.listInternal()).map((t) => t.name);
@@ -285,6 +270,15 @@ describe('the five read tools', () => {
     }
   });
 
+  // Change-request comments were removed (no screen ever showed one), and the
+  // tool that listed them went with them.
+  it('offers no comment tool on either surface', async () => {
+    await start();
+    for (const list of [await registryRef!.listInternal(), await registryRef!.listExternal()]) {
+      expect(list.map((t) => t.name).filter((n) => n.includes('comment'))).toEqual([]);
+    }
+  });
+
   // "None of the tools changes anything." A `write`-tagged tool is refused to
   // read-scoped callers; these must carry no such tag, because none writes.
   it('carry no `write` tag, so a read-scoped caller may use every one', async () => {
@@ -891,123 +885,13 @@ describe('list_change_request_reviews', () => {
   });
 });
 
-// ── Scenario: comments ──────────────────────────────────────────────────────
-
-describe('list_change_request_comments', () => {
-  // WHEN a reviewer left an inline comment and a reply followed THEN
-  // `list_change_request_comments` returns both, the reply with `parentId`.
-  it('returns the inline comment and its reply, the reply carrying parentId', async () => {
-    const base = await start();
-    details.set(
-      12,
-      detail({
-        comments: [
-          comment({ id: 'c-1', path: 'Knowledge/A.md', line: 14 }),
-          comment({
-            id: 'c-2',
-            author: { email: AUTHOR, name: 'Juan' },
-            body: 'Fixed.',
-            path: 'Knowledge/A.md',
-            line: 14,
-            parentId: 'c-1',
-            createdAt: '2026-09-29T09:00:00.000Z',
-          }),
-        ],
-      }),
-    );
-    const { status, json } = await call(base, 'list_change_request_comments', { number: 12 });
-    expect(status).toBe(200);
-    expect(json.comments).toHaveLength(2);
-    expect(json.comments[0]).toMatchObject({
-      id: 'c-1',
-      author: { name: 'Mia', email: VIEWER },
-      body: 'This line is out of date.',
-      path: 'Knowledge/A.md',
-      line: 14,
-      headSha: 'head-1',
-      createdAt: '2026-09-29T08:00:00.000Z',
-    });
-    expect(json.comments[1]).toMatchObject({ id: 'c-2', parentId: 'c-1' });
-    expect(json.withheldComments).toBe(0);
-  });
-
-  it('keeps a general comment, which belongs to the request rather than a file', async () => {
-    const base = await start();
-    details.set(12, detail({ comments: [comment({ id: 'c-9', body: 'Ready for review.' })] }));
-    const { json } = await call(base, 'list_change_request_comments', { number: 12 });
-    expect(json.comments).toHaveLength(1);
-    expect((json.comments as unknown as { path?: string }[])[0].path).toBeUndefined();
-  });
-
-  it('leaves out a comment on a file the caller may not read, and counts it', async () => {
-    const base = await start();
-    readable = ['Knowledge/A.md'];
-    details.set(
-      12,
-      detail({
-        files: [file('Knowledge/A.md'), file('Payroll/Rates.md')],
-        comments: [
-          comment({ id: 'c-1', path: 'Knowledge/A.md', line: 1 }),
-          comment({ id: 'c-2', path: 'Payroll/Rates.md', line: 2, body: 'The band is wrong.' }),
-        ],
-      }),
-    );
-    const { json } = await call(base, 'list_change_request_comments', { number: 12 });
-    expect((json.comments as unknown as { id: string }[]).map((c) => c.id)).toEqual(['c-1']);
-    expect(json.withheldComments).toBe(1);
-    expect(JSON.stringify(json)).not.toContain('Payroll');
-    expect(JSON.stringify(json)).not.toContain('band is wrong');
-  });
-
-  it('keeps a comment on a file the request no longer changes but the caller may read', async () => {
-    const base = await start();
-    readable = ['Knowledge/A.md', 'Knowledge/Gone.md'];
-    details.set(12, detail({ comments: [comment({ id: 'c-7', path: 'Knowledge/Gone.md', line: 3 })] }));
-    const { json } = await call(base, 'list_change_request_comments', { number: 12 });
-    expect((json.comments as unknown as { id: string }[]).map((c) => c.id)).toEqual(['c-7']);
-    expect(json.withheldComments).toBe(0);
-  });
-
-  it('pages the comments', async () => {
-    const base = await start();
-    details.set(
-      12,
-      detail({
-        comments: Array.from({ length: 40 }, (_, i) =>
-          comment({ id: `c-${i}`, createdAt: `2026-09-29T08:00:${String(i).padStart(2, '0')}.000Z` }),
-        ),
-      }),
-    );
-    const first = await call(base, 'list_change_request_comments', { number: 12 });
-    expect(first.json.comments).toHaveLength(30);
-    expect(first.json.hasNextPage).toBe(true);
-    const second = await call(base, 'list_change_request_comments', { number: 12, page: 2 });
-    expect(second.json.comments).toHaveLength(10);
-    expect(second.json.hasNextPage).toBe(false);
-  });
-
-  it('answers not found when the caller may read none of its files', async () => {
-    const base = await start();
-    readable = [];
-    details.set(12, detail({ comments: [comment({ id: 'c-1' })] }));
-    expect((await call(base, 'list_change_request_comments', { number: 12 })).status).toBe(404);
-  });
-});
-
 /**
  * Reproductions of what Local Testing found on sha ae2f49d9, through the HTTP
  * tool surface it found them on — not just the pure mapper underneath.
  */
 describe('a mixed-access caller is never handed a path they may not read', () => {
-  /** A body exactly as `openChangeRequest` builds it: prose, then the block. */
-  const bodyWithOwnersBlock = [
-    'Please review the check-in note.',
-    '',
-    '## Affected owners',
-    '',
-    '- `KnowledgeBase/Engineering/Knowledge/Avi-Checkin.md` — Admin',
-    '- `KnowledgeBase/GTM/Notes.md` — GTM Team',
-  ].join('\n');
+  /** A body as `openChangeRequest` stores it: the description, nothing else. */
+  const body = 'Please review the check-in note.';
 
   /** The reader of one folder of a two-folder request — john.newcomer's case. */
   function mixedAccessRequest(): void {
@@ -1020,7 +904,7 @@ describe('a mixed-access caller is never handed a path they may not read', () =>
       1,
       detail({
         number: 1,
-        body: bodyWithOwnersBlock,
+        body,
         files: [
           file('KnowledgeBase/Engineering/Knowledge/Avi-Checkin.md'),
           file('KnowledgeBase/GTM/Notes.md'),
@@ -1039,7 +923,7 @@ describe('a mixed-access caller is never handed a path they may not read', () =>
     );
   }
 
-  it('get_change_request answers the author\'s reason and names no withheld file anywhere', async () => {
+  it('get_change_request answers the description and names no withheld file anywhere', async () => {
     const base = await start();
     mixedAccessRequest();
     const { status, json } = await call(base, 'get_change_request', { number: 1 });
@@ -1054,13 +938,12 @@ describe('a mixed-access caller is never handed a path they may not read', () =>
     const whole = JSON.stringify(json);
     expect(whole).not.toContain('Avi-Checkin');
     expect(whole).not.toContain('KnowledgeBase/Engineering');
-    expect(whole).not.toContain('Affected owners');
     // The file they CAN read is still named, and its blocker still readable.
     expect(whole).toContain('KnowledgeBase/GTM/Notes.md');
     expect(json).toMatchObject({ withheldMergeBlockedReasons: 1 });
   });
 
-  it('no tool of the five names the withheld file, in any field', async () => {
+  it('no tool of the four names the withheld file, in any field', async () => {
     const base = await start();
     mixedAccessRequest();
     summaries = [details.get(1)!];
@@ -1081,7 +964,7 @@ describe('a mixed-access caller is never handed a path they may not read', () =>
     }
   });
 
-  it('the author sees their own body too — the cut is the same for everyone', async () => {
+  it('the author is handed the same body — one body for everyone', async () => {
     const base = await start();
     mixedAccessRequest();
     callerEmail = AUTHOR;
@@ -1090,14 +973,11 @@ describe('a mixed-access caller is never handed a path they may not read', () =>
       'KnowledgeBase/Engineering/Knowledge/Avi-Checkin.md',
     ];
     const { json } = await call(base, 'get_change_request', { number: 1 });
-    // A caller who may read everything gets the same author text, not the
-    // machine block — one body nobody has to reason about.
     expect(json).toMatchObject({
       body: 'Please review the check-in note.',
       changedFiles: 2,
       withheldFiles: 0,
     });
-    expect(JSON.stringify(json)).not.toContain('Affected owners');
   });
 });
 
@@ -1159,35 +1039,6 @@ describe('a file renamed out of a folder the caller may not read', () => {
     expect(json.withheldFiles).toBe(0);
   });
 
-  it('keeps a comment anchored to the withheld rename out of the comment list', async () => {
-    const base = await start();
-    renameRequest();
-    details.set(
-      12,
-      detail({
-        files: [
-          file('Knowledge/Open.md', { status: 'renamed', previousPath: 'Payroll/Rates.md' }),
-          file('Knowledge/Plain.md'),
-        ],
-        approvals: [approval('Knowledge/Open.md'), approval('Knowledge/Plain.md')],
-        comments: [
-          comment({ id: 'c-1', path: 'Knowledge/Plain.md', line: 4 }),
-          comment({ id: 'c-2', path: 'Knowledge/Open.md', line: 9, body: 'Rate band looks off.' }),
-        ],
-      }),
-    );
-    const { json } = await call(base, 'list_change_request_comments', { number: 12 });
-    // `Knowledge/Open.md` passes a bare read check — it is the file's new name —
-    // but the file is withheld whole, so a comment on it is withheld too. Were
-    // it kept, it would print the name the files tool refuses to print.
-    expect((json.comments as unknown as { id: string }[]).map((c) => c.id)).toEqual(['c-1']);
-    expect(json.withheldComments).toBe(1);
-    const whole = JSON.stringify(json);
-    expect(whole).not.toContain('Knowledge/Open.md');
-    expect(whole).not.toContain('Payroll');
-    expect(whole).not.toContain('Rate band');
-  });
-
   it('keeps the withheld rename out of the files a review names, and counts it', async () => {
     const base = await start();
     renameRequest();
@@ -1472,83 +1323,3 @@ describe('reading a request that is no longer open', () => {
     expect(mine.json).toMatchObject({ state: 'closed', changedFiles: 0, viewer: { isAuthor: true } });
   });
 });
-
-/**
- * Scenario (Razvan's review, 2026-10-02, finding 3): a reply is shown only when
- * the comment it replies to is.
- *
- * `post_change_request_comment` takes `parentId` without requiring `path`, so a
- * reply to a comment on a withheld file has no path of its own — and judged on
- * itself it looked like a general comment about the whole request. It came back
- * with its body and a `parentId` naming a comment the caller cannot see.
- */
-describe('a reply is shown only when the comment it replies to is', () => {
-  /** A request whose two files the caller can read one of. */
-  function threadRequest(comments: ChangeRequestComment[]) {
-    readable = ['Knowledge/Open.md'];
-    details.set(
-      12,
-      detail({
-        files: [file('Knowledge/Open.md'), file('Payroll/Rates.md')],
-        approvals: [approval('Knowledge/Open.md'), approval('Payroll/Rates.md')],
-        comments,
-      }),
-    );
-  }
-
-  it('withholds a pathless reply to a comment on a file the caller may not read', async () => {
-    const base = await start();
-    threadRequest([
-      comment({ id: 'c-1', path: 'Payroll/Rates.md', line: 3, body: 'This band is wrong.' }),
-      comment({ id: 'c-2', parentId: 'c-1', body: 'Agreed, the band moved in April.' }),
-    ]);
-    const { json } = await call(base, 'list_change_request_comments', { number: 12 });
-    expect(json.comments).toEqual([]);
-    expect(json.withheldComments).toBe(2);
-    const whole = JSON.stringify(json);
-    // Neither the parent's path, nor the reply's body, nor the id it answers.
-    expect(whole).not.toContain('Payroll');
-    expect(whole).not.toContain('band moved');
-    expect(whole).not.toContain('c-1');
-  });
-
-  it('withholds every reply down the thread, however deep it runs', async () => {
-    const base = await start();
-    threadRequest([
-      comment({ id: 'c-1', path: 'Payroll/Rates.md', body: 'This band is wrong.' }),
-      comment({ id: 'c-2', parentId: 'c-1', body: 'Which one?' }),
-      comment({ id: 'c-3', parentId: 'c-2', body: 'The senior one.' }),
-    ]);
-    const { json } = await call(base, 'list_change_request_comments', { number: 12 });
-    expect(json.comments).toEqual([]);
-    expect(json.withheldComments).toBe(3);
-    expect(JSON.stringify(json)).not.toContain('senior');
-  });
-
-  it('keeps a thread on a file the caller may read, replies and all', async () => {
-    const base = await start();
-    threadRequest([
-      comment({ id: 'c-1', path: 'Knowledge/Open.md', line: 4, body: 'Out of date.' }),
-      comment({ id: 'c-2', parentId: 'c-1', body: 'Fixed.' }),
-      comment({ id: 'c-3', parentId: 'c-2', body: 'Thanks.' }),
-    ]);
-    const { json } = await call(base, 'list_change_request_comments', { number: 12 });
-    expect((json.comments as unknown as { id: string }[]).map((c) => c.id)).toEqual([
-      'c-1',
-      'c-2',
-      'c-3',
-    ]);
-    expect(json.withheldComments).toBe(0);
-  });
-
-  it('keeps a general comment and its replies — neither is about a file', async () => {
-    const base = await start();
-    threadRequest([
-      comment({ id: 'c-1', body: 'Ready for review.' }),
-      comment({ id: 'c-2', parentId: 'c-1', body: 'Looking now.' }),
-    ]);
-    const { json } = await call(base, 'list_change_request_comments', { number: 12 });
-    expect(json.comments).toHaveLength(2);
-    expect(json.withheldComments).toBe(0);
-  });
-});

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

@@ -0,0 +1,306 @@
+import type { Server as HttpServer } from 'node:http';
+import express from 'express';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import type { IWorkflowService } from '@bevel-software/platform-shared';
+import { testKbContext } from '../../../../__tests__/kb-context.js';
+import { ToolRegistry } from '../../../tool-registry/tool-registry.js';
+import { InternalTokenService } from '../../../tool-auth/internal-token.service.js';
+import { createToolAuthMiddleware } from '../../../tool-auth/tool-auth.middleware.js';
+import { createToolContextResolver } from '../../../tool-helpers/tool-context.js';
+import { createToolHandlerFactory } from '../../../tool-helpers/tool-handler.js';
+import { WorkflowDomainError } from '../../../../shared/domain-errors.js';
+import type { IAccessControl } from '../../../access/access-control.interface.js';
+import type { AuthService } from '../../../auth/auth.service.js';
+import type { WorkspaceService } from '../../../workspace/workspace.service.js';
+import type { WorkflowEventBus } from '../../event-bus.js';
+import { createWorkflowRoutes } from '../../workflow.routes.js';
+import { registerWorkflowTools } from '../workflow.tools.js';
+
+/**
+ * The app's `PATCH /api/workflow/change-requests/:number` and the agent's
+ * `update_change_request` are one verb: both reach the SAME service method
+ * with the same caller and the same fields, and every refusal it makes reaches
+ * both callers with the same status and the same words. The rule itself is
+ * pinned in `workflow.service.update-change-request.test.ts`; this pins that
+ * neither surface narrows, widens or rewords it.
+ *
+ * One answer differs, and on purpose: a request the caller may not READ is
+ * not found to the agent (404, as `get_change_request` answers it), before
+ * its state or the edit rule is consulted. The app serves every request's
+ * detail to any signed-in viewer, so its route has nothing to hide.
+ */
+
+const CALLER = { id: 'user-A', email: 'alice@example.com', name: 'Alice' };
+
+let calls: unknown[][] = [];
+/** What the shared service does next: answer the request, or refuse. */
+let outcome: () => unknown;
+/** `get_change_request`'s visibility gate, as the tool is handed it. */
+let maySee: (number: number) => Promise<boolean>;
+
+const updated = {
+  number: 9,
+  url: 'https://bevel.example.com/change-requests/9',
+  title: 'New title',
+  state: 'open',
+  touchedNodePaths: ['Docs/a.md'],
+};
+
+const workflowService = {
+  updateChangeRequest: async (number: number, user: { id: string; email: string }, input: unknown) => {
+    calls.push(['updateChangeRequest', number, user.id, input]);
+    return outcome();
+  },
+} as unknown as IWorkflowService;
+
+const authService = { getUserById: async () => CALLER } as unknown as AuthService;
+const workspaceService = {
+  getOrCreateForUser: async () => ({ id: 'ws' }),
+  findAnyWorkspaceId: async () => 'ws',
+} as unknown as WorkspaceService;
+const events = { emit: () => ({}) } as unknown as WorkflowEventBus;
+const internalToken = new InternalTokenService({ secret: 's' });
+
+let httpServer: HttpServer | undefined;
+/** The agent tools `start` registered, as the manual lists them. */
+let registry: ToolRegistry;
+
+async function start(): Promise<string> {
+  const app = express();
+  app.use(express.json());
+
+  // The app's route, signed in as CALLER.
+  const appRouter = express.Router();
+  appRouter.use((req, _res, next) => {
+    (req as unknown as { userId: string }).userId = CALLER.id;
+    next();
+  });
+  appRouter.use(
+    createWorkflowRoutes(
+      workflowService,
+      workspaceService,
+      authService,
+      events,
+      { canReadBatch: async () => new Map() } as unknown as IAccessControl,
+      'knowledge-base',
+    ),
+  );
+
+  // The agent's tool, as CALLER over an internal token.
+  registry = new ToolRegistry();
+  const toolRouter = express.Router();
+  const toolAuth = createToolAuthMiddleware(
+    { looksLikeExternalApiKey: () => false, verifyAndLoadToken: async () => null } as never,
+    internalToken,
+  );
+  const resolve = createToolContextResolver({
+    authService,
+    workspaceService,
+    workflowService,
+    events,
+    kbDirName: 'knowledge-base',
+    creatorAccess: { planForCreate: async () => null, grantInExtractedFile: async () => null, noteAccessFileWritten: () => {} },
+  } as never);
+  registerWorkflowTools(registry, toolRouter, toolAuth, createToolHandlerFactory(resolve), testKbContext(), async (_ctx, number) =>
+    maySee(number),
+  );
+
+  app.use('/api', toolRouter);
+  app.use('/api', appRouter);
+  httpServer = await new Promise<HttpServer>((r) => {
+    const s = app.listen(0, () => r(s));
+  });
+  return `http://127.0.0.1:${(httpServer.address() as { port: number }).port}`;
+}
+
+async function viaRoute(base: string, body: Record<string, unknown>) {
+  const res = await fetch(`${base}/api/workflow/change-requests/9`, {
+    method: 'PATCH',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify(body),
+  });
+  return { status: res.status, body: (await res.json()) as Record<string, unknown> };
+}
+
+async function viaTool(base: string, body: Record<string, unknown>) {
+  const res = await fetch(`${base}/api/agent/tools/update_change_request`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', authorization: `Bearer ${internalToken.mint({ userId: CALLER.id })}` },
+    body: JSON.stringify({ number: 9, ...body }),
+  });
+  return { status: res.status, body: (await res.json()) as Record<string, unknown> };
+}
+
+beforeEach(() => {
+  calls = [];
+  outcome = () => updated;
+  maySee = async () => true;
+});
+afterEach(async () => {
+  if (httpServer) await new Promise<void>((r) => httpServer!.close(() => r()));
+  httpServer = undefined;
+});
+
+describe('update_change_request ⇔ PATCH /workflow/change-requests/:number', () => {
+  it('both hand the same service call the same caller and the same fields', async () => {
+    const base = await start();
+    const fields = { title: 'New title', description: 'P2 - Planned\n\nWhy.' };
+    expect((await viaRoute(base, fields)).status).toBe(200);
+    expect((await viaTool(base, fields)).status).toBe(200);
+    expect(calls).toEqual([
+      ['updateChangeRequest', 9, CALLER.id, fields],
+      ['updateChangeRequest', 9, CALLER.id, fields],
+    ]);
+  });
+
+  it('a description alone reaches the service as a description alone, from both', async () => {
+    const base = await start();
+    await viaRoute(base, { description: 'Only this.' });
+    await viaTool(base, { description: 'Only this.' });
+    expect(calls).toEqual([
+      ['updateChangeRequest', 9, CALLER.id, { title: undefined, description: 'Only this.' }],
+      ['updateChangeRequest', 9, CALLER.id, { title: undefined, description: 'Only this.' }],
+    ]);
+  });
+
+  it('an append reaches the service as an append, from both — the tool offers the field the route takes', async () => {
+    const base = await start();
+    expect((await viaRoute(base, { appendDescription: 'Round two.' })).status).toBe(200);
+    expect((await viaTool(base, { appendDescription: 'Round two.' })).status).toBe(200);
+    expect(calls).toEqual([
+      ['updateChangeRequest', 9, CALLER.id, { title: undefined, description: undefined, appendDescription: 'Round two.' }],
+      ['updateChangeRequest', 9, CALLER.id, { title: undefined, description: undefined, appendDescription: 'Round two.' }],
+    ]);
+  });
+
+  it("the tool's input schema names every field the route takes", async () => {
+    await start();
+    const tool = (await registry.listInternal()).find((t) => t.name === 'update_change_request');
+    // The catalog nests a tool's arguments under `body`.
+    const top = (tool?.inputs as { properties: Record<string, { properties?: Record<string, unknown> }> }).properties;
+    const props = top.body?.properties ?? top;
+    expect(Object.keys(props).sort()).toEqual(['appendDescription', 'description', 'number', 'title']);
+  });
+
+  const refusals: [string, () => never][] = [
+    [
+      'neither the author nor someone who may merge it (403)',
+      () => {
+        throw new WorkflowDomainError(
+          "Only the request's author, an admin, or someone who may approve every file it changes can edit its title and description.",
+          403,
+        );
+      },
+    ],
+    [
+      'a merged request (409)',
+      () => {
+        throw new WorkflowDomainError(
+          'This change request has already been applied; its title and description can no longer be changed.',
+          409,
+        );
+      },
+    ],
+    [
+      'a closed request (409)',
+      () => {
+        throw new WorkflowDomainError(
+          'This change request is closed; its title and description can no longer be changed.',
+          409,
+        );
+      },
+    ],
+  ];
+
+  for (const [name, refuse] of refusals) {
+    it(`refuses ${name} with the same status and the same words`, async () => {
+      const base = await start();
+      outcome = refuse;
+      const route = await viaRoute(base, { title: 'New title' });
+      const tool = await viaTool(base, { title: 'New title' });
+      expect(route.status).toBeGreaterThanOrEqual(400);
+      expect(tool).toEqual(route);
+      expect(typeof route.body.error).toBe('string');
+      expect((route.body.error as string).length).toBeGreaterThan(20);
+    });
+  }
+
+  it('the tool answers a request the caller may not see as not found, whatever its state or the rule would say', async () => {
+    const base = await start();
+    maySee = async () => false;
+    for (const [, refuse] of refusals) {
+      outcome = refuse;
+      const tool = await viaTool(base, { title: 'New title' });
+      expect(tool).toEqual({ status: 404, body: { error: 'Change request #9 not found.' } });
+    }
+    expect(calls).toEqual([]);
+  });
+
+  it('the tool answers the request’s link and its title; the route the request', async () => {
+    const base = await start();
+    const tool = await viaTool(base, { title: 'New title' });
+    expect(tool.body).toEqual({
+      number: 9,
+      url: 'https://bevel.example.com/change-requests/9',
+      title: 'New title',
+    });
+    const route = await viaRoute(base, { title: 'New title' });
+    expect(route.body).toMatchObject({ number: 9, title: 'New title' });
+  });
+
+  it('asks for something to change before reaching the service', async () => {
+    const base = await start();
+    const tool = await viaTool(base, {});
+    expect(tool.status).toBe(400);
+    expect(calls).toEqual([]);
+  });
+
+  it('the route refuses a non-string field before reaching the service', async () => {
+    const base = await start();
+    const route = await viaRoute(base, { title: 7 });
+    expect(route.status).toBe(400);
+    expect(calls).toEqual([]);
+  });
+});
+
+/**
+ * The comment system is gone: no screen ever showed a comment, so the routes,
+ * the service methods, the storage and the two agent tools were removed
+ * rather than surfaced. Its old addresses answer 404 and its tools are not
+ * offered; the request itself still answers on its own address.
+ */
+describe('change-request comments are gone', () => {
+  const routes: [string, string][] = [
+    ['GET', '/api/workflow/change-requests/9/comments'],
+    ['POST', '/api/workflow/change-requests/9/comments'],
+    ['PATCH', '/api/workflow/change-requests/9/comments/00000000-0000-4000-8000-000000000000'],
+    ['DELETE', '/api/workflow/change-requests/9/comments/00000000-0000-4000-8000-000000000000'],
+  ];
+  for (const [method, path] of routes) {
+    it(`${method} ${path.replace('/api', '')} answers 404`, async () => {
+      const base = await start();
+      const res = await fetch(`${base}${path}`, {
+        method,
+        headers: { 'content-type': 'application/json' },
+        ...(method === 'GET' || method === 'DELETE' ? {} : { body: JSON.stringify({ body: 'hi' }) }),
+      });
+      expect(res.status).toBe(404);
+      expect(calls).toEqual([]);
+    });
+  }
+
+  it('the agent is offered no comment tool, and calling one answers 404', async () => {
+    const base = await start();
+    for (const name of ['post_change_request_comment']) {
+      const res = await fetch(`${base}/api/agent/tools/${name}`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', authorization: `Bearer ${internalToken.mint({ userId: CALLER.id })}` },
+        body: JSON.stringify({ number: 9, body: 'hi' }),
+      });
+      expect(res.status).toBe(404);
+    }
+    const names = (await registry.listInternal()).map((t) => t.name);
+    expect(names).toContain('update_change_request');
+    expect(names.filter((n) => n.includes('comment'))).toEqual([]);
+  });
+});