canopycms 0.8.1 → 0.8.3

package/dist/api/branch-review.js

@@ -8,7 +8,7 @@ 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';
+import { getBranchProtection, isAdmin } from '../authorization/index.js';
 import { sanitizeDisplayName } from '../submission-attribution.js';
 /** Optional on the wire: a bodiless request means no note. */
 const requestChangesBodySchema = z
@@ -130,8 +130,11 @@ const approveBranchHandler = async (gc, ctx, req, _params) => {
         };
     }
     const meta = getBranchMetadataFileManager(branchContext.branchRoot, branchContext.baseRoot);
-    // As for request changes, the status on disk decides, in the step that writes.
+    // As for request changes, the status on disk decides, in the step that writes. So does an
+    // unfinished submit: what's approved may not be what the pull request holds.
     let found;
+    let unfinished = false;
+    let notQueued = false;
     const updated = await meta.saveIf({
         branch: {
             name: branchContext.branch.name,
@@ -140,8 +143,22 @@ const approveBranchHandler = async (gc, ctx, req, _params) => {
         },
     }, (existing) => {
         found = existing?.branch.status;
-        return found === 'submitted';
+        unfinished = existing?.branch.submitUnfinished === true;
+        notQueued = existing?.branch.submitNotQueued === true;
+        return found === 'submitted' && !unfinished;
     });
+    if (unfinished && found === 'submitted') {
+        return {
+            ok: false,
+            status: 409,
+            error: "This branch's last submit didn't finish, so it can't be approved until it does. " +
+                (notQueued
+                    ? 'Use "Request changes" to send it back to its editor.'
+                    : isAdmin(req.user.groups)
+                        ? 'Retry the submit from the "Tasks" tab in "System health".'
+                        : 'Ask an admin to retry the submit.'),
+        };
+    }
     if (!updated)
         return approveConflict(found);
     // Against the branch the save returned, as for request changes. Best-effort: syncPrComments

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/authorization/branch.d.ts

@@ -25,6 +25,12 @@ interface BranchAccessOptions {
      * private.
      */
     isProtectedBranch?: boolean;
+    /**
+     * Whether this is dev's auto-provisioned active branch ({@link isDevActiveBranch}). It passes
+     * this layer where the base branch does, so it reads (and in dev saves) like the base;
+     * {@link canPerformWorkflowAction} never passes it, so no workflow rights follow.
+     */
+    isDevActiveBranch?: boolean;
 }
 /**
  * Check if user has access to a branch with explicit default behavior.
@@ -35,17 +41,17 @@ interface BranchAccessOptions {
  * 3. An explicit user/group ACL -- an allowlist omitting the creator still
  *    denies them, so an admin can lock down a branch someone else created
  * 4. With no ACL: the branch creator, then `defaultAccess`, and only where that
- *    would deny, the protected base branch grant
- *    (see {@link BranchAccessOptions.isProtectedBranch})
+ *    would deny, the base branch or dev active branch grant ({@link BranchAccessOptions})
  * @internal Exported for tests.
  */
 export declare function checkBranchAccessWithDefault(context: BranchContext, user: CanopyUser, defaultAccess?: DefaultBranchAccess, options?: BranchAccessOptions): BranchAccessResult;
 /**
  * Bind a default access level. `config` is needed only to resolve the
  * protected-base-branch question, which routes through `getBranchProtection`,
- * its single source of truth, rather than repeating the comparison here.
+ * its single source of truth, rather than repeating the comparison here, and
+ * the dev-active-branch question ({@link isDevActiveBranch}).
  */
-export declare function createCheckBranchAccess(defaultAccess?: DefaultBranchAccess, config?: Pick<CanopyConfig, 'mode' | 'defaultBaseBranch'>): (context: BranchContext, user: CanopyUser) => BranchAccessResult;
+export declare function createCheckBranchAccess(defaultAccess?: DefaultBranchAccess, config?: Pick<CanopyConfig, 'mode' | 'defaultBaseBranch' | 'defaultActiveBranch'>): (context: BranchContext, user: CanopyUser) => BranchAccessResult;
 /** Options tightening {@link canPerformWorkflowAction} beyond the default hybrid model. */
 export interface WorkflowActionOptions {
     /**

package/dist/authorization/branch.js

@@ -1,6 +1,22 @@
 import { isAdmin, isLockedOutOfBranch, isReviewer } from './helpers.js';
 import { getBranchProtection } from './protected-branch.js';
-import { SYSTEM_USER_ID } from '../system-users.js';
+import { isSystemUserId, SYSTEM_USER_ID } from '../system-users.js';
+import { sanitizeBranchName } from '../paths/branch-name.js';
+import { baseBranchOf } from '../utils/base-branch.js';
+/**
+ * Whether `context` is the active branch a dev server provisioned for itself: owned by a CanopyCMS
+ * system user, so nobody is its creator, and named like the active branch now, which follows git
+ * HEAD unless configured and is not the base when HEAD has left a configured `defaultBaseBranch`.
+ * A person's branch never is.
+ * `mode` is the adopter's configured operating mode; a prod deployment's is 'prod', so prod
+ * returns before the name comparison and never consults its possibly unresolved base branch.
+ */
+function isDevActiveBranch(config, context) {
+    if (config.mode !== 'dev' || !isSystemUserId(context.branch.createdBy))
+        return false;
+    const active = config.defaultActiveBranch ?? baseBranchOf(config);
+    return sanitizeBranchName(context.branch.name) === sanitizeBranchName(active);
+}
 /**
  * Check if user has access to a branch with explicit default behavior.
  *
@@ -10,8 +26,7 @@ import { SYSTEM_USER_ID } from '../system-users.js';
  * 3. An explicit user/group ACL -- an allowlist omitting the creator still
  *    denies them, so an admin can lock down a branch someone else created
  * 4. With no ACL: the branch creator, then `defaultAccess`, and only where that
- *    would deny, the protected base branch grant
- *    (see {@link BranchAccessOptions.isProtectedBranch})
+ *    would deny, the base branch or dev active branch grant ({@link BranchAccessOptions})
  * @internal Exported for tests.
  */
 export function checkBranchAccessWithDefault(context, user, defaultAccess = 'deny', options) {
@@ -43,6 +58,9 @@ export function checkBranchAccessWithDefault(context, user, defaultAccess = 'den
         if (options?.isProtectedBranch) {
             return { allowed: true, reason: 'base_branch' };
         }
+        if (options?.isDevActiveBranch) {
+            return { allowed: true, reason: 'dev_active_branch' };
+        }
         return { allowed: false, reason: 'no_acl' };
     }
     const userAllowed = hasUserConstraint && access.allowedUsers?.includes(user.userId);
@@ -53,13 +71,15 @@ export function checkBranchAccessWithDefault(context, user, defaultAccess = 'den
 /**
  * Bind a default access level. `config` is needed only to resolve the
  * protected-base-branch question, which routes through `getBranchProtection`,
- * its single source of truth, rather than repeating the comparison here.
+ * its single source of truth, rather than repeating the comparison here, and
+ * the dev-active-branch question ({@link isDevActiveBranch}).
  */
 export function createCheckBranchAccess(defaultAccess = 'deny', config) {
     return (context, user) => checkBranchAccessWithDefault(context, user, defaultAccess, {
         isProtectedBranch: config
             ? getBranchProtection(config, context.branch.name, context.branch.baseBranch).isProtected
             : false,
+        isDevActiveBranch: config ? isDevActiveBranch(config, context) : false,
     });
 }
 /**

package/dist/authorization/types.d.ts

@@ -7,7 +7,7 @@ export type PermissionPath = string & {
 };
 export interface BranchAccessResult {
     allowed: boolean;
-    reason: 'privileged' | 'base_branch' | 'creator' | 'allowed_by_acl' | 'denied_by_acl' | 'no_acl';
+    reason: 'privileged' | 'base_branch' | 'dev_active_branch' | 'creator' | 'allowed_by_acl' | 'denied_by_acl' | 'no_acl';
 }
 export interface PathPermissionResult {
     allowed: boolean;

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. */