canopycms 0.8.1 → 0.8.2

package/dist/api/branch-status.js

@@ -6,7 +6,7 @@ import { withdrawBranch } from './branch-withdraw.js';
 import { requestChanges, approveBranch } from './branch-review.js';
 import { markAsMerged } from './branch-merge.js';
 import { defineEndpoint } from './route-builder.js';
-import { canPerformWorkflowAction, getBranchProtection } from '../authorization/index.js';
+import { canPerformWorkflowAction, getBranchProtection, isAdmin } from '../authorization/index.js';
 import { syncSubmitPr } from './github-sync.js';
 import { getErrorMessage, redactCredentials, sanitizeErrorMessage } from '../utils/error.js';
 import { isNonFastForwardRejection } from '../utils/git.js';
@@ -85,6 +85,19 @@ const submitBranchForMergeHandler = async (gc, ctx, req, _params, body) => {
                 : `Cannot submit branch with status '${status}'. Only 'editing' branches can be submitted.`,
         };
     }
+    // The worker pushes nothing for such a branch, so this would commit and report a failure later.
+    if (branchContext.branch.rewrittenOnGitHub !== undefined) {
+        return {
+            ok: false,
+            status: 409,
+            error: `"${shortNameOf(ctx.services.config, branchContext.branch.name)}" was changed on GitHub in ` +
+                "a way CanopyCMS can't combine with the work here, so it can't be submitted. Nothing is " +
+                'lost. ' +
+                (isAdmin(req.user.groups)
+                    ? 'See the "Branches" tab in "System health".'
+                    : 'Ask an admin for help.'),
+        };
+    }
     // Commit and push changes
     const submitter = submissionEditorFromUser(req.user);
     const { authPlugin } = ctx;
