@bevel-software/platform-core-backend 0.14.0 → 0.19.0

package/src/modules/tool-helpers/tool-context.ts

@@ -1,10 +1,17 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
 import { LocalFilesystem } from '@mastra/core/workspace';
 import type { IWorkflowService } from '@bevel-software/platform-shared';
 import { LockingFilesystem } from '../kb-fs/locking-filesystem.js';
 import { ReadOnlyFilesystem } from '../kb-fs/read-only-filesystem.js';
-import { makeRolesYamlWriteValidator } from '../access-model/roles-yaml-guard.js';
+import {
+  makeAgentRolesYamlWriteValidator,
+  ROLES_YAML_BASENAME,
+} from '../access-model/roles-yaml-guard.js';
 import type { ICreatorAccess } from '../access-model/creator.js';
+import type { GroupsIndex } from '../access-model/group-files.js';
 import type { WorkspaceService } from '../workspace/workspace.service.js';
+import { isAbsence } from '../../shared/fs.contract.js';
 import { branchForWorkspaceId } from '../../shared/workspace-id.js';
 import type { WorkflowEventBus } from '../workflow/event-bus.js';
 import type { AuthService } from '../auth/auth.service.js';
@@ -24,6 +31,25 @@ export interface ToolContextDeps {
    * `modules/access/creator-access`).
    */
   creatorAccess: ICreatorAccess;
