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

package/src/modules/workflow/__tests__/workflow.routes.open-change-request.test.ts

@@ -0,0 +1,79 @@
+import type { Server } from 'node:http';
+import type { AddressInfo } from 'node:net';
+import express from 'express';
+import { describe, it, expect, afterEach, vi } from 'vitest';
+import type { AuthUser, IWorkflowService } from '@bevel-software/platform-shared';
+import type { IAccessControl } from '../../access/access-control.interface.js';
+import type { AuthService } from '../../auth/auth.service.js';
+import type { WorkspaceService } from '../../workspace/workspace.service.js';
+import { WorkflowEventBus } from '../event-bus.js';
+import { createWorkflowRoutes } from '../workflow.routes.js';
+
+/**
+ * `POST /api/workflow/change-requests` answers the opened request as the
+ * service hands it over, `notified` included: the channels the deployment's
+ * change-request listeners said reached the approvers, so the dialog can say
+ * "the reviewers were emailed" — or hand over the link when nobody was.
+ */
+
+const ALICE: AuthUser = { id: '11111111-1111-4111-8111-111111111111', email: 'alice@example.com', name: 'Alice' };
+
+async function serve(workflow: Partial<IWorkflowService>): Promise<{ server: Server; baseUrl: string }> {
+  const authService = { getUserById: vi.fn(async () => ALICE) } as unknown as AuthService;
+  const workspaceService = {
+    getOrCreateForBranch: vi.fn(async (branch: string) => ({ id: encodeURIComponent(branch) })),
+  } as unknown as WorkspaceService;
+  const app = express();
+  app.use(express.json());
+  app.use('/api', (req, _res, next) => {
+    (req as unknown as { userId: string }).userId = ALICE.id;
+    next();
+  });
+  app.use(
+    '/api',
+    createWorkflowRoutes(
+      workflow as IWorkflowService,
+      workspaceService,
+      authService,
+      new WorkflowEventBus(),
+      {} as unknown as IAccessControl,
+      'knowledge-base',
+    ),
+  );
+  const server = await new Promise<Server>((resolve) => {
+    const s = app.listen(0, () => resolve(s));
+  });
+  return { server, baseUrl: `http://127.0.0.1:${(server.address() as AddressInfo).port}` };
+}
+
+describe('POST /workflow/change-requests answers who was notified', () => {
+  let server: Server | undefined;
+  afterEach(async () => {
+    if (server) await new Promise<void>((resolve, reject) => server!.close((e) => (e ? reject(e) : resolve())));
+    server = undefined;
+  });
+
+  it.each([
+    ['the channels that reached the approvers', ['email']],
+    ['nobody, truthfully', []],
+  ])('carries `notified`: %s', async (_what, notified) => {
+    const openChangeRequest = vi.fn(async () => ({ number: 12, branch: 'alice/deal', base: 'main', notified }) as never);
+    let baseUrl: string;
+    ({ server, baseUrl } = await serve({ openChangeRequest }));
+
+    const res = await fetch(`${baseUrl}/api/workflow/change-requests`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ sourceBranch: 'alice/deal', targetBranch: 'main', title: 'Deal' }),
+    });
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ number: 12, branch: 'alice/deal', base: 'main', notified });
+    // The open runs in the SOURCE branch's workspace, by the caller.
+    expect(openChangeRequest).toHaveBeenCalledTimes(1);
+    expect(openChangeRequest).toHaveBeenCalledWith(
+      encodeURIComponent('alice/deal'),
+      ALICE,
+      { sourceBranch: 'alice/deal', targetBranch: 'main', title: 'Deal', description: undefined },
+    );
+  });
+});

package/src/modules/workflow/__tests__/workflow.service.delete-branch.test.ts

@@ -115,6 +115,7 @@ interface Harness {
   deleted: string[];
   /** What the service announced to connected tabs. */
   emitted: { kind: string; number?: number }[];
+  changeRequestHooks: { onChangeRequestOpened: ReturnType<typeof vi.fn>; runChangeRequestOpened: ReturnType<typeof vi.fn> };
   hasAnyActive: MockInstance<FileLockService['hasAnyActive']>;
 }
 
