canopycms 0.0.67-int.90 → 0.0.67

package/dist/worker/git-sync.js

@@ -9,8 +9,8 @@ import { getErrorMessage, isNodeError, redactCredentials } from '../utils/error.
 import { isNonFastForwardRejection } from '../utils/git.js';
 import { hasPendingHistoryRewrite } from './history-rewrite.js';
 import { runRebaseCycle } from './rebase.js';
-import { cleanupOldTasks } from './task-queue.js';
-import { writeWorkerStatus } from './worker-status.js';
+import { cleanupOldTasks } from '../task-queue/cms-task-queue.js';
+import { writeWorkerStatus } from '../task-queue/worker-status.js';
 import { workerLog, workerLogError, workerLogWarn } from './log.js';
 /**
  * [C1] Retention window for `.trash-*` branch directories left behind by the
@@ -37,22 +37,17 @@ function parseTrashStamp(stamp) {
 }
 /**
  * Push THIS deployment's own settings branch (`ensureSettingsBranch()`) from
- * remote.git to GitHub. Non-fatal: a no-op push for an up-to-date branch
- * just succeeds quietly.
+ * remote.git to GitHub. Non-fatal: a no-op push for an up-to-date branch just
+ * succeeds quietly.
  *
- * Deliberately narrowed to one branch — this used to push EVERY local
- * branch matching `canopycms-settings-*`. With the tracking-namespace fetch
- * fix (GITHUB_TRACKING_REF_PREFIX), `reconcileTrackedBranches` creates local
- * heads for branches that exist on GitHub, so ANOTHER deployment's settings
- * branch (sharing this same GitHub repo) can legitimately show up as a
- * local head here too. Pushing it would be this deployment shipping
- * settings state it doesn't own.
+ * Narrowed to that ONE branch, never every local `canopycms-settings-*`:
+ * `reconcileTrackedBranches` creates local heads for branches that exist on
+ * GitHub, so ANOTHER deployment's settings branch (sharing this GitHub repo)
+ * can legitimately show up as a local head here. Pushing it would be this
+ * deployment shipping settings state it does not own.
  */
 export async function pushSettingsBranches(ctx, git, trackedNames) {
     try {
-        // Resolved once here rather than at each use below: ensureSettingsBranch()
-        // is idempotent, but a local reads better and keeps the eight references
-        // in this method obviously talking about one value.
         const settingsBranch = ctx.ensureSettingsBranch();
         const branches = await git.branch();
         const settingsBranches = branches.all.filter((b) => b.startsWith(RESERVED_SETTINGS_BRANCH_PREFIX));
@@ -66,19 +61,17 @@ export async function pushSettingsBranches(ctx, git, trackedNames) {
         // Check the full branch list, not the `canopycms-settings-*` subset: an
         // adopter-supplied `settingsBranch` override need not carry that prefix.
         const ownBranchMissing = !branches.all.includes(settingsBranch);
-        // [SYNC-M3] A settings branch present in remote.git but absent from
-        // GitHub's tracking refs was pushed here LOCALLY -- only this
-        // deployment's own API can write to remote.git -- and has never
-        // reached GitHub. That is the discriminating signature: in the
-        // SUPPORTED two-deployments-one-repo case the foreign branch arrives
-        // through the GitHub fetch and therefore always has a tracking ref, so
-        // the warn above cannot tell the two apart on its own and a
-        // "owned-branch-absent" test alone would fire on every deployment that
-        // simply has not had a settings edit yet.
+        // [SYNC-M3] A settings branch in remote.git but absent from GitHub's
+        // tracking refs was pushed here LOCALLY (only this deployment's own API
+        // writes to remote.git) and has never reached GitHub. That absence is the
+        // discriminating signature: in the SUPPORTED two-deployments-one-repo case
+        // the foreign branch arrives through the GitHub fetch and so always has a
+        // tracking ref, while an "owned-branch-absent" test alone would fire on
+        // every deployment that has simply had no settings edit yet.
         //
-        // With this deployment's own branch also missing, the API and this
-        // worker have resolved different deploymentNames, and every settings
-        // change the API commits is stranded in remote.git forever.
+        // With this deployment's own branch also missing, the API and this worker
+        // have resolved different deploymentNames, and every settings change the
+        // API commits is stranded in remote.git forever.
         const strandedLocal = foreign.filter((b) => !trackedNames.has(b));
         if (strandedLocal.length > 0) {
             workerLogWarn(ownBranchMissing
@@ -97,25 +90,20 @@ export async function pushSettingsBranches(ctx, git, trackedNames) {
             return;
         }
         try {
-            // Resolved in place rather than hoisted: this is the only push in the
-            // function, so there is no second call to keep consistent, and the
-            // resolution would have to move out to syncGit and arrive as an argument
-            // -- changing pushSettingsBranches' signature, which cms-worker.test.ts
-            // calls directly through the instance against an inline type naming it
-            // (see the `PushSettingsBranchesInternals` suite).
+            // Resolved in place, not hoisted: this is the only push in the function,
+            // so there is no second call to keep consistent, and hoisting would move
+            // the resolution out to syncGit and change this signature -- which
+            // cms-worker.test.ts pins by calling the method through the instance.
             await git.push(await ctx.buildGitHubUrl(), settingsBranch);
             workerLog(`Pushed settings branch ${settingsBranch} to GitHub`);
         }
         catch (err) {
-            // Non-fatal: branch may already be up-to-date. This call site has no
-            // task to throw a PermanentTaskError into (unlike pushBranchToGitHub)
-            // and is deliberately not restructured to add one -- but a
-            // non-fast-forward rejection here is the highest-signal instance of
-            // this whole failure class: it means another CanopyCMS deployment's
-            // worker already pushed ITS OWN state to its own settings branch on
-            // GitHub (an actual settings-branch name collision, not just the
-            // "foreign branch found locally" case warned about above), so make
-            // that explicit instead of a generic "push failed" line.
+            // Non-fatal: the branch may already be up to date, and this call site has
+            // no task to throw a PermanentTaskError into (unlike pushBranchToGitHub).
+            // A non-fast-forward rejection here still gets its own wording: it means
+            // another deployment's worker already pushed ITS OWN state to this
+            // settings-branch name on GitHub -- an actual collision, not just the
+            // "foreign branch found locally" case warned about above.
             const message = getErrorMessage(err);
             if (isNonFastForwardRejection(message)) {
                 workerLogWarn(`Settings push for ${settingsBranch} was rejected (non-fast-forward): another ` +
@@ -135,49 +123,32 @@ export async function pushSettingsBranches(ctx, git, trackedNames) {
 }
 /**
  * Bring `refs/heads/*` in `remote.git` toward what was just fetched into
- * `GITHUB_TRACKING_REF_PREFIX` -- WITHOUT ever force-rewinding or deleting
- * a local head. This is the non-destructive replacement for what the old
- * `+refs/heads/*:refs/heads/*` fetch refspec used to do implicitly (and
- * destructively) as part of the fetch itself; see
- * `GITHUB_TRACKING_REF_PREFIX`'s doc comment for the two failure modes
- * that refspec caused.
+ * `GITHUB_TRACKING_REF_PREFIX` -- WITHOUT ever force-rewinding or deleting a
+ * local head (see that constant's doc comment for the two failure modes a
+ * `+refs/heads/*:refs/heads/*` fetch refspec causes).
  *
- * Per tracked branch:
- * - no local `refs/heads/<name>` yet -> create it at the tracked commit
- *   (a branch created on GitHub, or by another deployment sharing this
- *   GitHub repo, becomes visible locally).
- * - local is a strict ancestor of tracked (behind) -> fast-forward it.
- * - local === tracked -> nothing to do.
- * - tracked is a strict ancestor of local (ahead) -> LEAVE IT ALONE. This
- *   is unpushed editor/settings work; the queued push task (or
- *   pushSettingsBranches) ships it. This is exactly the branch state the
- *   old refspec used to destroy.
- * - neither is an ancestor of the other (diverged) -> LEAVE IT ALONE and
- *   count/log it. A real collision (e.g. another deployment moved the
- *   same branch name on GitHub); the next push attempt will be rejected
- *   non-fast-forward, which is the correct, visible outcome -- this
- *   method must never silently pick a winner. The one expected, benign
- *   form of this -- our own rebase loop having published a rewrite into
- *   remote.git with the GitHub push still queued -- is split out into the
- *   `rewritten` bucket so the collision warning stays meaningful.
+ * Per tracked branch: no local `refs/heads/<name>` -> create it at the tracked
+ * commit; local behind -> fast-forward; equal -> nothing to do; local AHEAD ->
+ * LEAVE IT ALONE, since that is unpushed editor/settings work the queued push
+ * task (or pushSettingsBranches) ships; diverged -> LEAVE IT ALONE, count and
+ * log it. Divergence is a real collision (another deployment moved the same
+ * branch name on GitHub) and the next push is rejected non-fast-forward, the
+ * correct visible outcome -- this must never silently pick a winner. The one
+ * benign form, our own rebase loop having published a rewrite with the GitHub
+ * push still queued, is split into `rewritten` so that warning stays meaningful.
  *
- * Never deletes a local head: a branch removed on GitHub simply stops
- * being tracked here; the local ref persists until removed through its
- * own explicit path (the sync loop must not be one of them).
+ * Never deletes a local head: a branch removed on GitHub simply stops being
+ * tracked here; the local ref persists until removed through its own explicit
+ * path, which the sync loop must not be.
  *
- * `remote.git` is bare, so there is no worktree to invalidate by moving
- * these refs -- unlike a non-bare repo, updating the ref that happens to
- * be "checked out" is a non-issue here.
- *
- * Concurrency: `remote.git` is bare and on EFS, and the Lambda pushes into
- * it concurrently (`GitManager.push()`'s `target:target` refspec) while
- * this runs. Every `update-ref` below passes the expected old value (the
- * all-zeros OID for "must not exist yet" on creation, the previously-read
- * SHA for the fast-forward case) so a concurrent Lambda write landing in
- * the gap between the read and the write loses the ref update instead of
- * being silently clobbered -- the branch is simply revisited next cycle.
+ * Concurrency: `remote.git` is bare and on EFS, and the Lambda pushes into it
+ * while this runs. Every `update-ref` below passes the expected old value (the
+ * all-zeros OID for "must not exist yet" on creation, the just-read SHA for a
+ * fast-forward), so a concurrent Lambda write landing between the read and the
+ * write loses the ref update instead of silently clobbering it -- that branch
+ * is simply revisited next cycle.
  */
-export async function reconcileTrackedBranches(ctx, git) {
+async function reconcileTrackedBranches(ctx, git) {
     const GIT_ZERO_OID = '0000000000000000000000000000000000000000';
     const created = [];
     const fastForwarded = [];
@@ -186,7 +157,7 @@ export async function reconcileTrackedBranches(ctx, git) {
     const rewritten = [];
     // One invocation enumerates both namespaces: refs/heads/<name> (what the
     // Lambda pushes into and branch clones read from) and
-    // GITHUB_TRACKING_REF_PREFIX<name> (GitHub's tip, just fetched above).
+    // GITHUB_TRACKING_REF_PREFIX<name> (GitHub's tip).
     const raw = await git.raw([
         'for-each-ref',
         '--format=%(refname) %(objectname)',
@@ -212,9 +183,9 @@ export async function reconcileTrackedBranches(ctx, git) {
         const localRef = `refs/heads/${name}`;
         if (!localSha) {
             try {
-                // Zero old-value asserts the ref does not already exist -- guards
-                // against a concurrent Lambda push creating this exact branch
-                // name between the for-each-ref read above and this update.
+                // The zero old-value asserts the ref does not already exist, guarding
+                // against a concurrent Lambda push creating this exact branch name
+                // between the for-each-ref read above and this update.
                 await git.raw(['update-ref', localRef, trackedSha, GIT_ZERO_OID]);
                 created.push(name);
             }
@@ -225,30 +196,26 @@ export async function reconcileTrackedBranches(ctx, git) {
         }
         if (localSha === trackedSha)
             continue; // nothing to do
-        // [SYNC-M2] Everything below is per-branch best-effort. The rev-list
-        // used to sit between the two guarded update-ref calls with no guard
-        // of its own, so a single ref pointing at a missing or partially
-        // written object -- plausible on EFS with the Lambda writing
-        // concurrently -- threw out of this loop, out of syncGit()'s try, and
-        // skipped pushSettingsBranches(), refreshBaseBranchWorkspace() and
-        // rebaseActiveBranches() entirely. Nothing self-healed, so it recurred
-        // every cycle. One unreadable ref must cost its own branch, not the
-        // whole sync cycle.
+        // [SYNC-M2] Everything below is per-branch best-effort: one unreadable ref
+        // must cost its own branch, not the whole sync cycle. A ref pointing at a
+        // missing or partially written object is plausible on EFS with the Lambda
+        // writing concurrently, and an unguarded throw here escapes syncGit()'s try
+        // -- skipping pushSettingsBranches(), refreshBaseBranchWorkspace() and the
+        // rebase cycle, with nothing to self-heal it on the next pass.
         try {
-            // Count commits unique to each side in one call: left = commits local
-            // has that tracked doesn't (ahead), right = commits tracked has that
-            // local doesn't (behind). Exits 0 regardless of ancestry direction,
-            // unlike `merge-base --is-ancestor` (which simple-git would throw on
-            // a non-zero exit for the common "not an ancestor" case).
+            // Commits unique to each side in one call: left = local's (ahead), right
+            // = tracked's (behind). Exits 0 regardless of ancestry direction, unlike
+            // `merge-base --is-ancestor`, whose non-zero exit for the common "not an
+            // ancestor" case simple-git would throw on.
             const counts = (await git.raw(['rev-list', '--left-right', '--count', `${localSha}...${trackedSha}`])).trim();
             const [leftStr, rightStr] = counts.split(/\s+/);
             const localAheadCount = parseInt(leftStr, 10);
             const localBehindCount = parseInt(rightStr, 10);
             if (!Number.isInteger(localAheadCount) || !Number.isInteger(localBehindCount)) {
-                // Unparseable output means we could not read this branch, NOT that
-                // it diverged: falling through to the `diverged` bucket below would
-                // warn operators about a cross-deployment collision that never
-                // happened (parseInt yields NaN, and NaN fails both comparisons).
+                // Unparseable output means this branch could not be read, NOT that it
+                // diverged: falling through to the `diverged` bucket (parseInt yields
+                // NaN, which fails both comparisons) would warn operators about a
+                // cross-deployment collision that never happened.
                 workerLogWarn(`  Tracked-branch reconcile: skipping ${name}: unparseable rev-list output ${JSON.stringify(counts)}`);
                 continue;
             }
@@ -264,15 +231,14 @@ export async function reconcileTrackedBranches(ctx, git) {
                 }
             }
             else if (localBehindCount === 0 && localAheadCount > 0) {
-                // Unpushed local work -- exactly what the old destructive refspec
-                // used to force-rewind or delete. Leave it.
+                // Unpushed local work. Leave it.
                 ahead.push(name);
             }
             else if (await hasPendingHistoryRewrite(ctx, name)) {
-                // [SYNC-H1] Our own rebase published a rewrite into remote.git and
-                // the GitHub push has not landed yet. Ref-level this is identical
-                // to a collision, but it is expected and self-resolving, so it must
-                // not fire the collision warning below.
+                // [SYNC-H1] Our own rebase published a rewrite into remote.git and the
+                // GitHub push has not landed yet. Ref-level this is identical to a
+                // collision, but expected and self-resolving, so it must not fire the
+                // collision warning below.
                 rewritten.push(name);
             }
             else {
@@ -291,10 +257,9 @@ export async function reconcileTrackedBranches(ctx, git) {
     if (rewritten.length > 0) {
         workerLog(`  Tracked-branch reconcile: ${rewritten.length} branch(es) rebased locally with the GitHub push still pending: ${rewritten.join(', ')}`);
     }
-    // trackedNames is returned alongside the summary (rather than folded into
-    // it) because it is a working set for pushSettingsBranches' stranded-
-    // branch check, not part of the worker-status snapshot -- it lists every
-    // branch on GitHub and would bloat worker-status.json for no reader.
+    // trackedNames is returned alongside the summary rather than folded into it:
+    // it is a working set for pushSettingsBranches' stranded-branch check, and
+    // listing every branch on GitHub would bloat worker-status.json for no reader.
     return {
         summary: { created, fastForwarded, ahead, diverged, rewritten },
         trackedNames: new Set(tracked.keys()),
@@ -312,24 +277,21 @@ export async function syncGit(ctx) {
         // is inactivity-based, so a slow-but-flowing transfer is unaffected.
         timeout: { block: ctx.taskTimeoutMs },
     });
-    // This instance also drives pushSettingsBranches(git) below, whose
-    // classification of a rejected settings-branch push (see that method)
-    // needs the same stable-English guarantee as pushBranchToGitHub. Network
-    // env for the same reason: the fetch and push here reach GitHub.
+    // gitNetworkChildEnv because the fetch and push here reach GitHub, and
+    // because pushSettingsBranches(git) below needs its stable-English guarantee
+    // to classify a rejected settings-branch push.
     git.env(gitNetworkChildEnv());
-    // PR-W1: the whole cycle is wrapped so both outcomes -- success and
-    // hard failure (e.g. the fetch throwing against a poisoned remote.git)
-    // -- record a worker-status.json snapshot. The status write itself is
-    // always best-effort (.catch below): it must never turn an otherwise
-    // successful cycle into a failure, and must never mask the real error
-    // on a failed one. On failure we rethrow so scheduleLoop's existing
+    // The whole cycle is wrapped so both outcomes -- success and hard failure
+    // (e.g. the fetch throwing against a poisoned remote.git) -- record a
+    // worker-status.json snapshot. The status write itself is always best-effort
+    // (.catch below): it must never turn a successful cycle into a failure, nor
+    // mask the real error on a failed one. Failures rethrow, so scheduleLoop's
     // per-cycle catch stays the loud path.
     try {
-        // Fetch all branches from GitHub using direct URL (no named remote),
-        // into the GITHUB_TRACKING_REF_PREFIX remote-tracking namespace rather
-        // than refs/heads/* directly -- see that constant's doc comment for
-        // the destructive-fetch bug this avoids. We use raw git commands since
-        // simple-git's fetch() with a URL doesn't support --prune directly.
+        // Direct URL (no named remote), into the GITHUB_TRACKING_REF_PREFIX
+        // remote-tracking namespace rather than refs/heads/* -- see that constant's
+        // doc comment for the destructive-fetch bug this avoids. Raw git, because
+        // simple-git's fetch() with a URL does not support --prune.
         await git.raw([
             'fetch',
             await ctx.buildGitHubUrl(),
@@ -337,9 +299,6 @@ export async function syncGit(ctx) {
             `+refs/heads/*:${GITHUB_TRACKING_REF_PREFIX}*`,
         ]);
         workerLog('Fetched from GitHub');
-        // Bring refs/heads/* toward what was just fetched, WITHOUT ever
-        // force-rewinding or deleting a local head -- see
-        // reconcileTrackedBranches()'s doc comment.
         const { summary: trackedSummary, trackedNames } = await reconcileTrackedBranches(ctx, git);
         // Push settings branches to GitHub (belt-and-suspenders for task queue).
         // Ensures settings reach GitHub even if a task queue entry is lost.
@@ -349,12 +308,11 @@ export async function syncGit(ctx) {
         await pushSettingsBranches(ctx, git, trackedNames);
         await refreshBaseBranchWorkspace(ctx);
         const rebaseSummary = await runRebaseCycle(ctx);
-        // Periodically clean up old completed/failed tasks
         await cleanupOldTasks(ctx.taskDir, undefined, ctx.log);
-        // [C1] Sweep branch directories the admin purge action trashed more
-        // than TRASH_RETENTION_MS ago. Worker-only by design: purge itself
-        // never deletes anything (reversible), and this cycle is the sole
-        // place actual removal happens.
+        // [C1] Sweep branch directories the admin purge action trashed more than
+        // TRASH_RETENTION_MS ago. Worker-only by design: purge itself never deletes
+        // anything (it stays reversible), and this is the sole place removal
+        // actually happens.
         const trashRemoved = await cleanupTrashedBranchDirs(ctx);
         if (trashRemoved > 0) {
             workerLog(`Removed ${trashRemoved} expired trashed branch dir(s)`);
@@ -386,14 +344,12 @@ export async function syncGit(ctx) {
     }
 }
 /**
- * [C1] Remove `.trash-*` branch directories (created by the admin purge
- * action, api/admin-branch-health.ts) whose name-embedded stamp is older
- * than {@link TRASH_RETENTION_MS}. Names that don't match the expected
- * `.trash-{dirName}-{STAMP}` shape, or whose stamp fails to parse, are
- * left alone (logged once per cycle, not per file, to avoid flooding logs
- * if something odd accumulates) -- purge is the only writer of this
- * naming scheme, so an unparseable name is unexpected and worth a human
- * looking rather than a silent skip.
+ * [C1] Remove `.trash-*` branch directories (created by the admin purge action,
+ * api/admin-branch-health.ts) whose name-embedded stamp is older than
+ * {@link TRASH_RETENTION_MS}. A name that doesn't match `.trash-{dirName}-
+ * {STAMP}`, or whose stamp fails to parse, is left alone and logged once per
+ * cycle: purge is the only writer of this naming scheme, so an unparseable name
+ * is unexpected and worth a human looking rather than a silent skip.
  */
 export async function cleanupTrashedBranchDirs(ctx) {
     let entries;
@@ -439,24 +395,17 @@ export async function cleanupTrashedBranchDirs(ctx) {
 }
 /**
  * Fast-forward the base branch's own working-tree clone
- * (content-branches/<baseBranch>) to match origin/<baseBranch>.
+ * (content-branches/<baseBranch>) to match origin/<baseBranch>, every sync
+ * cycle, so the drift window is bounded by gitSyncInterval.
  *
- * Previously this clone was refreshed only incidentally, by the generic
- * rebase loop below (rebaseActiveBranches): for a branch with status
- * 'editing', rebasing onto origin/<baseBranch> degenerates to a
- * fast-forward when the clone IS the base branch. But that loop's skip
- * paths -- a dirty tree, a missing .git -- are silent, which is the
- * suspected live failure mode: a wedged base clone with no diagnosable
- * signal in the logs. This dedicated step makes the refresh explicit,
- * ff-only, and loud, so a stuck base view (an editor forking a new branch
- * "from base" that's actually a stale snapshot) is diagnosable from logs.
- * This runs every sync cycle so the drift window is bounded by
- * gitSyncInterval.
+ * A dedicated, explicit and LOUD step rather than a side effect of the rebase
+ * loop, whose skip paths (a dirty tree, a missing .git) are silent: a wedged
+ * base clone otherwise leaves no diagnosable signal, and an editor forking a
+ * new branch "from base" silently gets a stale snapshot.
  *
  * ff-only on purpose: this clone must stay a linear mirror of
- * origin/<baseBranch>, so a merge that isn't a fast-forward (diverged
- * local history) is treated as a should-never-happen condition and left
- * untouched rather than force-resolved.
+ * origin/<baseBranch>, so a merge that isn't a fast-forward (diverged local
+ * history) is left untouched rather than force-resolved.
  */
 export async function refreshBaseBranchWorkspace(ctx) {
     // Sanitized name for the workspace directory (a base branch containing
@@ -478,28 +427,22 @@ export async function refreshBaseBranchWorkspace(ctx) {
         const baseGit = simpleGit({
             baseDir: basePath,
             // Keep git non-interactive during the merge so it never blocks on an
-            // editor. simple-git >=3.32 blocks setting core.editor unless
-            // explicitly opted in; the value here is a hardcoded literal
-            // ("true", the shell no-op), not user input, so enabling
-            // allowUnsafeEditor carries no injection risk (same as the rebase
-            // loop's git config below).
+            // editor. simple-git >=3.32 requires opting in to set core.editor; the
+            // value is a hardcoded literal ("true", the shell no-op), not user input,
+            // so allowUnsafeEditor carries no injection risk here.
             config: ['core.editor=true'],
             unsafe: { allowUnsafeEditor: true },
-            // DEP-H1: a hung fetch/merge against this EFS-backed clone would
-            // stall the sync loop forever (scheduleLoop only reschedules after
-            // completion). The block timeout is inactivity-based, so a
-            // slow-but-flowing transfer is unaffected -- same as syncGit()'s
-            // remote handle.
+            // DEP-H1: a hung fetch/merge against this EFS-backed clone would stall
+            // the sync loop forever (scheduleLoop only reschedules after completion).
+            // Inactivity-based, so a slow-but-flowing transfer is unaffected.
             timeout: { block: ctx.taskTimeoutMs },
         });
-        // Nothing makes this clone read-only. A direct edit here (or a stray
-        // process) wedges every editor's view of the base branch until an
-        // operator intervenes, so a dirty tree is loud, not a quiet skip.
-        // Only TRACKED changes block the refresh: a stray untracked file (e.g.
-        // runtime metadata missing from .git/info/exclude) must not wedge the
-        // fast-forward forever — if an untracked file would collide with
-        // incoming content, the --ff-only merge below refuses on its own and
-        // that failure is already logged loudly.
+        // Nothing makes this clone read-only, and a direct edit here wedges every
+        // editor's view of the base branch until an operator intervenes, so a dirty
+        // tree is loud, not a quiet skip. Only TRACKED changes block the refresh: a
+        // stray untracked file must not wedge the fast-forward forever, and if one
+        // would collide with incoming content the --ff-only merge below refuses on
+        // its own and that failure is already logged loudly.
         const status = await baseGit.status();
         const trackedDirty = status.files.filter((f) => f.index !== '?' || f.working_dir !== '?');
         if (trackedDirty.length > 0) {
@@ -510,16 +453,12 @@ export async function refreshBaseBranchWorkspace(ctx) {
         // against origin/<baseBranch>, not filesystem paths, so they must use
         // the same name GitHub knows the branch by.
         await baseGit.fetch('origin', ctx.baseBranch);
-        // Use rev-list instead of status.behind for the same reason as the
-        // rebase loop below: status.behind only works with an upstream
-        // tracking branch configured, which isn't guaranteed here.
-        // Compare against the just-fetched tip rather than origin/<base>:
-        // workspaces are cloned --single-branch (git-manager.ts), so their
-        // fetch refspec only materializes a remote-tracking ref for the branch
-        // they were cloned from — for any other base branch, origin/<base>
-        // simply never exists and rev-list dies with "ambiguous argument".
-        // Pin FETCH_HEAD to a SHA immediately: FETCH_HEAD is one shared mutable
-        // file per repo, silently repointed by ANY other fetch in this clone.
+        // rev-list, not status.behind, which needs an upstream tracking branch that
+        // is not guaranteed here. Against the just-fetched tip rather than
+        // origin/<base>: workspaces are cloned --single-branch (git-manager.ts), so
+        // for any other base branch origin/<base> never exists and rev-list dies
+        // with "ambiguous argument". Pin FETCH_HEAD to a SHA immediately -- it is
+        // one shared mutable file per repo, silently repointed by any other fetch.
         const fetchedTip = (await baseGit.revparse(['FETCH_HEAD'])).trim();
         const behindCount = parseInt((await baseGit.raw(['rev-list', '--count', `HEAD..${fetchedTip}`])).trim(), 10);
         if (behindCount > 0) {
@@ -533,11 +472,10 @@ export async function refreshBaseBranchWorkspace(ctx) {
             await invalidateBranchContentCaches(basePath);
         }
         // Hygiene: conflictStatus/conflictFiles are meaningless for the base
-        // branch's own metadata and may be left over from before the base was
-        // excluded from rebaseActiveBranches()'s conflict-resolution loop.
-        // Reuse the already-clean no-op-save guard from that loop: save()
-        // eager-regenerates the branch registry (O(branch count) EFS reads),
-        // so skip it when there's nothing to clear.
+        // branch's own metadata, which is excluded from the rebase loop's
+        // conflict-resolution pass. Guarded on already-clean, like that loop:
+        // save() eager-regenerates the branch registry (O(branch count) EFS reads),
+        // so skip it when there is nothing to clear.
         const currentMeta = await BranchMetadataFileManager.loadOnly(basePath);
         const conflictStatus = currentMeta?.branch.conflictStatus;
         const conflictFiles = currentMeta?.branch.conflictFiles;

package/dist/worker/github-auth.d.ts

@@ -192,6 +192,7 @@ export declare function resolveWorkerGitHubAuth(config: GitHubAuthConfig): Resol
  * A named class rather than a bare Error because `isTransientAuthFailure`
  * below has to recognise it: a timeout carries no HTTP status, and the
  * fail-closed rule there would otherwise read "slow network" as "wrong key".
+ * @internal Exported for tests.
  */
 export declare class MintTimeoutError extends Error {
     constructor(timeoutMs: number);
@@ -244,25 +245,18 @@ export declare function isTransientAuthFailure(err: unknown): boolean;
  * is configured, naming the key — rather than surfacing later as an opaque
  * JWT signing failure.
  *
- * The PKCS#1 → PKCS#8 conversion is INSURANCE, not a fix for a current
- * failure. GitHub issues App keys as PKCS#1 (`-----BEGIN RSA PRIVATE KEY-----`),
- * and whether that is accepted depends on which build of
- * `universal-github-app-jwt` a bundler resolves, never on the key:
- * - At the pin we install (`@octokit/auth-app@6` → `universal-github-app-jwt@1.2.0`,
- *   which has no `exports` field) the worker's own flags,
- *   `esbuild --platform=node --format=esm`, resolve `main` → the `dist-node`
- *   build, which signs via `jsonwebtoken` and takes PKCS#1 happily. Measured
- *   by bundling with exactly those flags: an unconverted key works.
- * - That same package's `module`/`browser` entry is a WebCrypto build that
- *   throws "Private Key is in PKCS#1 format, but only PKCS#8 is supported".
- *   Any resolver preferring `module` reaches it.
- * - Per their published package.json files (neither is installed here),
- *   `@octokit/auth-app@7` moves to `universal-github-app-jwt@2`, which is
- *   WebCrypto-only and converts PKCS#1 solely under the **`node` condition of
- *   its `imports` map** (`"#crypto"` → `lib/crypto-node.js`); the `default`
- *   sibling's `convertPrivateKey` is a literal no-op, and the key throws.
- *
- * So a bundler flag or a dependency bump can turn a working key into a boot
+ * The PKCS#1 → PKCS#8 conversion is INSURANCE, not a fix for a current failure.
+ * GitHub issues App keys as PKCS#1 (`-----BEGIN RSA PRIVATE KEY-----`), and
+ * whether that is accepted depends on which build of `universal-github-app-jwt`
+ * a bundler resolves, never on the key: at the pin we install
+ * (`@octokit/auth-app@6` → `universal-github-app-jwt@1.2.0`, no `exports`
+ * field) the worker's `esbuild --platform=node --format=esm` reaches `main` →
+ * the `dist-node` build, which signs via `jsonwebtoken` and takes PKCS#1; that
+ * same package's `module`/`browser` entry is a WebCrypto build that rejects it;
+ * and `universal-github-app-jwt@2` (what `@octokit/auth-app@7` pulls in) is
+ * WebCrypto-only, converting PKCS#1 solely under the `node` condition of its
+ * `imports` map, its `default` sibling's `convertPrivateKey` being a no-op. So
+ * a bundler flag or a dependency bump can turn a working key into a boot
  * failure without the key changing. Three lines here remove that coupling.
  */
 export declare function normalizeGitHubAppPrivateKey(privateKey: string): string;

package/dist/worker/github-auth.js

@@ -232,6 +232,7 @@ async function mintInstallationToken(app, timeoutMs) {
  * A named class rather than a bare Error because `isTransientAuthFailure`
  * below has to recognise it: a timeout carries no HTTP status, and the
  * fail-closed rule there would otherwise read "slow network" as "wrong key".
+ * @internal Exported for tests.
  */
 export class MintTimeoutError extends Error {
     constructor(timeoutMs) {
@@ -343,25 +344,18 @@ function getHttpStatus(err) {
  * is configured, naming the key — rather than surfacing later as an opaque
  * JWT signing failure.
  *
- * The PKCS#1 → PKCS#8 conversion is INSURANCE, not a fix for a current
- * failure. GitHub issues App keys as PKCS#1 (`-----BEGIN RSA PRIVATE KEY-----`),
- * and whether that is accepted depends on which build of
- * `universal-github-app-jwt` a bundler resolves, never on the key:
- * - At the pin we install (`@octokit/auth-app@6` → `universal-github-app-jwt@1.2.0`,
- *   which has no `exports` field) the worker's own flags,
- *   `esbuild --platform=node --format=esm`, resolve `main` → the `dist-node`
- *   build, which signs via `jsonwebtoken` and takes PKCS#1 happily. Measured
- *   by bundling with exactly those flags: an unconverted key works.
- * - That same package's `module`/`browser` entry is a WebCrypto build that
- *   throws "Private Key is in PKCS#1 format, but only PKCS#8 is supported".
- *   Any resolver preferring `module` reaches it.
- * - Per their published package.json files (neither is installed here),
- *   `@octokit/auth-app@7` moves to `universal-github-app-jwt@2`, which is
- *   WebCrypto-only and converts PKCS#1 solely under the **`node` condition of
- *   its `imports` map** (`"#crypto"` → `lib/crypto-node.js`); the `default`
- *   sibling's `convertPrivateKey` is a literal no-op, and the key throws.
- *
- * So a bundler flag or a dependency bump can turn a working key into a boot
+ * The PKCS#1 → PKCS#8 conversion is INSURANCE, not a fix for a current failure.
+ * GitHub issues App keys as PKCS#1 (`-----BEGIN RSA PRIVATE KEY-----`), and
+ * whether that is accepted depends on which build of `universal-github-app-jwt`
+ * a bundler resolves, never on the key: at the pin we install
+ * (`@octokit/auth-app@6` → `universal-github-app-jwt@1.2.0`, no `exports`
+ * field) the worker's `esbuild --platform=node --format=esm` reaches `main` →
+ * the `dist-node` build, which signs via `jsonwebtoken` and takes PKCS#1; that
+ * same package's `module`/`browser` entry is a WebCrypto build that rejects it;
+ * and `universal-github-app-jwt@2` (what `@octokit/auth-app@7` pulls in) is
+ * WebCrypto-only, converting PKCS#1 solely under the `node` condition of its
+ * `imports` map, its `default` sibling's `convertPrivateKey` being a no-op. So
+ * a bundler flag or a dependency bump can turn a working key into a boot
  * failure without the key changing. Three lines here remove that coupling.
  */
 export function normalizeGitHubAppPrivateKey(privateKey) {