canopycms 0.6.0 → 0.7.1

package/dist/api/branch-review.js

@@ -1,43 +1,121 @@
+import { z } from 'zod';
 import { branchParamSchema } from './validators.js';
 import { toBranchListItem } from './branch.js';
 import { getBranchMetadataFileManager } from '../branch-metadata.js';
 import { defineEndpoint } from './route-builder.js';
 import { syncConvertToDraft } from './github-sync.js';
-const requestChangesHandler = async (gc, ctx, req, _params) => {
+import { syncPrComments } from './pr-comment-sync.js';
+import { CommentStore } from '../comment-store.js';
+import { getErrorMessage } from '../utils/error.js';
+import { REQUEST_CHANGES_NOTE_MAX_LENGTH } from '../authorization/review-role.js';
+import { getBranchProtection } from '../authorization/index.js';
+/** Optional on the wire: a bodiless request means no note. */
+const requestChangesBodySchema = z
+    .object({ note: z.string().trim().max(REQUEST_CHANGES_NOTE_MAX_LENGTH).optional() })
+    .optional();
+const NOTE_NOT_SAVED_WARNING = "Changes were requested, but your note couldn't be saved.";
+/**
+ * The 409 for a branch that left review before this request arrived, because the reviewer's page
+ * was stale. `action` finishes "so ..." for any status that has no wording of its own.
+ */
+const staleStatusError = (status, action) => status === 'editing'
+    ? "This branch is no longer in review: it's back with its editor."
+    : status === undefined
+        ? `This branch's status can't be read, so ${action}.`
+        : `This branch is ${status}, so ${action}.`;
+const canRequestChangesFrom = (status) => status === 'submitted' || status === 'approved';
+const requestChangesConflict = (status) => ({
+    ok: false,
+    status: 409,
+    error: staleStatusError(status, "changes can't be requested"),
+});
+const approveConflict = (status) => ({
+    ok: false,
+    status: 409,
+    error: status === 'approved'
+        ? 'This branch is already approved.'
+        : staleStatusError(status, "it can't be approved"),
+});
+const requestChangesHandler = async (gc, ctx, req, _params, body) => {
     const { branchContext } = gc;
-    if (branchContext.branch.status !== 'submitted') {
-        return {
-            ok: false,
-            status: 400,
-            error: `Cannot request changes on branch with status '${branchContext.branch.status}'. Only 'submitted' branches can have changes requested.`,
-        };
+    if (!canRequestChangesFrom(branchContext.branch.status)) {
+        return requestChangesConflict(branchContext.branch.status);
     }
     await syncConvertToDraft(ctx, branchContext);
     const meta = getBranchMetadataFileManager(branchContext.branchRoot, branchContext.baseRoot);
-    const updated = await meta.save({
-        branch: { name: branchContext.branch.name, status: 'editing' },
+    // The status the guard read can be stale by now, so the save checks the status on disk, in the
+    // same step that writes. A branch that left review meanwhile is refused, and the draft
+    // conversion above is left as it is: withdraw converts the pull request to a draft too, and a
+    // merged one cannot be converted.
+    let found;
+    const updated = await meta.saveIf({ branch: { name: branchContext.branch.name, status: 'editing' } }, (existing) => {
+        found = existing?.branch.status;
+        return canRequestChangesFrom(found);
     });
-    // TODO: Optionally record comment in .canopy-meta/comments.json when comment system is implemented
+    if (!updated)
+        return requestChangesConflict(found);
+    // The note is written after the status change so a failed write never blocks the branch from
+    // returning to editing; the caller is warned instead.
+    const note = body?.note;
+    let warning;
+    if (note) {
+        try {
+            await new CommentStore(branchContext.branchRoot).addComment({
+                userId: req.user.userId,
+                text: `Changes requested: ${note}`,
+                type: 'branch',
+            });
+        }
+        catch (err) {
+            console.error(`CanopyCMS: Failed to save the request-changes note for ${branchContext.branch.name}:`, getErrorMessage(err));
+            warning = NOTE_NOT_SAVED_WARNING;
+        }
+        if (!warning)
+            await syncPrComments(ctx, { ...branchContext, branch: updated.branch });
+    }
     return {
         ok: true,
         status: 200,
-        data: { branch: toBranchListItem(ctx.services.config, updated.branch, req.user) },
+        data: {
+            branch: toBranchListItem(ctx.services.config, updated.branch, req.user),
+            ...(warning && { warning }),
+        },
     };
 };
 const approveBranchHandler = async (gc, ctx, req, _params) => {
     const { branchContext } = gc;
-    if (branchContext.branch.status !== 'submitted') {
+    // Approve is a CanopyCMS status only. The CMS authors its pull requests and GitHub refuses
+    // an author's approval review, so nothing is sent to GitHub.
+    if (branchContext.branch.createdBy === req.user.userId) {
+        return {
+            ok: false,
+            status: 403,
+            error: "You can't approve a branch you created. Ask another reviewer to approve it.",
+        };
+    }
+    // Request changes stays open on the base branch, as Withdraw does, to recover one stuck in review.
+    const { isProtected } = getBranchProtection(ctx.services.config, branchContext.branch.name, branchContext.branch.baseBranch);
+    if (isProtected) {
+        return { ok: false, status: 400, error: "The base branch can't be approved." };
+    }
+    if (branchContext.branch.status !== 'submitted')
+        return approveConflict(branchContext.branch.status);
+    if (branchContext.branch.pullRequestState === 'closed') {
         return {
             ok: false,
             status: 400,
-            error: `Cannot approve branch with status '${branchContext.branch.status}'. Only 'submitted' branches can be approved.`,
+            error: 'The pull request was closed on GitHub, so this branch cannot be approved. Withdraw it from review, then submit it again to open a new one.',
         };
     }
     const meta = getBranchMetadataFileManager(branchContext.branchRoot, branchContext.baseRoot);
-    const updated = await meta.save({
-        branch: { name: branchContext.branch.name, status: 'approved' },
+    // As for request changes, the status on disk decides, in the step that writes.
+    let found;
+    const updated = await meta.saveIf({ branch: { name: branchContext.branch.name, status: 'approved' } }, (existing) => {
+        found = existing?.branch.status;
+        return found === 'submitted';
     });
-    // TODO: Optionally call githubService.approvePullRequest() when GitHub integration is needed
+    if (!updated)
+        return approveConflict(found);
     return {
         ok: true,
         status: 200,
@@ -50,8 +128,8 @@ export const requestChanges = defineEndpoint({
     method: 'POST',
     path: '/:branch/request-changes',
     params: branchParamSchema,
-    // body/bodyType removed: comment field was declared but never stored.
-    // Re-add when comment storage is implemented (see TODO in handler).
+    body: requestChangesBodySchema,
+    bodyType: 'RequestChangesBody',
     responseType: 'BranchListItemResponse',
     response: {},
     defaultMockData: {

package/dist/api/branch-status.d.ts

@@ -3,6 +3,7 @@ import type { ApiResponse } from './types.js';
 import { type BranchListItem, type BranchListItemResponse } from './branch.js';
 import type { StampedEntry } from '../stamp-on-publish.js';
 export type { BranchMergeResponse } from './branch-merge.js';
+export type { RequestChangesBody } from './branch-review.js';
 /**
  * A submit's answer: the branch, plus the entries the submit stamped (stamp-on-publish.ts) when
  * there were any, so the editor can carry its open forms and drafts onto their new versions.
@@ -11,6 +12,16 @@ export type SubmitBranchResponse = ApiResponse<{
     branch: BranchListItem;
     stamped?: StampedEntry[];
 }>;
+declare const submitBranchBodySchema: z.ZodOptional<z.ZodObject<{
+    /** The editor page's URL (`location.origin + location.pathname`), for the PR body's links. */
+    editorUrl: z.ZodCatch<z.ZodOptional<z.ZodString>>;
+}, "strip", z.ZodTypeAny, {
+    editorUrl?: string | undefined;
+}, {
+    editorUrl?: unknown;
+}>>;
+/** The submit request body. */
+export type SubmitBranchBody = z.infer<typeof submitBranchBodySchema>;
 export declare const WORKFLOW_ROUTES: {
     readonly getStatus: import("./route-builder.js").RouteDefinition<z.ZodObject<{
         branch: z.ZodType<import("../paths/index.js").BranchName, z.ZodTypeDef, import("../paths/index.js").BranchName>;
@@ -33,7 +44,14 @@ export declare const WORKFLOW_ROUTES: {
         branch: string & {
             readonly __brand: "BranchName";
         };
-    }>, undefined, SubmitBranchResponse>;
+    }>, z.ZodOptional<z.ZodObject<{
+        /** The editor page's URL (`location.origin + location.pathname`), for the PR body's links. */
+        editorUrl: z.ZodCatch<z.ZodOptional<z.ZodString>>;
+    }, "strip", z.ZodTypeAny, {
+        editorUrl?: string | undefined;
+    }, {
+        editorUrl?: unknown;
+    }>>, SubmitBranchResponse>;
     readonly withdraw: import("./route-builder.js").RouteDefinition<z.ZodObject<{
         branch: z.ZodType<import("../paths/index.js").BranchName, z.ZodTypeDef, import("../paths/index.js").BranchName>;
     }, "strip", z.ZodTypeAny, {
@@ -55,7 +73,13 @@ export declare const WORKFLOW_ROUTES: {
         branch: string & {
             readonly __brand: "BranchName";
         };
-    }>, undefined, BranchListItemResponse>;
+    }>, z.ZodOptional<z.ZodObject<{
+        note: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        note?: string | undefined;
+    }, {
+        note?: string | undefined;
+    }>>, BranchListItemResponse>;
     readonly approve: import("./route-builder.js").RouteDefinition<z.ZodObject<{
         branch: z.ZodType<import("../paths/index.js").BranchName, z.ZodTypeDef, import("../paths/index.js").BranchName>;
     }, "strip", z.ZodTypeAny, {

package/dist/api/branch-status.js

@@ -1,3 +1,4 @@
+import { z } from 'zod';
 import { branchParamSchema } from './validators.js';
 import { toBranchListItem } from './branch.js';
 import { getBranchMetadataFileManager } from '../branch-metadata.js';
@@ -13,6 +14,7 @@ import { ContentWriteLockBusyError } from '../utils/content-write-lock.js';
 import { submissionEditorFromUser } from '../submission-attribution.js';
 import { NothingToSubmitError } from '../services.js';
 import { baseBranchOf } from '../utils/base-branch.js';
+import { resolveEditorUrl } from '../editor-url.js';
 const getBranchStatusHandler = async (gc, ctx, req, _params) => {
     const { branchContext } = gc;
     return {
@@ -21,7 +23,33 @@ const getBranchStatusHandler = async (gc, ctx, req, _params) => {
         data: { branch: toBranchListItem(ctx.services.config, branchContext.branch, req.user) },
     };
 };
-const submitBranchForMergeHandler = async (gc, ctx, req, _params) => {
+const submitBranchBodySchema = z
+    .object({
+    /** The editor page's URL (`location.origin + location.pathname`), for the PR body's links. */
+    // Any value but a usable URL costs only the links (editor-url.ts), never the submit.
+    editorUrl: z.string().optional().catch(undefined),
+})
+    .optional();
+/**
+ * The editor URL the PR body links to: `config.editorUrl`, else the URL the editor reported
+ * when the request was addressed to its host (editor-url.ts). A reported URL that fails that
+ * check is logged once per submit, since every link then goes missing.
+ */
+function submitEditorUrl(ctx, req, claimed) {
+    const configured = ctx.services.config.editorUrl;
+    const resolved = resolveEditorUrl({
+        configured,
+        claimed,
+        header: req.rawRequest ? (name) => req.rawRequest?.header(name) ?? null : undefined,
+    });
+    if (!resolved && !configured && claimed) {
+        console.warn('CanopyCMS: The pull request body has no editor links: the editor URL the browser reported ' +
+            'is not on the host the request was addressed to (X-Forwarded-Host, else Host). Set ' +
+            'editorUrl in the CanopyCMS config to the editor page URL.');
+    }
+    return resolved;
+}
+const submitBranchForMergeHandler = async (gc, ctx, req, _params, body) => {
     const { branchContext } = gc;
     // Check if user can perform workflow actions (creator OR ACL access). isProtectedBranch
     // is passed for defense-in-depth (disables the system-branch grant); the 'submittableBranch'
@@ -61,10 +89,11 @@ const submitBranchForMergeHandler = async (gc, ctx, req, _params) => {
     const { authPlugin } = ctx;
     let changedPaths;
     let editors;
+    let entryPaths;
     let stamped;
     try {
         ;
-        ({ changedPaths, editors, stamped } = await ctx.services.submitBranch({
+        ({ changedPaths, editors, entryPaths, stamped } = await ctx.services.submitBranch({
             context: branchContext,
             submitter,
             lookupEditor: authPlugin ? (id) => authPlugin.getUserMetadata(id) : undefined,
@@ -123,10 +152,13 @@ const submitBranchForMergeHandler = async (gc, ctx, req, _params) => {
     }
     // Create or update PR (sync via githubService, or async via task queue)
     const submittedAt = new Date().toISOString();
+    const editorUrl = submitEditorUrl(ctx, req, body?.editorUrl);
     const prResult = await syncSubmitPr(ctx, branchContext, {
         submitter,
         editors,
         changedPaths,
+        entryPaths,
+        editorUrl,
         submittedAt,
     });
     const meta = getBranchMetadataFileManager(branchContext.branchRoot, branchContext.baseRoot);
@@ -149,6 +181,8 @@ const submitBranchForMergeHandler = async (gc, ctx, req, _params) => {
             status: 'submitted',
             submittedAt,
             ...pushed,
+            // Only a request-derived URL: config.editorUrl is read live by every later re-render.
+            ...(editorUrl && !ctx.services.config.editorUrl ? { editorUrl } : {}),
             syncFailureReason: prResult.syncFailureReason,
             pullRequestUrl: prResult.prUrl ?? branchContext.branch.pullRequestUrl,
             pullRequestNumber: prResult.prNumber ?? branchContext.branch.pullRequestNumber,
@@ -196,6 +230,8 @@ const submitBranchForMerge = defineEndpoint({
     method: 'POST',
     path: '/:branch/submit',
     params: branchParamSchema,
+    body: submitBranchBodySchema,
+    bodyType: 'SubmitBranchBody',
     responseType: 'SubmitBranchResponse',
     response: {},
     defaultMockData: {

package/dist/api/branch-withdraw.js

@@ -22,13 +22,10 @@ const withdrawBranchHandler = async (gc, ctx, req, _params) => {
             error: 'You do not have permission to withdraw this branch from review.',
         };
     }
-    // 'approved' is accepted alongside 'submitted' because withdraw is its only
-    // non-destructive exit. Every non-'editing' status blocks content writes, and
-    // request-changes requires 'submitted' -- so before this, an approved branch
-    // could only be escaped by a raw workflow.submit call, which silently
-    // discarded the approval and is now refused by the submit status gate
-    // (api/branch-status.ts). Without this, closing that hole would seal the dead
-    // end completely, leaving deletion as the only way out.
+    // 'approved' is accepted alongside 'submitted' because withdraw is the author's
+    // way back from either: the editor offers an author no Request changes. Every
+    // non-'editing' status blocks content writes, and a raw workflow.submit would
+    // discard the approval, which the submit status gate refuses (api/branch-status.ts).
     //
     // 'archived' stays refused: the PR is merged and there is nothing to return to.
     const status = branchContext.branch.status;

package/dist/api/branch.d.ts

@@ -57,6 +57,8 @@ export interface BranchListItem extends BranchMetadata {
  */
 export type BranchListItemResponse = ApiResponse<{
     branch: BranchListItem;
+    /** Set when the request succeeded but a secondary effect failed; show it to the user. */
+    warning?: string;
 }>;
 /** Response type for listing branches */
 export type BranchListResponse = ApiResponse<{

package/dist/api/client.d.ts

@@ -9,7 +9,7 @@ import { type RequestOptions } from './request-deadline.js';
 export { isApiTimeoutError, WRITE_TIMED_OUT_MESSAGE, type RequestOptions } from './request-deadline.js';
 import type { OperatingMode } from '../operating-mode/types.js';
 import type { BranchDeleteResponse, BranchListItemResponse, BranchListResponse, CreateBranchBody, UpdateBranchAccessBody } from './branch.js';
-import type { BranchMergeResponse, SubmitBranchResponse } from './branch-status.js';
+import type { BranchMergeResponse, RequestChangesBody, SubmitBranchBody, SubmitBranchResponse } from './branch-status.js';
 import type { AddCommentBody, AddCommentResponse, CommentsResponse, ResolveCommentResponse } from './comments.js';
 import type { ContentReadResponse, ContentWriteResponse, ReferenceValidationResponse, RenameEntryBody, RenameEntryResponse, ValidateReferencesBody, WriteContentBody } from './content.js';
 import type { ReferenceOptionsResponse } from './reference-options.js';
@@ -82,7 +82,7 @@ export declare class CanopyApiClient {
         /** POST /:branch/withdraw */
         withdraw: (params: Record<string, string>, options?: RequestOptions) => Promise<BranchListItemResponse>;
         /** POST /:branch/request-changes */
-        requestChanges: (params: Record<string, string>, options?: RequestOptions) => Promise<BranchListItemResponse>;
+        requestChanges: (params: Record<string, string>, body: RequestChangesBody, options?: RequestOptions) => Promise<BranchListItemResponse>;
         /** POST /:branch/approve */
         approve: (params: Record<string, string>, options?: RequestOptions) => Promise<BranchListItemResponse>;
         /** POST /:branch/mark-merged */
@@ -90,7 +90,7 @@ export declare class CanopyApiClient {
         /** GET /:branch/status */
         getStatus: (params: Record<string, string>, options?: RequestOptions) => Promise<BranchListItemResponse>;
         /** POST /:branch/submit */
-        submit: (params: Record<string, string>, options?: RequestOptions) => Promise<SubmitBranchResponse>;
+        submit: (params: Record<string, string>, body: SubmitBranchBody, options?: RequestOptions) => Promise<SubmitBranchResponse>;
     };
     readonly comments: {
         /** GET /:branch/comments */

package/dist/api/client.js

@@ -47,8 +47,8 @@ export class CanopyApiClient {
                 return this.request('POST', this.buildPath('/:branch/withdraw', params), undefined, 'standard', options);
             },
             /** POST /:branch/request-changes */
-            requestChanges: (params, options) => {
-                return this.request('POST', this.buildPath('/:branch/request-changes', params), undefined, 'standard', options);
+            requestChanges: (params, body, options) => {
+                return this.request('POST', this.buildPath('/:branch/request-changes', params), body, 'standard', options);
             },
             /** POST /:branch/approve */
             approve: (params, options) => {
@@ -63,8 +63,8 @@ export class CanopyApiClient {
                 return this.request('GET', this.buildPath('/:branch/status', params), undefined, 'standard', options);
             },
             /** POST /:branch/submit */
-            submit: (params, options) => {
-                return this.request('POST', this.buildPath('/:branch/submit', params), undefined, 'long', options);
+            submit: (params, body, options) => {
+                return this.request('POST', this.buildPath('/:branch/submit', params), body, 'long', options);
             },
         };
         this.comments = {

package/dist/api/comments.d.ts

@@ -60,16 +60,16 @@ export declare const COMMENT_ROUTES: {
     }, "strip", z.ZodTypeAny, {
         type: "branch" | "entry" | "field";
         text: string;
-        entryPath?: LogicalPath | undefined;
         threadId?: string | undefined;
         itemKeys?: string[] | undefined;
+        entryPath?: LogicalPath | undefined;
         canopyPath?: string | undefined;
     }, {
         type: "branch" | "entry" | "field";
         text: string;
-        entryPath?: LogicalPath | undefined;
         threadId?: string | undefined;
         itemKeys?: string[] | undefined;
+        entryPath?: LogicalPath | undefined;
         canopyPath?: string | undefined;
     }>, AddCommentResponse>;
     readonly resolve: import("./route-builder.js").RouteDefinition<z.ZodObject<{

package/dist/api/comments.js

@@ -6,6 +6,7 @@ import { isReviewer } from '../authorization/index.js';
 import { parseLogicalPath } from '../paths/validation.js';
 import { normalizeFilesystemPath } from '../paths/normalize.js';
 import { defineEndpoint } from './route-builder.js';
+import { syncPrComments } from './pr-comment-sync.js';
 import { isItemKey } from '../item-keys.js';
 import { parseCanopyPath } from '../editor/canopy-path.js';
 import { branchParamSchema, branchNameSchema, logicalPathSchema } from './validators.js';
@@ -141,6 +142,7 @@ const addCommentHandler = async (gc, ctx, req, _params, body) => {
         if (!reply) {
             return { ok: false, status: 404, error: 'Thread not found' };
         }
+        await syncPrComments(ctx, branchContext);
         return { ok: true, status: 201, data: reply };
     }
     if (!canRead(body.entryPath)) {
@@ -154,6 +156,7 @@ const addCommentHandler = async (gc, ctx, req, _params, body) => {
         canopyPath: body.canopyPath,
         itemKeys: body.itemKeys,
     });
+    await syncPrComments(ctx, branchContext);
     return { ok: true, status: 201, data: result };
 };
 const resolveCommentHandler = async (gc, ctx, req, params) => {
@@ -181,6 +184,7 @@ const resolveCommentHandler = async (gc, ctx, req, params) => {
     if (!resolved) {
         return { ok: false, status: 404, error: 'Thread not found' };
     }
+    await syncPrComments(ctx, branchContext);
     return { ok: true, status: 200, data: { resolved: true } };
 };
 // Deliberately no 'writableBranch' guard on any endpoint below: comments live

package/dist/api/content.d.ts

@@ -103,12 +103,12 @@ export declare const CONTENT_ROUTES: {
         body: z.ZodOptional<z.ZodString>;
         expectedVersion: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
     }, "strip", z.ZodTypeAny, {
-        format: "mdx" | "md" | "json" | "yaml";
+        format: "md" | "mdx" | "json" | "yaml";
         data?: Record<string, unknown> | undefined;
         expectedVersion?: number | null | undefined;
         body?: string | undefined;
     }, {
-        format: "mdx" | "md" | "json" | "yaml";
+        format: "md" | "mdx" | "json" | "yaml";
         data?: Record<string, unknown> | undefined;
         expectedVersion?: number | null | undefined;
         body?: string | undefined;

package/dist/api/github-sync.d.ts

@@ -21,6 +21,10 @@ export interface SubmissionRecord {
     /** Every recorded editor of the branch; the PR body lists those other than the submitter. */
     editors?: readonly SubmissionEditor[];
     changedPaths: readonly string[];
+    /** The entry logical path of each changed path that is an entry, for its editor link. */
+    entryPaths?: ReadonlyMap<string, string>;
+    /** The editor page URL the PR body links to (editor-url.ts resolveEditorUrl). */
+    editorUrl?: string;
     /** The submit's `submittedAt`, carried to the worker so its failure handling targets this submit. */
     submittedAt?: string;
 }

package/dist/api/github-sync.js

@@ -6,6 +6,19 @@ import { sanitizeBranchName } from '../paths/branch-name.js';
 import { buildPrSection, mergePrSection } from '../submission-attribution.js';
 import { isNoCommitsBetweenError, isRefAlreadyGoneError } from '../github-service.js';
 import { baseBranchOf } from '../utils/base-branch.js';
+import { CommentStore } from '../comment-store.js';
+import { prBodyLockKey, refreshCommentsBlock } from '../pr-comments.js';
+import { withLock } from '../utils/async-mutex.js';
+/** The branch's comment threads for the PR body, or null (said so in the body) if unreadable. */
+async function readThreadsOrWarn(context) {
+    try {
+        return await new CommentStore(context.branchRoot).listThreadsStrict();
+    }
+    catch (err) {
+        console.warn(`CanopyCMS: Could not read the editor comments of ${context.branch.name} for its PR:`, getErrorMessage(err));
+        return null;
+    }
+}
 /**
  * Uses githubService directly if available, otherwise queues a task for the worker.
  *
@@ -16,11 +29,16 @@ export async function syncSubmitPr(ctx, context, submission) {
     const { githubService } = ctx.services;
     const mode = ctx.services.config.mode;
     const prTitle = context.branch.title || `Submit ${context.branch.name}`;
+    const threads = await readThreadsOrWarn(context);
     const prSection = buildPrSection({
         description: context.branch.description,
         submitter: submission.submitter,
         editors: submission.editors,
         changedPaths: submission.changedPaths,
+        branch: context.branch.name,
+        editorUrl: submission.editorUrl,
+        entryPaths: submission.entryPaths,
+        threads,
     });
     // Target the fork point recorded at branch creation when available.
     const baseBranch = context.branch.baseBranch ?? baseBranchOf(ctx.services.config);
@@ -40,12 +58,24 @@ export async function syncSubmitPr(ctx, context, submission) {
     if (githubService) {
         try {
             if (context.branch.pullRequestNumber) {
+                const prNumber = context.branch.pullRequestNumber;
                 // Read before writing: the update keeps the human text around the
                 // canopycms section, and the same read says whether the PR is a draft.
-                const pr = await githubService.getPullRequest(context.branch.pullRequestNumber);
-                await githubService.updatePullRequest(context.branch.pullRequestNumber, {
-                    title: prTitle,
-                    body: mergePrSection(pr.body, prSection),
+                const pr = await withLock(prBodyLockKey(context.branchRoot), async () => {
+                    const current = await githubService.getPullRequest(prNumber);
+                    // Re-read under the lock: a comment synced since the read above has the newer block.
+                    const section = await refreshCommentsBlock({
+                        branchRoot: context.branchRoot,
+                        branch: context.branch.name,
+                        editorUrl: submission.editorUrl,
+                        section: prSection,
+                        warn: (message) => console.warn(`CanopyCMS: ${message}`),
+                    });
+                    await githubService.updatePullRequest(prNumber, {
+                        title: prTitle,
+                        body: mergePrSection(current.body, section),
+                    });
+                    return current;
                 });
                 // Best-effort draft->ready conversion. This branch updates a known
                 // PR number directly (not through createOrUpdatePR), so it doesn't
@@ -83,14 +113,14 @@ export async function syncSubmitPr(ctx, context, submission) {
                 // shared createOrUpdatePullRequest helper (github-service.ts), which
                 // treats conversion as best-effort so a permissions-limited token
                 // can't fail this submit.
-                const result = await githubService.createOrUpdatePR({
+                const result = await withLock(prBodyLockKey(context.branchRoot), () => githubService.createOrUpdatePR({
                     head: context.branch.name,
                     base: baseBranch,
                     title: prTitle,
                     body: prSection,
                     markReadyIfDraft: true,
                     mergeSectionIntoBody: true,
-                });
+                }));
                 return {
                     prUrl: result.url,
                     prNumber: result.number,
@@ -127,6 +157,8 @@ export async function syncSubmitPr(ctx, context, submission) {
             title: prTitle,
             body: prSection,
             mergeSectionIntoBody: true,
+            // The worker re-renders the comment block from comments.json when the task runs.
+            ...(submission.editorUrl ? { editorUrl: submission.editorUrl } : {}),
             baseBranch,
             pullRequestNumber: context.branch.pullRequestNumber,
             // A content submit is an explicit "ready for review" action: convert a

package/dist/api/pr-comment-sync.d.ts

@@ -0,0 +1,18 @@
+import type { ApiContext } from './types.js';
+import type { BranchContext } from '../types.js';
+/**
+ * Brings the PR's editor-comment summary up to date after a comment is added, replied to or
+ * resolved. Best-effort: a failure is logged and never fails the comment request.
+ *
+ * Direct path: read the PR body, replace the block, write it back, within
+ * DIRECT_SYNC_TIMEOUT_MS so a slow or rate-limited GitHub never holds the comment request.
+ * GitHub's PR update takes no expected version; the per-branch lock (prBodyLockKey) only
+ * orders this process's writers (docs/concurrency.md).
+ *
+ * Queued path: one pending task per branch and PR, rendered by the worker from comments.json
+ * when it runs, so a burst of comments costs one update. The comment was written before this
+ * call and a pending task reads comments.json only after it leaves pending, so its run carries
+ * the change this call skipped; a task already running doesn't count, so a later change gets
+ * a run of its own.
+ */
+export declare function syncPrComments(ctx: ApiContext, context: BranchContext): Promise<void>;

package/dist/api/pr-comment-sync.js

@@ -0,0 +1,77 @@
+import { clientOperatingStrategy } from '../operating-mode/index.js';
+import { SYNC_PR_COMMENTS_ACTION, prBodyLockKey, renderPrCommentsBody } from '../pr-comments.js';
+import { isApiTimeoutError, runWithDeadline } from './request-deadline.js';
+import { enqueueTask, listTasks } from '../task-queue/cms-task-queue.js';
+import { getTaskQueueDir } from '../task-queue/task-queue-config.js';
+import { withLock } from '../utils/async-mutex.js';
+import { getErrorMessage } from '../utils/error.js';
+/** A PR the comment summary is still worth updating on: one exists and is not merged or closed. */
+function openPullRequest(context) {
+    const { pullRequestNumber, pullRequestState, status } = context.branch;
+    if (!pullRequestNumber || status === 'archived')
+        return undefined;
+    return pullRequestState === 'merged' || pullRequestState === 'closed'
+        ? undefined
+        : pullRequestNumber;
+}
+/** How long a comment request waits on GitHub for its summary update, lock wait included. */
+const DIRECT_SYNC_TIMEOUT_MS = 10_000;
+/**
+ * Brings the PR's editor-comment summary up to date after a comment is added, replied to or
+ * resolved. Best-effort: a failure is logged and never fails the comment request.
+ *
+ * Direct path: read the PR body, replace the block, write it back, within
+ * DIRECT_SYNC_TIMEOUT_MS so a slow or rate-limited GitHub never holds the comment request.
+ * GitHub's PR update takes no expected version; the per-branch lock (prBodyLockKey) only
+ * orders this process's writers (docs/concurrency.md).
+ *
+ * Queued path: one pending task per branch and PR, rendered by the worker from comments.json
+ * when it runs, so a burst of comments costs one update. The comment was written before this
+ * call and a pending task reads comments.json only after it leaves pending, so its run carries
+ * the change this call skipped; a task already running doesn't count, so a later change gets
+ * a run of its own.
+ */
+export async function syncPrComments(ctx, context) {
+    const prNumber = openPullRequest(context);
+    if (prNumber === undefined)
+        return;
+    if (!clientOperatingStrategy(ctx.services.config.mode).supportsPullRequests())
+        return;
+    const branch = context.branch.name;
+    const editorUrl = ctx.services.config.editorUrl ?? context.branch.editorUrl;
+    try {
+        const { githubService } = ctx.services;
+        if (githubService) {
+            await runWithDeadline((signal) => withLock(prBodyLockKey(context.branchRoot), async () => {
+                const pr = await githubService.getPullRequest(prNumber, signal);
+                if (pr.state !== 'open')
+                    return;
+                const body = await renderPrCommentsBody({
+                    branchRoot: context.branchRoot,
+                    branch,
+                    editorUrl,
+                    body: pr.body,
+                });
+                if (body !== undefined)
+                    await githubService.updatePullRequest(prNumber, { body }, signal);
+            }), { method: 'PATCH', path: `pull request #${prNumber}`, timeoutMs: DIRECT_SYNC_TIMEOUT_MS });
+            return;
+        }
+        const taskDir = getTaskQueueDir(ctx.services.config);
+        const pending = await listTasks(taskDir, 'pending', Number.MAX_SAFE_INTEGER);
+        const queued = pending.some((t) => t.action === SYNC_PR_COMMENTS_ACTION &&
+            t.payload.branch === branch &&
+            t.payload.pullRequestNumber === prNumber);
+        if (queued)
+            return;
+        await enqueueTask(taskDir, {
+            action: SYNC_PR_COMMENTS_ACTION,
+            payload: { branch, pullRequestNumber: prNumber, ...(editorUrl ? { editorUrl } : {}) },
+        });
+    }
+    catch (err) {
+        console.warn(`CanopyCMS: Could not update the editor comments on PR #${prNumber} for ${branch}:`, isApiTimeoutError(err)
+            ? `GitHub did not answer within ${DIRECT_SYNC_TIMEOUT_MS / 1000} s`
+            : getErrorMessage(err));
+    }
+}