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

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

@@ -5,12 +5,11 @@ import type {
   ChangedPathPair,
   FileApproval,
 } from '@bevel-software/platform-shared';
-import type { IToolRegistry, JsonSchema } from '../../tool-registry/tool.contract.js';
-import { ToolError, type ToolContext, type ToolHandler } from '../../tool-helpers/tool.contract.js';
-import { toolDef } from '../../tool-helpers/tool-def.js';
-import type { ToolHandlerFactory } from '../../tool-helpers/tool-handler.js';
+import type { IToolRegistry, JsonSchema } from '../../tool-registry/index.js';
+import { ToolError, type ToolContext, type ToolHandler, toolDef } from '../../tool-helpers/index.js';
+import type { ToolHandlerFactory } from '../../tool-helpers/index.js';
 import type { KbContext } from '../../../shared/kb-context.js';
-import type { IAccessControl } from '../../access/access-control.interface.js';
+import type { IAccessControl } from '../../access/index.js';
 import { readablePathsAt } from '../read-on-branch.js';
 import {
   PER_PAGE_DEFAULT,
@@ -23,21 +22,19 @@ import {
   pageOf,
   pagingOf,
   statesFor,
-  toCrComment,
   toCrDetail,
   toCrFile,
   toCrReviews,
   toCrSummary,
   toCrViewer,
   visibleBlockers,
-  visibleComments,
 } from './change-request-read-shape.js';
 
 /**
- * The five read tools over change requests, named and shaped after GitHub's
+ * The four read tools over change requests, named and shaped after GitHub's
  * pull-request API: `list_change_requests`, `get_change_request`,
- * `list_change_request_files`, `list_change_request_reviews` and
- * `list_change_request_comments`. The mapping lives in
+ * `list_change_request_files` and `list_change_request_reviews`. The mapping
+ * lives in
  * `change-request-read-shape.ts`; this file does the IO and the access
  * filtering.
  *
@@ -49,7 +46,7 @@ import {
  * The shape module's header says what that changed, field by field.
  *
  * None of them writes anything — every handler is registered `write: false`,
- * so a read-scoped connection key may call all five, and every service call
+ * so a read-scoped connection key may call all four, and every service call
  * below is a read.
  *
  * ## What the caller may see
@@ -58,7 +55,7 @@ import {
  * detail to any signed-in viewer; only the file CONTENT routes gate per path
  * (`canReadAtRef` at `origin/<base>`, with an unresolvable verdict as a
  * denial). These tools apply that same content gate to the whole payload,
- * because an agent's answer is the content: a file list, a reviewer's comment
+ * because an agent's answer is the content: a file list, an approval
  * and a gate warning all name paths, and an agent hands what it reads to
  * whoever it is talking to.
  *
@@ -75,11 +72,10 @@ import {
  *     answered 404 for;
  *   - files the caller may not read are left out and counted in
  *     `withheldFiles`, never named (decision 2 on the ticket);
- *   - comments on a withheld file, and gate blockers naming one, go the same
- *     way, with their own counts; a REPLY goes when the comment it replies to
- *     does, up the whole chain;
- *   - `body` is the author's own description, with the generated
- *     `## Affected owners` block cut off the end — see `authorsDescription`;
+ *   - approvals and gate blockers naming a withheld file go the same way, with
+ *     their own counts;
+ *   - `body` is the request's description, verbatim: Hexis writes nothing of
+ *     its own into it, so a path it names is one its author chose to write;
  *   - a request with no readable file and no claim of authorship answers 404,
  *     indistinguishable from a number that was never issued.
  *
@@ -172,7 +168,7 @@ export function registerChangeRequestReadTools(
     properties: {
       login: { type: 'string', description: 'Hash-derived login (`user-<12 hex>`); no raw address.' },
       name: { type: 'string' },
-      email: { type: 'string', description: 'Set for comment authors and approvers only.' },
+      email: { type: 'string', description: 'Set for approvers only.' },
     },
     required: ['login'],
   };
@@ -189,7 +185,7 @@ export function registerChangeRequestReadTools(
       sourceBranch: { type: 'string', description: 'The branch the change comes from.' },
       targetBranch: { type: 'string', description: 'The branch it would be applied to.' },
       createdAt: { type: 'string', description: 'ISO timestamp.' },
-      updatedAt: { type: 'string', description: 'ISO timestamp — the close time of a closed request, else the creation time.' },
+      updatedAt: { type: 'string', description: 'ISO timestamp — the latest of the request\'s creation time, its row `updated_at` (a title or description edit, a reopen) and its close time; approvals do not affect it.' },
       changedFiles: { type: 'integer', description: 'How many of its files YOU may read.' },
       withheldFiles: { type: 'integer', description: 'How many of its files you may not read. Never named.' },
       lastApplyFailure: {
@@ -294,7 +290,7 @@ export function registerChangeRequestReadTools(
       // move under its new name alone, so a file moved out of a folder this
       // caller cannot open looked readable here while the detail — which pairs
       // the two names — refused it: the list advertised a change request that
-      // all four by-number tools answered 404 for, and counted its withheld
+      // all three by-number tools answered 404 for, and counted its withheld
       // file as zero. One notion of a readable file, shared with the detail
       // through the same `fileIsReadable`, is what stops the two disagreeing.
       const byBase = new Map<string, string[]>();
@@ -354,7 +350,7 @@ export function registerChangeRequestReadTools(
       type: 'object',
       properties: {
         ...(changeRequestSchema as { properties: Record<string, JsonSchema> }).properties,
-        body: { type: 'string', description: "What the AUTHOR wrote. The generated `## Affected owners` block Hexis appends — which names every changed path — is cut off the end; read who must approve each file from `list_change_request_files`." },
+        body: { type: 'string', description: "The request's description, exactly as its author or a later edit left it. Who must approve each file is not in it; read that from `list_change_request_files`." },
         headSha: { type: 'string', description: 'The source commit this answer describes. Absent when no commit could be resolved.' },
         baseSha: { type: 'string', description: 'The target commit it is read against. Absent when no commit could be resolved.' },
         mergeable: { type: 'boolean', description: "Hexis's merge gate, which also waits on the per-file approvals. May be false while `mergeBlockedReasons` is empty, if a blocker names a file you may not read." },
@@ -501,9 +497,9 @@ export function registerChangeRequestReadTools(
       "List a change request's reviews (GitHub: list reviews): who approved what, and when. " +
       'Hexis approves per FILE, so each entry names a `reviewer`, the `files` they approved and ' +
       'the time of the latest of them; `stale` is true for approvals a later push invalidated. ' +
-      'Nothing records who DECLINED a request, so no entry reports one — a reviewer\'s objection ' +
-      'is a comment. Read-only: an entry keeps only the files you may read, and one with no ' +
-      'readable file at all is counted in `withheldReviews` rather than named.',
+      'Nothing records who DECLINED a request, so no entry reports one. Read-only: an entry keeps ' +
+      'only the files you may read, and one with no readable file at all is counted in ' +
+      '`withheldReviews` rather than named.',
     inputs: {
       type: 'object',
       properties: {
@@ -549,74 +545,11 @@ export function registerChangeRequestReadTools(
       return { reviews: items, withheldReviews, ...paging };
     },
   });
-
-  // ── list_change_request_comments ──────────────────────────────────────────
-
-  mount({
-    name: 'list_change_request_comments',
-    description:
-      "List a change request's comments (GitHub: list review comments and issue comments — Hexis " +
-      'keeps both in one thread). Each carries its `author`, `body`, `path` and `line` when it is ' +
-      'anchored to a file, `parentId` when it is a reply (the same id you pass to ' +
-      '`post_change_request_comment` to reply yourself), and its times. Read-only. A comment on a ' +
-      'file you may not read is left out and counted in `withheldComments`, and so is a reply to ' +
-      'a comment that was left out.',
-    inputs: {
-      type: 'object',
-      properties: {
-        number: { type: 'integer', minimum: 1, description: 'Change request number.' },
-        ...pagingInputs,
-      },
-      required: ['number'],
-      additionalProperties: false,
-    },
-    outputs: {
-      type: 'object',
-      properties: {
-        comments: {
-          type: 'array',
-          items: {
-            type: 'object',
-            properties: {
-              id: { type: 'string', description: 'Pass as `parentId` to `post_change_request_comment` to reply.' },
-              author: userSchema,
-              body: { type: 'string' },
-              path: { type: 'string', description: 'Repository-relative path, on a file-level or inline comment.' },
-              line: { type: 'integer', description: 'Set on an inline comment.' },
-              parentId: { type: 'string', description: 'The comment this one replies to.' },
-              headSha: { type: 'string', description: 'The commit the comment was anchored to.' },
-              createdAt: { type: 'string', description: 'ISO timestamp.' },
-              updatedAt: { type: 'string', description: 'ISO timestamp; present once edited.' },
-            },
-            required: ['id', 'author', 'body', 'headSha', 'createdAt'],
-          },
-        },
-        withheldComments: { type: 'integer', description: 'Comments on a file you may not read, and replies to those.' },
-        ...pagingOutputs,
-      },
-      required: ['comments', 'withheldComments', ...pagingRequired],
-    },
-    handler: async (args, ctx: ToolContext) => {
-      const number = numberArg(args);
-      const { perPage, page } = pagingOf(args);
-      const scoped = await scopedDetail(ctx, number, { patches: false });
-      // A comment with no path is about the request as a whole; one with a path
-      // is as readable as that path is NAMEABLE here. A reply inherits its
-      // parent's verdict up the chain — see `visibleComments`.
-      const { visible, withheld } = visibleComments(scoped.detail.comments, scoped.mayShow);
-      const { items, ...paging } = pageOf(visible, perPage, page);
-      return {
-        comments: items.map(toCrComment),
-        withheldComments: withheld,
-        ...paging,
-      };
-    },
-  });
 }
 
 /**
  * The detail of request `number` with the access filter applied, or a 404 —
- * the one place the four by-number tools get their data, so they cannot
+ * the one place the three by-number tools get their data, so they cannot
  * drift on who may see what.
  */
 export interface ScopedDetail {
@@ -634,8 +567,8 @@ export interface ScopedDetail {
    * The two differ on exactly one shape, and it is the shape that leaks: a
    * file moved out of a folder the caller may not read is readable under
    * its NEW name, yet `fileIsReadable` withholds it whole (its diff shows the
-   * old path's content). Anything keyed on that new path — an approval, a
-   * comment anchored to it — would otherwise say the request touches a file
+   * old path's content). Anything keyed on that new path — an approval of
+   * it — would otherwise say the request touches a file
    * the file tool refuses to list, under a name it refuses to print.
    */
   mayShow: (path: string) => boolean;
@@ -686,15 +619,10 @@ export function changeRequestScope(
     });
     if (!detail) throw notFound(number);
     const viewerIsAuthor = isAuthor(detail, ctx.user.email);
-    // Comment paths join the batch: a comment may name a file the request no
-    // longer changes, and without a verdict of its own it would be withheld
-    // from a caller who can read it perfectly well.
-    const commentPaths = detail.comments.map((c) => c.path).filter((p): p is string => !!p);
     // BOTH names of every file: a move is judged on its old path as well as
     // its new one, because the diff of a move shows what was at the old one.
     const readable = await readablePaths(ctx, workspaceId, detail.base, [
       ...detail.files.flatMap(pathsOf),
-      ...commentPaths,
     ]);
     const mayRead = (path: string) => readable.has(path);
     const readableFiles = detail.files.filter((f) => fileIsReadable(f, mayRead));
@@ -703,7 +631,7 @@ export function changeRequestScope(
     }
     // Every name a withheld file goes by, so a gate warning quoting either
     // spelling is caught by the blocker filter — and so `mayShow` catches
-    // whichever spelling an approval or a comment happens to use.
+    // whichever spelling an approval happens to use.
     const withheldFilePaths = detail.files
       .filter((f) => !fileIsReadable(f, mayRead))
       .flatMap(pathsOf);

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

@@ -65,7 +65,11 @@ export interface ChangeRequestApprovers {
   path: string;
   /** Roles that confer approval here. `everyone` means any signed-in approver. */
   roles: string[];
-  /** Approvers named directly, by display name. */
+  /**
+   * Approvers named directly: each by display name, or by email when the
+   * access tree resolved no name (an owner listed only by email has none).
+   * Never a blank string — an approver with neither is left out.
+   */
   users: string[];
   /** True once an eligible approver has approved at the request's current head. */
   approved: boolean;
@@ -129,12 +133,22 @@ export function changeKindOf(status: PrFileStatus | undefined): ChangeKind {
   }
 }
 
+/**
+ * How the answer names one approver: the display name when there is one, the
+ * email otherwise. The resolver hands back an empty name for an owner that
+ * `roles.yaml` lists by email, so the name alone left the agent `[""]` while
+ * `mergeBlockedReasons` named the same owner by email.
+ */
+function approverName(user: { name?: string; email?: string }): string {
+  return user.name?.trim() || user.email?.trim() || '';
+}
+
 function approversOf(approval: FileApproval): ChangeRequestApprovers {
   const eligible = approval.eligibleApprovers ?? { roles: [], users: [] };
   return {
     path: approval.path,
     roles: eligible.roles ?? [],
-    users: (eligible.users ?? []).map((u) => u.name),
+    users: (eligible.users ?? []).map(approverName).filter((n) => n !== ''),
     approved: approval.isApproved,
     inMergeGate: approval.inMergeGate,
     // Anything but an explicit `true` is unresolved — a detail built before

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

@@ -1,16 +1,15 @@
 import type { Router, RequestHandler } from 'express';
-import type { IToolRegistry, JsonSchema } from '../../tool-registry/tool.contract.js';
-import { ToolError, hasHttpStatus, type ToolContext, type ToolHandler } from '../../tool-helpers/tool.contract.js';
+import type { IToolRegistry, JsonSchema } from '../../tool-registry/index.js';
+import { ToolError, hasHttpStatus, type ToolContext, type ToolHandler, toolDef } from '../../tool-helpers/index.js';
 import { isCommitSha } from '../../../shared/git.contract.js';
-import { toolDef } from '../../tool-helpers/tool-def.js';
-import type { ToolHandlerFactory } from '../../tool-helpers/tool-handler.js';
-import { requireInternalSource } from '../../tool-auth/tool-auth.middleware.js';
-import type { IAccessControl } from '../../access/access-control.interface.js';
+import type { ToolHandlerFactory } from '../../tool-helpers/index.js';
+import { requireInternalSource } from '../../tool-auth/index.js';
+import type { IAccessControl } from '../../access/index.js';
 import { assertAgentWriteAllowed, notifyAgentRead, SESSION_ID_INPUT, type AgentAccessGate } from '../../workspace/index.js';
 import { readablePathsAt, readableAtCommits, assertReadableAtCommits } from '../read-on-branch.js';
 import type { KbContext } from '../../../shared/kb-context.js';
 import { workspaceIdForBranch } from '../../../shared/workspace-id.js';
-import { assertInsideRepo, normalizePathArgs } from '../../kb-fs/repo-path.js';
+import { assertInsideRepo, normalizePathArgs } from '../../kb-fs/index.js';
 import { RETIRED_TOOL_MESSAGES } from '@bevel-software/platform-mcp-core';
 import {
   CHANGE_REQUEST_INCLUDES,
@@ -30,7 +29,7 @@ const protectedInline = (kb: Pick<KbContext, 'protectedBranches'>) =>
   [...kb.protectedBranches].map((b) => `\`${b}\``).join(' / ');
 
 // Output sub-schemas for the git-aliased workflow payloads (Branch, Change,
-// ChangeRequestComment, …). Defined once and referenced by the individual tool
+// ChangeRequest, …). Defined once and referenced by the individual tool
 // defs below so each tool still declares its own `outputs`.
 const branchSchema: JsonSchema = {
   type: 'object',
@@ -75,7 +74,7 @@ const changeRequestApproversSchema: JsonSchema = {
   properties: {
     path: { type: 'string' },
     roles: { type: 'array', items: { type: 'string' }, description: 'Roles that confer approval here; `everyone` means any signed-in approver.' },
-    users: { type: 'array', items: { type: 'string' }, description: 'Approvers named directly, by display name.' },
+    users: { type: 'array', items: { type: 'string' }, description: 'Approvers named directly: each by display name, or by email when the access tree resolved no name. Never a blank string.' },
     approved: { type: 'boolean', description: 'True once an eligible approver has approved at the current head.' },
     inMergeGate: { type: 'boolean', description: 'False when the merge gate does not bind this path — then nobody has to approve it.' },
     approversUnknown: { type: 'boolean', description: 'Present when the access tree could not be resolved: empty `roles`/`users` means unknown, not nobody.' },
@@ -83,22 +82,6 @@ const changeRequestApproversSchema: JsonSchema = {
   required: ['path', 'roles', 'users', 'approved', 'inMergeGate'],
 };
 
-const commentSchema: JsonSchema = {
-  type: 'object',
-  properties: {
-    id: { type: 'string' },
-    author: { type: 'object', properties: { email: { type: 'string' }, name: { type: 'string' } }, required: ['email', 'name'] },
-    body: { type: 'string' },
-    path: { type: 'string', description: 'Set for file-level / inline comments.' },
-    line: { type: 'integer', description: 'Set for inline comments.' },
-    headSha: { type: 'string', description: 'Head the comment was anchored to.' },
-    parentId: { type: 'string', description: 'Root comment id when this is a reply.' },
-    createdAt: { type: 'string', description: 'ISO timestamp.' },
-    updatedAt: { type: 'string', description: 'ISO timestamp; present once edited.' },
-  },
-  required: ['id', 'author', 'body', 'headSha', 'createdAt'],
-};
-
 const changeRequestUrlSchema: JsonSchema = {
   type: 'string',
   description:
@@ -107,13 +90,6 @@ const changeRequestUrlSchema: JsonSchema = {
 };
 const changeRequestUrlNoteSchema: JsonSchema = { type: 'string', description: 'Present only when `url` is relative — how to get absolute links.' };
 
-/** The link to a change request, for a tool whose payload is not the change request itself. */
-const changeRequestLinkSchema: JsonSchema = {
-  type: 'object',
-  properties: { number: { type: 'integer' }, url: changeRequestUrlSchema, urlNote: changeRequestUrlNoteSchema },
-  required: ['number', 'url'],
-};
-
 /** `{ number, url, urlNote? }` of a change request summary or detail. */
 function linkOf(cr: { number: number; url: string; urlNote?: string }): { number: number; url: string; urlNote?: string } {
   return { number: cr.number, url: cr.url, ...(cr.urlNote ? { urlNote: cr.urlNote } : {}) };
@@ -183,7 +159,9 @@ export function registerWorkflowTools(
   /**
    * Whether the caller may see change request `number` — `get_change_request`'s
    * own gate (`changeRequestScope(...).maySee`). `delete_branch` neither names
-   * nor links a request it answers no for.
+   * nor links a request it answers no for, and `update_change_request` answers
+   * such a request exactly as `get_change_request` does (404) before reading its
+   * state or who may edit it.
    */
   maySeeChangeRequest: (ctx: ToolContext, number: number) => Promise<boolean>,
   /**
@@ -472,7 +450,7 @@ export function registerWorkflowTools(
         sourceBranch: { type: 'string', minLength: 1, description: 'The draft branch carrying the changes.' },
         targetBranch: { type: 'string', minLength: 1, description: `The branch to apply to (e.g. '${kb.defaultBranch}').` },
         title: { type: 'string', minLength: 1, maxLength: 256, description: 'Short imperative title (≤256 chars).' },
-        description: { type: 'string', description: 'Optional markdown body shown verbatim to reviewers.' },
+        description: { type: 'string', maxLength: 64_000, description: 'Optional markdown body shown verbatim to reviewers (≤64,000 chars).' },
         include: {
           type: 'array',
           items: { type: 'string', enum: [...CHANGE_REQUEST_INCLUDES] },
@@ -507,66 +485,62 @@ export function registerWorkflowTools(
   });
 
   mount({
-    name: 'post_change_request_comment',
+    name: 'update_change_request',
     description:
-      'Post a review comment on a change request. Three modes: general (no path), file-level (path), ' +
-      'inline (path + line). Anchors to the CR\'s current head.',
+      'Change the title and/or the description of an OPEN change request. Allowed for its author and for anyone ' +
+      'who may merge it (an admin, or someone who may approve every file it changes) — the same rule as the app\'s ' +
+      'Edit control; anyone else is refused (403), and so is a merged or closed request (409), in words. ' +
+      "`description` replaces the request's description whole — the text `get_change_request` answers as `body`; " +
+      '`appendDescription` instead adds a paragraph after the description as it stands when the write happens, so two ' +
+      'notes racing each other both land (never together with `description`). Give at least one field; an absent one keeps its text. ' +
+      '`get_change_request` answers the new text at once. A request you may not see answers 404, as `get_change_request` does.',
     inputs: {
       type: 'object',
       properties: {
         number: { type: 'integer', minimum: 1, description: 'Change request number.' },
-        body: { type: 'string', minLength: 1, description: 'Comment body (Markdown).' },
-        path: { type: 'string', description: `Repository-relative path of the changed file for a file-level/inline comment (e.g. \`KnowledgeBase/Foo.md\`); the workspace form \`${kbDirName}/KnowledgeBase/Foo.md\`, with or without a leading slash, names the same file.` },
-        line: { type: 'integer', minimum: 1, description: 'Line number for an inline comment. Requires `path`.' },
-        parentId: { type: 'string', description: 'Comment id to reply to.' },
+        title: { type: 'string', minLength: 1, maxLength: 256, description: 'The new title (≤256 chars).' },
+        description: { type: 'string', maxLength: 64_000, description: 'The new description (Markdown, ≤64,000 chars); an empty string clears it.' },
+        appendDescription: { type: 'string', maxLength: 64_000, description: 'A paragraph (Markdown) added after the description as stored at the moment of the write; what it leaves is ≤64,000 chars. Not together with `description`.' },
       },
-      required: ['number', 'body'],
+      required: ['number'],
       additionalProperties: false,
     },
     outputs: {
       type: 'object',
       properties: {
-        comment: { ...commentSchema, description: 'The posted review comment.' },
-        changeRequest: { ...changeRequestLinkSchema, description: 'The change request commented on.' },
+        number: { type: 'integer' },
+        url: changeRequestUrlSchema,
+        urlNote: changeRequestUrlNoteSchema,
+        title: { type: 'string', description: 'The title as it now stands.' },
       },
-      required: ['comment', 'changeRequest'],
+      required: ['number', 'url', 'title'],
     },
     write: true,
-    // Keyed by change-request number, not a draft — the workspace is only a
-    // scratch clone to run the repo op in, so resolve any existing one rather
-    // than requiring a `branch`.
+    // Keyed by change-request number; the service resolves the request's own
+    // base branch for the permission check.
     skipBranch: true,
     handler: async (args, ctx: ToolContext) => {
+      const title = typeof args.title === 'string' ? args.title : undefined;
+      const description = typeof args.description === 'string' ? args.description : undefined;
+      const appendDescription = typeof args.appendDescription === 'string' ? args.appendDescription : undefined;
+      if (title === undefined && description === undefined && appendDescription === undefined) {
+        throw new ToolError('Give a new `title`, a new `description`, or an `appendDescription`.', 400);
+      }
+      // A request the caller may not read is not found — never a 403 or a
+      // state-specific 409, which would tell a probe that it exists.
       const number = args.number as number;
-      const line = typeof args.line === 'number' ? args.line : undefined;
-      // A change request's files are repository-relative; the workspace form
-      // Copy path gives (`/<kbDirName>/…`, its slash already dropped by the
-      // mount) carries the clone folder, which no changed file would match.
-      const path = typeof args.path === 'string' ? stripKbDir(args.path, kbDirName) : undefined;
-      if (line !== undefined && !path) {        throw new ToolError('`path` is required when `line` is provided (inline comments anchor to a file).', 400);
+      if (!(await maySeeChangeRequest(ctx, number))) {
+        throw new ToolError(`Change request #${number} not found.`, 404);
       }
-      const detail = await ctx.workflowService.getChangeRequestDetail(number, {
-        fresh: true,
-        workspaceId: await repoGlobalWorkspaceId(ctx),
-        viewerEmail: ctx.user.email,
+      const updated = await ctx.workflowService.updateChangeRequest(number, ctx.user, {
+        title,
+        description,
+        appendDescription,
       });
-      if (!detail) {        throw new ToolError(`Change request #${number} not found.`, 404);
-      }
-      // A comment anchors to a commit, and a DECLINED request has none to anchor
-      // to: nothing durable records what it proposed, so its detail carries no
-      // head (see `changeSourceFor`). Say that, rather than letting the service's
-      // `head sha is required` surface as a 400 about an argument the caller
-      // never passed. An APPLIED request still takes comments — its head is the
-      // source tip its merge commit recorded.
-      if (!detail.headSha) {        throw new ToolError(`Change request #${number} is ${detail.state} and has no commit to anchor a comment to.`, 409);
-      }
-      const comment = await ctx.workflowService.postComment(
-        number,
-        ctx.user,
-        { body: args.body as string, path, line, parentId: typeof args.parentId === 'string' ? args.parentId : undefined },
-        detail.headSha,
-      );
-      return { comment, changeRequest: linkOf(detail) };
+      return {
+        ...linkOf(updated),
+        title: updated.title,
+      };
     },
   });
 

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

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

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

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