@bevel-software/platform-core-backend 0.32.0 → 0.34.0

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

@@ -1,16 +1,15 @@
 import type { Router, RequestHandler } from 'express';
-import type { IToolRegistry, JsonSchema } from '../../tool-registry/tool.contract.js';
-import { ToolError, hasHttpStatus, type ToolContext, type ToolHandler } from '../../tool-helpers/tool.contract.js';
+import type { IToolRegistry, JsonSchema } from '../../tool-registry/index.js';
+import { ToolError, hasHttpStatus, type ToolContext, type ToolHandler, toolDef } from '../../tool-helpers/index.js';
 import { isCommitSha } from '../../../shared/git.contract.js';
-import { toolDef } 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 type { IAccessControl } from '../../access/access-control.interface.js';
+import type { ToolHandlerFactory } from '../../tool-helpers/index.js';
+import { requireInternalSource } from '../../tool-auth/index.js';
+import type { IAccessControl } from '../../access/index.js';
 import { assertAgentWriteAllowed, notifyAgentRead, SESSION_ID_INPUT, type AgentAccessGate } from '../../workspace/index.js';
 import { readablePathsAt, readableAtCommits, assertReadableAtCommits } from '../read-on-branch.js';
 import type { KbContext } from '../../../shared/kb-context.js';
 import { workspaceIdForBranch } from '../../../shared/workspace-id.js';