@@ -142,6 +143,7 @@ function harness(opts: {
 }): Harness {
   const deleted: string[] = [];
   const emitted: { kind: string; number?: number }[] = [];
+  const changeRequestHooks = { onChangeRequestOpened: vi.fn(), runChangeRequestOpened: vi.fn(async () => []) };
   const rows = opts.rows ?? [];
   const branches = { ...(opts.branches ?? {}) };
   const git = {
@@ -212,8 +214,11 @@ function harness(opts: {
     testKbContext(),
     openChangeGate(),
     { emit: (e: { kind: string; number?: number }) => void emitted.push(e) } as unknown as WorkflowEventBus,
+    undefined,
+    undefined,
+    changeRequestHooks,
   );
-  return { svc, git, fetch, deleted, emitted, hasAnyActive };
+  return { svc, git, fetch, deleted, emitted, hasAnyActive, changeRequestHooks };
 }
 
 const merged = (number: number, source: string, sha: string | null): CrRow => ({
@@ -557,6 +562,9 @@ describe('a change request that proposes nothing never blocks a deletion', () =>
       expect.objectContaining({ number: 21, source: 'ali/sync', target: DEFAULT }),
       expect.objectContaining({ number: 22, source: 'ali/feature', target: 'ali/sync' }),
     ]);
+    // A reopened request was opened once already: the deployment's
+    // change-request-opened listeners are not told again.
+    expect(h.changeRequestHooks.runChangeRequestOpened).not.toHaveBeenCalled();
     // The app's path, the same.
     reopens.length = 0;
     await expect(h.svc.deleteBranch(workspaceIdForBranch(DEFAULT), 'ali/sync', ADMIN)).rejects.toThrow(/stale info/);

package/src/modules/workflow/__tests__/workflow.service.facade.test.ts

@@ -1,4 +1,8 @@
-import { describe, it, expect, vi } from 'vitest';
+import { afterAll, beforeAll, describe, it, expect, vi } from 'vitest';
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
 import { testKbContext } from '../../../__tests__/kb-context.js';
 import type {
   AuthUser,
@@ -15,10 +19,13 @@ import { PendingCommitsService, type PendingCommit } from '../pending-commits.se
 import { PendingCommitsWorker } from '../pending-commits.worker.js';
 import { HttpCommunicationProtocol } from '@utcp/http';
 import { WorkflowService } from '../workflow.service.js';
+import type { ChangeRequestOpenedEvent, IChangeRequestHooks } from '../change-request-hooks.js';
 import {
+  ChangeRequestConflictsError,
   PullRebaseConflictError,
   PushNeedsAgentResolutionError,
   WorkflowDomainError,
+  WorkflowValidationError,
 } from '../../../shared/domain-errors.js';
 import type { WorkflowEventBus } from '../event-bus.js';
 import { DEFAULT_BRANCH } from '@bevel-software/platform-shared';
@@ -225,6 +232,8 @@ function makePrs(): PullRequestService {
     getPrDetail: vi.fn(),
     invalidateDetailCache: vi.fn(),
     setDetailEnricher: vi.fn(),
+    // No public address configured: the in-app path, with its note.
+    linkFor: vi.fn((number: number) => ({ url: `/change-requests/${number}`, urlNote: 'Set PUBLIC_FRONTEND_URL to get absolute links.' })),
   } as unknown as PullRequestService;
 }
 
@@ -1640,6 +1649,254 @@ describe('WorkflowService.openChangeRequest — when the repository host refuses
   });
 });
 
