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

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

@@ -1,9 +1,13 @@
 import type { Router, RequestHandler } from 'express';
 import type { IToolRegistry, JsonSchema } from '../../tool-registry/tool.contract.js';
-import { ToolError, type ToolContext, type ToolHandler } from '../../tool-helpers/tool.contract.js';
+import { ToolError, hasHttpStatus, type ToolContext, type ToolHandler } from '../../tool-helpers/tool.contract.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 { 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';
@@ -150,6 +154,12 @@ const changeRequestSummarySchema: JsonSchema = {
       description: `The changed paths with their kind of change, cut to ${CHANGE_REQUEST_PATH_LIMIT}; \`include: ["all-paths"]\` lists them all.`,
     },
     totalFiles: { type: 'integer', description: 'How many files the request changes in total, cut or not.' },
+    notified: {
+      type: 'array',
+      items: { type: 'string' },
+      description:
+        'On the answer to an open only: the channels that reached the approvers ("email", say), as the deployment\'s listeners said; empty when nobody was told and the request waits to be found in the app.',
+    },
   },
   required: ['url', 'number', 'title', 'state', 'sourceBranch', 'targetBranch', 'approvals', 'mergeBlockedReasons', 'files', 'totalFiles'],
 };
@@ -176,6 +186,21 @@ export function registerWorkflowTools(
    * nor links a request it answers no for.
    */
   maySeeChangeRequest: (ctx: ToolContext, number: number) => Promise<boolean>,
+  /**
+   * The per-file read gate the history tools apply: a file's past is the
+   * file, so a history read takes the read the file itself takes — on the
+   * workspace for its own branch's history (`canRead`), at the commit
+   * another branch's content was served from (`canReadAtRef`, through
+   * `readableAtCommits`, the compare route's own rule), and in batches for
+   * the path lists `branch_status` shows.
+   */
+  accessControl: Pick<IAccessControl, 'canRead' | 'canReadAtRef' | 'canReadBatch' | 'canReadBatchAtRef'>,
+  /**
+   * The deployment's blocking read hook, told of every file content a history
+   * tool serves, as `read_file` tells it — a hook that refuses the read
+   * refuses the history too.
+   */
+  agentAccessGate: AgentAccessGate,
 ): void {
   const { kbDirName } = kb;
   const mount = (spec: {
@@ -748,4 +773,446 @@ export function registerWorkflowTools(
       };
     },
   });
