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

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

@@ -18,6 +18,8 @@
  */
 
 import path from 'node:path';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
 import { logger } from '../../shared/logging.js';
 
 // One logger per tag this file has always written under, so a line's prefix
@@ -31,8 +33,6 @@ const mergeLog = logger('merge');
 /** Who the leftover cleanup deletes as. Its deletions skip the authorship check, and the log names them `system`. */
 const SYSTEM_ACTOR: AuthUser = { id: 'system', email: 'system', name: 'system' };
 import { promises as fs } from 'node:fs';
-import { execFile } from 'node:child_process';
-import { promisify } from 'node:util';
 import type {
   AcquireLockResult,
   AuthUser,
@@ -44,7 +44,6 @@ import type {
   ChangeInput,
   ChangeRequest,
   ChangeRequestApplyFailureKind,
-  ChangeRequestComment,
   ChangeRequestDetail,
   ChangeRequestUpdateResult,
   ChangeRequestState,
@@ -60,37 +59,42 @@ import type {
   MergeChangeRequestOutcome,
   MergeResolution,
   OpenChangeRequestInput,
-  PostChangeRequestCommentInput,
   RemoteSyncPullResult,
   UpdateBranchOutcome,
+  UpdateChangeRequestFields,
 } from '@bevel-software/platform-shared';
 import {
   isFolderPlaceholder,
   folderPlaceholderPath,
   isPlatformRestoreShape,
+  CHANGE_REQUEST_DESCRIPTION_MAX,
+  CHANGE_REQUEST_TITLE_MAX,
 } from '@bevel-software/platform-shared';
 import type { KbContext } from '../../shared/kb-context.js';
 import { readableAtCommits, ReadOnBranchDeniedError } from './read-on-branch.js';
 import { and, desc, eq, inArray, isNotNull, isNull, lt, ne, or, sql } from 'drizzle-orm';
-import type { Database } from '../database/connection.js';
-import { changeRequests } from '../database/schema.js';
-import { pgErrorCode } from '../database/pg-error.js';
+import type { Database } from '../database/index.js';
+import { changeRequests, pgErrorCode } from '../database/index.js';
 import type { GitService } from './git/git.service.js';
 import { redactSecret } from '../../shared/redact-secret.js';
 import type { PullRequestService } from './git/pull-request.service.js';
 import type { IReviewWorkflowService } from './review-workflow/review-workflow.interface.js';
-import type { WorkspaceService } from '../workspace/workspace.service.js';
+import type { WorkspaceService } from '../workspace/index.js';
 import { workspaceIdForBranch, branchForWorkspaceId } from '../../shared/workspace-id.js';
-import type { IAccessControl } from '../access/access-control.interface.js';
-import { FileLockService } from './file-lock.service.js';
+import type { IAccessControl } from '../access/index.js';
+import type { FileLockService } from './file-lock.service.js';
 import { canonicalFileIdentity } from '../../shared/canonical-file-identity.js';
-import { PendingCommitsService } from './pending-commits.service.js';
+import type { PendingCommitsService } from './pending-commits.service.js';
 import type { WorkflowEventBus } from './event-bus.js';
 import { describeSyncFailure, sanitizeError } from './sanitize-error.js';
-import type { FileChangeNotifier } from '../kb-fs/file-change-notifier.js';
+import type { FileChangeNotifier } from '../kb-fs/index.js';
 import { WorkflowHooks } from './workflow-hooks.js';
-import { WorkspaceMutex } from '../kb-fs/mutex.js';
-import { assertValidBranchName } from '../kb-fs/branch-name.js';
+import {
+  ChangeRequestHooks,
+  type ChangeRequestPerson,
+  type IChangeRequestHooks,
+} from './change-request-hooks.js';
+import { WorkspaceMutex, assertValidBranchName } from '../kb-fs/index.js';
 import { canonicalEmail, hashEmail } from '../../shared/email-identity.js';
 import {
   BranchAuthorshipError,
@@ -108,8 +112,7 @@ import {
   WorkflowValidationError,
 } from '../../shared/domain-errors.js';
 import { RECOVERY_BOT_EMAIL, RECOVERY_BOT_NAME } from './recovery-bot.js';
-import { AccessDeniedError } from '../access-model/access-errors.js';
-import type { IChangeReadGate } from '../access-model/change-gate.js';
+import { AccessDeniedError, EVERYONE_CANONICAL, type IChangeReadGate } from '../access-model/index.js';
 import { printable } from '../../shared/printable.js';
 
 const execFileAsync = promisify(execFile);
@@ -181,72 +184,51 @@ function redactTokens(msg: string, token: string | null | undefined): string {
 }
 
 /**
- * Cap on how many changed paths the `## Affected owners` CR-body block lists
- * individually. The block is passed to `gh pr create --body`, an argv string,
- * so an uncapped per-path list on a large changeset (hundreds/thousands of
- * files) makes the whole command exceed the OS arg limit and fail with E2BIG.
+ * Only an open request's title and description may change: an applied one is
+ * history, and a closed one is no longer asking anything. A worded 409 either
+ * way, so the refusal says which.
  */
-export const MAX_AFFECTED_PATHS_LISTED = 50;
-
-type EligibleWriters = Map<
-  string,
-  { roles: string[]; users: { name: string; email: string }[] }
->;
-
-const formatWriter = (u: { name: string; email: string }): string =>
-  u.name ? `${u.name} <${u.email}>` : u.email;
-
 /**
- * Render the `## Affected owners` block for the CR body: eligible approvers per
- * changed path, but only the first `maxListed` paths are listed individually;
- * the overflow is collapsed into a single deduped summary of every eligible
- * approver across the change. This keeps the body bounded regardless of how
- * many files the change touches (see {@link MAX_AFFECTED_PATHS_LISTED}).
- * Returns '' when no path has resolvable eligibility. The empty-folder
- * placeholder is never listed or counted: it is not content, and no one
- * reviews it.
+ * A description — on opening, a replacement, or what an append leaves — is
+ * at most {@link CHANGE_REQUEST_DESCRIPTION_MAX} characters; a worded 400
+ * past it. Undefined (no description given) always fits.
  */
-export function formatAffectedOwnersBlock(
-  paths: string[],
-  resolved: EligibleWriters,
-  maxListed: number = MAX_AFFECTED_PATHS_LISTED,
-): string {
-  const listed: string[] = [];
-  const allRoles = new Set<string>();
-  const allUsers = new Map<string, string>(); // email -> display, deduped
-  let eligible = 0;
-  for (const p of paths) {
-    if (isFolderPlaceholder(p)) continue;
-    const info = resolved.get(p);
-    if (!info) continue;
-    const parts: string[] = [];
-    if (info.roles.length > 0) {
-      info.roles.forEach((r) => allRoles.add(r));
-      parts.push(info.roles.join(', '));
-    }
-    if (info.users.length > 0) {
-      info.users.forEach((u) => allUsers.set(u.email, formatWriter(u)));
-      parts.push(info.users.map(formatWriter).join(', '));
-    }
-    if (parts.length === 0) continue;
-    eligible++;
-    if (listed.length < maxListed) listed.push(`- \`${p}\` — ${parts.join('; ')}`);
+function assertDescriptionFits(description: string | undefined): void {
+  if (description !== undefined && description.length > CHANGE_REQUEST_DESCRIPTION_MAX) {
+    throw new WorkflowValidationError(
+      `A change request's description is at most ${CHANGE_REQUEST_DESCRIPTION_MAX} characters; this one would have ${description.length}.`,
+    );
   }
-  if (eligible === 0) return '';
-
-  const out = ['## Affected owners', '', ...listed];
-  if (eligible > listed.length) {
-    const summary = [
-      allRoles.size > 0 ? [...allRoles].sort().join(', ') : '',
-      allUsers.size > 0 ? [...allUsers.values()].sort().join(', ') : '',
-    ].filter((s) => s.length > 0);
-    out.push(
-      '',
-      `…and ${eligible - listed.length} more changed path(s). ` +
-        `All eligible approvers across this change: ${summary.join('; ')}`,
+}
+
+function assertEditable(state: string): void {
+  if (state === 'merged') {
+    throw new WorkflowDomainError(
+      'This change request has already been applied; its title and description can no longer be changed.',
+      409,
+    );
+  }
+  if (state !== 'open') {
+    throw new WorkflowDomainError(
+      'This change request is closed; its title and description can no longer be changed.',
+      409,
     );
   }
-  return out.join('\n');
+}
+
+/** What the access layer answers for the changed paths of a request, or null when it cannot. */
+type EligibleWritersAtRef = Awaited<ReturnType<IAccessControl['eligibleWritersForPathsAtRef']>>;
+
+/**
+ * The one question the open asks of accounts: which of these addresses have
+ * a live account. `AuthService.findActiveAccountsByEmail` answers it in a
+ * single indexed read; the shape is spelled here so the workflow module
+ * imports nothing of auth's. Keyed by the canonical address asked for.
+ */
+export interface ApproverAccounts {
+  findActiveAccountsByEmail(
+    emails: readonly string[],
+  ): Promise<Map<string, { id: string; email: string; name: string }>>;
 }
 
 /** Git commit subjects are capped at 200 characters (`GitService.commitFile`). */
@@ -343,6 +325,19 @@ export class WorkflowService implements IWorkflowService {
      * hooks) unchanged.
      */
     public readonly hooks: WorkflowHooks = new WorkflowHooks(),
+    /**
+     * The seam a deployment's notification extends when a request is opened
+     * (see `change-request-hooks.ts`). The composition root passes the SAME
+     * instance it exposes as `changeRequestHooks`; the default registers
+     * nobody, so a test construction notifies nobody and says so.
+     */
+    private readonly changeRequestHooks: IChangeRequestHooks = new ChangeRequestHooks(),
+    /**
+     * Who turns the addresses the access model names into accounts, for the
+     * opened event's `approvers`. Absent (a harness without accounts), every
+     * approver counts as unresolved.
+     */
+    private readonly accounts?: ApproverAccounts,
   ) {
     // The type already requires it; this holds for a caller the compiler did
     // not see (plain JavaScript, a positional slip in a harness).
@@ -716,7 +711,6 @@ export class WorkflowService implements IWorkflowService {
             source: summary.branch,
             target: summary.base,
             authorIdHash: summary.authorId ?? null,
-            title: summary.title,
           });
         }
       }
@@ -2270,18 +2264,23 @@ export class WorkflowService implements IWorkflowService {
    *      account, so no hidden body marker). The DB-assigned number is the CR id.
    *   6. Re-fetch the full detail via the PR service so the response shape
    *      matches every other CR endpoint.
+   *   7. Tell the deployment's change-request listeners (see
+   *      `change-request-hooks.ts`); `notified` in the answer says which
+   *      channels reached the approvers. Once per request, here, whether a
+   *      person or an agent opened it — both take this road.
    */
   async openChangeRequest(
     workspaceId: string,
     user: AuthUser,
     input: OpenChangeRequestInput,
-  ): Promise<ChangeRequestDetail> {
+  ): Promise<ChangeRequestDetail & { notified: string[] }> {
     if (!input.sourceBranch) throw new WorkflowValidationError('sourceBranch is required');
     if (!input.targetBranch) throw new WorkflowValidationError('targetBranch is required');
     if (input.sourceBranch === input.targetBranch) {
       throw new WorkflowValidationError('source and target branches must differ');
     }
     if (!input.title?.trim()) throw new WorkflowValidationError('title is required');
+    assertDescriptionFits(input.description?.trim());
     if (this.kb.isProtectedBranch(input.sourceBranch)) {
       throw new WorkflowValidationError(
         `Cannot open a change request *from* a protected branch ("${input.sourceBranch}").`,
@@ -2300,7 +2299,19 @@ export class WorkflowService implements IWorkflowService {
     // its branches is retired inside the window, and holding only the source
     // left a `Y -> X` request open to X being deleted under it — the very
     // failure the widened guards exist to prevent.
-    return this.runOnBranchPair(input.sourceBranch, input.targetBranch, async () => {
+    //
+    // The deployment's listeners are told AFTER the locks are released: they
+    // are awaited (the answer's `notified` is true to what happened), and a
+    // slow mailer must hold up this answer alone, never a delete or a merge
+    // on either branch. So the locked part answers what it made — the detail,
+    // or the refusal — and the telling follows.
+    const outcome = await this.runOnBranchPair(input.sourceBranch, input.targetBranch, async (): Promise<
+      { number: number; eligible: EligibleWritersAtRef } & (
+        | { detail: ChangeRequestDetail; pushRefused: null; detailError: null }
+        | { detail: null; pushRefused: PushNeedsAgentResolutionError; detailError: null }
+        | { detail: null; pushRefused: null; detailError: Error }
+      )
+    > => {
     // Uniqueness rule — A→B blocks A→B (the spec is explicit that B→A in
     // parallel is still allowed). `listOpenPrs` is cached for 30s so we
     // force-fresh to catch a CR that opened just now.
@@ -2356,27 +2367,21 @@ export class WorkflowService implements IWorkflowService {
     const workspacePath = await this.workspaceService.getWorkspacePath(workspaceId);
     const cwd = path.join(workspacePath, this.kbDirName);
 
-    // Touched paths between target and source — basis for the
-    // affected-owners block we append to the CR body. We compute it
-    // ourselves rather than waiting for GitHub to expose `pr.files`
-    // (which only populates after the PR exists). Three-dot range
-    // matches what `gh pr create` will eventually show as the diff.
+    // Touched paths between target and source — the diff the request will
+    // surface — and the eligible approvers per path at the target, resolved
+    // once for the opened event, which hands the same people to the
+    // deployment's listeners. None of it is written into the body: the request
+    // is a DB row whose author is a column, whose body is the description and
+    // nothing else, and whose access-request level and note are columns of
+    // their own. Who must approve each file is resolved live, per file,
+    // whenever the request is read.
     const touchedPaths = await this.listChangedPathsBetweenBranches(
       cwd,
       input.targetBranch,
       input.sourceBranch,
     );
-    const affectedOwnersBlock = await this.buildAffectedOwnersBlock(
-      workspaceId,
-      input.targetBranch,
-      touchedPaths,
-    );
-
-    // The change request is a plain DB row now — no provider PR. Author is a
-    // real column (no hidden body marker needed, since nothing runs as a shared
-    // service account anymore).
-    const description = input.description?.trim() ?? '';
-    const body = [description, affectedOwnersBlock].filter((s) => s.length > 0).join('\n\n');
+    const eligible = await this.eligibleWritersFor(workspaceId, input.targetBranch, touchedPaths);
+    const note = input.accessRequest?.note?.trim();
 
     let prNumber: number;
     try {
@@ -2386,10 +2391,12 @@ export class WorkflowService implements IWorkflowService {
           sourceBranch: input.sourceBranch,
           targetBranch: input.targetBranch,
           title: input.title.trim(),
-          body,
+          body: input.description?.trim() ?? '',
           authorEmail: canonicalEmail(user.email),
           authorEmailBidx: user.email,
           authorName: user.name,
+          accessRequestLevel: input.accessRequest?.level ?? null,
+          accessRequestNote: note ? note : null,
         })
         .returning({ number: changeRequests.number });
       prNumber = row.number;
@@ -2446,31 +2453,125 @@ export class WorkflowService implements IWorkflowService {
       source: input.sourceBranch,
       target: input.targetBranch,
       authorIdHash: hashEmail(user.email),
-      title: input.title,
     } as const;
     if (pushRefused) {
       // The request exists; its detail reads the published refs, which the
       // refused push never moved — answering the refusal is what the caller
       // needs, not a detail read that may fail on a branch the host lacks.
       this.events?.emit(opened);
-      throw pushRefused;
+      return { number: prNumber, eligible, detail: null, pushRefused, detailError: null };
     }
 
-    const detail = await this.prs.getPrDetail(prNumber, {
-      fresh: true,
-      workspaceId,
-      viewerEmail: user.email,
-    });
-    if (!detail) {
-      throw new WorkflowValidationError(
-        `Created change request #${prNumber} but could not fetch its detail`,
-      );
-    }
+    // The row exists and the push landed: every tab is told, whatever the
+    // read-back below does.
     this.events?.emit(opened);
-    return detail;
+    // Reading the detail back is the caller's answer, not the open: a read
+    // that fails is reported, but it is not allowed to cost the reviewers
+    // their message — the request stands, and a retry of the open meets the
+    // duplicate check, so there is no second chance to tell them.
+    let detail: ChangeRequestDetail | null = null;
+    let detailError: Error | null = null;
+    try {
+      detail = await this.prs.getPrDetail(prNumber, {
+        fresh: true,
+        workspaceId,
+        viewerEmail: user.email,
+      });
+    } catch (err) {
+      detailError = err instanceof Error ? err : new Error(String(err));
+    }
+    if (detail) return { number: prNumber, eligible, detail, pushRefused: null, detailError: null };
+    return {
+      number: prNumber,
+      eligible,
+      detail: null,
+      pushRefused: null,
+      detailError:
+        detailError ?? new WorkflowValidationError(`Created change request #${prNumber} but could not fetch its detail`),
+    };
+    });
+
+    // The request exists in every branch of the outcome — the listeners are
+    // told all the same when the push was refused (`pushPending` says so:
+    // the request is there to find, its commits reach the host with the
+    // branch's next push, and what that is worth to a reviewer is each
+    // listener's call) and when its detail could not be read back. Only
+    // then is the refusal or the failed read the caller's answer.
+    const notified = await this.notifyOpened(outcome.number, input, user, outcome.eligible, outcome.pushRefused !== null);
+    if (outcome.pushRefused) throw outcome.pushRefused;
+    if (outcome.detailError) throw outcome.detailError;
+    return { ...outcome.detail, notified };
+  }
+
+  /**
+   * Tell the deployment's listeners the request was opened (see
+   * {@link IChangeRequestHooks}); the channels that reached the approvers.
+   * Never throws: a listener's failure is the hooks' to log, and a failed
+   * read of the approvers' accounts hands the listeners none of them, counted
+   * as unresolved.
+   */
+  private async notifyOpened(
+    number: number,
+    input: OpenChangeRequestInput,
+    user: AuthUser,
+    eligible: EligibleWritersAtRef,
+    pushPending: boolean,
+  ): Promise<string[]> {
+    const { approvers, unresolvedApprovers } = await this.resolveApprovers(eligible);
+    // Only an address a person can open from outside is handed over; the
+    // relative in-app path (no `PUBLIC_FRONTEND_URL`) is the listener's to
+    // complete.
+    const link = this.prs.linkFor(number);
+    return this.changeRequestHooks.runChangeRequestOpened({
+      number,
+      title: input.title.trim(),
+      sourceBranch: input.sourceBranch,
+      targetBranch: input.targetBranch,
+      openedBy: { id: user.id, email: user.email, name: user.name },
+      approvers,
+      unresolvedApprovers,
+      ...(link.urlNote === undefined ? { url: link.url } : {}),
+      pushPending,
     });
   }
 
+  /**
+   * The distinct people eligible to approve some changed path, as accounts.
+   * Each path's eligibility already expands its roles and groups to the
+   * addresses the access model names (`emails`), so a person is one address
+   * however many paths or roles name them; the addresses are looked up as
+   * live accounts in one read. An address with no account, or with one
+   * switched off, and the built-in `everyone` (anyone signed in may approve;
+   * nobody can be listed for that), are counted, not handed over.
+   */
+  private async resolveApprovers(
+    eligible: EligibleWritersAtRef,
+  ): Promise<{ approvers: ChangeRequestPerson[]; unresolvedApprovers: number }> {
+    const addresses = new Set<string>();
+    let everyone = false;
+    for (const info of eligible?.values() ?? []) {
+      for (const email of info.emails) addresses.add(canonicalEmail(email));
+      if (info.roles.includes(EVERYONE_CANONICAL)) everyone = true;
+    }
+    let accounts = new Map<string, { id: string; email: string; name: string }>();
+    if (addresses.size > 0 && this.accounts) {
+      try {
+        accounts = await this.accounts.findActiveAccountsByEmail([...addresses]);
+      } catch (err) {
+        crLog.warn('the approvers of a change request could not be read as accounts; the listeners are handed none:', { err });
+      }
+    }
+    const approvers: ChangeRequestPerson[] = [];
+    let unresolvedApprovers = everyone ? 1 : 0;
+    for (const address of addresses) {
+      const account = accounts.get(address);
+      if (account) approvers.push({ id: account.id, email: account.email, name: account.name });
+      else unresolvedApprovers++;
+    }
+    approvers.sort((a, b) => a.email.localeCompare(b.email));
+    return { approvers, unresolvedApprovers };
+  }
+
   /**
    * Refresh an existing change request from its target — re-runs the
    * `target → source` auto-merge so the CR diff reflects what the merge
@@ -2707,37 +2808,6 @@ export class WorkflowService implements IWorkflowService {
     return { ...refreshed, updatedPaths };
   }
 
-  listComments(number: number): Promise<ChangeRequestComment[]> {
-    return this.reviewWorkflow.listComments(number);
-  }
-
-  async postComment(
-    number: number,
-    user: AuthUser,
-    input: PostChangeRequestCommentInput,
-    headSha: string,
-  ): Promise<ChangeRequestComment> {
-    const comment = await this.reviewWorkflow.postComment(number, user, input, headSha);
-    this.prs.invalidateDetailCache(number);
-    return comment;
-  }
-
-  async editComment(
-    commentId: string,
-    number: number,
-    user: AuthUser,
-    body: string,
-  ): Promise<ChangeRequestComment> {
-    const updated = await this.reviewWorkflow.editComment(commentId, number, user, body);
-    this.prs.invalidateDetailCache(number);
-    return updated;
-  }
-
-  async deleteComment(commentId: string, number: number, user: AuthUser): Promise<void> {
-    await this.reviewWorkflow.deleteComment(commentId, number, user);
-    this.prs.invalidateDetailCache(number);
-  }
-
   async approveFile(
     number: number,
     path: string,
@@ -2773,6 +2843,7 @@ export class WorkflowService implements IWorkflowService {
       kind: 'approval-changed',
       number,
       path,
+      targetBranch: baseBranch,
       approverUserId: user.id,
       change: 'added',
     });
@@ -2804,6 +2875,7 @@ export class WorkflowService implements IWorkflowService {
       kind: 'approval-changed',
       number,
       path,
+      targetBranch: baseBranch,
       approverUserId: user.id,
       change: 'removed',
     });
@@ -3385,6 +3457,204 @@ export class WorkflowService implements IWorkflowService {
     await this.retireMergedSourceBranch(number, summary.base, user);
   }
 
+  /**
+   * The one rule for who may DECIDE an open change request — close it
+   * (`rejectChangeRequest`) or rewrite what it asks (`updateChangeRequest`):
+   *   - its author (the stored author hash, never anything the caller sends),
+   *   - an admin (write on `roles.yaml` at `origin/<base>`), or
+   *   - the holder of write on every file it changes at `origin/<base>`,
+   *     i.e. anyone who may merge it.
+   * Returns which grant the caller holds, or `null` for none.
+   *
+   * The grants beyond authorship are read at `origin/<base>`, never a local
+   * ref, behind a STRICT fetch: a right revoked a moment ago must not still
+   * pass against a stale tree, so an unreachable origin is a worded 409, not
+   * a refusal. The path list comes from a fresh detail read, so the rule
+   * applies to the current head. A base that cannot be read, or a detail read
+   * that fails (one of the request's branches is gone), kicks the
+   * deleted-branch sweep; see `kickDeletedBranchSweep`.
+   */
+  private async changeRequestDecisionGrant(
+    number: number,
+    user: AuthUser,
+    authorIdHash: string | null,
+    baseBranch: string,
+    resolveWorkspaceId: () => Promise<string>,
+  ): Promise<'author' | 'admin' | 'writes-every-file' | null> {
+    if (authorIdHash && authorIdHash === hashEmail(user.email)) return 'author';
+    const workspaceId = await resolveWorkspaceId();
+    // `force` as well as `strict`: `strict` alone trusts a fetch from
+    // within the cache window, so a right revoked inside it — with origin
+    // down for the refresh — would still pass against the older refs.
+    try {
+      await this.workspaceService.ensureRemotesFetched(workspaceId, { strict: true, force: true });
+    } catch {
+      this.kickDeletedBranchSweep();
+      throw new WorkflowDomainError(
+        `Could not verify the base branch "${baseBranch}" — origin was unreachable. Retry in a moment.`,
+        409,
+      );
+    }
+    const isAdmin = await this.accessControl.canWriteAtRef(
+      workspaceId,
+      `origin/${baseBranch}`,
+      user.email,
+      'roles.yaml',
+    );
+    if (isAdmin === true) return 'admin';
+    // A base that cannot be read decides nothing further: the per-file check
+    // below reads the same tree and would answer the same, after a detail
+    // read and a batch lookup done for nothing.
+    if (isAdmin === null) {
+      this.kickDeletedBranchSweep();
+      throw new WorkflowDomainError(
+        `The base branch "${baseBranch}" could not be resolved — it may have been deleted, or origin was unreachable. A background check is running; retry in a moment.`,
+        409,
+      );
+    }
+    let detail;
+    try {
+      detail = await this.prs.getPrDetail(number, {
+        fresh: true,
+        workspaceId,
+        viewerEmail: user.email,
+        // Only `files[].path` is read below; a patch per file would be one
+        // git subprocess each, generated for nothing.
+        patches: false,
+      });
+    } catch (err) {
+      this.kickDeletedBranchSweep();
+      throw err;
+    }
+    const paths = detail?.files.map((f) => f.path) ?? [];
+    if (paths.length > 0) {
+      const writeMap = await this.accessControl.canWriteBatchAtRef(
+        workspaceId,
+        `origin/${baseBranch}`,
+        user.email,
+        paths,
+      );
+      if (writeMap && paths.every((p) => writeMap.get(p) === true)) return 'writes-every-file';
+    }
+    return null;
+  }
+
+  /**
+   * Change an OPEN request's title and/or description. Who may: the people
+   * who may close it — `changeRequestDecisionGrant`, the one rule both verbs
+   * share. What a request asks belongs to the same people who may decide it.
+   *
+   * `description` replaces the body whole — the body is the description and
+   * nothing else; `appendDescription` adds a paragraph after it as stored.
+   */
+  async updateChangeRequest(
+    number: number,
+    user: AuthUser,
+    input: UpdateChangeRequestFields,
+  ): Promise<ChangeRequest> {
+    const title = input.title === undefined ? undefined : input.title.trim();
+    const description = input.description === undefined ? undefined : input.description.trim();
+    const appended = input.appendDescription === undefined ? undefined : input.appendDescription.trim();
+    if (title === undefined && description === undefined && appended === undefined) {
+      throw new WorkflowValidationError('Give a new title, a new description, or both.');
+    }
+    if (description !== undefined && appended !== undefined) {
+      throw new WorkflowValidationError('Give either a new description or text to append to it, not both.');
+    }
+    if (title !== undefined && title.length === 0) {
+      throw new WorkflowValidationError('A change request needs a title; it cannot be empty.');
+    }
+    if (title !== undefined && title.length > CHANGE_REQUEST_TITLE_MAX) {
+      throw new WorkflowValidationError(
+        `A change request's title is at most ${CHANGE_REQUEST_TITLE_MAX} characters; this one has ${title.length}.`,
+      );
+    }
+    // A replacement is measured here; an append is measured on what it
+    // leaves, inside the transaction, since that depends on the body as
+    // stored.
+    assertDescriptionFits(description);
+    const summary = await this.prs.getPr(number);
+    if (!summary) throw new WorkflowDomainError('change request not found', 404);
+    assertEditable(summary.state);
+
+    // The grants beyond authorship are read in the base branch's own workspace,
+    // resolved only once authorship has not already decided: an author's edit
+    // touches no workspace. Any failure to resolve it kicks the deleted-branch
+    // sweep, as delete does.
+    const grant = await this.changeRequestDecisionGrant(
+      number,
+      user,
+      summary.authorId ?? null,
+      summary.base,
+      async () => {
+        try {
+          return (await this.workspaceService.getOrCreateForBranch(summary.base)).id;
+        } catch (err) {
+          this.kickDeletedBranchSweep();
+          throw err;
+        }
+      },
+    );
+    if (grant === null) {
+      throw new WorkflowDomainError(
+        "Only the request's author, an admin, or someone who may approve every file it changes can edit its title and description.",
+        403,
+      );
+    }
+
+    // The body is rewritten from the row as stored, not from the summary read
+    // above, inside one transaction holding the row's lock (`FOR UPDATE`) from
+    // the read to the write: a merge or close that won the race leaves no open
+    // row and refuses the edit instead of being written over, and an edit
+    // racing this one waits for it and then applies to the body it left — so
+    // two appends racing each other both land. The lock, never a comparison of
+    // the stored body, is what serialises them: `body` is encrypted with a
+    // fresh IV on every write, so its ciphertext never equals a re-encryption
+    // of the same text.
+    const updated = await this.db.transaction(async (tx) => {
+      const [row] = await tx
+        .select({ body: changeRequests.body })
+        .from(changeRequests)
+        .where(and(eq(changeRequests.number, number), eq(changeRequests.state, 'open')))
+        .limit(1)
+        .for('update');
+      if (!row) return false;
+      // The body IS the description: a replacement is written as given, an
+      // append goes after the text as stored. An access request's level and
+      // note live on their own columns and are never touched by an edit.
+      const body =
+        appended === undefined
+          ? description
+          : [row.body.trim(), appended].filter((s) => s.length > 0).join('\n\n');
+      // What an append leaves is measured against the same ceiling as a
+      // replacement; a refusal here rolls the transaction back and writes
+      // nothing.
+      assertDescriptionFits(body);
+      const written = await tx
+        .update(changeRequests)
+        .set({
+          ...(title !== undefined ? { title } : {}),
+          ...(body !== undefined ? { body } : {}),
+          updatedAt: new Date(),
+        })
+        .where(and(eq(changeRequests.number, number), eq(changeRequests.state, 'open')))
+        .returning({ id: changeRequests.id });
+      return written.length > 0;
+    });
+    this.prs.invalidateDetailCache(number);
+    if (!updated) {
+      const fresh = await this.prs.getPr(number);
+      if (!fresh) throw new WorkflowDomainError('change request not found', 404);
+      assertEditable(fresh.state);
+      throw new WorkflowDomainError('This change request changed while it was being edited. Retry in a moment.', 409);
+    }
+    crLog.info(`#${number} title/description edited`);
+    this.events?.emit({ kind: 'change-request-edited', number });
+    const fresh = await this.prs.getPr(number);
+    if (!fresh) throw new WorkflowDomainError('change request not found', 404);
+    return fresh;
+  }
+
   /**
    * Close an open change request whose diff has EMPTIED — everything it
    * proposed has since landed on the target, been reverted, or been undone on
@@ -3891,20 +4161,13 @@ export class WorkflowService implements IWorkflowService {
 
 
   /**
-   * Reject (close-without-merging) a change request. Per PLAN.md spec, the
-   * authorized set is:
-   *   - the CR author (hash-matched against the body marker), OR
-   *   - any user with write permission to *every* changed file on the
-   *     target branch, OR
-   *   - an admin (write on `roles.yaml` at `origin/<target>`).
+   * Reject (close-without-merging) a change request. Who may: the people
+   * `changeRequestDecisionGrant` names — its author, an admin, or the holder
+   * of write on every file it changes at `origin/<target>`.
    *
-   * The first and third are enforced by the underlying `cancelPr`. The
-   * second is the workflow's broader rule; we check it here and, on
-   * success, spoof `authorIdHash` to `hashEmail(user.email)` so `cancelPr`
-   * accepts the call via its existing "viewer is author" branch. The
-   * spoofing is safe because no caller outside this method can construct
-   * an `authorIdHash` that matches its own email's hash — `cancelPr`
-   * receives the hash via this internal call only.
+   * A caller holding a grant reaches the underlying `cancelPr` as the author
+   * (its `authorIdHash` is set to the caller's own hash); one holding none is
+   * passed through unchanged, and `cancelPr` refuses it.
    */
   async rejectChangeRequest(
     number: number,
@@ -3915,49 +4178,22 @@ export class WorkflowService implements IWorkflowService {
     workspaceId: string,
   ): Promise<CancelChangeRequestResult> {
     let effectiveAuthorIdHash = authorIdHash;
-    const callerHash = hashEmail(user.email);
-    const callerIsAuthor = !!(authorIdHash && authorIdHash === callerHash);
-
-    if (!callerIsAuthor) {
-      // Broader rule: write perm on every changed file at origin/<target>.
-      // The path list comes from the PR detail — fetch fresh so the rule
-      // applies against the current head (a stale list would let a user
-      // reject a CR whose files they no longer all own).
-      let detail;
-      try {
-        detail = await this.prs.getPrDetail(number, {
-          fresh: true,
-          workspaceId,
-          viewerEmail: user.email,
-          // Only `files[].path` is read below; a patch per file would be one
-          // git subprocess each, generated for nothing, on every reject by a
-          // non-author.
-          patches: false,
-        });
-      } catch (err) {
-        // The detail read resolves both branch tips (`resolvePrShas`), so a
-        // request one of whose branches is gone fails HERE, on the verb that
-        // exists to get rid of it. Kick the sweep (which proves the absence
-        // and closes the stranded rows) and surface the failure; see
-        // `kickDeletedBranchSweep`.
-        this.kickDeletedBranchSweep();
-        throw err;
-      }
-      const paths = detail?.files.map((f) => f.path) ?? [];
-      if (paths.length > 0) {
-        const writeMap = await this.accessControl.canWriteBatchAtRef(
-          workspaceId,
-          `origin/${baseBranch}`,
-          user.email,
-          paths,
-        );
-        const writesAll = !!writeMap && paths.every((p) => writeMap.get(p) === true);
-        if (writesAll) {
-          // Spoof so the underlying `cancelPr` authorizes via its viewer-
-          // is-author branch. The admin branch (write on roles.yaml) still
-          // works alongside — `cancelPr` checks both.
-          effectiveAuthorIdHash = callerHash;
-        }
+    // A request that is no longer open is refused by `cancelPr` with its own
+    // already-applied / already-cancelled answer; no grant is read for it.
+    if (state === 'open') {
+      const grant = await this.changeRequestDecisionGrant(
+        number,
+        user,
+        authorIdHash,
+        baseBranch,
+        async () => workspaceId,
+      );
+      if (grant !== null) {
+        // Spoof so the underlying `cancelPr` authorizes via its viewer-is-
+        // author branch. The spoofing is safe because no caller outside this
+        // method can construct an `authorIdHash` that matches its own email's
+        // hash — `cancelPr` receives the hash via this internal call only.
+        effectiveAuthorIdHash = hashEmail(user.email);
       }
     }
 
@@ -4694,37 +4930,30 @@ export class WorkflowService implements IWorkflowService {
   }
 
   /**
-   * Build the `## Affected owners` markdown block that gets appended to
-   * the CR body. Lists the eligible approvers (roles + named users) per
-   * changed path, per the access tree on `origin/<targetBranch>` — the same
-   * tree the approval gate uses server-side, so what the body advertises
-   * matches who can actually approve at merge time. The per-path list is
-   * capped (see {@link formatAffectedOwnersBlock}) so the body stays within
-   * the `gh pr create --body` arg limit on large changesets.
-   *
-   * Returns the empty string when there are no touched paths or no
-   * resolvable eligibility — keeps the body clean rather than printing
-   * a stub heading.
+   * The eligible approvers (roles + named users, and the addresses they
+   * expand to) per changed path, per the access tree on
+   * `origin/<targetBranch>` — the same tree the approval gate uses
+   * server-side, so what the body advertises and the listeners are told
+   * matches who can actually approve at merge time. Null when there are no
+   * touched paths or no resolvable eligibility: a missing affected-owners
+   * block is cosmetic, not a reason to abort the open.
    */
-  private async buildAffectedOwnersBlock(
+  private async eligibleWritersFor(
     workspaceId: string,
     targetBranch: string,
     paths: string[],
-  ): Promise<string> {
-    if (paths.length === 0) return '';
-    let resolved: Awaited<ReturnType<IAccessControl['eligibleWritersForPathsAtRef']>> = null;
+  ): Promise<EligibleWritersAtRef> {
+    if (paths.length === 0) return null;
     try {
-      resolved = await this.accessControl.eligibleWritersForPathsAtRef(
+      return await this.accessControl.eligibleWritersForPathsAtRef(
         workspaceId,
         `origin/${targetBranch}`,
         paths,
       );
     } catch (err) {
       log.warn('eligibleWritersForPathsAtRef failed:', { err });
+      return null;
     }
-    if (!resolved || resolved.size === 0) return '';
-
-    return formatAffectedOwnersBlock(paths, resolved);
   }
 
   async updateBranch(