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

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

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

@@ -27,19 +27,27 @@
  * has evicted past `n`, the route emits `{ kind: 'resync' }` so the
  * client refetches state from scratch.
  *
+ * **Who receives what** — the bus picks the sessions that HEAR about an
+ * event (focus for workspace events, owner for user events); before writing
+ * it, the route asks the delivery rule (`IEventDelivery`) whether this
+ * session's person may have it, and in what form (`events-delivery.ts`). Live fan-out and replay go
+ * through the same rule, and through one ordered queue per session, so a
+ * slow verdict never reorders a session's stream.
+ *
  * **Heartbeat** — every 25 s the route writes an SSE comment (`:\n\n`).
  * Keeps proxies (nginx, Coolify's Traefik, Cloudflare) from killing the
  * connection as idle. Cheap (~15 bytes), eliminates a whole class of bug.
  */
 
-import type { Request, Response } from 'express';
+import type { Response } from 'express';
 import { logger } from '../../shared/logging.js';
 
 const log = logger('events');
 import express from 'express';
-import type { WorkflowEvent } from '@bevel-software/platform-shared';
+import { type WorkflowEvent } from '@bevel-software/platform-shared';
 import type { WorkflowEventBus } from './event-bus.js';
-import '../auth/auth.middleware.js'; // Express Request augmentation
+import type { IEventDelivery } from './events-delivery.js';
+import '../auth/index.js'; // Express Request augmentation
 
 /** Interval between SSE keep-alive comments (ms). 25 s sits comfortably under
  * the typical 30–100 s proxy idle timeout. */
@@ -73,15 +81,16 @@ interface ActiveSession {
    * suggestion branch got no `file-changed` for the images on screen and kept
    * showing a screenshot a teammate had already replaced.
    *
-   * The client declares the list; this is a delivery filter, not an access
-   * check. It always was — a session could name any workspace as its focus —
-   * and the events it selects carry no file contents, only paths. Whether the
-   * reader may open what changed is settled by the routes that serve it.
+   * The client declares the list, and may name any workspace in it: this is
+   * a delivery filter, not an access check. The access check is the
+   * delivery rule (`IEventDelivery`) every event passes on its way to the session.
    */
   focusedWorkspaceIds: string[];
   /** Set when the SSE connection closes. Used by the focus POST so a
    *  request that arrives after the connection drops 404s cleanly. */
   closed: boolean;
+  /** Tail of this session's writes: each event waits for its verdict, in arrival order. */
+  queue: Promise<void>;
   /** The Express response stream backing this session. Stored so a
    *  same-id reconnect can `end()` the old response and close its TCP
    *  socket immediately, rather than leaving a dangling connection that
@@ -97,6 +106,7 @@ interface ActiveSession {
 export function createEventsRoutes(
   bus: WorkflowEventBus,
   authMiddleware: express.RequestHandler,
+  delivery: IEventDelivery,
 ): express.Router {
   const router = express.Router();
 
@@ -114,6 +124,7 @@ export function createEventsRoutes(
       return;
     }
     const userId = req.userId!;
+    const viewer = { userId, email: req.userEmail };
 
     // SSE headers. `X-Accel-Buffering: no` tells nginx not to buffer the
     // response (would batch events behind a flush boundary, killing
@@ -158,15 +169,24 @@ export function createEventsRoutes(
       userId,
       focusedWorkspaceIds: [],
       closed: false,
+      queue: Promise.resolve(),
       res,
       // Filled in below once `unsubscribe` + `heartbeat` exist.
       cleanup: () => {},
     };
     sessions.set(sessionId, session);
 
+    // Every event this session hears goes through the delivery rule, in the
+    // order it arrived: the verdict is async, the stream must not reorder.
     const push = (event: WorkflowEvent): void => {
       if (session.closed) return;
-      writeSseEvent(res, event);
+      const verdict = delivery.judge(event, viewer);
+      session.queue = session.queue.then(async () => {
+        const deliverable = await verdict;
+        if (deliverable && !session.closed) writeSseEvent(res, deliverable);
+      }).catch((err: unknown) => {
+        log.warn(`write to session=${sessionId} failed:`, { err });
+      });
     };
 
     const unsubscribe = bus.subscribe({
@@ -196,7 +216,8 @@ export function createEventsRoutes(
           reason: 'last-event-id too old; ring buffer evicted',
         });
       } else {
-        for (const event of replay) writeSseEvent(res, event);
+        // The same rule as live delivery, queued ahead of anything live.
+        for (const event of replay) push(event);
       }
     }
 

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

@@ -58,8 +58,8 @@
  */
 
 import { and, eq, gt, inArray, lte } from 'drizzle-orm';
-import type { Database } from '../database/connection.js';
-import { fileLocks } from '../database/schema.js';
+import type { Database } from '../database/index.js';
+import { fileLocks } from '../database/index.js';
 import type { AcquireLockResult, AuthUser, FileLock } from '@bevel-software/platform-shared';
 import { WorkflowValidationError } from '../../shared/domain-errors.js';
 import { canonicalFileIdentity } from '../../shared/canonical-file-identity.js';

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

@@ -22,11 +22,11 @@ const ROW = {
   closedAt: null,
 };
 
-function makeDb(): Database {
+function makeDb(row: Record<string, unknown> = ROW): Database {
   return {
     select: () => ({
       from: () => ({
-        where: () => ({ limit: async () => [ROW] }),
+        where: () => ({ limit: async () => [row] }),
       }),
     }),
   } as unknown as Database;
@@ -42,10 +42,10 @@ const FORK = 'c'.repeat(40);
  * both refs), so the file list must be pinned to those same commits rather
  * than fetch and resolve again. The SHAs and the file list are read on every
  * call (a new head must show); what the detail cache saves is the DB
- * enrichment (comments, approvals), so that is where "cached" is observed.
+ * enrichment (approvals), so that is where "cached" is observed.
  */
 describe('PullRequestService.getPrDetail — git work per read', () => {
-  function harness() {
+  function harness(row: Record<string, unknown> = ROW) {
     const resolvePrShas = vi.fn(async () => ({ baseSha: BASE, headSha: HEAD }));
     const changedFilesForPr = vi.fn(async () => []);
     const forkPointForPr = vi.fn(async () => ({ mergeBaseSha: FORK, behind: true }));
@@ -61,11 +61,9 @@ describe('PullRequestService.getPrDetail — git work per read', () => {
       ensureRemotesFetched: async () => undefined,
     } as unknown as WorkspaceService;
     const access = { canWriteAtRef: async () => false } as unknown as IAccessControl;
-    const svc = new PullRequestService(makeDb(), workspace, access, git);
-    const listComments = vi.fn(async () => []);
+    const svc = new PullRequestService(makeDb(row), workspace, access, git);
     const getApprovalStates = vi.fn(async () => []);
     svc.setDetailEnricher({
-      listComments,
       getApprovalStates,
       evaluateMergeGate: () => ({ mergeable: false, reasons: [], warnings: [] }),
     });
@@ -79,6 +77,25 @@ describe('PullRequestService.getPrDetail — git work per read', () => {
     };
   }
 
+  it('carries the body as stored, and an access request\'s level and note off the row — absent on an ordinary request', async () => {
+    const plain = await harness().svc.getPrDetail(7, { fresh: true });
+    expect(plain?.body).toBe('');
+    expect(plain).not.toHaveProperty('accessRequest');
+
+    const asked = await harness({
+      ...ROW,
+      body: 'Rita asked for **Owner** on Research.',
+      accessRequestLevel: 'owner',
+      accessRequestNote: 'I maintain these pages now',
+    }).svc.getPrDetail(7, { fresh: true });
+    expect(asked?.body).toBe('Rita asked for **Owner** on Research.');
+    expect(asked?.accessRequest).toEqual({ level: 'owner', note: 'I maintain these pages now' });
+
+    // A level with no note: the note never stands alone, and never as ''.
+    const noNote = await harness({ ...ROW, accessRequestLevel: 'write', accessRequestNote: null }).svc.getPrDetail(7, { fresh: true });
+    expect(noNote?.accessRequest).toEqual({ level: 'write' });
+  });
+
   it('pins the file list to the SHAs it just resolved, and keeps patches for a client read', async () => {
     const { svc, resolvePrShas, changedFilesForPr } = harness();
     const detail = await svc.getPrDetail(7, { fresh: true });
@@ -164,7 +181,6 @@ describe('PullRequestService — change request link', () => {
     const access = { canWriteAtRef: async () => false } as unknown as IAccessControl;
     const svc = new PullRequestService(makeDb(), workspace, access, git, publicFrontendUrl);
     svc.setDetailEnricher({
-      listComments: async () => [],
       getApprovalStates: async () => [],
       evaluateMergeGate: () => ({ mergeable: false, reasons: [], warnings: [] }),
     });
@@ -244,7 +260,6 @@ describe('PullRequestService.getPrDetail — needsUpdate', () => {
     } as unknown as Database;
     const svc = new PullRequestService(db, workspace, access, git);
     svc.setDetailEnricher({
-      listComments: async () => [],
       getApprovalStates: async () => [],
       evaluateMergeGate: () => ({ mergeable: false, reasons: [], warnings: [] }),
     });

package/src/modules/workflow/git/git.service.ts

@@ -21,15 +21,12 @@ import type {
 } from '@bevel-software/platform-shared';
 import { isFolderPlaceholder } from '@bevel-software/platform-shared';
 import { mergeCommitMessageNames } from './merge-commit.js';
-import type { WorkspaceService } from '../../workspace/workspace.service.js';
+import type { WorkspaceService } from '../../workspace/index.js';
 import type { WorkflowHooks, CommitValidationContext } from '../workflow-hooks.js';
-import type { IAccessControl } from '../../access/access-control.interface.js';
-import { AccessDeniedError } from '../../access-model/access-errors.js';
-import { WorkspaceIdMutex, type WorkspaceMutex } from '../../kb-fs/index.js';
+import type { IAccessControl } from '../../access/index.js';
+import { AccessDeniedError } from '../../access-model/index.js';
+import { WorkspaceIdMutex, type WorkspaceMutex, assertInsideRepo, cloneTrackingConfigArgs, SAFE_IMPLICIT_FETCH_ARGS, readRefSha } from '../../kb-fs/index.js';
 import { isAbsence } from '../../../shared/fs.contract.js';
-import { assertInsideRepo } from '../../kb-fs/repo-path.js';
-import { cloneTrackingConfigArgs, SAFE_IMPLICIT_FETCH_ARGS } from '../../kb-fs/clone-config.js';
-import { readRefSha } from '../../kb-fs/index.js';
 import { utf8Text } from '../../../shared/utf8-text.js';
 import { lstatOrNull } from '../../../shared/rename-no-replace.js';
 import { linkedAncestor } from '../../../shared/no-link-below.js';
@@ -38,7 +35,7 @@ import {
   assertValidRelativePath,
   isBranchAuthoredBy,
   isOwnSuggestionsBranch,
-} from '../../kb-fs/branch-name.js';
+} from '../../kb-fs/index.js';
 import type { KbContext } from '../../../shared/kb-context.js';
 import {
   AppliedChangeMismatchError,

package/src/modules/workflow/git/node-git-runner.ts

@@ -10,7 +10,7 @@ import {
   type IGitRunner,
 } from '../../../shared/git.contract.js';
 import { logger } from '../../../shared/logging.js';
-import { credentialHelperValue } from '../../kb-fs/clone-config.js';
+import { credentialHelperValue } from '../../kb-fs/index.js';
 
 const log = logger('git-runner');
 

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

@@ -7,7 +7,6 @@ import type {
   ChangedPathPair,
   FileApprovalState,
   IPullRequestService,
-  PrReviewComment,
   PullRequestDetail,
   PullRequestFile,
   PullRequestState,
@@ -15,22 +14,22 @@ import type {
   IGitService,
 } from '@bevel-software/platform-shared';
 import { isFolderPlaceholder } from '@bevel-software/platform-shared';
-import type { Database } from '../../database/connection.js';
-import { changeRequests } from '../../database/schema.js';
-import type { WorkspaceService } from '../../workspace/workspace.service.js';
-import type { IAccessControl } from '../../access/access-control.interface.js';
-import { AccessUnreadableError } from '../../access-model/access-errors.js';
+import type { Database } from '../../database/index.js';
+import { changeRequests } from '../../database/index.js';
+import type { WorkspaceService } from '../../workspace/index.js';
+import type { IAccessControl } from '../../access/index.js';
+import { AccessUnreadableError } from '../../access-model/index.js';
 import { AppliedChangeMismatchError, WorkflowValidationError } from '../../../shared/domain-errors.js';
 import { canonicalEmail, hashEmail } from '../../../shared/email-identity.js';
 import { changeRequestLink, changeRequestLinkBase } from './change-request-link.js';
 
 /**
- * The latest moment a change-request row records — its close time when it has
- * one, else its creation time, with `updated_at` folded in for the day
- * something writes it. Deliberately derived from the ROW alone: a time taken
- * from the newest comment or approval would make the same request report
- * different "last changed" moments to a list (which reads no comments) and a
- * detail (which does).
+ * The latest moment a change-request row records — the latest of its creation,
+ * its `updated_at` (a title or description edit) and its close time.
+ * Deliberately derived from the ROW alone: a time taken
+ * from the newest approval would make the same request report different
+ * "last changed" moments to a list (which reads no approvals) and a detail
+ * (which does).
  */
 function latestRowMoment(row: {
   createdAt: Date;
@@ -148,7 +147,6 @@ export function changeSourceFor(row: {
  * relationship in the composition root is explicit and minimal.
  */
 export interface PrDetailEnricher {
-  listComments(prNumber: number): Promise<PrReviewComment[]>;
   /**
    * Per-file approval state. `baseBranch` selects the access tree (resolved
    * against `origin/<baseBranch>`); `workspaceId` is optional and gates the
@@ -184,8 +182,8 @@ export interface PrDetailEnricher {
  *
  * The durable facts (pairing, title/body, author, state) live in the row; the
  * head/base SHAs, file list, and diffs are derived live from git so a new commit
- * or force-push is always reflected. Comments + per-file approvals + the merge
- * gate are stitched in from the review-workflow service (also DB-backed).
+ * or force-push is always reflected. Per-file approvals and the merge gate
+ * are stitched in from the review-workflow service (also DB-backed).
  */
 export class PullRequestService implements IPullRequestService {
   /**
@@ -837,16 +835,11 @@ export class PullRequestService implements IPullRequestService {
       })),
     );
 
-    // Comments + approvals come from our own DB via the review-workflow service.
-    // The enricher is optional — if it isn't wired yet (startup ordering,
-    // isolated tests) we return empty lists rather than blocking the fetch.
-    const [comments, approvals] = this.detailEnricher
-      ? await Promise.all([
-          this.detailEnricher.listComments(prNumber).catch((err) => {
-            log.warn(`listComments failed for #${prNumber}:`, { err });
-            return [] as PrReviewComment[];
-          }),
-          this.detailEnricher
+    // Approvals come from our own DB via the review-workflow service. The
+    // enricher is optional — if it isn't wired yet (startup ordering, isolated
+    // tests) we return an empty list rather than blocking the fetch.
+    const approvals = this.detailEnricher
+      ? await this.detailEnricher
             .getApprovalStates(
               prNumber,
               files,
@@ -863,9 +856,8 @@ export class PullRequestService implements IPullRequestService {
               if (err instanceof AccessUnreadableError) throw err;
               log.warn(`getApprovalStates failed for #${prNumber}:`, { err });
               return [] as FileApprovalState[];
-            }),
-        ])
-      : [[] as PrReviewComment[], [] as FileApprovalState[]];
+            })
+      : ([] as FileApprovalState[]);
 
     const gate = this.detailEnricher
       ? this.detailEnricher.evaluateMergeGate({
@@ -933,10 +925,19 @@ export class PullRequestService implements IPullRequestService {
     const detail: PullRequestDetail = {
       ...summary,
       body: row.body,
+      // Only a request the access-request flow opened has a level; the note
+      // rides with it and never stands alone.
+      ...(row.accessRequestLevel
+        ? {
+            accessRequest: {
+              level: row.accessRequestLevel as 'write' | 'owner',
+              ...(row.accessRequestNote ? { note: row.accessRequestNote } : {}),
+            },
+          }
+        : {}),
       headSha,
       baseSha,
       files,
-      comments,
       approvals,
       mergeableInBevel: gate.mergeable,
       mergeBlockedReasons: gate.reasons,
@@ -951,6 +952,10 @@ export class PullRequestService implements IPullRequestService {
       viewerCanUpdate,
       viewerIsAuthor,
       viewerCanDelete,
+      // Who may close a request may also change what it asks: the same
+      // grants, so the same predicate (`WorkflowService.updateChangeRequest`
+      // enforces it).
+      viewerCanEdit: viewerCanCancel,
     };
 
     // A patch-less detail is an internal read; it must not be served to the

package/src/modules/workflow/index.ts

@@ -1,7 +1,20 @@
 /**
  * What the workflow module offers the other modules: the addresses of its
  * change requests, so a module that lands a proposal can hand back a link
- * built by the one rule — rather than each spelling the route for itself.
- * The services are wired by the composition root.
+ * built by the one rule — rather than each spelling the route for itself;
+ * and the live-event surface — the bus, the events route, and the delivery
+ * rule every event passes on its way to a session. The services are wired by
+ * the composition root.
  */
 export { CHANGE_REQUEST_URL_NOTE, changeRequestLink, changeRequestLinkBase } from './git/change-request-link.js';
+export { WorkflowEventBus } from './event-bus.js';
+export { createEventsRoutes } from './events.routes.js';
+export { EventDelivery, createEventAccess } from './events-delivery.js';
+export type { ChangeRequestFacts, EventAccess, EventViewer, IEventDelivery } from './events-delivery.js';
+// Reached by other modules; exported here so they stop importing the files.
+export { NodeGitRunner } from './git/node-git-runner.js';
+export { RECOVERY_BOT_EMAIL } from './recovery-bot.js';
+export type { IReviewWorkflowService } from './review-workflow/review-workflow.interface.js';
+export { sanitizeError } from './sanitize-error.js';
+export type { WorkflowHooks } from './workflow-hooks.js';
+export type { WorkflowService } from './workflow.service.js';