+/**
+ * Opening a request tells the deployment's change-request listeners — once,
+ * here, whether a person or an agent opened it — and answers `notified`: the
+ * channels the listeners said reached the approvers. The approvers are the
+ * people the `## Affected owners` block lists, resolved to accounts and
+ * handed over once each; who could not be is counted.
+ */
+describe('WorkflowService.openChangeRequest — tells the change-request listeners', () => {
+  const INPUT = { sourceBranch: 'ali/x', targetBranch: 'main', title: '  Tidy the glossary  ' };
+  const PATHS = ['KnowledgeBase/Sales/Deal.md', 'KnowledgeBase/Legal/Terms.md'];
+  const ACCOUNTS: Record<string, { id: string; email: string; name: string }> = {
+    'dana@acme.test': { id: 'u-dana', email: 'dana@acme.test', name: 'Dana' },
+    'lena@acme.test': { id: 'u-lena', email: 'Lena@acme.test', name: 'Lena' },
+  };
+
+  function eligibility(
+    perPath: Record<string, { roles?: string[]; emails: string[] }>,
+  ): Map<string, { roles: string[]; users: { name: string; email: string }[]; emails: Set<string> }> {
+    const out = new Map<string, { roles: string[]; users: { name: string; email: string }[]; emails: Set<string> }>();
+    for (const [p, { roles = [], emails }] of Object.entries(perPath)) {
+      out.set(p, { roles, users: emails.map((email) => ({ name: '', email })), emails: new Set(emails) });
+    }
+    return out;
+  }
+
+  // A real repository, so the changed paths come from the `git diff` the
+  // service runs in production and not from a replaced helper: `main` is the
+  // base and the ref `origin/main` the diff is taken against; `ali/x` adds
+  // PATHS. The checkout sits under the knowledge-base folder name the test
+  // context gives, where the service looks for it.
+  let workspace: string;
+  beforeAll(() => {
+    workspace = fs.mkdtempSync(path.join(os.tmpdir(), 'hexis-open-tells-'));
+    const repo = path.join(workspace, testKbContext().kbDirName);
+    fs.mkdirSync(repo);
+    const git = (...args: string[]) =>
+      execFileSync('git', ['-c', 'user.name=t', '-c', 'user.email=t@t.test', '-c', 'commit.gpgsign=false', ...args], { cwd: repo, stdio: 'pipe' });
+    git('init', '-q', '-b', 'main');
+    git('commit', '-q', '--allow-empty', '-m', 'base');
+    git('update-ref', 'refs/remotes/origin/main', 'HEAD');
+    git('checkout', '-q', '-b', 'ali/x');
+    for (const p of PATHS) {
+      fs.mkdirSync(path.dirname(path.join(repo, p)), { recursive: true });
+      fs.writeFileSync(path.join(repo, p), `# ${p}\n`);
+    }
+    git('add', '-A');
+    git('commit', '-q', '-m', 'the change');
+  });
+  afterAll(() => {
+    fs.rmSync(workspace, { recursive: true, force: true });
+  });
+
+  function makeNotifyHarness(opts: {
+    eligible?: ReturnType<typeof eligibility> | null;
+    push?: ReturnType<typeof vi.fn>;
+    merge?: ReturnType<typeof vi.fn>;
+    detail?: ReturnType<typeof vi.fn>;
+    accounts?: { findActiveAccountsByEmail: ReturnType<typeof vi.fn> } | undefined;
+    link?: { url: string; urlNote?: string };
+  } = {}) {
+    const git = Object.assign(makeGit(), {
+      mergeFromOrigin: opts.merge ?? vi.fn().mockResolvedValue({ kind: 'clean', alreadyUpToDate: false }),
+      push: opts.push ?? vi.fn().mockResolvedValue(undefined),
+      pull: vi.fn().mockResolvedValue({ treeChanged: false }),
+    }) as unknown as GitService;
+    const prs = makePrs();
+    (prs.listOpenPrs as ReturnType<typeof vi.fn>).mockResolvedValue([]);
+    if (opts.detail) prs.getPrDetail = opts.detail as unknown as PullRequestService['getPrDetail'];
+    else (prs.getPrDetail as ReturnType<typeof vi.fn>).mockResolvedValue({ number: 12, branch: 'ali/x', base: 'main' });
+    if (opts.link) (prs.linkFor as ReturnType<typeof vi.fn>).mockReturnValue(opts.link);
+    const workspaces = makeWorkspaceService();
+    (workspaces.getWorkspacePath as ReturnType<typeof vi.fn>).mockResolvedValue(workspace);
+    const access = makeAccessControl();
+    (access.eligibleWritersForPathsAtRef as ReturnType<typeof vi.fn>).mockResolvedValue(opts.eligible ?? null);
+    const values = vi.fn(() => ({ returning: vi.fn(async () => [{ number: 12 }]) }));
+    const db = { insert: vi.fn(() => ({ values })) } as unknown as Database;
+    const run = vi.fn<(event: ChangeRequestOpenedEvent) => Promise<string[]>>(async () => ['email']);
+    const hooks: IChangeRequestHooks = { onChangeRequestOpened: vi.fn(), runChangeRequestOpened: run };
+    const accounts =
+      'accounts' in opts
+        ? opts.accounts
+        : {
+            findActiveAccountsByEmail: vi.fn(async (emails: readonly string[]) => {
+              const found = new Map<string, { id: string; email: string; name: string }>();
+              for (const email of emails) {
+                const account = ACCOUNTS[email];
+                if (account) found.set(email, account);
+              }
+              return found;
+            }),
+          };
+    const svc = new WorkflowService(
+      db, git, prs, makeReviewWorkflow(), workspaces, access,
+      makeFileLockService(), makePendingCommits(), testKbContext(), openChangeGate(),
+      { emit: vi.fn() } as unknown as WorkflowEventBus, undefined, undefined, hooks, accounts,
+    );
+    return { svc, run, prs, access, accounts, values };
+  }
+
+  it('fires once, after the row exists, with the request, who opened it and the approvers as accounts — once each', async () => {
+    const h = makeNotifyHarness({
+      eligible: eligibility({
+        [PATHS[0]]: { roles: ['Sales'], emails: ['dana@acme.test', 'lena@acme.test'] },
+        // Lena again, by another spelling: one person.
+        [PATHS[1]]: { roles: ['Legal'], emails: ['LENA@acme.test'] },
+      }),
+    });
+    const user = makeUser({ id: 'u-ali', email: 'ali@acme.test', name: 'Ali' });
+    const answer = await h.svc.openChangeRequest('ali%2Fx', user, INPUT);
+
+    expect(h.run).toHaveBeenCalledTimes(1);
+    const [event] = h.run.mock.calls[0]!;
+    expect(event).toEqual({
+      number: 12,
+      title: 'Tidy the glossary',
+      sourceBranch: 'ali/x',
+      targetBranch: 'main',
+      openedBy: { id: 'u-ali', email: 'ali@acme.test', name: 'Ali' },
+      approvers: [
+        { id: 'u-dana', email: 'dana@acme.test', name: 'Dana' },
+        { id: 'u-lena', email: 'Lena@acme.test', name: 'Lena' },
+      ],
+      unresolvedApprovers: 0,
+      pushPending: false,
+    });
+    // No public address: no `url` at all, not a relative one.
+    expect(event).not.toHaveProperty('url');
+    // The accounts were read once, for the distinct canonical addresses.
+    expect(h.accounts!.findActiveAccountsByEmail).toHaveBeenCalledTimes(1);
+    expect(h.accounts!.findActiveAccountsByEmail.mock.calls[0]![0]).toEqual(['dana@acme.test', 'lena@acme.test']);
+    // The eligibility was asked for the paths the request changes — the
+    // `git diff` against the target's published ref, as in production.
+    const eligibleFor = h.access.eligibleWritersForPathsAtRef as ReturnType<typeof vi.fn>;
+    expect(eligibleFor).toHaveBeenCalledTimes(1);
+    expect(eligibleFor.mock.calls[0]!.slice(-1)[0]).toEqual([...PATHS].sort()); // as `git diff --name-only` orders them
+    // The row landed before anyone was told, and the answer says who was.
+    expect(h.values).toHaveBeenCalledTimes(1);
+    expect(h.values.mock.invocationCallOrder[0]).toBeLessThan(h.run.mock.invocationCallOrder[0]!);
+    expect(answer).toMatchObject({ number: 12, notified: ['email'] });
+  });
+
+  it('counts a person without an account and the built-in `everyone` as unresolved, and hands neither over', async () => {
+    const h = makeNotifyHarness({
+      eligible: eligibility({
+        [PATHS[0]]: { roles: ['everyone'], emails: ['dana@acme.test', 'nobody@acme.test'] },
+        [PATHS[1]]: { roles: ['everyone', 'Legal'], emails: ['dana@acme.test'] },
+      }),
+    });
+    await h.svc.openChangeRequest('ali%2Fx', makeUser(), INPUT);
+    const [event] = h.run.mock.calls[0]!;
+    expect(event.approvers).toEqual([{ id: 'u-dana', email: 'dana@acme.test', name: 'Dana' }]);
+    // `nobody@` once, `everyone` once however many paths grant it.
+    expect(event.unresolvedApprovers).toBe(2);
+  });
+
+  it('hands over the public address when one is configured', async () => {
+    const h = makeNotifyHarness({ link: { url: 'https://kb.acme.test/change-requests/12' } });
+    await h.svc.openChangeRequest('ali%2Fx', makeUser(), INPUT);
+    expect(h.run.mock.calls[0]![0]).toMatchObject({ url: 'https://kb.acme.test/change-requests/12', approvers: [], unresolvedApprovers: 0 });
+  });
+
+  it('with no accounts to ask, or a read of them that fails, every approver is unresolved and the open goes on', async () => {
+    const eligible = eligibility({ [PATHS[0]]: { emails: ['dana@acme.test', 'lena@acme.test'] } });
+    const without = makeNotifyHarness({ eligible, accounts: undefined });
+    await without.svc.openChangeRequest('ali%2Fx', makeUser(), INPUT);
+    expect(without.run.mock.calls[0]![0]).toMatchObject({ approvers: [], unresolvedApprovers: 2 });
+
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    try {
+      const failing = makeNotifyHarness({
+        eligible,
+        accounts: { findActiveAccountsByEmail: vi.fn().mockRejectedValue(new Error('db down')) },
+      });
+      await expect(failing.svc.openChangeRequest('ali%2Fx', makeUser(), INPUT)).resolves.toMatchObject({ notified: ['email'] });
+      expect(failing.run.mock.calls[0]![0]).toMatchObject({ approvers: [], unresolvedApprovers: 2 });
+    } finally {
+      warn.mockRestore();
+    }
+  });
+
+  it('answers `notified: []` truthfully when the listeners reached nobody', async () => {
+    const h = makeNotifyHarness();
+    h.run.mockResolvedValue([]);
+    await expect(h.svc.openChangeRequest('ali%2Fx', makeUser(), INPUT)).resolves.toMatchObject({ number: 12, notified: [] });
+  });
+
+  it('tells the listeners even when the host refused the push, and says so: the request exists, its commits are still to land', async () => {
+    const h = makeNotifyHarness({
+      push: vi.fn().mockRejectedValue(new Error('git push failed: remote: Internal Server Error\n ! [remote rejected] ali/x -> ali/x (Internal Server Error)')),
+    });
+    const err = await h.svc.openChangeRequest('ali%2Fx', makeUser(), INPUT).catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(PushNeedsAgentResolutionError);
+    expect(h.run).toHaveBeenCalledTimes(1);
+    expect(h.run.mock.calls[0]![0]).toMatchObject({ number: 12, sourceBranch: 'ali/x', targetBranch: 'main', pushPending: true });
+  });
+
+  it('tells the listeners once the branches\' lifecycle locks are released: a slow mailer holds up the answer, not a delete or a merge', async () => {
+    const h = makeNotifyHarness();
+    let release!: () => void;
+    const gate = new Promise<void>((resolve) => { release = resolve; });
+    h.run.mockImplementation(async () => { await gate; return ['email']; });
+    const opening = h.svc.openChangeRequest('ali%2Fx', makeUser(), INPUT);
+    await vi.waitFor(() => { expect(h.run).toHaveBeenCalledTimes(1); });
+    // `createBranch` takes the branch's lifecycle lock — the one `deleteBranch`
+    // and `mergeBranch` take too — so it completing while the listener still
+    // waits shows the lock was released before the listeners were told.
+    const free = await Promise.race([
+      h.svc.createBranch('ali%2Fx', 'ali/x').then(() => 'free'),
+      new Promise<string>((resolve) => setTimeout(() => resolve('held'), 300)),
+    ]);
+    expect(free).toBe('free');
+    release();
+    await expect(opening).resolves.toMatchObject({ number: 12, notified: ['email'] });
+  });
+
+  it('tells the listeners when the detail cannot be read back: the request exists, a retry would be a duplicate', async () => {
+    const failing = makeNotifyHarness({ detail: vi.fn().mockRejectedValue(new Error('detail store down')) });
+    await expect(failing.svc.openChangeRequest('ali%2Fx', makeUser(), INPUT)).rejects.toThrow('detail store down');
+    expect(failing.run).toHaveBeenCalledTimes(1);
+    expect(failing.run.mock.calls[0]![0]).toMatchObject({ number: 12, pushPending: false });
+
+    const missing = makeNotifyHarness({ detail: vi.fn().mockResolvedValue(null) });
+    await expect(missing.svc.openChangeRequest('ali%2Fx', makeUser(), INPUT)).rejects.toBeInstanceOf(WorkflowValidationError);
+    expect(missing.run).toHaveBeenCalledTimes(1);
+  });
+
+  it('a refused open tells nobody: a validation failure, a conflicting auto-merge', async () => {
+    const invalid = makeNotifyHarness();
+    await expect(invalid.svc.openChangeRequest('ali%2Fx', makeUser(), { ...INPUT, title: '   ' })).rejects.toBeInstanceOf(WorkflowValidationError);
+    expect(invalid.run).not.toHaveBeenCalled();
+    expect(invalid.values).not.toHaveBeenCalled();
+
+    const conflicting = makeNotifyHarness({
+      merge: vi.fn().mockResolvedValue({ kind: 'conflicts', paths: ['KnowledgeBase/Sales/Deal.md'] }),
+    });
+    await expect(conflicting.svc.openChangeRequest('ali%2Fx', makeUser(), INPUT)).rejects.toBeInstanceOf(ChangeRequestConflictsError);
+    expect(conflicting.run).not.toHaveBeenCalled();
+    expect(conflicting.values).not.toHaveBeenCalled();
+  });
+
+  it('a refused open (a duplicate, say) tells nobody', async () => {
+    const h = makeNotifyHarness();
+    (h.prs.listOpenPrs as ReturnType<typeof vi.fn>).mockResolvedValue([{ number: 3, branch: 'ali/x', base: 'main' }]);
+    await expect(h.svc.openChangeRequest('ali%2Fx', makeUser(), INPUT)).rejects.toThrow();
+    expect(h.run).not.toHaveBeenCalled();
+  });
+});
+
 /**
  * Writes are committed asynchronously: a write tool answers once the bytes are
  * on disk, and the pending-commits worker commits and pushes them seconds

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

@@ -652,6 +652,16 @@ describe('registerWorkflowTools', () => {
       expect(files.every((f) => !('patch' in f))).toBe(true);
     });
 
+    it('says who was notified when the service does, and nothing of it otherwise', async () => {
+      const base = await start();
+      // A read of a request later has no `notified` to report: the key is absent, not empty.
+      expect(await open(base)).not.toHaveProperty('notified');
+      opened = { ...BIG(), notified: ['email'] };
+      expect(await open(base)).toMatchObject({ number: 7, notified: ['email'] });
+      opened = { ...BIG(), notified: [] };
+      expect((await open(base)).notified).toEqual([]);
+    });
+
     it('keeps the 27-file answer under 10,000 characters', async () => {
       const base = await start();
       const body = await open(base);

package/src/modules/workflow/agent-tools/change-request-summary.ts

@@ -96,6 +96,13 @@ export interface ChangeRequestSummary {
   files: ChangeRequestSummaryFile[];
   /** How many files the request changes in total, cut or not. */
   totalFiles: number;