+
+  // ── History and syncing ────────────────────────────────────────────────────
+  //
+  // What the app's History tab, compare view and "update from target" do,
+  // as tools: the agent never runs git itself. Each reads through the
+  // workflow service's gated methods and takes the per-file read the file
+  // itself takes.
+
+  /** The branch's workspace, made when it is not on disk yet, and its id. */
+  const workspaceOf = async (ctx: ToolContext, branch: string): Promise<string> => {
+    await ctx.workspaceService.getOrCreateForBranch(branch);
+    return workspaceIdForBranch(branch);
+  };
+
+  /**
+   * The per-file read gate on the workspace's own branch, and the
+   * deployment's read hook told of the read (as `read_file` tells it);
+   * answers the repository-relative path.
+   */
+  const requireRead = async (ctx: ToolContext, branch: string, workspaceId: string, path: string): Promise<string> => {
+    const rel = stripKbDir(path, kbDirName);
+    await notifyAgentRead(agentAccessGate, ctx, branch, path);
+    if (!(await accessControl.canRead(workspaceId, ctx.user.email, rel))) {
+      throw new ToolError(`You don't have permission to read "${rel}".`, 403, { kind: 'read-denied', path: rel });
+    }
+    return rel;
+  };
+
+  /**
+   * The per-file read gate for content served from ANOTHER branch — the
+   * compare route's rule: at every commit the branch resolves to (the one
+   * the service serves it from, and its other tip when the local head and
+   * the published tip differ), all of which must grant, asked by the
+   * service inside its reservation before anything is said about the path
+   * there.
+   */
+  const requireReadAtCommits = (ctx: ToolContext, workspaceId: string, rel: string, commits: readonly string[], branch: string): Promise<void> =>
+    assertReadableAtCommits(accessControl, workspaceId, ctx.user.email, rel, commits, branch);
+
+  /** Which of `paths` the caller may read at `origin/<base>` — the change-request reads' rule, `readablePathsAt`. */
+  const readableAt = (ctx: ToolContext, workspaceId: string, base: string, paths: string[]): Promise<Set<string>> =>
+    readablePathsAt(accessControl, workspaceId, ctx.user.email, base, paths);
+
+
+  mount({
+    name: 'list_file_changes',
+    description:
+      'The history of one file on `branch`: its commits, newest first — who made each, when, and its ' +
+      'subject — as the app\'s History tab shows them. `limit` caps the list (default 20, at most 100). ' +
+      'Read a version with `read_file_at` and its diff with `compare_file`. Takes the read the file itself ' +
+      'takes; a folder has no history of its own (ask per file).',
+    inputs: {
+      type: 'object',
+      properties: {
+        path: { type: 'string', minLength: 1, description: 'The file, workspace-relative (as `read_file` takes it).' },
+        limit: { type: 'integer', minimum: 1, maximum: 100, description: 'How many commits at most (default 20).' },
+        sessionId: SESSION_ID_INPUT,
+      },
+      required: ['path'],
+      additionalProperties: false,
+    },
+    outputs: {
+      type: 'object',
+      properties: {
+        path: { type: 'string', description: 'The file, repository-relative.' },
+        changes: { type: 'array', items: commitSchema, description: 'Newest first.' },
+      },
+      required: ['path', 'changes'],
+    },
+    write: false,
+    handler: async (args, ctx: ToolContext) => {
+      const branch = args.branch as string;
+      const path = args.path;
+      if (typeof path !== 'string' || path.length === 0) throw new ToolError('`path` is required.', 400);
+      const workspaceId = await workspaceOf(ctx, branch);
+      const rel = await requireRead(ctx, branch, workspaceId, path);
+      const limit = typeof args.limit === 'number' ? args.limit : undefined;
+      const changes = await ctx.workflowService.listChangesForFile(workspaceId, path, limit);
+      return { path: rel, changes };
+    },
+  });
+
+  mount({
+    name: 'read_file_at',
+    description:
+      'One file as it was at a point in history: `at` is a commit (from `list_file_changes`, on `branch`\'s ' +
+      'own history) or the name of another branch (its published tip). Answers `content` (null when the ' +
+      'file was not there) and `sha`, the commit it was read at; for a commit, also `before`, the file ' +
+      'just before that commit. To put an earlier version back, write it with `write_file`. Takes the read ' +
+      'the file takes at that point.',
+    inputs: {
+      type: 'object',
+      properties: {
+        path: { type: 'string', minLength: 1, description: 'The file, workspace-relative.' },
+        at: { type: 'string', minLength: 1, description: 'A commit sha, or a branch name.' },
+        sessionId: SESSION_ID_INPUT,
+      },
+      required: ['path', 'at'],
+      additionalProperties: false,
+    },
+    outputs: {
+      type: 'object',
+      properties: {
+        path: { type: 'string', description: 'The file, repository-relative.' },
+        at: { type: 'string', description: 'What was asked for.' },
+        kind: { type: 'string', enum: ['commit', 'branch'] },
+        sha: { type: 'string', description: 'The commit the content was read at.' },
+        content: { type: ['string', 'null'], description: 'The file at that commit; null when it was not there.' },
+        before: { type: ['string', 'null'], description: 'For a commit: the file just before it; null when it was not there (or the commit is the first).' },
+      },
+      required: ['path', 'at', 'kind', 'sha', 'content'],
+    },
+    write: false,
+    handler: async (args, ctx: ToolContext) => {
+      const branch = args.branch as string;
+      const path = args.path;
+      const at = args.at;
+      if (typeof path !== 'string' || path.length === 0) throw new ToolError('`path` is required.', 400);
+      if (typeof at !== 'string' || at.length === 0) throw new ToolError('`at` is required: a commit sha or a branch name.', 400);
+      const workspaceId = await workspaceOf(ctx, branch);
+      // The hook and the workspace gate first, whichever point in history is
+      // read: the file is this workspace's file.
+      const rel = await requireRead(ctx, branch, workspaceId, path);
+      if (isCommitSha(at)) {
+        const { baseline, current } = await ctx.workflowService.fileAtChange(workspaceId, path, at);
+        return { path: rel, at, kind: 'commit', sha: at, content: current, before: baseline };
+      }
+      // Read at the branch's published tip, authorized at that very commit
+      // inside the read — before anything is said about the path there,
+      // the folder refusal included: the ref is a name a fetch may move
+      // between a verdict and a read; the commit is not.
+      const read = await ctx.workflowService.fileAtBranch(workspaceId, path, at, (commits) => requireReadAtCommits(ctx, workspaceId, rel, commits, at));
+      return { path: rel, at, kind: 'branch', sha: read.sha, content: read.content };
+    },
+  });
+
+  mount({
+    name: 'compare_file',
+    description:
+      'The unified diff of one file: between two branches (`from`, `to`; either may be `branch` itself), ' +
+      'or of one commit on `branch` (`at`: what that commit changed in the file). Empty when identical. ' +
+      'Takes the read the file takes on each side.',
+    inputs: {
+      type: 'object',
+      properties: {
+        path: { type: 'string', minLength: 1, description: 'The file, workspace-relative.' },
+        from: { type: 'string', minLength: 1, description: 'A branch: the diff\'s left side.' },
+        to: { type: 'string', minLength: 1, description: 'A branch: the diff\'s right side.' },
+        at: { type: 'string', minLength: 1, description: 'A commit sha on `branch`: the diff that commit made in the file.' },
+        sessionId: SESSION_ID_INPUT,
+      },
+      required: ['path'],
+      additionalProperties: false,
+    },
+    outputs: {
+      type: 'object',
+      properties: {
+        path: { type: 'string', description: 'The file, repository-relative.' },
+        diff: { type: 'string', description: 'A unified diff; empty when the two sides are identical.' },
+      },
+      required: ['path', 'diff'],
+    },
+    write: false,
+    handler: async (args, ctx: ToolContext) => {
+      const branch = args.branch as string;
+      const path = args.path;
+      if (typeof path !== 'string' || path.length === 0) throw new ToolError('`path` is required.', 400);
+      const workspaceId = await workspaceOf(ctx, branch);
+      // As the compare route: the workspace's own gate on the path (the
+      // checked-out side can be served from the working tree), then each
+      // compared side at the commit it was served from.
+      const rel = await requireRead(ctx, branch, workspaceId, path);
+      if (typeof args.at === 'string' && args.at.length > 0) {
+        if (!isCommitSha(args.at)) throw new ToolError('`at` must be a full commit sha.', 400);
+        return { path: rel, diff: await ctx.workflowService.showFileAtChange(workspaceId, path, args.at) };
+      }
+      const from = args.from;
+      const to = args.to;
+      if (typeof from !== 'string' || from.length === 0 || typeof to !== 'string' || to.length === 0) {
+        throw new ToolError('Give `from` and `to` (two branches), or `at` (one commit).', 400);
+      }
+      const compared = await ctx.workflowService.compareFile(workspaceId, path, from, to, async (sides) => {
+        await requireReadAtCommits(ctx, workspaceId, rel, sides.from, from);
+        await requireReadAtCommits(ctx, workspaceId, rel, sides.to, to);
+      });
+      return { path: rel, diff: compared.diff };
+    },
+  });
+
+  mount({
+    name: 'branch_status',
+    description:
+      'Where `branch` stands, before proposing or syncing a draft. Answers whether it is on the shared ' +
+      'repository, how far ahead of and behind its upstream it is, whether the shared branch has commits this ' +
+      'workspace lacks (`behindRemote`: `update_branch` brings them in), the files written but not committed ' +
+      'yet, the protected branch it was forked from (`forkBase`), and `changedPaths`: what it changes against ' +
+      '`base` (default: the fork base) — the files a change request into it would carry.',
+    inputs: {
+      type: 'object',
+      properties: {
+        base: { type: 'string', minLength: 1, description: 'The branch to compare against (default: the fork base).' },
+        sessionId: SESSION_ID_INPUT,
+      },
+      additionalProperties: false,
+    },
+    outputs: {
+      type: 'object',
+      properties: {
+        branch: { type: 'string' },
+        isProtected: { type: 'boolean' },
+        hasRemote: { type: 'boolean', description: 'True when the shared repository has the branch.' },
+        ahead: { type: ['integer', 'null'], description: 'Commits ahead of the upstream (or the fork base); null when unresolved.' },
+        behind: { type: ['integer', 'null'], description: 'Commits behind; null when unresolved.' },
+        behindRemote: { type: 'boolean', description: 'The shared branch has commits this workspace has not merged yet.' },
+        uncommittedPaths: { type: 'array', items: { type: 'string' }, description: 'Written but not committed yet (saves still landing).' },
+        forkBase: { type: ['string', 'null'], description: 'The protected branch this one was forked from; null when none can be reached.' },
+        base: { type: ['string', 'null'], description: 'What `changedPaths` is against.' },
+        changedPaths: { type: 'array', items: { type: 'string' }, description: 'Repository-relative; rename-aware; only the paths you may read. Empty when `base` is null.' },
+        withheldPaths: { type: 'integer', description: 'How many changed or uncommitted paths were left out because you may not read them.' },
+      },
+      required: ['branch', 'isProtected', 'hasRemote', 'ahead', 'behind', 'behindRemote', 'uncommittedPaths', 'forkBase', 'base', 'changedPaths', 'withheldPaths'],
+    },
+    write: false,
+    handler: async (args, ctx: ToolContext) => {
+      const branch = args.branch as string;
+      const workspaceId = await workspaceOf(ctx, branch);
+      // Each read below takes the workspace's reservation on its own: this
+      // is a REPORT of independent facts, not a range measured across steps,
+      // 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([
+        ctx.workflowService.branchStatus(workspaceId),
+        ctx.workflowService.listBranches(workspaceId),
+        ctx.workflowService.listPendingChangePaths(workspaceId),
+        ctx.workflowService.resolveForkBase(workspaceId, branch),
+      ]);
+      const info = branches.find((b) => b.name === branch);
+      const base = typeof args.base === 'string' && args.base.length > 0 ? args.base : forkBase;
+      // A path's name is information too: the changed paths are shown as the
+      // change-request reads show them (readable at `origin/<base>`), the
+      // uncommitted ones as the workspace's own listing would.
+      const changedAll =
+        base && base !== branch ? await ctx.workflowService.changedPathsBetweenBranches(workspaceId, base, branch) : [];
+      const readableChanged = base ? await readableAt(ctx, workspaceId, base, changedAll) : new Set<string>();
+      const changedPaths = changedAll.filter((p) => readableChanged.has(p));
+      const pendingRel = pending.map((p) => stripKbDir(p, kbDirName));
+      const pendingVerdicts = pendingRel.length > 0 ? await accessControl.canReadBatch(workspaceId, ctx.user.email, pendingRel) : new Map<string, boolean>();
+      const uncommittedPaths = pendingRel.filter((p) => pendingVerdicts.get(p) === true);
+      return {
+        branch,
+        isProtected: info?.isProtected ?? kb.protectedBranches.has(branch),
+        hasRemote: info?.hasRemote ?? status.hasUpstream,
+        ahead: info?.ahead ?? null,
+        behind: info?.behind ?? null,
+        behindRemote: status.unmergedFromUpstream,
+        uncommittedPaths,
+        forkBase,
+        base: base && base !== branch ? base : null,
+        changedPaths,
+        withheldPaths: changedAll.length - changedPaths.length + (pendingRel.length - uncommittedPaths.length),
+      };
+    },
+  });
+
+  mount({
+    name: 'update_branch',
+    description:
+      'Bring another branch into `branch` as a merge commit by you, and publish it: `from` (a draft\'s ' +
+      'target, to refresh the draft), or left out, the branch\'s own shared state when it moved while this ' +
+      'workspace held commits (`branch_status` says `behindRemote`). Never a protected branch. CONFLICTS: ' +
+      'the first call answers `conflicts` naming every conflicted path with the file at the merge base, on ' +
+      'each side (`ours` = `branch`, `theirs` = `from`) and the working copy with git\'s markers, and leaves ' +
+      'the branch as it was. Decide each file (keep both sides\' information unless one is clearly stale; ' +
+      '`list_file_changes` shows intent), then call again with `resolutions`, one per conflicted path: ' +
+      '`content` (the resolved text) or `choose` (`ours`, `theirs`, `delete`). Only conflicted paths are ' +
+      'written here; other edits go through the file tools. Answers `merged`, `nothing-to-merge`, ' +
+      '`conflicts` again (something changed meanwhile), or `pending-commits` (writes still landing: retry).',
+    inputs: {
+      type: 'object',
+      properties: {
+        from: { type: 'string', minLength: 1, description: 'The branch to bring in (default: this branch\'s own shared state).' },
+        sessionId: SESSION_ID_INPUT,
+        resolutions: {
+          type: 'array',
+          description: 'One per conflicted path, from a previous `conflicts` answer.',
+          items: {
+            type: 'object',
+            properties: {
+              path: { type: 'string', minLength: 1, description: 'The conflicted path, as the answer named it.' },
+              content: { type: 'string', description: 'The resolved text of the file.' },
+              choose: { type: 'string', enum: ['ours', 'theirs', 'delete'], description: 'Keep one side whole, or drop the file.' },
+            },
+            required: ['path'],
+            additionalProperties: false,
+          },
+        },
+      },
+      additionalProperties: false,
+    },
+    outputs: {
+      type: 'object',
+      properties: {
+        kind: { type: 'string', enum: ['merged', 'nothing-to-merge', 'conflicts', 'pending-commits'] },
+        from: { type: 'string', description: 'The branch brought in.' },
+        sha: { type: 'string', description: '`merged`: the merge commit, now the tip of `branch`, published; `nothing-to-merge`: the unchanged tip.' },
+        resolvedPaths: { type: 'array', items: { type: 'string' }, description: '`merged`: the conflicts the resolutions settled.' },
+        mergeBase: { type: ['string', 'null'], description: '`conflicts`: the common ancestor; null when the histories are unrelated.' },
+        ours: { type: 'string', description: '`conflicts`: the tip of `branch`.' },
+        theirs: { type: 'string', description: '`conflicts`: the tip of `from`.' },
+        files: {
+          type: 'array',
+          description:
+            '`conflicts`: every conflicted path you may read, with the file at the base, on each side, and the marked-up ' +
+            'working copy. A side is null when that side has no file — or when `truncated` names it (too large or not ' +
+            'text): then read `ours` with `read_file`, `theirs` with `read_file_at` at `from`, `base` with `read_file_at` ' +
+            'at `mergeBase`.',
+          items: {
+            type: 'object',
+            properties: {
+              path: { type: 'string' },
+              base: { type: ['string', 'null'] },
+              ours: { type: ['string', 'null'] },
+              theirs: { type: ['string', 'null'] },
+              merged: { type: ['string', 'null'] },
+              truncated: { type: 'array', items: { type: 'string', enum: ['base', 'ours', 'theirs', 'merged'] } },
+            },
+            required: ['path', 'base', 'ours', 'theirs', 'merged'],
+          },
+        },
+        unresolved: { type: 'array', items: { type: 'string' }, description: '`conflicts`: the paths you may read that no resolution covered.' },
+        withheldConflicts: {
+          type: 'integer',
+          description:
+            '`conflicts`: how many conflicted files were left out because you may not read them on one of the two branches. ' +
+            'They are not yours to settle: ask a person who can read them to update the draft in the app.',
+        },
+        branch: { type: 'string', description: '`pending-commits`: the branch whose writes are not committed yet.' },
+        pending: { type: 'integer', description: '`pending-commits`: how many.' },
+        needsAttention: { type: 'string', description: '`pending-commits`: a queued commit failed; the worker\'s message. Tell the user.' },
+        message: { type: 'string', description: '`pending-commits`: what to do next.' },
+      },
+      required: ['kind'],
+    },
+    write: true,
+    handler: async (args, ctx: ToolContext) => {
+      const branch = args.branch as string;
+      const from = args.from;
+      if (from !== undefined && (typeof from !== 'string' || from.length === 0)) {
+        throw new ToolError('`from` must be a branch name.', 400);
+      }
+      let resolutions: { path: string; content?: string; choose?: 'ours' | 'theirs' | 'delete' }[] | undefined;
+      if (args.resolutions !== undefined) {
+        if (!Array.isArray(args.resolutions)) throw new ToolError('`resolutions` must be a list.', 400);
+        resolutions = args.resolutions.map((r: unknown, i: number) => {
+          const entry = r as Record<string, unknown>;
+          if (!entry || typeof entry.path !== 'string' || entry.path.length === 0) {
+            throw new ToolError(`resolutions[${i}]: \`path\` is required.`, 400);
+          }
+          const out: { path: string; content?: string; choose?: 'ours' | 'theirs' | 'delete' } = { path: entry.path };
+          if (entry.content !== undefined) {
+            if (typeof entry.content !== 'string') throw new ToolError(`resolutions[${i}]: \`content\` must be text.`, 400);
+            out.content = entry.content;
+          }
+          if (entry.choose !== undefined) {
+            if (entry.choose !== 'ours' && entry.choose !== 'theirs' && entry.choose !== 'delete') {
+              throw new ToolError(`resolutions[${i}]: \`choose\` is \`ours\`, \`theirs\` or \`delete\`.`, 400);
+            }
+            out.choose = entry.choose;
+          }
+          return out;
+        });
+      }
+      const workspaceId = await workspaceOf(ctx, branch);
+      /**
+       * Whether the caller may read `rel` on both sides of this merge — at
+       * the two COMMITS the answer says the merge was of, which is what its
+       * bytes are from, never at a branch ref that may have moved since the
+       * reservation was released — with the deployment's read hook told of
+       * the read, as every history read tells it: a hook that refuses makes
+       * the file one the caller may not read; a hook that fails is not an
+       * answer and propagates.
+       */
+      const mayReadBothSides = async (rel: string, at: { ours: string; theirs: string }): Promise<boolean> => {
+        try {
+          await notifyAgentRead(agentAccessGate, ctx, branch, `${kbDirName}/${rel}`);
+        } catch (err) {
+          // A hook's own refusal carries a status; anything else is a failure of the hook, not an answer.
+          if (hasHttpStatus(err)) return false;
+          throw err;
+        }
+        return readableAtCommits(accessControl, workspaceId, ctx.user.email, rel, [at.ours, at.theirs]);
+      };
+      // A resolution reads a file on both branches and writes it on the
+      // draft, so the deployment's hooks are asked as they are for any read
+      // and any write. The access model's own verdicts — may the caller read
+      // the file on both branches, may they change it on the draft — are the
+      // service's, asked inside the merge against the source commit as
+      // fetched (`updateBranch`), so a rule that changed with the source
+      // cannot be outrun by a check made before it was fetched.
+      for (const r of resolutions ?? []) {
+        const wsPath = `${kbDirName}/${stripKbDir(r.path, kbDirName)}`;
+        try {
+          await notifyAgentRead(agentAccessGate, ctx, branch, wsPath);
+        } catch (err) {
+          if (hasHttpStatus(err)) {
+            throw new ToolError(`You may not read "${stripKbDir(r.path, kbDirName)}" here, so it is not yours to settle.`, 403, {
+              kind: 'read-denied',
+              path: stripKbDir(r.path, kbDirName),
+            });
+          }
+          throw err;
+        }
+        await assertAgentWriteAllowed(agentAccessGate, ctx, branch, wsPath);
+      }
+      // A resolution's content lands on the draft by the merge, not by the
+      // file tools' filesystem: it takes the same pre-disk gate that
+      // filesystem runs (`roles.yaml` must parse, no new role, no unknown
+      // group), handed to the service to ask before the merge.
+      const outcome =
+        resolutions !== undefined
+          ? await ctx.workflowService.updateBranch(workspaceId, ctx.user, {
+              ...(from !== undefined ? { from } : {}),
+              resolutions,
+              validateWrite: await ctx.getWriteValidator(branch),
+            })
+          : await ctx.workflowService.updateBranch(workspaceId, ctx.user, from !== undefined ? { from } : {});
+      if (outcome.kind !== 'conflicts') return outcome;
+      // A conflict answer carries the file on both branches, and a path's
+      // name is information too: a file the caller may not read on both is
+      // left out of `files` and `unresolved` alike and only counted.
+      const files = [];
+      for (const f of outcome.files) if (await mayReadBothSides(f.path, outcome)) files.push(f);
+      const shown = new Set(files.map((f) => f.path));
+      return {
+        ...outcome,
+        files,
+        unresolved: outcome.unresolved.filter((p) => shown.has(p)),
+        withheldConflicts: outcome.files.length - files.length,
+      };
+    },
+  });
 }

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