+  /**
+   * The resolver's active-group-source loader (`loadActiveGroups` in
+   * `modules/access`), injected so an agent's `roles.yaml` write adding a
+   * `- group:<Name>` entry is checked against the groups on that branch.
+   * Absent → group entries go unchecked.
+   */
+  loadActiveGroups?: (
+    read: (filename: string) => Promise<string | null>,
+  ) => Promise<{ groups: GroupsIndex; sourceFile: string; health: { ok: boolean } }>;
+}
+
+/** A file's text, or null when it does not exist. Any other failure throws. */
+async function readTextIfExists(absolutePath: string): Promise<string | null> {
+  try {
+    return await fs.readFile(absolutePath, 'utf-8');
+  } catch (err) {
+    if (isAbsence(err)) return null;
+    throw err;
+  }
 }
 
 export type ResolveToolContext = (
@@ -44,15 +70,11 @@ export type ResolveToolContext = (
  * a request body; `branch` arrives as an explicit argument from the tool.
  */
 export function createToolContextResolver(deps: ToolContextDeps): ResolveToolContext {
-  // Reject an agent write that would leave roles.yaml unparseable (app-wide
-  // admin lockout) before it reaches disk — the agent gets a tool error and the
-  // file is untouched, mirroring the human editor's save-time gate.
-  const validateRolesWrite = makeRolesYamlWriteValidator(deps.kbDirName);
-
   return async function resolveToolContext(auth, abortSignal, sessionId) {
     const user = await deps.authService.getUserById(auth.userId);
     if (!user) throw new ToolError('Your account is no longer available.', 401);
 
+    const { loadActiveGroups } = deps;
     const fsCache = new Map<string, LocalFilesystem>();
     const getFilesystem = async (branch: string): Promise<LocalFilesystem> => {
       const cached = fsCache.get(branch);
@@ -70,7 +92,24 @@ export function createToolContextResolver(deps: ToolContextDeps): ResolveToolCon
                 branch: branchForWorkspaceId(workspaceId),
                 user,
                 kbDirName: deps.kbDirName,
-                validateWrite: validateRolesWrite,
+                // Reject an agent write that would leave roles.yaml unparseable
+                // (app-wide admin lockout) or that creates a role before it
+                // reaches disk, or that adds a `- group:` entry naming no group
+                // — the agent gets a tool error and the file is untouched.
+                // Agents manage membership; roles are pre-set.
+                validateWrite: makeAgentRolesYamlWriteValidator(
+                  deps.kbDirName,
+                  () => readTextIfExists(path.join(basePath, deps.kbDirName, ROLES_YAML_BASENAME)),
+                  loadActiveGroups &&
+                    (async () => {
+                      // A source that exists but cannot be read leaves group
+                      // entries unchecked rather than refusing every one.
+                      const active = await loadActiveGroups((file) =>
+                        readTextIfExists(path.join(basePath, deps.kbDirName, file)),
+                      );
+                      return active.health.ok ? active : null;
+                    }),
+                ),
                 creatorAccess: deps.creatorAccess,
               },
             )

package/src/modules/tool-helpers/tool-handler.ts

@@ -1,5 +1,10 @@
 import type { Request, Response } from 'express';
-import { hasHttpStatus, type ToolHandler } from './tool.contract.js';
+import { logger } from '../../shared/logging.js';
+
+const log = logger('tools');
+import { hasHttpStatus, ToolError, type ToolHandler } from './tool.contract.js';
+import { WorkflowDomainError } from '../../shared/domain-errors.js';
+import { domainErrorBody } from '../../shared/http-errors.js';
 import type { ResolveToolContext } from './tool-context.js';
 import '../tool-auth/tool-auth.middleware.js'; // Express Request.toolAuth augmentation
 
@@ -71,17 +76,30 @@ export function createToolHandlerFactory(resolve: ResolveToolContext) {
         // A handler can throw after streaming has begun (headers committed); in
         // that case we can only end the stream, not rewrite the status.
         if (res.headersSent) {
-          if (hasHttpStatus(err)) console.error('[tools] handler failed post-stream:', err.message);
-          else console.error('[tools] handler failed post-stream:', err instanceof Error ? err.message : err);
+          if (hasHttpStatus(err)) log.error('handler failed post-stream:', { detail: err.message });
+          else log.error('handler failed post-stream:', { err });
           res.end();
           return;
         }
         if (hasHttpStatus(err)) {
-          res.status(err.status).json({ error: err.message });
+          // Structured details ride beside `error`, never over it. A domain
+          // refusal brings its own payload exactly as it does on the HTTP
+          // routes — most subclasses carry a `kind` and whatever that kind
+          // brings with it, others carry their own keys (`AccessConfigError`
+          // carries an `accessConfigErrors` list; see each subclass for its
+          // payload) — so a tool caller
+          // switching on `branch-not-found` vs `remote-branch-gone` does not
+          // have to read the prose to tell them apart.
+          if (err instanceof WorkflowDomainError) {
+            res.status(err.status).json(domainErrorBody(err));
+            return;
+          }
+          const details = err instanceof ToolError ? err.details : undefined;
+          res.status(err.status).json({ ...details, error: err.message });
           return;
         }
         const msg = err instanceof Error ? err.message : 'Unknown error';
-        console.error('[tools] handler failed:', msg);
+        log.error('handler failed:', { detail: msg });
         res.status(500).json({ error: msg });
       }
     };

package/src/modules/tool-helpers/tool.contract.ts

@@ -70,11 +70,16 @@ export type ToolHandler = (
  * A failure a tool handler can throw to choose its own HTTP status. The route
  * maps any thrown value with a numeric `status` to that code — covering this
  * and `AgentAskService`'s `AgentAskError`.
+ *
+ * `details` are machine-readable fields sent beside `error` in the response
+ * body (e.g. `{ kind: 'binary_not_writable', fileKind, useInstead }`), so a
+ * caller can branch on the refusal instead of parsing its prose.
  */
 export class ToolError extends Error {
   constructor(
     message: string,
     readonly status: number,
+    readonly details?: Record<string, unknown>,
   ) {
     super(message);
     this.name = 'ToolError';

package/src/modules/tool-manuals/__tests__/mcp-json-discovery.test.ts

@@ -1,8 +1,31 @@
 import { describe, expect, it, vi, afterEach } from 'vitest';
-import { descriptorsFromMcpJson } from '../mcp-json-discovery.js';
+import { descriptorsFromMcpJson, judgeMcpServerEntry } from '../mcp-json-discovery.js';
 
 afterEach(() => vi.restoreAllMocks());
 
+describe('judgeMcpServerEntry', () => {
+  it('keeps every accepted header and env key — one spelled __proto__ included', () => {
+    // Parsed from text, as a repository file is: JSON.parse makes `__proto__`
+    // an own key, and a plain-object copy would turn it into a prototype
+    // assignment and lose it.
+    const http = judgeMcpServerEntry(
+      'vendor',
+      JSON.parse('{"type":"streamable-http","url":"https://x.example","headers":{"__proto__":"p","X-A":"a"}}'),
+    );
+    expect(http.ok).toBe(true);
+    if (!http.ok || http.transport !== 'streamable-http') throw new Error('unreachable');
+    expect(Object.keys(http.entry.headers ?? {}).sort()).toEqual(['X-A', '__proto__']);
+    expect(http.entry.headers?.['__proto__']).toBe('p');
+
+    const stdio = judgeMcpServerEntry(
+      'launch',
+      JSON.parse('{"type":"stdio","command":"run","env":{"__proto__":"p"}}'),
+    );
+    if (!stdio.ok || stdio.transport !== 'stdio') throw new Error('unreachable');
+    expect(stdio.entry.env?.['__proto__']).toBe('p');
+  });
+});
+
 const MANIFEST = JSON.stringify({
   name: 'gtm',
   extensions: {

package/src/modules/tool-manuals/__tests__/mcp-server-edit.service.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, it, beforeEach, afterEach, vi } from 'vitest';
+import { NodeFs } from '../../kb-fs/node-fs.js';
 import fs from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
@@ -76,7 +77,7 @@ beforeEach(async () => {
     }),
   } as unknown as IToolManualService;
 
-  svc = new McpServerEditService(workspaceService, commits, accessControl, toolManuals, KB);
+  svc = new McpServerEditService(workspaceService, commits, accessControl, toolManuals, KB, new NodeFs());
 });
 
 afterEach(async () => {

package/src/modules/tool-manuals/__tests__/pending-tools.service.test.ts

@@ -0,0 +1,411 @@
+import { describe, test, expect } from 'vitest';
+import { DEFAULT_BRANCH, type ChangeRequest, type IWorkflowService } from '@bevel-software/platform-shared';
+import { PendingToolsService } from '../pending-tools.service.js';
+import { hashEmail } from '../../../shared/email-identity.js';
+import type { WorkspaceService } from '../../workspace/workspace.service.js';
+import type { IAccessControl } from '../../access/access-control.interface.js';
+import type { IToolManualService, ToolManualSummary } from '../tool-manuals.contract.js';
+
+/**
+ * The half of the tool catalog that is NOT on the default branch.
+ *
+ * The bug this exists for, told by the tester: they asked the agent for a tool,
+ * a change request opened, and the tools UI showed nothing at all until
+ * somebody approved it. So the tests below are mostly about WHO GETS TO SEE
+ * ONE, because "show it" and "show it to the wrong people" are the two ways to
+ * get this wrong — and about WHEN IT GOES AWAY, because a card that outlives
+ * its request is a card pointing at a decision already taken.
+ */
+
+const AUTHOR = 'ali@bevel.software';
+const ADMIN = 'olga@bevel.software';
+const BYSTANDER = 'sam@bevel.software';
+
+const TOOL_PATH = 'Plugins/Ops/weather.tool';
+const MCP_PATH = 'Plugins/Ops/mcp.json';
+
+const WEATHER_TOOL = `---
+id: weather
+type: http
+description: Forecasts for a place.
+url: https://weather.example/utcp
+---
+
+# Weather
+`;
+
+const MCP_JSON = JSON.stringify({
+  mcpServers: {
+    tickets: { type: 'streamable-http', url: 'https://tickets.example/mcp' },
+  },
+});
+
+function cr(over: Partial<ChangeRequest> = {}): ChangeRequest {
+  return {
+    number: 7,
+    title: 'Add the weather tool',
+    authorId: hashEmail(AUTHOR),
+    author: { login: 'user-abc', name: 'service' },
+    appAuthor: { name: 'Ali Raza' },
+    branch: 'agent/weather',
+    base: DEFAULT_BRANCH,
+    state: 'open',
+    createdAt: '2026-09-06T09:00:00.000Z',
+    touchedNodePaths: [TOOL_PATH],
+    review: { approvals: 0, changesRequested: 0, pendingLogins: [] },
+    url: '/change-requests/7',
+    ...over,
+  };
+}
+
+function harness(opts: {
+  crs: ChangeRequest[];
+  released?: Partial<ToolManualSummary>[];
+  /** Files present on a change request's branch, keyed `<branch>:<path>`. */
+  branchFiles?: Record<string, string>;
+  /** Emails allowed to write each path. Absent path ⇒ nobody. */
+  writers?: Record<string, string[]>;
+  /** The access tree cannot be read at all — `canWriteBatch` REJECTS. */
+  accessThrows?: boolean;
+}) {
+  const branchFiles = opts.branchFiles ?? { [`agent/weather:${TOOL_PATH}`]: WEATHER_TOOL };
+  const workspaceService = {
+    ensureRemotesFetched: async () => undefined,
+    readFileAtRef: async (_ws: string, ref: string, rel: string) =>
+      branchFiles[`${ref.replace(/^origin\//, '')}:${rel}`] ?? null,
+  } as unknown as WorkspaceService;
+
+  const accessControl = {
+    canWriteBatch: async (_ws: string, email: string, paths: string[]) => {
+      // A tree that cannot be read REJECTS — it does not answer `false` for
+      // every path. The two are different code paths in the caller and only
+      // this one reaches its `.catch`.
+      if (opts.accessThrows) throw new Error('access.md is unreadable');
+      return new Map(paths.map((p) => [p, (opts.writers?.[p] ?? []).includes(email)]));
+    },
+  } as unknown as IAccessControl;
+
+  const toolManuals = {
+    listAllSummaries: async () => (opts.released ?? []) as ToolManualSummary[],
+  } as unknown as IToolManualService;
+
+  const workflow = {
+    listChangeRequests: async () => opts.crs,
+  } as unknown as IWorkflowService;
+
+  return new PendingToolsService(workspaceService, accessControl, toolManuals, workflow);
+}
+
+const ADMIN_WRITES = { [TOOL_PATH]: [ADMIN] };
+
+describe('PendingToolsService', () => {
+  test('surfaces a `.tool` that exists only on a change request, to its author', async () => {
+    const pending = await harness({ crs: [cr()], writers: ADMIN_WRITES }).listPendingTools(AUTHOR);
+
+    expect(pending).toEqual([
+      {
+        slug: 'weather',
+        name: 'weather',
+        path: TOOL_PATH,
+        type: 'http',
+        description: 'Forecasts for a place.',
+        plugin: 'Ops',
+        changeRequestNumber: 7,
+        branch: 'agent/weather',
+        authorName: 'Ali Raza',
+        createdAt: '2026-09-06T09:00:00.000Z',
+        isAuthor: true,
+      },
+    ]);
+  });
+
+  test('surfaces it to whoever could approve it, marked as not theirs', async () => {
+    const pending = await harness({ crs: [cr()], writers: ADMIN_WRITES }).listPendingTools(ADMIN);
+    expect(pending.map((p) => [p.name, p.isAuthor])).toEqual([['weather', false]]);
+  });
+
+  /**
+   * The decision that shapes this surface: a proposal is between its author and
+   * the people who can approve it, and nobody else. Somebody who cannot see the
+   * change request sees no card — not a card without a link, no card.
+   */
+  test('hides it from everyone else', async () => {
+    expect(await harness({ crs: [cr()], writers: ADMIN_WRITES }).listPendingTools(BYSTANDER))
+      .toEqual([]);
+  });
+
+  /**
+   * Fail closed like the catalog: an access lookup that cannot answer is a
+   * denial, never a disclosure. Without this a broken access tree would show
+   * every open proposal to everyone.
+   */
+  test('shows nothing to a non-author when the access tree cannot be read', async () => {
+    const broken = harness({ crs: [cr()], accessThrows: true });
+    expect(await broken.listPendingTools(ADMIN)).toEqual([]);
+    // …and the author still sees their own, because that verdict needs no tree.
+    expect(await broken.listPendingTools(AUTHOR)).toHaveLength(1);
+  });
+
+  /** The ordinary denial, which is a verdict rather than a failure. */
+  test('shows nothing to a non-author the tree names as no writer', async () => {
+    const svc = harness({ crs: [cr()], writers: {} });
+    expect(await svc.listPendingTools(ADMIN)).toEqual([]);
+  });
+
+  /**
+   * After the request MERGES the tool is in the catalog, and the card must be
+   * replaced by the real one rather than doubled beside it. The catalog is the
+   * witness for that: a declaration whose UTCP name the default branch already
+   * serves is not a pending tool, whatever the request's own state says.
+   */
+  test('drops a proposal once its tool is in the released catalog', async () => {
+    const svc = harness({
+      crs: [cr()],
+      released: [{ slug: 'weather', name: 'weather', path: TOOL_PATH, type: 'http' }],
+      writers: ADMIN_WRITES,
+    });
+    expect(await svc.listPendingTools(AUTHOR)).toEqual([]);
+  });
+
+  /**
+   * The catalog is the DEFAULT BRANCH, and everything this surface says is said
+   * in terms of it — what counts as already released, and whose access tree
+   * decides the review. A request aimed somewhere else could merge in full and
+   * still put no tool in the catalog, so its card would never resolve.
+   */
+  test('ignores a change request aimed at a branch other than the default', async () => {
+    const svc = harness({ crs: [cr({ base: 'some-other-branch' })], writers: ADMIN_WRITES });
+    expect(await svc.listPendingTools(AUTHOR)).toEqual([]);
+  });
+
+  /**
+   * The catalog dedups by the UTCP NAMESPACE, not by the raw name: an mcp.json
+   * server key may carry a `-`, and `a-b` namespaces to the same `a__b_` a
+   * `.tool` id `a_b` does. Compared by name, a request re-declaring a
+   * released tool under the other spelling would get a ghost card beside the
+   * live one — for a namespace the catalog would refuse to serve twice.
+   */
+  test('drops a proposal whose UTCP namespace the catalog already serves', async () => {
+    const svc = harness({
+      crs: [cr({ number: 11, branch: 'agent/tickets', touchedNodePaths: [MCP_PATH] })],
+      branchFiles: {
+        [`agent/tickets:${MCP_PATH}`]: JSON.stringify({
+          mcpServers: { 'on-call': { type: 'streamable-http', url: 'https://oc.example/mcp' } },
+        }),
+      },
+      released: [{ slug: 'on_call', name: 'on_call', path: 'Plugins/Ops/oncall.tool', type: 'http' }],
+      writers: { [MCP_PATH]: [ADMIN] },
+    });
+    expect(await svc.listPendingTools(ADMIN)).toEqual([]);
+  });
+
+  /**
+   * The slug is the ROUTE the tool will be served at once released, and the
+   * catalog serves the resolved manual name — not the filename, which is only
+   * the parser's fallback. A card keyed to the filename would not line up with
+   * the tool that replaces it, and a filename like `My Weather.tool` is not
+   * route-safe to begin with.
+   */
+  test('slugs a proposal by its resolved manual name, not its file name', async () => {
+    const ODD = 'Plugins/Ops/My Weather.tool';
+    const svc = harness({
+      crs: [cr({ touchedNodePaths: [ODD] })],
+      branchFiles: {
+        [`agent/weather:${ODD}`]: '---\nid: get_weather\ntype: http\nurl: https://w.example/utcp\n---\n',
+      },
+      writers: { [ODD]: [ADMIN] },
+    });
+    const [pending] = await svc.listPendingTools(ADMIN);
+    expect(pending?.name).toBe('get_weather');
+    expect(pending?.slug).toBe('get_weather');
+  });
+
+  test('ignores change requests that are merged, closed or cancelled', async () => {
+    for (const state of ['merged', 'closed', 'cancelled'] as const) {
+      const svc = harness({ crs: [cr({ state })], writers: ADMIN_WRITES });
+      expect(await svc.listPendingTools(AUTHOR)).toEqual([]);
+    }
+  });
+
+  test('ignores touched paths that declare no tool', async () => {
+    const svc = harness({
+      crs: [
+        cr({
+          touchedNodePaths: [
+            'Plugins/Ops/access.md',
+            'Plugins/Ops/weather/SKILL.md',
+            'Plugins/Ops/plugin.json',
+            'Plugins/mcp.json', // no plugin for its servers to belong to
+          ],
+        }),
+      ],
+      writers: {
+        'Plugins/Ops/access.md': [ADMIN],
+        'Plugins/Ops/plugin.json': [ADMIN],
+        'Plugins/mcp.json': [ADMIN],
+      },
+    });
+    expect(await svc.listPendingTools(AUTHOR)).toEqual([]);
+  });
+
+  /**
+   * The proposal is read at the request's own branch. Reading the default
+   * branch would find nothing and drop the card — which is the original bug.
+   */
+  test('drops a proposal whose file cannot be read on its branch', async () => {
+    const svc = harness({ crs: [cr()], branchFiles: {}, writers: ADMIN_WRITES });
+    expect(await svc.listPendingTools(AUTHOR)).toEqual([]);
+  });
+
+  test('drops a `.tool` that does not parse — the catalog would skip it too', async () => {
+    const svc = harness({
+      crs: [cr()],
+      branchFiles: { [`agent/weather:${TOOL_PATH}`]: 'not: [a, valid, manual\n' },
+      writers: ADMIN_WRITES,
+    });
+    expect(await svc.listPendingTools(AUTHOR)).toEqual([]);
+  });
+
+  test('names a `.tool` after its file when the frontmatter declares no id', async () => {
+    const svc = harness({
+      crs: [cr()],
+      branchFiles: {
+        [`agent/weather:${TOOL_PATH}`]: '---\ntype: http\nurl: https://w.example/utcp\n---\n',
+      },
+      writers: ADMIN_WRITES,
+    });
+    const [pending] = await svc.listPendingTools(AUTHOR);
+    expect(pending?.name).toBe('weather');
+    expect(pending?.description).toBeUndefined();
+  });
+
+  describe('MCP servers', () => {
+    const MCP_CR = cr({ number: 11, branch: 'agent/tickets', touchedNodePaths: [MCP_PATH] });
+
+    test('surfaces a server added to a plugin mcp.json', async () => {
+      const svc = harness({
+        crs: [MCP_CR],
+        branchFiles: { [`agent/tickets:${MCP_PATH}`]: MCP_JSON },
+        writers: { [MCP_PATH]: [ADMIN] },
+      });
+      expect(await svc.listPendingTools(ADMIN)).toEqual([
+        {
+          slug: 'tickets',
+          name: 'tickets',
+          path: MCP_PATH,
+          type: 'mcp',
+          plugin: 'Ops',
+          changeRequestNumber: 11,
+          branch: 'agent/tickets',
+          authorName: 'Ali Raza',
+          createdAt: '2026-09-06T09:00:00.000Z',
+          isAuthor: false,
+        },
+      ]);
+    });
+
+    /**
+     * An `mcp.json` the request edits usually already holds servers. Only the
+     * ADDED one is a proposal; the siblings are live tools with pages of their
+     * own, and listing them here would put a ghost card beside each.
+     */
+    test('lists only the servers the default branch does not already serve', async () => {
+      const svc = harness({
+        crs: [MCP_CR],
+        branchFiles: {
+          [`agent/tickets:${MCP_PATH}`]: JSON.stringify({
+            mcpServers: {
+              rota: { type: 'streamable-http', url: 'https://rota.example/mcp' },
+              tickets: { type: 'streamable-http', url: 'https://tickets.example/mcp' },
+            },
+          }),
+        },
+        released: [{ slug: 'rota', name: 'rota', path: MCP_PATH, type: 'mcp' }],
+        writers: { [MCP_PATH]: [ADMIN] },
+      });
+      expect((await svc.listPendingTools(ADMIN)).map((p) => p.name)).toEqual(['tickets']);
+    });
+
+    /**
+     * The plugin's manifest carries what the portable `mcp.json` may not — the
+     * description, and the `local: true` that exempts a localhost server from
+     * the reachability gate. Read at the same branch: without it a proposed
+     * local server would be dropped as unreachable and never get a card.
+     */
+    test("reads the plugin's manifest on the branch for the extension block", async () => {
+      const svc = harness({
+        crs: [MCP_CR],
+        branchFiles: {
+          [`agent/tickets:${MCP_PATH}`]: JSON.stringify({
+            mcpServers: { tickets: { type: 'streamable-http', url: 'http://127.0.0.1:9911/mcp' } },
+          }),
+          'agent/tickets:Plugins/Ops/plugin.json': JSON.stringify({
+            extensions: {
+              'software.bevel.hexis': {
+                mcpServers: { tickets: { local: true, description: 'The on-call rota board.' } },
+              },
+            },
+          }),
+        },
+        writers: { [MCP_PATH]: [ADMIN] },
+      });
+      const [pending] = await svc.listPendingTools(ADMIN);
+      expect(pending?.name).toBe('tickets');
+      expect(pending?.description).toBe('The on-call rota board.');
+    });
+  });
+
+  /**
+   * This hangs off the library's list load. A workflow service that cannot
+   * answer must cost the reader an empty review shelf, not their whole library.
+   */
+  test('degrades to nothing pending when the change requests cannot be listed', async () => {
+    const workflow = {
+      listChangeRequests: async () => {
+        throw new Error('offline');
+      },
+    } as unknown as IWorkflowService;
+    const svc = new PendingToolsService(
+      {} as unknown as WorkspaceService,
+      {} as unknown as IAccessControl,
+      { listAllSummaries: async () => [] } as unknown as IToolManualService,
+      workflow,
+    );
+    await expect(svc.listPendingTools(AUTHOR)).resolves.toEqual([]);
+  });
+
+  test('degrades to nothing pending when the catalog cannot be scanned', async () => {
+    const svc = new PendingToolsService(
+      {} as unknown as WorkspaceService,
+      {} as unknown as IAccessControl,
+      {
+        listAllSummaries: async () => {
+          throw new Error('workspace gone');
+        },
+      } as unknown as IToolManualService,
+      { listChangeRequests: async () => [cr()] } as unknown as IWorkflowService,
+    );
+    await expect(svc.listPendingTools(AUTHOR)).resolves.toEqual([]);
+  });
+
+  test('oldest first — the request that has waited longest is the one to answer', async () => {
+    const OLDER = 'Plugins/Ops/rota.tool';
+    const svc = harness({
+      crs: [
+        cr({ number: 9, createdAt: '2026-09-06T12:00:00.000Z' }),
+        cr({
+          number: 3,
+          createdAt: '2026-09-01T12:00:00.000Z',
+          branch: 'agent/older',
+          touchedNodePaths: [OLDER],
+        }),
+      ],
+      branchFiles: {
+        [`agent/weather:${TOOL_PATH}`]: WEATHER_TOOL,
+        [`agent/older:${OLDER}`]: '---\nid: rota\ntype: http\nurl: https://r.example/utcp\n---\n',
+      },
+      writers: { ...ADMIN_WRITES, [OLDER]: [ADMIN] },
+    });
+    expect((await svc.listPendingTools(ADMIN)).map((p) => p.changeRequestNumber)).toEqual([3, 9]);
+  });
+});