@@ -122,28 +135,21 @@ const submitBranchForMergeHandler = async (gc, ctx, req, _params, body) => {
         // (e.g. x-access-token:TOKEN@github.com in git errors) are redacted even
         // from server logs — a live installation token must never persist in logs.
         console.error(`CanopyCMS: Failed to push branch changes (${branchContext.branchRoot}):`, redactCredentials(message));
-        // A non-fast-forward rejection means this branch and the deployment's
-        // local repository have diverged. Retrying the identical push can never
-        // succeed (see isNonFastForwardRejection), so surface 409 instead of the
-        // generic 500 below. Everything else (network, auth) keeps the 500 path.
-        //
-        // This push targets the deployment's OWN local origin (remote.git), not
-        // GitHub, so the message deliberately states only the observable fact and
-        // names no cause: a foreign deployment cannot reach this repo, and the
-        // realistic explanations are all internal (the worker's rebase loop
-        // reconciling the branch, or a commit reaching remote.git that this
-        // workspace never had). It also never advises renaming the branch --
-        // a branch that reaches this point has usually been submitted before, so
-        // it may well have an open PR that a rename would orphan.
+        // This push targets the deployment's OWN remote.git, so a non-fast-forward
+        // rejection means it holds a commit this clone lacks, which reached it from
+        // GitHub (worker/github-commits.ts). The commit made above stays: the tree is
+        // then clean, which is what the worker's merge needs, and the next submit
+        // pushes the result. A branch that reaches this point has usually been
+        // submitted before, so the message never advises renaming it: that would
+        // orphan its open PR.
         if (isNonFastForwardRejection(message)) {
             return {
                 ok: false,
                 status: 409,
-                error: `Could not submit "${shortName}": it has diverged from the copy in ` +
-                    `this deployment's repository and needs to be reconciled before it can be submitted. ` +
-                    `The background worker reconciles branches when the base branch moves, so this often ` +
-                    `clears on its own within a few minutes -- try again shortly, and ask an administrator ` +
-                    `to check the worker if it persists.`,
+                error: `Could not submit "${shortName}": it has commits from GitHub that aren't in the editor ` +
+                    `yet. Your saved changes are safe. CanopyCMS brings those commits in at its next sync, ` +
+                    `usually within a few minutes, so submit again then. If this keeps happening, ` +
+                    `${isAdmin(req.user.groups) ? 'check' : 'ask an admin to check'} "System health".`,
             };
         }
         return {
@@ -200,6 +206,11 @@ const submitBranchForMergeHandler = async (gc, ctx, req, _params, body) => {
             // warning through review and archive.
             rebaseFailure: undefined,
             review: undefined,
+            // Read by the card as soon as the status says review, and the worker's next read is minutes
+            // away, so what held the last submit must not show as holding this one.
+            pullRequestHold: undefined,
+            submitUnfinished: prResult.submitNotQueued,
+            submitNotQueued: prResult.submitNotQueued,
         },
     });
     return {

package/dist/api/branch.d.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import type { BranchContext, BranchMetadata } from '../types.js';
+import type { BranchContext, BranchHold, BranchMetadata } from '../types.js';
 import type { ApiContext, ApiRequest, ApiResponse } from './types.js';
 import { branchParamSchema } from './validators.js';
 import type { UserProfile } from '../auth/types.js';
@@ -15,7 +15,11 @@ import type { UserProfile } from '../auth/types.js';
  * rather than silently behaving as if nothing changed. That is by design:
  * wire compatibility here means "doesn't break", not "behaves the same".
  */
-export interface BranchListItem extends Omit<BranchMetadata, 'review'> {
+export interface BranchListItem extends Omit<BranchMetadata, 'review' | 'keptOverGitHub' | 'lastGitHubTip' | 'rewrittenOnGitHub' | 'submitUnfinished' | 'unpublishedAtMerge' | 'submitNotQueued' | 'rebaseFailure' | 'pullRequestHold'> {
+    /** What is stuck and needs a person, for the branch card. Names no file. */
+    hold?: BranchHold;
+    /** The last submit didn't finish, which the server refuses Approve for. */
+    approveBlocked?: boolean;
     /**
      * What pull request links carry for this branch, which `?branch=` and the `/:branch` segment
      * accept beside `name` (branch-param.ts's `shortNameOf`): `name` less the namespace for a branch
@@ -32,7 +36,8 @@ export interface BranchListItem extends Omit<BranchMetadata, 'review'> {
      */
     writeBlocked?: boolean;
     /**
-     * Populated from {@link BranchWriteProtection.submitBlockedIncludingStatus}
+     * Populated from {@link BranchWriteProtection.submitBlockedIncludingStatus},
+     * or true for a branch rewritten on GitHub
      * -- READ THAT DOC COMMENT before touching this field. On the wire this
      * name means the COMPOUND answer (base-branch OR non-'editing' status),
      * mirroring how `writeBlocked` above is the compound of `readOnly` + status

package/dist/api/branch.js

@@ -126,16 +126,36 @@ const accessForViewer = (access, viewer) => {
  */
 export const toBranchListItem = (config, branch, viewer) => {
     const protection = getBranchWriteProtection(config, branch.name, branch.baseBranch, branch.status);
-    // `review` names the reviewer, whom the editor has no use for.
-    const { review: _review, ...listed } = branch;
+    // `review` names the reviewer, whom the editor has no use for. `keptOverGitHub` and
+    // `rebaseFailure` can name files, which a viewer's path rules can hide; System Health reads
+    // failures from the admin endpoint. The others are the worker's.
+    const { review: _review, keptOverGitHub: _kept, lastGitHubTip: _tip, rewrittenOnGitHub: _rewritten, submitUnfinished: _unfinished, submitNotQueued, unpublishedAtMerge: _unpublished, rebaseFailure: _failure, pullRequestHold, ...listed } = branch;
+    const inReview = branch.status === 'submitted' || branch.status === 'approved';
+    const rewritten = branch.rewrittenOnGitHub !== undefined && branch.status !== 'archived';
+    const hold = rewritten
+        ? { kind: 'rewritten' }
+        : !inReview
+            ? branch.unpublishedAtMerge
+                ? { kind: 'unpublished-at-merge' }
+                : undefined
+            : branch.submitUnfinished
+                ? {
+                    kind: 'submit-unfinished',
+                    opened: branch.pullRequestNumber !== undefined,
+                    notQueued: submitNotQueued,
+                }
+                : pullRequestHold;
     return {
         ...listed,
+        hold,
+        approveBlocked: (inReview && branch.submitUnfinished) || undefined,
         shortName: shortNameOf(config, branch.name),
         ...accessForViewer(branch.access ?? {}, viewer),
         isProtected: protection.isProtected,
         readOnly: protection.readOnly,
         writeBlocked: protection.writeBlocked,
-        submitBlocked: protection.submitBlockedIncludingStatus,
+        // The worker refuses to push such a branch, so a submit could only fail later.
+        submitBlocked: protection.submitBlockedIncludingStatus || rewritten,
     };
 };
 /**
@@ -572,6 +592,15 @@ export const deleteBranchHandler = async (ctx, req, params) => {
             error: 'Cannot delete branch with open pull request',
         };
     }
+    // It may hold the only copy of commits the merge left out, and deleting it would drop the alert
+    // that says so.
+    if (branchContext.branch.unpublishedAtMerge && !isAdmin(req.user.groups)) {
+        return {
+            ok: false,
+            status: 409,
+            error: 'This branch may hold changes that never reached GitHub. Ask an admin to check it before deleting it.',
+        };
+    }
     // The branch directory leaves its name by one rename, under the same
     // server-enforced lockfile branch-metadata saves hold (see
     // utils/occ-json-write.ts), so a save() that reaches that lock after the

package/dist/api/client.d.ts

@@ -23,7 +23,7 @@ import type { ExternalGroupsResponse, InternalGroupsResponse, UpdateInternalGrou
 import type { UserInfoResponse } from './user.js';
 import type { AddEntryTypeApiResponse, CreateCollectionApiResponse, DeleteCollectionApiResponse, GetCollectionApiResponse, GetSchemaApiResponse, InvalidateSchemaCacheApiResponse, RemoveEntryTypeApiResponse, UpdateCollectionApiResponse, UpdateEntryTypeApiResponse, UpdateOrderApiResponse, UpdateOrderBody } from './schema.js';
 import type { CreateCollectionInput, CreateEntryTypeInput, UpdateCollectionInput, UpdateEntryTypeInput } from './../schema/schema-store-types.js';
-import type { AdminDeleteTaskResponse, AdminRetryTaskResponse, AdminStatusResponse, AdminTasksResponse, BranchHealthResponse, PurgeBranchDirResponse, RepairBranchDirResponse, RepairContentDuplicatesResponse } from './admin.js';
+import type { AdminDeleteTaskResponse, AdminRetryTaskResponse, AdminStatusResponse, AdminTasksResponse, BranchHealthResponse, DismissUnpublishedResponse, PurgeBranchDirResponse, RepairBranchDirResponse, RepairContentDuplicatesResponse } from './admin.js';
 /** Options for {@link createApiClient}. */
 export interface ApiClientOptions {
     /** Base URL for API requests. Defaults to '/api/canopycms'. */
@@ -206,6 +206,8 @@ export declare class CanopyApiClient {
         purgeBranchDir: (params: Record<string, string>, options?: RequestOptions) => Promise<PurgeBranchDirResponse>;
         /** POST /admin/branch-dirs/:dirName/repair-metadata */
         repairBranchDir: (params: Record<string, string>, options?: RequestOptions) => Promise<RepairBranchDirResponse>;
+        /** POST /admin/branch-dirs/:dirName/dismiss-unpublished */
+        dismissUnpublished: (params: Record<string, string>, options?: RequestOptions) => Promise<DismissUnpublishedResponse>;
         /** POST /admin/branch-dirs/:dirName/repair-content-duplicates */
         repairContentDuplicates: (params: Record<string, string>, options?: RequestOptions) => Promise<RepairContentDuplicatesResponse>;
         /** GET /admin/status */

package/dist/api/client.js

@@ -259,6 +259,10 @@ export class CanopyApiClient {
             repairBranchDir: (params, options) => {
                 return this.request('POST', this.buildPath('/admin/branch-dirs/:dirName/repair-metadata', params), undefined, 'long', options);
             },
+            /** POST /admin/branch-dirs/:dirName/dismiss-unpublished */
+            dismissUnpublished: (params, options) => {
+                return this.request('POST', this.buildPath('/admin/branch-dirs/:dirName/dismiss-unpublished', params), undefined, 'standard', options);
+            },
             /** POST /admin/branch-dirs/:dirName/repair-content-duplicates */
             repairContentDuplicates: (params, options) => {
                 return this.request('POST', this.buildPath('/admin/branch-dirs/:dirName/repair-content-duplicates', params), undefined, 'long', options);

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

@@ -14,6 +14,8 @@ export interface GitHubSyncResult {
     nothingToSubmit?: boolean;
     /** The direct path, whose submit pushes to GitHub itself: the branch is there whatever the PR call did. */
     pushedToGitHub?: boolean;
+    /** No task runs this submit, so only submitting again finishes it. */
+    submitNotQueued?: boolean;
 }
 /** What the PR body records about a submit. */
 export interface SubmissionRecord {

package/dist/api/github-sync.js

@@ -10,6 +10,8 @@ import { shortNameOf } from '../branch-param.js';
 import { CommentStore } from '../comment-store.js';
 import { prBodyLockKey, refreshCommentsBlock } from '../pr-comments.js';
 import { withLock } from '../utils/async-mutex.js';
+/** A submit's commits reached this deployment's repository, and nothing will take them further. */
+const SUBMIT_NOT_QUEUED_REASON = "This submit couldn't be queued, so nothing reached GitHub. Nothing is lost.";
 /** The branch's comment threads for the PR body, or null (said so in the body) if unreadable. */
 async function readThreadsOrWarn(context) {
     try {
@@ -153,7 +155,7 @@ export async function syncSubmitPr(ctx, context, submission) {
     // recorded the number, the next submit would otherwise re-enqueue
     // 'push-and-create-pr' and 422 on GitHub's duplicate-PR check, wedging the
     // branch in 'sync-failed' with no way to recover.
-    return enqueueGitHubTask(ctx, context, {
+    const queued = await enqueueGitHubTask(ctx, context, {
         action: 'push-and-create-or-update-pr',
         payload: {
             branch: context.branch.name,
@@ -171,6 +173,9 @@ export async function syncSubmitPr(ctx, context, submission) {
             submittedAt: submission.submittedAt,
         },
     });
+    return queued.syncStatus === 'sync-failed'
+        ? { ...queued, syncFailureReason: SUBMIT_NOT_QUEUED_REASON, submitNotQueued: true }
+        : queued;
 }
 /**
  * Used by withdraw and request-changes. Uses githubService directly if

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

@@ -66,7 +66,9 @@ export async function syncPrComments(ctx, context) {
         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);
+            t.payload.pullRequestNumber === prNumber &&
+            // The worker's own task leaves the comment summary as it is, so it carries no comment.
+            t.payload.reviewBlockOnly !== true);
         if (queued)
             return;
         await enqueueTask(taskDir, {

package/dist/branch-metadata-file.d.ts

@@ -82,9 +82,31 @@ export declare const branchMetadataSchema: z.ZodObject<{
         lastAt: string;
     }>>;
     historyRewrittenFrom: z.ZodOptional<z.ZodString>;
+    lastGitHubTip: z.ZodOptional<z.ZodString>;
+    keptOverGitHub: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    rewrittenOnGitHub: z.ZodOptional<z.ZodString>;
+    submitUnfinished: z.ZodOptional<z.ZodBoolean>;
+    submitNotQueued: z.ZodOptional<z.ZodBoolean>;
+    unpublishedAtMerge: z.ZodOptional<z.ZodBoolean>;
     syncFailureReason: z.ZodOptional<z.ZodString>;
     editors: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     uncommittedEditors: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    pullRequestHold: z.ZodCatch<z.ZodOptional<z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
+        kind: z.ZodLiteral<"conflicts">;
+    }, "strip", z.ZodTypeAny, {
+        kind: "conflicts";
+    }, {
+        kind: "conflicts";
+    }>, z.ZodObject<{
+        kind: z.ZodLiteral<"retargeted">;
+        base: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        kind: "retargeted";
+        base: string;
+    }, {
+        kind: "retargeted";
+        base: string;
+    }>]>>>;
     review: z.ZodCatch<z.ZodOptional<z.ZodObject<{
         state: z.ZodEnum<["approved", "changes-requested"]>;
         by: z.ZodObject<{
@@ -175,9 +197,31 @@ export declare const branchMetadataSchema: z.ZodObject<{
         lastAt: string;
     }>>;
     historyRewrittenFrom: z.ZodOptional<z.ZodString>;
+    lastGitHubTip: z.ZodOptional<z.ZodString>;
+    keptOverGitHub: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    rewrittenOnGitHub: z.ZodOptional<z.ZodString>;
+    submitUnfinished: z.ZodOptional<z.ZodBoolean>;
+    submitNotQueued: z.ZodOptional<z.ZodBoolean>;
+    unpublishedAtMerge: z.ZodOptional<z.ZodBoolean>;
     syncFailureReason: z.ZodOptional<z.ZodString>;
     editors: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     uncommittedEditors: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    pullRequestHold: z.ZodCatch<z.ZodOptional<z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
+        kind: z.ZodLiteral<"conflicts">;
+    }, "strip", z.ZodTypeAny, {
+        kind: "conflicts";
+    }, {
+        kind: "conflicts";
+    }>, z.ZodObject<{
+        kind: z.ZodLiteral<"retargeted">;
+        base: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        kind: "retargeted";
+        base: string;
+    }, {
+        kind: "retargeted";
+        base: string;
+    }>]>>>;
     review: z.ZodCatch<z.ZodOptional<z.ZodObject<{
         state: z.ZodEnum<["approved", "changes-requested"]>;
         by: z.ZodObject<{
@@ -268,9 +312,31 @@ export declare const branchMetadataSchema: z.ZodObject<{
         lastAt: string;
     }>>;
     historyRewrittenFrom: z.ZodOptional<z.ZodString>;
+    lastGitHubTip: z.ZodOptional<z.ZodString>;
+    keptOverGitHub: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    rewrittenOnGitHub: z.ZodOptional<z.ZodString>;
+    submitUnfinished: z.ZodOptional<z.ZodBoolean>;
+    submitNotQueued: z.ZodOptional<z.ZodBoolean>;
+    unpublishedAtMerge: z.ZodOptional<z.ZodBoolean>;
     syncFailureReason: z.ZodOptional<z.ZodString>;
     editors: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     uncommittedEditors: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    pullRequestHold: z.ZodCatch<z.ZodOptional<z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
+        kind: z.ZodLiteral<"conflicts">;
+    }, "strip", z.ZodTypeAny, {
+        kind: "conflicts";
+    }, {
+        kind: "conflicts";
+    }>, z.ZodObject<{
+        kind: z.ZodLiteral<"retargeted">;
+        base: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        kind: "retargeted";
+        base: string;
+    }, {
+        kind: "retargeted";
+        base: string;
+    }>]>>>;
     review: z.ZodCatch<z.ZodOptional<z.ZodObject<{
         state: z.ZodEnum<["approved", "changes-requested"]>;
         by: z.ZodObject<{

package/dist/branch-metadata-file.js

@@ -81,9 +81,23 @@ const branchMetadataShape = {
         .object({ message: z.string(), firstAt: z.string(), lastAt: z.string() })
         .optional(),
     historyRewrittenFrom: z.string().optional(),
+    lastGitHubTip: z.string().optional(),
+    keptOverGitHub: z.array(z.string()).optional(),
+    rewrittenOnGitHub: z.string().optional(),
+    submitUnfinished: z.boolean().optional(),
+    submitNotQueued: z.boolean().optional(),
+    unpublishedAtMerge: z.boolean().optional(),
     syncFailureReason: z.string().optional(),
     editors: z.array(z.string()).optional(),
     uncommittedEditors: z.array(z.string()).optional(),
+    // Dropped when malformed: it only decorates the branch card, so it never fails a read.
+    pullRequestHold: z
+        .discriminatedUnion('kind', [
+        z.object({ kind: z.literal('conflicts') }),
+        z.object({ kind: z.literal('retargeted'), base: z.string() }),
+    ])
+        .optional()
+        .catch(undefined),
     // Dropped when malformed: it only decorates the PR body, so it never fails a read.
     review: z
         .object({

package/dist/branch-metadata.d.ts

@@ -119,8 +119,10 @@ export declare function buildInitialBranchMetadata(incoming: BranchMetadataUpdat
 export interface BranchMetadataUpdate {
     branch?: Partial<Omit<BranchMetadata, 'createdAt' | 'updatedAt'>>;
 }
+/** A failed submit whose pull request step hasn't run; no other task's success clears its failure. */
+export declare const awaitsSubmitRetry: ({ submitUnfinished, status }: BranchMetadata) => boolean;
 /**
- * The metadata update for archiving a branch whose PR merged. Shared by the
+ * The metadata update for archiving `branch`, whose PR merged. Shared by the
  * worker's merge-poll (CmsWorker.pollMergeState) and the manual markAsMerged
  * API (api/branch-merge.ts), so both produce identical metadata.
  *
@@ -128,7 +130,7 @@ export interface BranchMetadataUpdate {
  * existing values for fields the incoming update omits, so the branch's ref and
  * its recorded PR number and URL survive untouched.
  */
-export declare function buildMergedBranchUpdate(now?: Date): NonNullable<BranchMetadataUpdate['branch']>;
+export declare function buildMergedBranchUpdate(branch: BranchMetadata, now?: Date): NonNullable<BranchMetadataUpdate['branch']>;
 /** {@link BranchMetadataFileManager.get} as a function. */
 export declare const getBranchMetadataFileManager: (branchRoot: string, baseRoot: string, options?: {
     settleMs?: number;

package/dist/branch-metadata.js

@@ -267,8 +267,14 @@ function mergeBranchMetadata(existing, version, incoming, now = new Date().toISO
 export function buildInitialBranchMetadata(incoming, now) {
     return mergeBranchMetadata(null, null, incoming, now);
 }
+/** A failed submit whose pull request step hasn't run; no other task's success clears its failure. */
+export const awaitsSubmitRetry = ({ submitUnfinished, status }) => submitUnfinished === true && (status === 'submitted' || status === 'approved');
+/** Only a submit writes `pending-sync` to branch.json, so that too is a submit not yet finished. */
+const owesSubmit = (branch) => awaitsSubmitRetry(branch) ||
+    (branch.syncStatus === 'pending-sync' &&
+        (branch.status === 'submitted' || branch.status === 'approved'));
 /**
- * The metadata update for archiving a branch whose PR merged. Shared by the
+ * The metadata update for archiving `branch`, whose PR merged. Shared by the
  * worker's merge-poll (CmsWorker.pollMergeState) and the manual markAsMerged
  * API (api/branch-merge.ts), so both produce identical metadata.
  *
@@ -276,7 +282,7 @@ export function buildInitialBranchMetadata(incoming, now) {
  * existing values for fields the incoming update omits, so the branch's ref and
  * its recorded PR number and URL survive untouched.
  */
-export function buildMergedBranchUpdate(now = new Date()) {
+export function buildMergedBranchUpdate(branch, now = new Date()) {
     return {
         status: 'archived',
         pullRequestState: 'merged',
@@ -284,6 +290,8 @@ export function buildMergedBranchUpdate(now = new Date()) {
         // The merge settled every conflict the record named.
         conflictStatus: 'clean',
         conflictFiles: [],
+        submitUnfinished: undefined,
+        ...(owesSubmit(branch) ? { unpublishedAtMerge: true } : {}),
     };
 }
 /** {@link BranchMetadataFileManager.get} as a function. */

package/dist/cli/cli.js

@@ -562,7 +562,7 @@ async function failTask(taskDir, taskId, error, logger = nullLogger) {
   });
   logger.debug("Failed task", { id: taskId, error });
 }
-async function retryTask(taskDir, taskId, error, logger = nullLogger) {
+async function retryTask(taskDir, taskId, error, logger = nullLogger, options = {}) {
   const processingPath = path6.join(taskDir, "processing", `${taskId}.json`);
   const pendingDir = path6.join(taskDir, "pending");
   const pendingPath = path6.join(pendingDir, `${taskId}.json`);
@@ -583,7 +583,7 @@ async function retryTask(taskDir, taskId, error, logger = nullLogger) {
     throw err2;
   }
   const retryCount = (task.retryCount ?? 0) + 1;
-  const backoffMs = Math.min(5e3 * Math.pow(2, retryCount - 1), 6e4);
+  const backoffMs = options.delayMs ?? Math.min(5e3 * Math.pow(2, retryCount - 1), 6e4);
   task.status = "pending";
   task.retryCount = retryCount;
   task.retryAfter = new Date(Date.now() + backoffMs).toISOString();
@@ -5357,9 +5357,7 @@ async function bumpResourceGeneration(root, resource, options) {
     await atomicWriteFile2(resourceGenerationPath(root, resource), token);
     return token;
   } catch (err2) {
-    log4.warn("generation", `Failed to bump ${resource} generation for ${root}`, {
-      error: getErrorMessage3(err2)
-    });
+    canopyLogWarn2(`CanopyCMS: failed to bump ${resource} generation for ${root}:`, getErrorMessage3(err2));
     if (options?.mustSucceed)
       throw err2;
     return null;
@@ -10746,6 +10744,7 @@ var init_generate_ai_content = __esm({
     init_field_traversal();
     init_atomic_write2();
     init_error3();
+    init_logger2();
     log4 = createDebugLogger2({ prefix: "ResourceGeneration" });
     META_DIR2 = ".canopy-meta";
     init_logger2();
@@ -12394,9 +12393,20 @@ var init_generate_ai_content = __esm({
       mergedAt: z72.string().optional(),
       rebaseFailure: z72.object({ message: z72.string(), firstAt: z72.string(), lastAt: z72.string() }).optional(),
       historyRewrittenFrom: z72.string().optional(),
+      lastGitHubTip: z72.string().optional(),
+      keptOverGitHub: z72.array(z72.string()).optional(),
+      rewrittenOnGitHub: z72.string().optional(),
+      submitUnfinished: z72.boolean().optional(),
+      submitNotQueued: z72.boolean().optional(),
+      unpublishedAtMerge: z72.boolean().optional(),
       syncFailureReason: z72.string().optional(),
       editors: z72.array(z72.string()).optional(),
       uncommittedEditors: z72.array(z72.string()).optional(),
+      // Dropped when malformed: it only decorates the branch card, so it never fails a read.
+      pullRequestHold: z72.discriminatedUnion("kind", [
+        z72.object({ kind: z72.literal("conflicts") }),
+        z72.object({ kind: z72.literal("retargeted"), base: z72.string() })
+      ]).optional().catch(void 0),
       // Dropped when malformed: it only decorates the PR body, so it never fails a read.
       review: z72.object({
         state: z72.enum(["approved", "changes-requested"]),
@@ -17848,9 +17858,7 @@ async function bumpResourceGeneration2(root, resource, options) {
     await atomicWriteFile3(resourceGenerationPath2(root, resource), token);
     return token;
   } catch (err2) {
-    log11.warn("generation", `Failed to bump ${resource} generation for ${root}`, {
-      error: getErrorMessage(err2)
-    });
+    canopyLogWarn3(`CanopyCMS: failed to bump ${resource} generation for ${root}:`, getErrorMessage(err2));
     if (options?.mustSucceed)
       throw err2;
     return null;
@@ -17879,6 +17887,7 @@ var init_resource_generation = __esm({
     init_atomic_write3();
     init_error();
     init_debug2();
+    init_logger3();
     log11 = createDebugLogger3({ prefix: "ResourceGeneration" });
     META_DIR3 = ".canopy-meta";
   }
@@ -19206,9 +19215,20 @@ var init_branch_metadata_file = __esm({
       mergedAt: z18.string().optional(),
       rebaseFailure: z18.object({ message: z18.string(), firstAt: z18.string(), lastAt: z18.string() }).optional(),
       historyRewrittenFrom: z18.string().optional(),
+      lastGitHubTip: z18.string().optional(),
+      keptOverGitHub: z18.array(z18.string()).optional(),
+      rewrittenOnGitHub: z18.string().optional(),
+      submitUnfinished: z18.boolean().optional(),
+      submitNotQueued: z18.boolean().optional(),
+      unpublishedAtMerge: z18.boolean().optional(),
       syncFailureReason: z18.string().optional(),
       editors: z18.array(z18.string()).optional(),
       uncommittedEditors: z18.array(z18.string()).optional(),
+      // Dropped when malformed: it only decorates the branch card, so it never fails a read.
+      pullRequestHold: z18.discriminatedUnion("kind", [
+        z18.object({ kind: z18.literal("conflicts") }),
+        z18.object({ kind: z18.literal("retargeted"), base: z18.string() })
+      ]).optional().catch(void 0),
       // Dropped when malformed: it only decorates the PR body, so it never fails a read.
       review: z18.object({
         state: z18.enum(["approved", "changes-requested"]),

package/dist/cli/generate-ai-content.js

@@ -4404,6 +4404,7 @@ init_error();
 import fs5 from "node:fs/promises";
 import path7 from "node:path";
 import { randomUUID } from "node:crypto";
+init_logger();
 var log4 = createDebugLogger({ prefix: "ResourceGeneration" });
 var META_DIR2 = ".canopy-meta";
 function resourceGenerationPath(root, resource) {
@@ -4415,9 +4416,7 @@ async function bumpResourceGeneration(root, resource, options) {
     await atomicWriteFile(resourceGenerationPath(root, resource), token);
     return token;
   } catch (err) {
-    log4.warn("generation", `Failed to bump ${resource} generation for ${root}`, {
-      error: getErrorMessage(err)
-    });
+    canopyLogWarn(`CanopyCMS: failed to bump ${resource} generation for ${root}:`, getErrorMessage(err));
     if (options?.mustSucceed)
       throw err;
     return null;
@@ -7848,9 +7847,20 @@ var branchMetadataShape = {
   mergedAt: z7.string().optional(),
   rebaseFailure: z7.object({ message: z7.string(), firstAt: z7.string(), lastAt: z7.string() }).optional(),
   historyRewrittenFrom: z7.string().optional(),
+  lastGitHubTip: z7.string().optional(),
+  keptOverGitHub: z7.array(z7.string()).optional(),
+  rewrittenOnGitHub: z7.string().optional(),
+  submitUnfinished: z7.boolean().optional(),
+  submitNotQueued: z7.boolean().optional(),
+  unpublishedAtMerge: z7.boolean().optional(),
   syncFailureReason: z7.string().optional(),
   editors: z7.array(z7.string()).optional(),
   uncommittedEditors: z7.array(z7.string()).optional(),
+  // Dropped when malformed: it only decorates the branch card, so it never fails a read.
+  pullRequestHold: z7.discriminatedUnion("kind", [
+    z7.object({ kind: z7.literal("conflicts") }),
+    z7.object({ kind: z7.literal("retargeted"), base: z7.string() })
+  ]).optional().catch(void 0),
   // Dropped when malformed: it only decorates the PR body, so it never fails a read.
   review: z7.object({
     state: z7.enum(["approved", "changes-requested"]),

package/dist/cli/init.js

@@ -1207,7 +1207,7 @@ async function failTask(taskDir, taskId, error, logger = nullLogger) {
   });
   logger.debug("Failed task", { id: taskId, error });
 }
-async function retryTask(taskDir, taskId, error, logger = nullLogger) {
+async function retryTask(taskDir, taskId, error, logger = nullLogger, options = {}) {
   const processingPath = path6.join(taskDir, "processing", `${taskId}.json`);
   const pendingDir = path6.join(taskDir, "pending");
   const pendingPath = path6.join(pendingDir, `${taskId}.json`);
@@ -1228,7 +1228,7 @@ async function retryTask(taskDir, taskId, error, logger = nullLogger) {
     throw err;
   }
   const retryCount = (task.retryCount ?? 0) + 1;
-  const backoffMs = Math.min(5e3 * Math.pow(2, retryCount - 1), 6e4);
+  const backoffMs = options.delayMs ?? Math.min(5e3 * Math.pow(2, retryCount - 1), 6e4);
   task.status = "pending";
   task.retryCount = retryCount;
   task.retryAfter = new Date(Date.now() + backoffMs).toISOString();

package/dist/editor/BranchManager.d.ts

@@ -1,6 +1,6 @@
 import React from 'react';
 import type { OperatingMode } from '../operating-mode/index.js';
-import type { ConflictStatus, PullRequestState, SyncStatus } from '../types.js';
+import type { BranchHold, ConflictStatus, PullRequestState, SyncStatus } from '../types.js';
 import type { CommentThread } from '../comment-store.js';
 import type { UserSearchResult } from '../auth/types.js';
 import type { CreateRefusal } from './hooks/create-branch-request.js';
@@ -32,17 +32,21 @@ export interface BranchSummary {
     conflictStatus?: ConflictStatus;
     /** ContentIds of entries where --theirs was applied during rebase; cleared on clean rebase */
     conflictFiles?: string[];
+    /** What is stuck and needs a person (api/branch.ts). */
+    hold?: BranchHold;
     commentCount?: number;
     isProtected?: boolean;
     readOnly?: boolean;
     /**
-     * Server-computed compound submit rule (base-branch OR non-'editing'
-     * status) -- see `useBranchManager.tsx`'s `BranchSummary.submitBlocked` and
-     * `BranchWriteProtection.submitBlockedIncludingStatus` for the full
+     * Server-computed compound submit rule (base-branch, non-'editing'
+     * status, or rewritten on GitHub) -- see `useBranchManager.tsx`'s
+     * `BranchSummary.submitBlocked` and `BranchWriteProtection.submitBlockedIncludingStatus` for the full
      * rationale. `getBranchPermissions`'s `canSubmit` consumes this directly
      * instead of re-deriving `status === 'editing' && !isProtected`.
      */
     submitBlocked?: boolean;
+    /** Server-computed: the API refuses Approve, as the last submit didn't finish. */
+    approveBlocked?: boolean;
 }
 export interface UserContext {
     userId: string;