@@ -0,0 +1,96 @@
+import type { AuthUser } from '@bevel-software/platform-shared';
+import { logger } from '../../shared/logging.js';
+import { ListenerSeam, type NotifyingListener } from '../../shared/listener-seam.js';
+
+const log = logger('cr');
+
+/** Somebody a listener can write to: an account's id, address and name. */
+export type ChangeRequestPerson = Pick<AuthUser, 'id' | 'email' | 'name'>;
+
+/**
+ * A change request was OPENED — by a person in the app or by an agent through
+ * its tool, which take the one road (`WorkflowService.openChangeRequest`).
+ * Raised once per request, after its row exists and its source branch was
+ * pushed, or the push was refused: the request exists either way, and the
+ * branch's next push carries the commits. Never raised for a request that is
+ * reopened after a failed branch deletion — it was opened once already — nor
+ * for one updated from its target.
+ */
+export interface ChangeRequestOpenedEvent {
+  number: number;
+  title: string;
+  sourceBranch: string;
+  targetBranch: string;
+  /** Who opened it: the person, or the person the agent acted for. */
+  openedBy: ChangeRequestPerson;
+  /**
+   * The distinct people eligible to approve some changed path, as accounts —
+   * the eligibility the request's `## Affected owners` block lists, 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
+   * will not tell people of their own request reads `openedBy`.
+   */
+  approvers: ChangeRequestPerson[];
+  /**
+   * Eligible approvers the event cannot hand over as accounts, each counted
+   * once: a person the access model names who has no account yet, and the
+   * built-in `everyone` (anyone signed in may approve, and nobody can be
+   * listed for that). Zero when every approver is in `approvers`.
+   */
+  unresolvedApprovers: number;
+  /**
+   * The request's address, when the deployment has a public address
+   * configured (`PUBLIC_FRONTEND_URL`). Absent otherwise: a listener that
+   * knows where the app is builds the link to `/change-requests/<number>`
+   * itself.
+   */
+  url?: string;
+  /**
+   * Whether the source branch's push was refused by the host as the request
+   * was opened: the request exists, but its commits reach the host only when
+   * an agent has reconciled the branch and pushed again, which is seconds
+   * usually and may fail. A listener decides what that is worth — a mail
+   * worded for it, a delay, or none — because a reviewer sent to the
+   * request before then opens one whose changes are not there yet. False
+   * when the push landed.
+   */
+  pushPending: boolean;
+}
+
+/**
+ * A listener answers how it reached the approvers — a non-empty channel name,
+ * `'email'` say — or null when it did not; the rule is {@link NotifyingListener}'s:
+ * awaited, a throw logged and counted as null, never failing the open.
+ */
+export type ChangeRequestOpenedHook = NotifyingListener<ChangeRequestOpenedEvent>;
+
+/**
+ * Core's seam for "a change request was opened": a deployment (the cloud
+ * with its mail, an enterprise overlay) registers how to tell the reviewers,
+ * and core says in its answer whether somebody did. Core registers nothing,
+ * so a core-only deployment notifies nobody and the request waits to be
+ * found in the app, as before.
+ */
+export interface IChangeRequestHooks {
+  onChangeRequestOpened(hook: ChangeRequestOpenedHook): void;
+  /** Run every listener in registration order; the channels that reached the approvers, in that order. */
+  runChangeRequestOpened(event: ChangeRequestOpenedEvent): Promise<string[]>;
+}
+
+export class ChangeRequestHooks implements IChangeRequestHooks {
+  // The request exists whether or not the reviewers were told: the opener's
+  // answer says they were not, and the request is found in the app as before.
+  private readonly opened = new ListenerSeam<ChangeRequestOpenedEvent>(
+    log,
+    'a change-request-opened listener failed; the reviewers were not notified by it:',
+  );
+
+  onChangeRequestOpened(hook: ChangeRequestOpenedHook): void {
+    this.opened.add(hook);
+  }
+
+  runChangeRequestOpened(event: ChangeRequestOpenedEvent): Promise<string[]> {
+    return this.opened.run(event);
+  }
+}