+  /**
+   * The channels that reached the approvers as the request was opened
+   * (`['email']`, say), as the deployment's listeners said; empty when nobody
+   * was told. Only on the answer to an open — a request read later has no
+   * such moment to report.
+   */
+  notified?: string[];
 }
 
 /**
@@ -157,7 +164,7 @@ function summaryFileOf(file: ChangedFile, withPatch: boolean): ChangeRequestSumm
  * by that: `mergeBlockedReasons` names every missing approval, cut or not.
  */
 export function summarizeChangeRequest(
-  detail: ChangeRequestDetail,
+  detail: ChangeRequestDetail & { notified?: string[] },
   include: readonly ChangeRequestInclude[] = [],
 ): ChangeRequestSummary {
   const all = detail.files ?? [];
@@ -176,6 +183,8 @@ export function summarizeChangeRequest(
     mergeBlockedReasons: detail.mergeBlockedReasons ?? [],
     files: listed.map((f) => summaryFileOf(f, withPatch)),
     totalFiles: all.length,
+    // Only an open carries it; a read of a request later has none to report.
+    ...(detail.notified ? { notified: detail.notified } : {}),
   };
 }
 

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

@@ -154,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'],
 };

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);
+  }
+}

package/src/modules/workflow/git/pull-request.service.ts

@@ -253,6 +253,16 @@ export class PullRequestService implements IPullRequestService {
     this.linkBase = changeRequestLinkBase(publicFrontendUrl);
   }
 
+  /**
+   * The link to change request `number`, as every summary and detail carries
+   * it — absolute under the public address, else the in-app path with its
+   * note. Needs no read: a caller holding only the number (an open whose push
+   * was refused, say) builds the same link a listing would.
+   */
+  linkFor(number: number): { url: string; urlNote?: string } {
+    return changeRequestLink(number, this.linkBase);
+  }
+
   setDetailEnricher(enricher: PrDetailEnricher): void {
     this.detailEnricher = enricher;
   }