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

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;

package/src/modules/workflow/events.routes.ts

@@ -33,6 +33,9 @@
  */
 
 import type { Request, Response } from 'express';
+import { logger } from '../../shared/logging.js';
+
+const log = logger('events');
 import express from 'express';
 import type { WorkflowEvent } from '@bevel-software/platform-shared';
 import type { WorkflowEventBus } from './event-bus.js';
@@ -42,16 +45,40 @@ import '../auth/auth.middleware.js'; // Express Request augmentation
  * the typical 30–100 s proxy idle timeout. */
 const HEARTBEAT_INTERVAL_MS = 25_000;
 
+/**
+ * Ceiling on how many workspaces one session may watch. The list is walked on
+ * every workspace-scoped event for every session, so it is a fan-out cost, and
+ * a client bug that appends without ever releasing would otherwise grow it
+ * without bound. Real pages want two: the branch in the address bar, and the
+ * default branch a skill page reads from.
+ */
+const MAX_WATCHED_WORKSPACES = 8;
+
 /**
  * Per-session bookkeeping the route owns. The bus's `Subscriber` holds a
- * `getFocusedWorkspaceId()` getter pointing at `session.focusedWorkspaceId`,
+ * `getFocusedWorkspaceIds()` getter pointing at `session.focusedWorkspaceIds`,
  * so the focus POST mutates this object and the next event fan-out picks
  * up the new value with no re-subscribe.
  */
 interface ActiveSession {
   sessionId: string;
   userId: string;
-  focusedWorkspaceId: string | null;
+  /**
+   * Every workspace this session wants events for, primary first.
+   *
+   * A LIST, not one id, because "the workspace the user is looking at" and
+   * "the workspaces the open page reads from" are different questions. The
+   * skill page is the case that forced it: it renders the DEFAULT branch's
+   * tree whatever branch is checked out, so a reader standing on their own
+   * suggestion branch got no `file-changed` for the images on screen and kept
+   * showing a screenshot a teammate had already replaced.
+   *
+   * The client declares the list; this is a delivery filter, not an access
+   * check. It always was — a session could name any workspace as its focus —
+   * and the events it selects carry no file contents, only paths. Whether the
+   * reader may open what changed is settled by the routes that serve it.
+   */
+  focusedWorkspaceIds: string[];
   /** Set when the SSE connection closes. Used by the focus POST so a
    *  request that arrives after the connection drops 404s cleanly. */
   closed: boolean;
@@ -75,7 +102,7 @@ export function createEventsRoutes(
 
   /**
    * Process-wide session registry. The same map services the SSE open
-   * (creates the entry) and the focus POST (mutates `focusedWorkspaceId`).
+   * (creates the entry) and the focus POST (mutates `focusedWorkspaceIds`).
    * Entries clear when the SSE connection closes.
    */
   const sessions = new Map<string, ActiveSession>();
@@ -116,26 +143,20 @@ export function createEventsRoutes(
       try {
         existing.cleanup();
       } catch (err) {
-        console.warn(
-          `[events] supersede cleanup threw for session=${sessionId}:`,
-          err instanceof Error ? err.message : err,
-        );
+        log.warn(`supersede cleanup threw for session=${sessionId}:`, { err });
       }
       existing.closed = true;
       try {
         if (!existing.res.writableEnded) existing.res.end();
       } catch (err) {
-        console.warn(
-          `[events] failed to end superseded SSE response for session=${sessionId}:`,
-          err instanceof Error ? err.message : err,
-        );
+        log.warn(`failed to end superseded SSE response for session=${sessionId}:`, { err });
       }
     }
 
     const session: ActiveSession = {
       sessionId,
       userId,
-      focusedWorkspaceId: null,
+      focusedWorkspaceIds: [],
       closed: false,
       res,
       // Filled in below once `unsubscribe` + `heartbeat` exist.
@@ -151,7 +172,7 @@ export function createEventsRoutes(
     const unsubscribe = bus.subscribe({
       sessionId,
       userId,
-      getFocusedWorkspaceId: () => session.focusedWorkspaceId,
+      getFocusedWorkspaceIds: () => session.focusedWorkspaceIds,
       push,
     });
 
@@ -163,7 +184,7 @@ export function createEventsRoutes(
     if (Number.isFinite(lastSeenId) && lastSeenId > 0) {
       const replay = bus.replayAfter(lastSeenId, {
         userId,
-        getFocusedWorkspaceId: () => session.focusedWorkspaceId,
+        getFocusedWorkspaceIds: () => session.focusedWorkspaceIds,
       });
       if (replay === null) {
         // Buffer evicted past `lastSeenId` — client must refetch from
@@ -202,7 +223,7 @@ export function createEventsRoutes(
     res.on('close', cleanup);
     res.on('error', cleanup);
 
-    console.log(`[events] open session=${sessionId} user=${userId} subscribers=${bus.size()}`);
+    log.info(`open session=${sessionId} user=${userId} subscribers=${bus.size()}`);
   });
 
   router.post('/events/:sessionId/focus', authMiddleware, express.json(), (req, res) => {
@@ -228,17 +249,31 @@ export function createEventsRoutes(
       res.status(403).json({ error: 'Session belongs to another user' });
       return;
     }
-    const { workspaceId } = (req.body ?? {}) as { workspaceId?: unknown };
+    const { workspaceId, alsoWatch } = (req.body ?? {}) as {
+      workspaceId?: unknown;
+      alsoWatch?: unknown;
+    };
     if (typeof workspaceId !== 'string' || workspaceId.length === 0) {
       res.status(400).json({ error: 'workspaceId is required in body' });
       return;
     }
-    const previous = session.focusedWorkspaceId;
-    session.focusedWorkspaceId = workspaceId;
-    console.log(
-      `[events] FOCUS session=${sessionId} user=${userId} ${previous ?? '(none)'} → ${workspaceId}`,
+    // `alsoWatch` is optional and additive: the workspaces an open page reads
+    // from besides the one in the address bar. Non-string and empty entries
+    // are dropped rather than 400-ing the whole update — the primary focus is
+    // the part the user's navigation depends on, and it is well-formed here.
+    const extra = Array.isArray(alsoWatch)
+      ? alsoWatch.filter((id): id is string => typeof id === 'string' && id.length > 0)
+      : [];
+    // Primary first, de-duplicated: `matches` walks this list per event.
+    const next = [...new Set([workspaceId, ...extra])].slice(0, MAX_WATCHED_WORKSPACES);
+    const previous = session.focusedWorkspaceIds;
+    session.focusedWorkspaceIds = next;
+    log.info(
+      `FOCUS session=${sessionId} user=${userId} ${
+        previous.join(',') || '(none)'
+      } → ${next.join(',')}`,
     );
-    res.json({ status: 'ok', focusedWorkspaceId: workspaceId });
+    res.json({ status: 'ok', focusedWorkspaceId: workspaceId, focusedWorkspaceIds: next });
   });
 
   return router;

package/src/modules/workflow/file-lock.service.ts

@@ -11,6 +11,24 @@
  * is the source of truth and any cache would lose its purpose the moment
  * a different replica takes over.
  *
+ * Path identity: every method here canonicalises the path it was handed
+ * before it touches a row, so `./x//a.md` and `x/a.md` are ONE lock no
+ * matter which caller spelled which. It happens HERE rather than in the
+ * routes because the lock row is the coordination point: the routes are only
+ * today's callers, and a caller that reaches this service directly (the
+ * agent's lock-aware filesystem, a future route family) has to land on the
+ * same identity or it is not coordinating with anyone. Canonicalisation also
+ * REFUSES a path that escapes the workspace or that only looks relative, with
+ * the statuses the file verbs answer for the same input, so a lock row can
+ * never be keyed on a path no file verb would accept. See
+ * `canonicalFileIdentity`.
+ *
+ * There is no transition handling for rows written under a raw spelling
+ * before this landed: such a row is now unreachable by name and expires on
+ * its own TTL. For one deploy an in-flight edit's lock can linger up to the
+ * TTL below; nothing migrates and nothing dual-matches, because a dual match
+ * would be a second identity and the whole point is that there is one.
+ *
  * Stale-lock semantics: `get`, `acquire`, and `heartbeat` all treat a row
  * with `expires_at <= now()` as if the lock didn't exist. We purge it
  * lazily on next access rather than running a sweeper — the row count is
@@ -22,6 +40,7 @@ import type { Database } from '../database/connection.js';
 import { fileLocks } from '../database/schema.js';
 import type { AcquireLockResult, AuthUser, FileLock } from '@bevel-software/platform-shared';
 import { WorkflowValidationError } from '../../shared/domain-errors.js';
+import { canonicalFileIdentity } from '../../shared/canonical-file-identity.js';
 
 /**
  * Lock lifetime without a heartbeat. The client is expected to heartbeat
@@ -73,10 +92,11 @@ export class FileLockService {
   async acquire(
     workspaceId: string,
     branch: string,
-    targetPath: string,
+    rawPath: string,
     user: AuthUser,
     opts?: { coordination?: boolean },
   ): Promise<AcquireLockResult> {
+    const targetPath = canonicalFileIdentity(rawPath);
     const now = new Date();
     const expiresAt = new Date(now.getTime() + LOCK_TTL_MS);
 
@@ -175,9 +195,10 @@ export class FileLockService {
   async heartbeat(
     workspaceId: string,
     branch: string,
-    targetPath: string,
+    rawPath: string,
     user: AuthUser,
   ): Promise<FileLock> {
+    const targetPath = canonicalFileIdentity(rawPath);
     const now = new Date();
     const expiresAt = new Date(now.getTime() + LOCK_TTL_MS);
     // The expiry guard (`expiresAt > now`) matters because an expired
@@ -221,9 +242,10 @@ export class FileLockService {
   async release(
     workspaceId: string,
     branch: string,
-    targetPath: string,
+    rawPath: string,
     user: AuthUser,
   ): Promise<void> {
+    const targetPath = canonicalFileIdentity(rawPath);
     await this.db
       .delete(fileLocks)
       .where(
@@ -244,8 +266,9 @@ export class FileLockService {
   async get(
     workspaceId: string,
     branch: string,
-    targetPath: string,
+    rawPath: string,
   ): Promise<FileLock | null> {
+    const targetPath = canonicalFileIdentity(rawPath);
     const rows = await this.db
       .select()
       .from(fileLocks)