@bevel-software/platform-core-backend 0.15.1 → 0.20.0

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

@@ -8,6 +8,7 @@ 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 { OpenChangeRequestBlocksMergeError } from '../../../../shared/domain-errors.js';
 
 const WS = 'target-company-state';
 
@@ -36,7 +37,7 @@ const workflowService = {
   },
   openChangeRequest: async (ws: string, user: { id: string }, body: unknown) => {
     calls.push(['openChangeRequest', ws, user.id, body]);
-    return { number: 7, url: 'http://cr/7' };
+    return { number: 7, url: 'https://bevel.example.com/change-requests/7' };
   },
   createBranch: async (ws: string, name: string) => {
     calls.push(['createBranch', ws, name]);
@@ -49,6 +50,31 @@ const workflowService = {
   releaseLock: async (ws: string, branch: string, path: string) => {
     calls.push(['releaseLock', ws, branch, path]);
   },
+  getChangeRequestDetail: async (number: number) => ({
+    number,
+    url: `https://bevel.example.com/change-requests/${number}`,
+    headSha: 'head-1',
+    approvals: [],
+    state: 'open',
+    title: 'T',
+    base: 'main',
+  }),
+  mergeChangeRequest: async (number: number) => {
+    calls.push(['mergeChangeRequest', number]);
+    return { kind: 'merged', result: { prNumber: number, sha: 'sha-1', mergedAt: '2026-09-17T00:00:00Z' } };
+  },
+  mergeBranch: async (user: { id: string }, source: string, target: string) => {
+    calls.push(['mergeBranch', user.id, source, target]);
+    if (source === 'me/conflicting') return { kind: 'conflicts-need-resolution', conflictedPaths: ['A.md'] };
+    if (source === 'me/proposed') {
+      throw new OpenChangeRequestBlocksMergeError(source, target, 12);
+    }
+    return { kind: 'merged', sha: 'merge-sha' };
+  },
+  postComment: async (number: number, _user: unknown, input: { path?: string }) => {
+    calls.push(['postComment', number, input.path]);
+    return { id: 'c-1' };
+  },
 } as never;
 const events = {
   emit: (p: unknown) => {
@@ -104,6 +130,94 @@ describe('registerWorkflowTools', () => {
     expect(calls).toContainEqual(['commitChange', WS, 'user-A', { summary: 'fix typo', description: undefined }]);
   });
 
+  // A change request's files are repository-relative; the Copy path form
+  // carries the clone folder, which is dropped so the comment lands on the file.
+  it('post_change_request_comment anchors a copied workspace path to the repository-relative file', async () => {
+    const base = await start();
+    for (const path of ['/knowledge-base/KnowledgeBase/Foo.md', 'knowledge-base/KnowledgeBase/Foo.md', 'KnowledgeBase/Foo.md']) {
+      const res = await post(`${base}/api/agent/tools/post_change_request_comment`, writeTok(), { number: 3, body: 'hi', path });
+      expect(res.status, path).toBe(200);
+    }
+    expect(calls.filter((c) => c[0] === 'postComment')).toEqual([
+      ['postComment', 3, 'KnowledgeBase/Foo.md'],
+      ['postComment', 3, 'KnowledgeBase/Foo.md'],
+      ['postComment', 3, 'KnowledgeBase/Foo.md'],
+    ]);
+  });
+
+  // An agent hands the change request's link to a person, so the tools that
+  // act on one by number return its `{ number, url }` beside their own payload.
+  it('post_change_request_comment returns the change request link', async () => {
+    const base = await start();
+    const comment = await post(`${base}/api/agent/tools/post_change_request_comment`, writeTok(), { number: 3, body: 'hi' });
+    expect(comment.status).toBe(200);
+    const commentBody = await comment.json();
+    expect(commentBody).toMatchObject({
+      comment: { id: 'c-1' },
+      changeRequest: { number: 3, url: 'https://bevel.example.com/change-requests/3' },
+    });
+    // A configured address yields an absolute link, so no note rides along.
+    expect(commentBody.changeRequest).not.toHaveProperty('urlNote');
+  });
+
+  // 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 () => {
+      const base = await start();
+      const res = await post(`${base}/api/agent/tools/merge_change_request`, writeTok(), { number: 4 });
+      expect(res.status).toBe(410);
+      expect(((await res.json()) as { error: string }).error).toMatch(/a change request is merged by a person in the app/);
+      expect(calls.some((c) => c[0] === 'mergeChangeRequest')).toBe(false);
+    });
+
+    it('merge_branch merges as the caller and returns merged', async () => {
+      const base = await start();
+      const res = await post(`${base}/api/agent/tools/merge_branch`, writeTok(), { source: 'target-company-state', target: 'me/draft' });
+      expect(res.status).toBe(200);
+      expect(await res.json()).toEqual({ outcome: { kind: 'merged', sha: 'merge-sha' } });
+      expect(calls).toContainEqual(['mergeBranch', 'user-A', 'target-company-state', 'me/draft']);
+    });
+
+    it('merge_branch returns conflicts-need-resolution with the conflicting paths', async () => {
+      const base = await start();
+      const res = await post(`${base}/api/agent/tools/merge_branch`, writeTok(), { source: 'me/conflicting', target: 'me/draft' });
+      expect(res.status).toBe(200);
+      expect(await res.json()).toEqual({ outcome: { kind: 'conflicts-need-resolution', conflictedPaths: ['A.md'] } });
+    });
+
+    it('merge_branch surfaces the open-request refusal, naming the request', async () => {
+      const base = await start();
+      const res = await post(`${base}/api/agent/tools/merge_branch`, writeTok(), { source: 'me/proposed', target: 'target-company-state' });
+      expect(res.status).toBe(409);
+      const body = JSON.stringify(await res.json());
+      expect(body).toContain('#12');
+      expect(body).toMatch(/review #12 in the app/);
+    });
+
+    it('merge_branch requires both branches', async () => {
+      const base = await start();
+      expect((await post(`${base}/api/agent/tools/merge_branch`, writeTok(), { source: 'a' })).status).toBe(400);
+      expect(calls.some((c) => c[0] === 'mergeBranch')).toBe(false);
+    });
+
+    it('no catalog offers merge_change_request or any approval tool; merge_branch documents the sync path', async () => {
+      await start();
+      for (const tools of [await registryRef!.listInternal(), await registryRef!.listExternal()]) {
+        const names = tools.map((t) => t.name);
+        expect(names).not.toContain('merge_change_request');
+        expect(names).toContain('merge_branch');
+        expect(names.filter((n) => /approv|bypass/i.test(n))).toEqual([]);
+        for (const t of tools) {
+          const inputs = JSON.stringify(t.inputs);
+          expect(inputs, t.name).not.toMatch(/"(bypass|approve|unapprove)"/);
+        }
+        const mergeBranch = tools.find((t) => t.name === 'merge_branch')!;
+        expect(mergeBranch.description).toMatch(/a person merges/);
+        expect(mergeBranch.description).toMatch(/SYNC/);
+      }
+    });
+  });
+
   it('list_branches takes no branch and lists from any existing clone (repo-global)', async () => {
     const base = await start();
     // No `branch` in the body — the tool is repo-global. It must NOT try to
@@ -122,7 +236,9 @@ describe('registerWorkflowTools', () => {
       title: 'My change',
     });
     expect(res.status).toBe(200);
-    expect(await res.json()).toMatchObject({ changeRequest: { number: 7 } });
+    expect(await res.json()).toMatchObject({
+      changeRequest: { number: 7, url: 'https://bevel.example.com/change-requests/7' },
+    });
     // The workspace must be derived from the SOURCE branch (not a separate
     // `branch` arg) — encodeURIComponent('me/draft'). Regression guard for the
     // `-b undefined` clone bug when the model omitted `branch`.
@@ -204,18 +320,30 @@ describe('registerWorkflowTools', () => {
 describe('save_file and the repository folder', () => {
   // `save_file` commits whatever is on disk at `path` through the lock
   // protocol, bypassing the locking filesystem's own guard. A path without the
-  // clone-folder prefix names a file git can never see, so it is refused here,
-  // before a lock is taken, with the same corrected-path message the write
-  // tools give.
-  it('refuses a repo-relative path before taking any lock', async () => {
+  // clone-folder prefix used to be refused here; the one normaliser PLACES it
+  // inside the clone now, so the lock is taken on the repository path — the
+  // file git can actually see — and the refusal is kept for the spellings no
+  // prefix can rescue.
+  it('places a repo-relative path inside the clone and locks THAT path', async () => {
     const base = await start();
     const res = await post(`${base}/api/agent/tools/save_file`, writeTok(), {
       path: 'KnowledgeBase/Reviews/PR-12.html',
       branch: WS,
     });
+    expect(res.status).toBe(200);
+    expect(await res.json()).toMatchObject({ saved: true });
+    expect(calls).toContainEqual(['acquireLock', WS, WS, 'knowledge-base/KnowledgeBase/Reviews/PR-12.html']);
+  });
+
+  it('still refuses a traversing path before taking any lock', async () => {
+    const base = await start();
+    const res = await post(`${base}/api/agent/tools/save_file`, writeTok(), {
+      path: 'KnowledgeBase/../../etc/passwd',
+      branch: WS,
+    });
     expect(res.status).toBe(400);
     const body = (await res.json()) as { error: string };
-    expect(body.error).toContain('"knowledge-base/KnowledgeBase/Reviews/PR-12.html"');
+    expect(body.error).toContain('outside the knowledge base repository');
     expect(calls.some((c) => c[0] === 'acquireLock')).toBe(false);
   });
 
@@ -240,6 +368,28 @@ describe('save_file and the repository folder', () => {
     expect(calls).toContainEqual(['releaseLock', WS, WS, 'knowledge-base/KnowledgeBase/Reviews/PR-12.html']);
   });
 
+  it('accepts the root-anchored form Copy path gives, as the same path', async () => {
+    const base = await start();
+    const res = await post(`${base}/api/agent/tools/save_file`, writeTok(), {
+      path: '/knowledge-base/KnowledgeBase/Reviews/PR-12.html',
+      branch: WS,
+    });
+    expect(res.status).toBe(200);
+    expect(calls).toContainEqual(['acquireLock', WS, WS, 'knowledge-base/KnowledgeBase/Reviews/PR-12.html']);
+  });
+
+  it('still refuses a slash-led path outside the repository', async () => {
+    const base = await start();
+    const res = await post(`${base}/api/agent/tools/save_file`, writeTok(), {
+      path: '/KnowledgeBase/Reviews/PR-12.html',
+      branch: WS,
+    });
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as { error: string };
+    expect(body.error).toContain('outside the knowledge base repository');
+    expect(calls.some((c) => c[0] === 'acquireLock')).toBe(false);
+  });
+
   it('describes the prefix on its path input', async () => {
     await start();
     const tools = await registryRef!.listInternal();
@@ -247,5 +397,6 @@ describe('save_file and the repository folder', () => {
     // `toolDef` wraps a tool's inputs under a single `body` property.
     const body = (def!.inputs as { properties: { body: { properties: Record<string, { description?: string }> } } }).properties.body;
     expect(body.properties.path.description).toContain('`knowledge-base/`');
+    expect(body.properties.path.description).toContain('with or without a leading slash');
   });
 });

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

@@ -6,7 +6,13 @@ import { toolDef, withBranchInput } 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 { workspaceIdForBranch } from '../../../shared/workspace-id.js';
-import { assertInsideRepo } from '../../kb-fs/repo-path.js';
+import { assertInsideRepo, normalizePathArgs } from '../../kb-fs/repo-path.js';
+import { RETIRED_TOOL_MESSAGES } from '@bevel-software/platform-mcp-core';
+
+/** `knowledge-base/KnowledgeBase/x.md` → `KnowledgeBase/x.md`; anything else unchanged. */
+function stripKbDir(path: string, kbDirName: string): string {
+  return path.startsWith(`${kbDirName}/`) ? path.slice(kbDirName.length + 1) : path;
+}
 
 // A function, not a constant: the branch model is applied during boot, and a
 // module-scope capture would freeze this at the empty set that exists before it.
@@ -71,11 +77,33 @@ const commentSchema: JsonSchema = {
   required: ['id', 'author', 'body', 'headSha', 'createdAt'],
 };
 
+const changeRequestUrlSchema: JsonSchema = {
+  type: 'string',
+  description:
+    'Link a person can open: absolute (`https://<public address>/change-requests/<number>`) when the deployment ' +
+    'has a public address configured, else the relative in-app path (with `urlNote`).',
+};
+const changeRequestUrlNoteSchema: JsonSchema = { type: 'string', description: 'Present only when `url` is relative — how to get absolute links.' };
+
+/** The link to a change request, for a tool whose payload is not the change request itself. */
+const changeRequestLinkSchema: JsonSchema = {
+  type: 'object',
+  properties: { number: { type: 'integer' }, url: changeRequestUrlSchema, urlNote: changeRequestUrlNoteSchema },
+  required: ['number', 'url'],
+};
+
+/** `{ number, url, urlNote? }` of a change request summary or detail. */
+function linkOf(cr: { number: number; url: string; urlNote?: string }): { number: number; url: string; urlNote?: string } {
+  return { number: cr.number, url: cr.url, ...(cr.urlNote ? { urlNote: cr.urlNote } : {}) };
+}
+
 const changeRequestDetailSchema: JsonSchema = {
   type: 'object',
   description: 'Full change-request detail (aliased from the underlying pull request).',
   properties: {
     number: { type: 'integer' },
+    url: changeRequestUrlSchema,
+    urlNote: changeRequestUrlNoteSchema,
     title: { type: 'string' },
     body: { type: 'string' },
     author: { type: 'object', properties: { login: { type: 'string' }, name: { type: 'string' } }, required: ['login'] },
@@ -85,23 +113,7 @@ const changeRequestDetailSchema: JsonSchema = {
     comments: { type: 'array', items: commentSchema },
     approvals: { type: 'array', items: { type: 'object', additionalProperties: true }, description: 'Per-file approval state, one entry per file in `files`.' },
   },
-  required: ['number', 'title', 'body', 'headSha', 'baseSha', 'files', 'comments', 'approvals'],
-  additionalProperties: true,
-};
-
-const mergeOutcomeSchema: JsonSchema = {
-  type: 'object',
-  description: 'Either a completed merge or a signal that conflicts must be resolved first.',
-  properties: {
-    kind: { type: 'string', enum: ['merged', 'conflicts-need-resolution'] },
-    result: {
-      type: 'object',
-      description: 'Present when `kind` is `merged`.',
-      properties: { prNumber: { type: 'integer' }, sha: { type: 'string', description: 'Merge commit SHA.' }, mergedAt: { type: 'string', description: 'ISO timestamp.' } },
-    },
-    conflictedPaths: { type: 'array', items: { type: 'string' }, description: 'Present when `kind` is `conflicts-need-resolution` — paths to resolve on the source branch.' },
-  },
-  required: ['kind'],
+  required: ['number', 'url', 'title', 'body', 'headSha', 'baseSha', 'files', 'comments', 'approvals'],
   additionalProperties: true,
 };
 
@@ -153,13 +165,17 @@ export function registerWorkflowTools(
       path.slice('/api'.length),
       toolAuth,
       ...(spec.internalOnly ? [requireInternalSource] : []),
-      toolHandler(spec.handler, { write: spec.write }),
+      // Every path input becomes a repository path here, once, through the one
+      // normaliser: the root-anchored `/<kbDirName>/…` form names the same
+      // workspace path, and a path with no prefix is placed under
+      // `<kbDirName>/` rather than refused.
+      toolHandler((args, ctx) => spec.handler(normalizePathArgs(args, kbDirName), ctx), { write: spec.write }),
     );
   };
 
-  // A workspace for a repo-global op (branch listing, change-request reads /
-  // merges) that doesn't act on any one draft. All clones share one origin, so
-  // any existing one is equivalent — reusing a clone already on disk avoids
+  // A workspace for a repo-global op (branch listing, change-request reads)
+  // that doesn't act on any one draft. All clones share one origin, so any
+  // existing one is equivalent — reusing a clone already on disk avoids
   // cloning a branch (or failing when the default branch isn't on the remote)
   // just to run a global op. Falls back to the default branch on a cold start
   // with no workspaces yet.
@@ -228,7 +244,7 @@ export function registerWorkflowTools(
         path: {
           type: 'string',
           minLength: 1,
-          description: `Workspace-relative path, as write_file expects: starts with \`${kbDirName}/\` (e.g. \`${kbDirName}/KnowledgeBase/Foo.md\`).`,
+          description: `Workspace-relative path, as write_file expects: under \`${kbDirName}/\` (e.g. \`${kbDirName}/KnowledgeBase/Foo.md\`), with or without a leading slash — a path without that prefix is placed under \`${kbDirName}/\`, so it names the same file.`,
         },
       },
       required: ['path'],
@@ -248,9 +264,9 @@ export function registerWorkflowTools(
       const path = args.path as string;
       const branch = args.branch as string;
       // This tool commits whatever is on disk at `path` through the lock
-      // protocol, bypassing the locking filesystem's own guard. A path without
-      // the clone-folder prefix names a file git can never see: refuse it
-      // before a lock is taken, with the same corrected-path message.
+      // protocol, bypassing the locking filesystem's own guard. The normaliser
+      // above has already placed the path inside the clone; this is the check
+      // that what came out is really in there, before a lock is taken.
       if (typeof path !== 'string' || path.length === 0) {
         throw new ToolError('`path` is required and must be a non-empty string.', 400);
       }
@@ -334,7 +350,8 @@ export function registerWorkflowTools(
     description:
       'Open a change request from a draft branch into a target branch. Auto-merges the latest target ' +
       'into the source first, pushes, then creates the CR. On conflicts returns a ' +
-      '`change-request-conflicts` error with affected paths. The author marker is injected server-side.',
+      '`change-request-conflicts` error with affected paths. The author marker is injected server-side. ' +
+      'An agent proposes; a person reviews and merges the request in the app — hand the user its `url`.',
     inputs: {
       type: 'object',
       properties: {
@@ -376,7 +393,7 @@ export function registerWorkflowTools(
       properties: {
         number: { type: 'integer', minimum: 1, description: 'Change request number.' },
         body: { type: 'string', minLength: 1, description: 'Comment body (Markdown).' },
-        path: { type: 'string', description: 'Workspace-relative path for a file-level/inline comment.' },
+        path: { type: 'string', description: `Repository-relative path of the changed file for a file-level/inline comment (e.g. \`KnowledgeBase/Foo.md\`); the workspace form \`${kbDirName}/KnowledgeBase/Foo.md\`, with or without a leading slash, names the same file.` },
         line: { type: 'integer', minimum: 1, description: 'Line number for an inline comment. Requires `path`.' },
         parentId: { type: 'string', description: 'Comment id to reply to.' },
       },
@@ -385,8 +402,11 @@ export function registerWorkflowTools(
     },
     outputs: {
       type: 'object',
-      properties: { comment: { ...commentSchema, description: 'The posted review comment.' } },
-      required: ['comment'],
+      properties: {
+        comment: { ...commentSchema, description: 'The posted review comment.' },
+        changeRequest: { ...changeRequestLinkSchema, description: 'The change request commented on.' },
+      },
+      required: ['comment', 'changeRequest'],
     },
     write: true,
     // Keyed by change-request number, not a draft — the workspace is only a
@@ -396,7 +416,10 @@ export function registerWorkflowTools(
     handler: async (args, ctx: ToolContext) => {
       const number = args.number as number;
       const line = typeof args.line === 'number' ? args.line : undefined;
-      const path = typeof args.path === 'string' ? args.path : undefined;
+      // A change request's files are repository-relative; the workspace form
+      // Copy path gives (`/<kbDirName>/…`, its slash already dropped by the
+      // mount) carries the clone folder, which no changed file would match.
+      const path = typeof args.path === 'string' ? stripKbDir(args.path, kbDirName) : undefined;
       if (line !== undefined && !path) {        throw new ToolError('`path` is required when `line` is provided (inline comments anchor to a file).', 400);
       }
       const detail = await ctx.workflowService.getChangeRequestDetail(number, {
@@ -412,60 +435,66 @@ export function registerWorkflowTools(
         { body: args.body as string, path, line, parentId: typeof args.parentId === 'string' ? args.parentId : undefined },
         detail.headSha,
       );
-      return { comment };
+      return { comment, changeRequest: linkOf(detail) };
     },
   });
 
   mount({
-    name: 'merge_change_request',
+    name: 'merge_branch',
     description:
-      'Merge a change request into its target branch. Returns `merged` or ' +
-      '`conflicts-need-resolution`. Hard blocks (closed, no files, missing approvals) raise an error. ' +
-      '`bypass: true` proceeds despite soft warnings (admin only).',
+      'Merge branch `source` into branch `target` as you, and publish `target`. An agent proposes and syncs; ' +
+      'a person merges: this tool never lands a change request. It refuses when a change request from `source` ' +
+      'into `target` is open (naming it) — ask the user to review that request in the app instead. It refuses ' +
+      'when `target` is a protected branch unless you could commit every changed file directly to it. ' +
+      'SYNC: merging the target into your draft (`source` = the change request\'s target, `target` = your draft) ' +
+      'is always allowed, even with that draft\'s request open — use it to bring a draft up to date. ' +
+      'Returns `merged` with the merge commit, or `conflicts-need-resolution` with the conflicting paths ' +
+      '(nothing is written; resolve them on `source` and merge again).',
+    // Names both branches itself; the merge runs in `target`'s workspace.
+    skipBranch: true,
     inputs: {
       type: 'object',
       properties: {
-        number: { type: 'integer', minimum: 1, description: 'Change request number.' },
-        bypass: { type: 'boolean', description: 'Proceed despite missing owner approvals on .md files (admin only).' },
+        source: { type: 'string', minLength: 1, description: 'The branch whose commits are merged in.' },
+        target: { type: 'string', minLength: 1, description: 'The branch that receives the merge.' },
       },
-      required: ['number'],
+      required: ['source', 'target'],
       additionalProperties: false,
     },
     outputs: {
       type: 'object',
-      properties: { outcome: mergeOutcomeSchema },
+      properties: {
+        outcome: {
+          type: 'object',
+          description: 'Either a completed merge or a signal that conflicts must be resolved first.',
+          properties: {
+            kind: { type: 'string', enum: ['merged', 'conflicts-need-resolution'] },
+            sha: { type: 'string', description: 'Present when `kind` is `merged` — the tip of `target` after the merge.' },
+            conflictedPaths: { type: 'array', items: { type: 'string' }, description: 'Present when `kind` is `conflicts-need-resolution`.' },
+          },
+          required: ['kind'],
+        },
+      },
       required: ['outcome'],
     },
     write: true,
-    // Keyed by change-request number, not a draft — the workspace is only a
-    // scratch clone to run the merge in, so resolve any existing one rather than
-    // requiring a `branch`.
-    skipBranch: true,
     handler: async (args, ctx: ToolContext) => {
-      const number = args.number as number;
-      const workspaceId = await repoGlobalWorkspaceId(ctx);
-      const detail = await ctx.workflowService.getChangeRequestDetail(number, {
-        fresh: true,
-        workspaceId,
-        viewerEmail: ctx.user.email,
-      });
-      if (!detail) {        throw new ToolError(`Change request #${number} not found.`, 404);
+      const source = args.source;
+      const target = args.target;
+      if (typeof source !== 'string' || source.length === 0 || typeof target !== 'string' || target.length === 0) {
+        throw new ToolError('`source` and `target` are required branch names.', 400);
       }
-      const outcome = await ctx.workflowService.mergeChangeRequest(
-        number,
-        ctx.user,
-        detail.headSha,
-        detail.approvals,
-        detail.state,
-        detail.title,
-        detail.base,
-        workspaceId,
-        { bypass: args.bypass === true },
-      );
-      return { outcome };
+      return { outcome: await ctx.workflowService.mergeBranch(ctx.user, source, target) };
     },
   });
 
+  // `merge_change_request` is retired: a change request is merged by a person
+  // in the app. It is in no catalog, but a caller holding an old manual still
+  // posts to its path — answer with who merges now, not a bare 404.
+  router.post('/agent/tools/merge_change_request', toolAuth, (_req, res) => {
+    res.status(410).json({ error: RETIRED_TOOL_MESSAGES.merge_change_request });
+  });
+
   mount({
     name: 'switch_branch',
     description:

package/src/modules/workflow/event-bus.ts

@@ -42,6 +42,9 @@ import {
   type WorkflowEvent,
   type WorkflowEventPayload,
 } from '@bevel-software/platform-shared';
+import { logger } from '../../shared/logging.js';
+
+const log = logger('event-bus');
 
 /**
  * Capacity of the global event ring buffer. A new event evicts the oldest
@@ -60,7 +63,7 @@ const BUFFER_CAPACITY = 500;
 export type SubscriberPush = (event: WorkflowEvent) => void;
 
 /**
- * Per-session subscription bookkeeping. `getFocusedWorkspaceId` is a getter
+ * Per-session subscription bookkeeping. `getFocusedWorkspaceIds` is a getter
  * (not a value) so the route layer can update the session's focus via a
  * separate POST without re-subscribing — the next `emit` sees the new focus
  * on the next call.
@@ -68,7 +71,13 @@ export type SubscriberPush = (event: WorkflowEvent) => void;
 export interface Subscriber {
   sessionId: string;
   userId: string;
-  getFocusedWorkspaceId: () => string | null;
+  /**
+   * Every workspace this session wants events for. A LIST because a page can
+   * read from more than one: the skill page renders default-branch content
+   * while the reader stands on a suggestion branch. Empty = no workspace
+   * events (the session has not declared a focus yet).
+   */
+  getFocusedWorkspaceIds: () => string[];
   push: SubscriberPush;
 }
 
@@ -127,10 +136,7 @@ export class WorkflowEventBus {
       try {
         listener(event);
       } catch (err) {
-        console.warn(
-          '[event-bus] onEmit listener threw:',
-          err instanceof Error ? err.message : err,
-        );
+        log.warn('onEmit listener threw:', { err });
       }
     }
     // Single-line emit log with all the fields most useful for tracing a
@@ -148,8 +154,8 @@ export class WorkflowEventBus {
     if ('branch' in event && event.branch) extra.push(`branch=${event.branch}`);
     if ('newSha' in event && event.newSha !== undefined) extra.push(`sha=${event.newSha ?? 'null'}`);
     if ('holderName' in event && event.holderName) extra.push(`holder=${event.holderName}`);
-    console.log(
-      `[event-bus] EMIT id=${event.id} kind=${event.kind} ${scope}${extra.length ? ' ' + extra.join(' ') : ''} subs=${this.subscribers.size}`,
+    log.info(
+      `EMIT id=${event.id} kind=${event.kind} ${scope}${extra.length ? ' ' + extra.join(' ') : ''} subs=${this.subscribers.size}`,
     );
     let matched = 0;
     let skipped = 0;
@@ -157,7 +163,7 @@ export class WorkflowEventBus {
       // Best-effort per subscriber — one bad subscriber must not block
       // the rest of the fan-out OR propagate back to the caller. The
       // try/catch covers both the scope check (`matches` reaches into
-      // `sub.getFocusedWorkspaceId()`, which could throw if a bizarre
+      // `sub.getFocusedWorkspaceIds()`, which could throw if a bizarre
       // subscriber holds buggy state) and the dispatch itself, so
       // workflow mutations stay successful even if a listener throws.
       // Callers can rely on `emit` never throwing, so they don't need
@@ -170,15 +176,10 @@ export class WorkflowEventBus {
         sub.push(event);
         matched++;
       } catch (err) {
-        console.warn(
-          `[event-bus] dispatch to session ${sub.sessionId} threw:`,
-          err instanceof Error ? err.message : err,
-        );
+        log.warn(`dispatch to session ${sub.sessionId} threw:`, { err });
       }
     }
-    console.log(
-      `[event-bus] EMIT id=${event.id} kind=${event.kind} → delivered=${matched} skipped=${skipped}`,
-    );
+    log.info(`EMIT id=${event.id} kind=${event.kind} → delivered=${matched} skipped=${skipped}`);
     return event;
   }
 
@@ -189,18 +190,14 @@ export class WorkflowEventBus {
    */
   subscribe(sub: Subscriber): () => void {
     this.subscribers.set(sub.sessionId, sub);
-    console.log(
-      `[event-bus] SUBSCRIBE session=${sub.sessionId} user=${sub.userId} → total=${this.subscribers.size}`,
-    );
+    log.info(`SUBSCRIBE session=${sub.sessionId} user=${sub.userId} → total=${this.subscribers.size}`);
     return () => {
       // Only delete if the same Subscriber is still registered — protects
       // against a stale unsubscribe (e.g. a reconnect replaced the entry
       // before the old `close` handler fired).
       if (this.subscribers.get(sub.sessionId) === sub) {
         this.subscribers.delete(sub.sessionId);
-        console.log(
-          `[event-bus] UNSUBSCRIBE session=${sub.sessionId} user=${sub.userId} → total=${this.subscribers.size}`,
-        );
+        log.info(`UNSUBSCRIBE session=${sub.sessionId} user=${sub.userId} → total=${this.subscribers.size}`);
       }
     };
   }
@@ -221,7 +218,7 @@ export class WorkflowEventBus {
    * is greater than `lastSeenId + 1` (i.e. we evicted events the client
    * needs to see).
    */
-  replayAfter(lastSeenId: number, sub: Pick<Subscriber, 'userId' | 'getFocusedWorkspaceId'>): WorkflowEvent[] | null {
+  replayAfter(lastSeenId: number, sub: Pick<Subscriber, 'userId' | 'getFocusedWorkspaceIds'>): WorkflowEvent[] | null {
     // Empty buffer: a client that never saw anything (lastSeenId === 0) has
     // nothing to replay and the empty array is correct. A client that DID
     // see events (lastSeenId > 0) but reached an empty buffer means the
@@ -259,14 +256,14 @@ export class WorkflowEventBus {
    *   - User-scoped events: only sessions whose `userId` matches `forUserId`.
    *   - Global events (heartbeat, resync, change-request-*): everyone.
    *
-   * The focus check resolves through `getFocusedWorkspaceId()` so a session
+   * The focus check resolves through `getFocusedWorkspaceIds()` so a session
    * that hasn't yet POSTed its focus gets no workspace events (correct —
    * we don't know what it cares about).
    */
-  private matches(event: WorkflowEvent, sub: Pick<Subscriber, 'userId' | 'getFocusedWorkspaceId'>): boolean {
+  private matches(event: WorkflowEvent, sub: Pick<Subscriber, 'userId' | 'getFocusedWorkspaceIds'>): boolean {
     if (isWorkspaceScoped(event)) {
-      const focus = sub.getFocusedWorkspaceId();
-      if (focus === null) return false;
+      const watched = sub.getFocusedWorkspaceIds();
+      if (watched.length === 0) return false;
       // **Normalise URL encoding before comparing.** The frontend stores
       // `workspace.id` as `encodeURIComponent(branch)` (e.g.
       // `razvan-radulescu%2Fsc`) and sends that as the focus value via
@@ -277,7 +274,8 @@ export class WorkflowEventBus {
       // contains a `/`, silently dropping all live updates (lock state,
       // file-changed, fs-tree) on feature branches. Decoding both sides
       // collapses the two forms into the same canonical key.
-      return canonicalize(focus) === canonicalize(event.workspaceId);
+      const target = canonicalize(event.workspaceId);
+      return watched.some((id) => canonicalize(id) === target);
     }
     if (isUserScoped(event)) {
       return sub.userId === event.forUserId;