-import { assertInsideRepo, normalizePathArgs } from '../../kb-fs/repo-path.js';
+import { assertInsideRepo, normalizePathArgs } from '../../kb-fs/index.js';
 import { RETIRED_TOOL_MESSAGES } from '@bevel-software/platform-mcp-core';
 import {
   CHANGE_REQUEST_INCLUDES,
@@ -30,18 +29,16 @@ const protectedInline = (kb: Pick<KbContext, 'protectedBranches'>) =>
   [...kb.protectedBranches].map((b) => `\`${b}\``).join(' / ');
 
 // Output sub-schemas for the git-aliased workflow payloads (Branch, Change,
-// ChangeRequestComment, …). Defined once and referenced by the individual tool
+// ChangeRequest, …). Defined once and referenced by the individual tool
 // defs below so each tool still declares its own `outputs`.
 const branchSchema: JsonSchema = {
   type: 'object',
   properties: {
     name: { type: 'string' },
     isProtected: { type: 'boolean' },
-    ahead: { type: ['integer', 'null'], description: 'Commits ahead of upstream / nearest protected base; null if unresolved.' },
-    behind: { type: ['integer', 'null'], description: 'Commits behind; null if unresolved.' },
     hasRemote: { type: 'boolean', description: 'True iff `origin/<name>` exists after the last fetch.' },
   },
-  required: ['name', 'isProtected', 'ahead', 'behind', 'hasRemote'],
+  required: ['name', 'isProtected', 'hasRemote'],
 };
 
 const commitSchema: JsonSchema = {
@@ -75,7 +72,7 @@ const changeRequestApproversSchema: JsonSchema = {
   properties: {
     path: { type: 'string' },
     roles: { type: 'array', items: { type: 'string' }, description: 'Roles that confer approval here; `everyone` means any signed-in approver.' },
-    users: { type: 'array', items: { type: 'string' }, description: 'Approvers named directly, by display name.' },
+    users: { type: 'array', items: { type: 'string' }, description: 'Approvers named directly: each by display name, or by email when the access tree resolved no name. Never a blank string.' },
     approved: { type: 'boolean', description: 'True once an eligible approver has approved at the current head.' },
     inMergeGate: { type: 'boolean', description: 'False when the merge gate does not bind this path — then nobody has to approve it.' },
     approversUnknown: { type: 'boolean', description: 'Present when the access tree could not be resolved: empty `roles`/`users` means unknown, not nobody.' },
@@ -83,22 +80,6 @@ const changeRequestApproversSchema: JsonSchema = {
   required: ['path', 'roles', 'users', 'approved', 'inMergeGate'],
 };
 
-const commentSchema: JsonSchema = {
-  type: 'object',
-  properties: {
-    id: { type: 'string' },
-    author: { type: 'object', properties: { email: { type: 'string' }, name: { type: 'string' } }, required: ['email', 'name'] },
-    body: { type: 'string' },
-    path: { type: 'string', description: 'Set for file-level / inline comments.' },
-    line: { type: 'integer', description: 'Set for inline comments.' },
-    headSha: { type: 'string', description: 'Head the comment was anchored to.' },
-    parentId: { type: 'string', description: 'Root comment id when this is a reply.' },
-    createdAt: { type: 'string', description: 'ISO timestamp.' },
-    updatedAt: { type: 'string', description: 'ISO timestamp; present once edited.' },
-  },
-  required: ['id', 'author', 'body', 'headSha', 'createdAt'],
-};
-
 const changeRequestUrlSchema: JsonSchema = {
   type: 'string',
   description:
@@ -107,13 +88,6 @@ const changeRequestUrlSchema: JsonSchema = {
 };
 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 } : {}) };
@@ -183,7 +157,9 @@ export function registerWorkflowTools(
   /**
    * Whether the caller may see change request `number` — `get_change_request`'s
    * own gate (`changeRequestScope(...).maySee`). `delete_branch` neither names
-   * nor links a request it answers no for.
+   * nor links a request it answers no for, and `update_change_request` answers
+   * such a request exactly as `get_change_request` does (404) before reading its
+   * state or who may edit it.
    */
   maySeeChangeRequest: (ctx: ToolContext, number: number) => Promise<boolean>,
   /**
@@ -261,7 +237,9 @@ export function registerWorkflowTools(
         // `getFilesystem` — so the branch-less call the tool handler refuses
         // before this runs would otherwise commit to, or fork from, a
         // workspace literally named "undefined".
-        (args, ctx) => spec.handler(normalizePathArgs(args, kbDirName), ctx),
+        // The normaliser also refuses a tmp ref (`__tmp__/…`) in every path
+        // input: none of these tools takes one (see `kb-fs/tmp-ref.ts`).
+        (args, ctx) => spec.handler(normalizePathArgs(args, kbDirName, { tool: spec.name }), ctx),
         { write: spec.write },
       ),
     );
@@ -280,7 +258,8 @@ export function registerWorkflowTools(
     name: 'list_branches',
     description:
       'List every draft known to the repository (protected versions + unprotected drafts, ' +
-      'local and on the shared remote). Returns `{ branches: [{ name, isProtected, ahead, behind, hasRemote }] }`. ' +
+      'local and on the shared remote). Returns `{ branches: [{ name, isProtected, hasRemote }] }`; ' +
+      'how far one branch is ahead or behind is `branch_status`\'s answer. ' +
       'Takes no arguments — branch listing is repo-global, not scoped to any one draft.',
     // Repo-global: the branch set is the same from any clone, so don't require
     // (and risk cloning) a model-named branch — resolve any existing workspace.
@@ -472,7 +451,7 @@ export function registerWorkflowTools(
         sourceBranch: { type: 'string', minLength: 1, description: 'The draft branch carrying the changes.' },
         targetBranch: { type: 'string', minLength: 1, description: `The branch to apply to (e.g. '${kb.defaultBranch}').` },
         title: { type: 'string', minLength: 1, maxLength: 256, description: 'Short imperative title (≤256 chars).' },
-        description: { type: 'string', description: 'Optional markdown body shown verbatim to reviewers.' },
+        description: { type: 'string', maxLength: 64_000, description: 'Optional markdown body shown verbatim to reviewers (≤64,000 chars).' },
         include: {
           type: 'array',
           items: { type: 'string', enum: [...CHANGE_REQUEST_INCLUDES] },
@@ -507,66 +486,62 @@ export function registerWorkflowTools(
   });
 
   mount({
-    name: 'post_change_request_comment',
+    name: 'update_change_request',
     description:
-      'Post a review comment on a change request. Three modes: general (no path), file-level (path), ' +
-      'inline (path + line). Anchors to the CR\'s current head.',
+      'Change the title and/or the description of an OPEN change request. Allowed for its author and for anyone ' +
+      'who may merge it (an admin, or someone who may approve every file it changes) — the same rule as the app\'s ' +
+      'Edit control; anyone else is refused (403), and so is a merged or closed request (409), in words. ' +
+      "`description` replaces the request's description whole — the text `get_change_request` answers as `body`; " +
+      '`appendDescription` instead adds a paragraph after the description as it stands when the write happens, so two ' +
+      'notes racing each other both land (never together with `description`). Give at least one field; an absent one keeps its text. ' +
+      '`get_change_request` answers the new text at once. A request you may not see answers 404, as `get_change_request` does.',
     inputs: {
       type: 'object',
       properties: {
         number: { type: 'integer', minimum: 1, description: 'Change request number.' },
-        body: { type: 'string', minLength: 1, description: 'Comment body (Markdown).' },
-        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.' },
+        title: { type: 'string', minLength: 1, maxLength: 256, description: 'The new title (≤256 chars).' },
+        description: { type: 'string', maxLength: 64_000, description: 'The new description (Markdown, ≤64,000 chars); an empty string clears it.' },
+        appendDescription: { type: 'string', maxLength: 64_000, description: 'A paragraph (Markdown) added after the description as stored at the moment of the write; what it leaves is ≤64,000 chars. Not together with `description`.' },
       },
-      required: ['number', 'body'],
+      required: ['number'],
       additionalProperties: false,
     },
     outputs: {
       type: 'object',
       properties: {
-        comment: { ...commentSchema, description: 'The posted review comment.' },
-        changeRequest: { ...changeRequestLinkSchema, description: 'The change request commented on.' },
+        number: { type: 'integer' },
+        url: changeRequestUrlSchema,
+        urlNote: changeRequestUrlNoteSchema,
+        title: { type: 'string', description: 'The title as it now stands.' },
       },
-      required: ['comment', 'changeRequest'],
+      required: ['number', 'url', 'title'],
     },
     write: true,
-    // Keyed by change-request number, not a draft — the workspace is only a
-    // scratch clone to run the repo op in, so resolve any existing one rather
-    // than requiring a `branch`.
+    // Keyed by change-request number; the service resolves the request's own
+    // base branch for the permission check.
     skipBranch: true,
     handler: async (args, ctx: ToolContext) => {
+      const title = typeof args.title === 'string' ? args.title : undefined;
+      const description = typeof args.description === 'string' ? args.description : undefined;
+      const appendDescription = typeof args.appendDescription === 'string' ? args.appendDescription : undefined;
+      if (title === undefined && description === undefined && appendDescription === undefined) {
+        throw new ToolError('Give a new `title`, a new `description`, or an `appendDescription`.', 400);
+      }
+      // A request the caller may not read is not found — never a 403 or a
+      // state-specific 409, which would tell a probe that it exists.
       const number = args.number as number;
-      const line = typeof args.line === 'number' ? args.line : 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);
+      if (!(await maySeeChangeRequest(ctx, number))) {
+        throw new ToolError(`Change request #${number} not found.`, 404);
       }
-      const detail = await ctx.workflowService.getChangeRequestDetail(number, {
-        fresh: true,
-        workspaceId: await repoGlobalWorkspaceId(ctx),
-        viewerEmail: ctx.user.email,
+      const updated = await ctx.workflowService.updateChangeRequest(number, ctx.user, {
+        title,
+        description,
+        appendDescription,
       });
-      if (!detail) {        throw new ToolError(`Change request #${number} not found.`, 404);
-      }
-      // A comment anchors to a commit, and a DECLINED request has none to anchor
-      // to: nothing durable records what it proposed, so its detail carries no
-      // head (see `changeSourceFor`). Say that, rather than letting the service's
-      // `head sha is required` surface as a 400 about an argument the caller
-      // never passed. An APPLIED request still takes comments — its head is the
-      // source tip its merge commit recorded.
-      if (!detail.headSha) {        throw new ToolError(`Change request #${number} is ${detail.state} and has no commit to anchor a comment to.`, 409);
-      }
-      const comment = await ctx.workflowService.postComment(
-        number,
-        ctx.user,
-        { body: args.body as string, path, line, parentId: typeof args.parentId === 'string' ? args.parentId : undefined },
-        detail.headSha,
-      );
-      return { comment, changeRequest: linkOf(detail) };
+      return {
+        ...linkOf(updated),
+        title: updated.title,
+      };
     },
   });
 
@@ -1004,9 +979,13 @@ export function registerWorkflowTools(
       // and a save or sync landing between two of them is tolerated — the
       // next call reports it. (The one answer that must be exact, what a
       // merge is of, is taken under one reservation by `update_branch`.)
-      const [status, branches, pending, forkBase] = await Promise.all([
+      // The counts alone wait for the listing: its fetch refreshes the
+      // remote-tracking refs they are measured against.
+      const [status, [branches, counts], pending, forkBase] = await Promise.all([
         ctx.workflowService.branchStatus(workspaceId),
-        ctx.workflowService.listBranches(workspaceId),
+        ctx.workflowService
+          .listBranches(workspaceId)
+          .then(async (listed) => [listed, await ctx.workflowService.branchCounts(workspaceId)] as const),
         ctx.workflowService.listPendingChangePaths(workspaceId),
         ctx.workflowService.resolveForkBase(workspaceId, branch),
       ]);
@@ -1026,8 +1005,8 @@ export function registerWorkflowTools(
         branch,
         isProtected: info?.isProtected ?? kb.protectedBranches.has(branch),
         hasRemote: info?.hasRemote ?? status.hasUpstream,
-        ahead: info?.ahead ?? null,
-        behind: info?.behind ?? null,
+        ahead: counts.ahead,
+        behind: counts.behind,
         behindRemote: status.unmergedFromUpstream,
         uncommittedPaths,
         forkBase,

package/src/modules/workflow/change-request-hooks.ts

@@ -25,7 +25,7 @@ export interface ChangeRequestOpenedEvent {
   openedBy: ChangeRequestPerson;
   /**
    * The distinct people eligible to approve some changed path, as accounts —
-   * the eligibility the request's `## Affected owners` block lists, with the
+   * the eligibility the request's per-file approvals show, with the
    * roles and groups expanded to their members, each person once however
    * many paths or roles name them. Only a person with an account is here: a
    * listener writes to accounts. The author is not left out; a listener that

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

@@ -179,7 +179,9 @@ export class WorkflowEventBus {
         log.warn(`dispatch to session ${sub.sessionId} threw:`, { err });
       }
     }
-    log.info(`EMIT id=${event.id} kind=${event.kind} → delivered=${matched} skipped=${skipped}`);
+    // `pushed`, not delivered: the events route's delivery rule may still
+    // withhold the event from a session it was pushed to.
+    log.info(`EMIT id=${event.id} kind=${event.kind} → pushed=${matched} skipped=${skipped}`);
     return event;
   }
 

package/src/modules/workflow/events-delivery.ts

@@ -0,0 +1,278 @@
+/**
+ * Who may receive an event: the per-kind delivery rule the events route
+ * applies, once per event per session, before it writes the event out.
+ *
+ * The bus decides which sessions HEAR about an event — its focus filter
+ * (workspace-scoped kinds) and user filter (user-scoped kinds). That is a
+ * delivery filter, and a session may name any workspace as its focus. This is
+ * the access check on top of it: an event that names something reaches only a
+ * person who may read what it names, judged by the same services the routes
+ * that serve that thing judge it by.
+ *
+ *   - An event that names a path on a workspace (`file-changed`, the two lock
+ *     events, and any later kind that carries `workspaceId` and `path`): the
+ *     person may read the path on that branch, as the file routes judge it —
+ *     after the one normaliser the file routes put every path through, so a
+ *     path a client sent without the `<kbDirName>/` prefix (the lock route
+ *     takes both spellings) is judged as the repository path it names, never
+ *     as "outside the knowledge base, readable".
+ *   - `approval-changed`: the person may read the approved path on the
+ *     request's target branch — judged as a file event on that branch is,
+ *     from the server's checkout of it (a cached read of the access rules
+ *     from disk, no git), and only for a target the server holds no checkout
+ *     of from its published ref. Never by reading the request's detail, which
+ *     diffs the branch pair with several git subprocesses per person per event.
+ *   - `change-request-opened`: the person may see the request, by the rule the
+ *     request tools list and 404 by (`maySeeChangeRequest`): its author, or
+ *     someone who may read one of its files — both names of a move — at its
+ *     target, read at `origin/<target>` exactly as the tools read it
+ *     (`readablePathsAt`), so the event never announces a request the tools
+ *     answer as not found. The request's file list is read ONCE per event,
+ *     however many sessions are judged; each person then costs one batch
+ *     verdict from the access tree cached by commit.
+ *   - `git-sync-failed`: the event names the workspace's root and, for a sync
+ *     conflict, each conflicted file (its `reason` quotes them too). The person
+ *     gets the paths they may read; git's words reach only a person who may
+ *     read the root and every path the conflict names, and everyone else gets
+ *     a fixed sentence.
+ *   - `agent-tool-call`: the person whose agent made the call, as the bus
+ *     already filters it; the rule says the same, so a bus that passed it on
+ *     would not widen the audience.
+ *
+ * Every other kind is delivered as it is. That includes the number-only
+ * change-request lifecycle kinds (`-merged`, `-rejected`, `-apply-failed`),
+ * which follow an announcement the person was either given or not. A verdict
+ * that cannot be reached (the access tree fails to load, the request cannot be
+ * read) withholds, or for `git-sync-failed` redacts:
+ * failing closed costs a live refresh, failing open names a file.
+ *
+ * Nothing here changes what publishers emit; the rule only reads the event.
+ */
+
+import type { ChangeRequest, WorkflowEvent } from '@bevel-software/platform-shared';
+import { logger } from '../../shared/logging.js';
+import { workspaceIdForBranch } from '../../shared/workspace-id.js';
+import type { IAccessControl } from '../access/index.js';
+import { canReadWorkspacePath } from '../access-model/index.js';
+import { normalizeWorkspacePath } from '../kb-fs/index.js';
+import { fileIsReadable, isAuthor, maySeeChangeRequest, pathsOf } from './agent-tools/change-request-read-shape.js';
+import { readablePathsAt } from './read-on-branch.js';
+
+const log = logger('events');
+
+/** What a `git-sync-failed` says in place of git's words. */
+const GIT_SYNC_FAILED_REDACTED_REASON = 'The last push did not land.';
+
+/** The person behind a session, as the auth middleware named them. */
+export interface EventViewer {
+  userId: string;
+  email: string | undefined;
+}
+
+/**
+ * The verdicts the rule asks for. Each one is the question a route already
+ * answers for the thing the event names; `createEventAccess` wires them to
+ * those services, and tests to a fake.
+ */
+export interface EventAccess {
+  /** May `email` read the workspace-relative `wsPath` on `workspaceId` — the file routes' verdict. */
+  mayReadPath(workspaceId: string, email: string, wsPath: string): Promise<boolean>;
+  /** May `email` read the KB-repo-relative `repoPath` on `workspaceId`; `''` is the root. */
+  mayReadRepoPath(workspaceId: string, email: string, repoPath: string): Promise<boolean>;
+  /** Which of the KB-repo-relative `repoPaths` `email` may read on `targetBranch` — what a request into that branch is scoped by. */
+  readableAtTarget(targetBranch: string, email: string, repoPaths: string[]): Promise<Set<string>>;
+  /** Which of the KB-repo-relative `repoPaths` `email` may read at `origin/<base>` — the change-request tools' verdict, `readablePathsAt`. */
+  readableAtBase(base: string, email: string, repoPaths: string[]): Promise<Set<string>>;
+  /**
+   * Request `number` as the request list judges it — its target, author and
+   * changed files — or null when there is none. Read once per event: callers
+   * judging one event for many sessions share the read.
+   */
+  changeRequest(number: number): Promise<ChangeRequestFacts | null>;
+}
+
+/** What the visibility rule reads of a request. */
+export type ChangeRequestFacts = Pick<ChangeRequest, 'base' | 'authorId' | 'touchedNodeFiles'>;
+
+/**
+ * What the events route asks of the rule. The route depends on this, never on
+ * `EventDelivery`, so the rule can be substituted behind it.
+ */
+export interface IEventDelivery {
+  /** The event as `viewer` may receive it: itself, a redacted copy, or null. Never rejects. */
+  judge(event: WorkflowEvent, viewer: EventViewer): Promise<WorkflowEvent | null>;
+}
+
+/** The deployment's `EventAccess`: the access service the file routes use, read in the server's own checkouts. */
+export function createEventAccess(deps: {
+  accessControl: Pick<IAccessControl, 'canRead' | 'canReadBatch' | 'canReadBatchAtRef'>;
+  kbDirName: string;
+  /** `IWorkflowService.getChangeRequest`: the summary the request list judges, files included. */
+  getChangeRequest(number: number): Promise<ChangeRequestFacts | null>;
+  workspaces: {
+    /** Whether the server holds a checkout for `workspaceId` (the branch's own workspace). */
+    hasWorkspace(workspaceId: string): Promise<boolean>;
+    /**
+     * A workspace to read a published ref in: always for a request's base,
+     * and for an approval's target the server holds no checkout of. Every
+     * verdict at `origin/<branch>` is the same from any clone of the
+     * repository, so any existing one serves.
+     */
+    anyWorkspaceId(): Promise<string>;
+  };
+}): EventAccess {
+  /** A request's read, shared while it is in flight: one per event's fan-out, never a stale one after. */
+  const requestsInFlight = new Map<number, Promise<ChangeRequestFacts | null>>();
+  return {
+    // Normalised first, by the file routes' own normaliser: a path it refuses
+    // throws, and the rule withholds the event.
+    mayReadPath: async (workspaceId, email, wsPath) =>
+      canReadWorkspacePath(
+        (w, e, p) => deps.accessControl.canRead(w, e, p),
+        workspaceId,
+        email,
+        deps.kbDirName,
+        normalizeWorkspacePath(wsPath, deps.kbDirName),
+      ),
+    mayReadRepoPath: (workspaceId, email, repoPath) => deps.accessControl.canRead(workspaceId, email, repoPath),
+    readableAtTarget: async (targetBranch, email, repoPaths) => {
+      if (repoPaths.length === 0) return new Set();
+      const unique = [...new Set(repoPaths)];
+      // The branch's own checkout, when the server has one (the default
+      // branch always): the same disk read a file event on that branch gets.
+      const own = workspaceIdForBranch(targetBranch);
+      const verdicts = (await deps.workspaces.hasWorkspace(own))
+        ? await deps.accessControl.canReadBatch(own, email, unique)
+        : await deps.accessControl.canReadBatchAtRef(
+            await deps.workspaces.anyWorkspaceId(),
+            `origin/${targetBranch}`,
+            email,
+            unique,
+          );
+      // A ref that cannot be resolved answers null: nothing is granted on it.
+      return new Set(unique.filter((p) => verdicts?.get(p) === true));
+    },
+    // The request tools' own rule and reading, never the target's checkout: a
+    // grant there that is not yet published must not announce a request
+    // `get_change_request` answers as not found.
+    readableAtBase: async (base, email, repoPaths) =>
+      readablePathsAt(deps.accessControl, await deps.workspaces.anyWorkspaceId(), email, base, repoPaths),
+    changeRequest: (number) => {
+      const pending = requestsInFlight.get(number);
+      if (pending) return pending;
+      const read = deps.getChangeRequest(number).finally(() => requestsInFlight.delete(number));
+      requestsInFlight.set(number, read);
+      return read;
+    },
+  };
+}
+
+/**
+ * The event as `viewer` may receive it: the event itself, a redacted copy, or
+ * null for nothing at all.
+ */
+async function deliveryFor(
+  event: WorkflowEvent,
+  viewer: EventViewer,
+  access: EventAccess,
+): Promise<WorkflowEvent | null> {
+  const email = viewer.email;
+  try {
+    switch (event.kind) {
+      case 'approval-changed':
+        return email && (await access.readableAtTarget(event.targetBranch, email, [event.path])).has(event.path)
+          ? event
+          : null;
+      case 'change-request-opened':
+        return email && (await maySeeRequest(event.number, email, access)) ? event : null;
+      case 'git-sync-failed':
+        return email ? await gitSyncFailedFor(event, email, access) : redactGitSyncFailed(event, []);
+      case 'agent-tool-call':
+        return viewer.userId === event.forUserId ? event : null;
+    }
+    // Structural, not by kind: anything that names a path on a workspace is
+    // judged by the path, so a kind added later is covered without a line here.
+    const named = pathOnWorkspace(event);
+    if (named) return email && (await access.mayReadPath(named.workspaceId, email, named.path)) ? event : null;
+    return event;
+  } catch (err) {
+    log.warn(`delivery verdict failed for event id=${event.id} kind=${event.kind} user=${viewer.userId}; withheld`, { err });
+    return event.kind === 'git-sync-failed' ? redactGitSyncFailed(event, []) : null;
+  }
+}
+
+/**
+ * The request tools' visibility rule, over the request the list judges: its
+ * author sees it; anyone else sees it when one of its files is readable at
+ * the target, a move only when both its names are. No request, no file list
+ * (a diff that could not be computed): author only, as the tools answer it.
+ */
+async function maySeeRequest(number: number, email: string, access: EventAccess): Promise<boolean> {
+  const request = await access.changeRequest(number);
+  if (!request) return false;
+  if (isAuthor(request, email)) return true;
+  const files = request.touchedNodeFiles ?? [];
+  const readable = await access.readableAtBase(request.base, email, files.flatMap(pathsOf));
+  const readableFiles = files.filter((f) => fileIsReadable(f, (p) => readable.has(p))).length;
+  return maySeeChangeRequest({ readableFiles, isAuthor: false });
+}
+
+type GitSyncFailed = Extract<WorkflowEvent, { kind: 'git-sync-failed' }>;
+
+/**
+ * Every path the event names is judged: the root, which git's words are about,
+ * and each conflicted file, which a conflict's `reason` also quotes. Git's
+ * words go out only when every one of them is readable; otherwise the person
+ * keeps the conflicted files they may read and a fixed sentence.
+ */
+async function gitSyncFailedFor(event: GitSyncFailed, email: string, access: EventAccess): Promise<WorkflowEvent> {
+  const conflicted = event.conflictedPaths ?? [];
+  const [root, ...each] = await Promise.all([
+    access.mayReadRepoPath(event.workspaceId, email, ''),
+    ...conflicted.map((p) => access.mayReadRepoPath(event.workspaceId, email, p)),
+  ]);
+  const readable = conflicted.filter((_, i) => each[i]);
+  return root && readable.length === conflicted.length ? event : redactGitSyncFailed(event, readable);
+}
+
+function pathOnWorkspace(event: WorkflowEvent): { workspaceId: string; path: string } | null {
+  const e = event as { workspaceId?: unknown; path?: unknown };
+  return typeof e.workspaceId === 'string' && typeof e.path === 'string'
+    ? { workspaceId: e.workspaceId, path: e.path }
+    : null;
+}
+
+/**
+ * Same shape, so a client parses it as before: git's words are gone, and of
+ * the conflicted files only `readable` remain (none, the key absent).
+ */
+function redactGitSyncFailed(event: GitSyncFailed, readable: string[]): WorkflowEvent {
+  const redacted: GitSyncFailed = { ...event, reason: GIT_SYNC_FAILED_REDACTED_REASON };
+  if (readable.length > 0) redacted.conflictedPaths = readable;
+  else delete redacted.conflictedPaths;
+  return redacted;
+}
+
+/**
+ * The rule, shared per (event, person) while it is being judged: a person with
+ * three tabs open is judged once per event, not three times. A verdict is
+ * dropped the moment it settles and never reused, so a replay after a
+ * reconnect asks again, and a grant or a revocation since the event was first
+ * delivered decides what the replay carries.
+ */
+export class EventDelivery implements IEventDelivery {
+  private readonly inFlight = new Map<string, Promise<WorkflowEvent | null>>();
+
+  constructor(private readonly access: EventAccess) {}
+
+  judge(event: WorkflowEvent, viewer: EventViewer): Promise<WorkflowEvent | null> {
+    const key = `${event.id}\u0000${event.ts}\u0000${viewer.userId}`;
+    const pending = this.inFlight.get(key);
+    if (pending) return pending;
+    // `deliveryFor` never rejects: a verdict it cannot reach withholds the
+    // event, or for `git-sync-failed` redacts it.
+    const verdict = deliveryFor(event, viewer, this.access).finally(() => this.inFlight.delete(key));
+    this.inFlight.set(key, verdict);
+    return verdict;
+  }
+}