canopycms 0.0.67-int.90 → 0.0.67

package/dist/worker/cms-worker.d.ts

@@ -3,16 +3,16 @@ export { PermanentTaskError, isPermanentTaskFailure } from './task-runner.js';
 export { workerLog, workerLogWarn, workerLogError, installWorkerLogger } from './log.js';
 export { normalizeGitHubAppPrivateKey, DEFAULT_GIT_TOKEN_MINT_TIMEOUT_MS, DEFAULT_GITHUB_TOKEN_REFRESH_MIN_INTERVAL_MS, type GitHubAppAuth, type GitHubAuthConfig, } from './github-auth.js';
 /**
- * Auth cache refresh function type.
- * Adopters provide their auth-plugin-specific implementation.
- * For Clerk: use refreshClerkCache from canopycms-auth-clerk/cache-writer.
+ * Auth cache refresh function type; adopters supply their auth-plugin-specific
+ * implementation (for Clerk, refreshClerkCache from
+ * canopycms-auth-clerk/cache-writer).
  */
 export type AuthCacheRefresher = () => Promise<void>;
 /**
  * `githubToken` / `githubAppAuth` / `gitTokenMintTimeoutMs` are declared
- * together in `GitHubAuthConfig` (./github-auth) because they are one
- * decision, resolved in one place. The token remains the documented default;
- * see that interface for the two shapes and why an App is optional.
+ * together in `GitHubAuthConfig` (./github-auth) because they are one decision,
+ * resolved in one place. The token is the documented default; see that
+ * interface for the two shapes and why an App is optional.
  */
 export interface CmsWorkerConfig extends GitHubAuthConfig {
     /** Path to workspace root on EFS (e.g., /mnt/efs/workspace) */
@@ -21,11 +21,7 @@ export interface CmsWorkerConfig extends GitHubAuthConfig {
     githubOwner: string;
     /** GitHub repo name (e.g., 'docs-site') */
     githubRepo: string;
-    /**
-     * Auth cache refresh callback. Called periodically to update the auth
-     * metadata cache on EFS. Adopters provide their auth-plugin-specific
-     * implementation (e.g., refreshClerkCache from canopycms-auth-clerk).
-     */
+    /** Called periodically to update the auth metadata cache on EFS. */
     refreshAuthCache?: AuthCacheRefresher;
     /** Task queue poll interval in ms (default: 5000) */
     taskPollInterval?: number;
@@ -36,22 +32,20 @@ export interface CmsWorkerConfig extends GitHubAuthConfig {
     /** Base branch name (default: 'main') */
     baseBranch?: string;
     /**
-     * Deployment name, used to compute THIS worker's own settings branch
-     * (`canopycms-settings-{deploymentName}`, default: 'prod' — matches
-     * ProdStrategy's mode default in operating-mode/client-unsafe-strategy.ts,
-     * the only mode the worker runs in). Two deployments can share one GitHub
-     * repo with distinct settings branches; this tells the worker which one it
-     * owns, so it never pushes another deployment's settings branch (see
-     * `pushSettingsBranches`).
+     * Names THIS worker's own settings branch
+     * (`canopycms-settings-{deploymentName}`, default 'prod' — ProdStrategy's
+     * mode default in operating-mode/client-unsafe-strategy.ts, the only mode the
+     * worker runs in). Two deployments can share one GitHub repo with distinct
+     * settings branches; this is what tells the worker which one it owns, so it
+     * never pushes another deployment's (see `pushSettingsBranches`).
      */
     deploymentName?: string;
     /**
-     * Explicit settings branch name, taking precedence over `deploymentName`.
-     * Mirrors the strategy's own precedence (`config.settingsBranch` short-circuits
-     * `getSettingsBranchName` before `deploymentName` is consulted, see
-     * operating-mode/client-unsafe-strategy.ts): an adopter who overrides
-     * `settingsBranch` in canopycms.config.ts must set this too, or the worker
-     * would own a branch name the Lambda never writes to.
+     * Explicit settings branch name, taking precedence over `deploymentName` and
+     * mirroring the strategy's own precedence (operating-mode/
+     * client-unsafe-strategy.ts). An adopter who overrides `settingsBranch` in
+     * canopycms.config.ts MUST set this too, or the worker owns a branch name the
+     * Lambda never writes to.
      */
     settingsBranch?: string;
     /** Max tasks to process per cycle (default: 10) */
@@ -63,23 +57,20 @@ export interface CmsWorkerConfig extends GitHubAuthConfig {
     /** Content root directory name relative to repo root (default: 'content') */
     contentRoot?: string;
     /**
-     * Worker lock staleness TTL in ms (default: 60000, minimum 2000).
-     * The holder refreshes the lock heartbeat at half this interval; a lock
-     * whose heartbeat is older than this is considered abandoned and taken
-     * over by the next worker to start.
+     * Worker lock staleness TTL in ms (default 60000, minimum 2000). The holder
+     * refreshes the heartbeat at half this interval; a lock whose heartbeat is
+     * older than this is abandoned and taken over by the next worker to start.
      */
     lockStaleMs?: number;
 }
 /**
- * CMS Worker daemon.
- * Handles operations that Lambda (with no internet) cannot perform:
- * - Processing queued tasks (push branches, create PRs)
- * - Syncing bare repo with GitHub
- * - Rebasing active branch workspaces
- * - Refreshing auth metadata cache (via pluggable callback)
+ * CMS Worker daemon: the operations Lambda, which has no internet, cannot
+ * perform -- draining the task queue, syncing the bare repo with GitHub,
+ * rebasing branch workspaces, and refreshing the auth metadata cache through a
+ * pluggable callback.
  *
- * Auth-agnostic: does not depend on any specific auth provider.
- * Cloud-agnostic: uses git/Octokit directly, no AWS SDK dependency.
+ * Auth-agnostic (no specific auth provider) and cloud-agnostic (git/Octokit
+ * directly, no AWS SDK dependency).
  */
 export declare class CmsWorker {
     private config;
@@ -105,40 +96,33 @@ export declare class CmsWorker {
     private githubAuth?;
     constructor(config: CmsWorkerConfig);
     /**
-     * Lazily get (and initialize if necessary) this worker's self-reported
-     * status object (PR-W1). Normally set once, up front, at the top of
-     * start(). The lazy fallback here covers two cases: (1) something in
-     * start() reaching a status-write point before that normal init runs
-     * (defensive -- see start()'s catch), and (2) unit tests that exercise
-     * syncGit()/processTaskQueue() directly without calling start() first.
+     * This worker's self-reported status object, initialized on first use.
+     * Normally set at the top of start(); the lazy fallback covers something in
+     * start() reaching a status-write point before that (see start()'s catch) and
+     * unit tests driving syncGit()/processTaskQueue() without calling start().
      */
     private ensureStatusReport;
     /**
      * Resolve this deployment's settings branch, throwing if the infra-stamped
      * deployment name is not a valid git ref component.
      *
-     * Routed through the shared resolver, not a local `?? 'prod'`: it is the
+     * Routed through the shared resolver, not a local `?? 'prod'`: that is the
      * single definition of the env > config > mode-default precedence the Lambda
-     * already follows, and the only place the resolved value is validated.
-     * Without it the worker could silently own a different settings branch than
-     * the Lambda writing to the same workspace -- and pushSettingsBranches would
-     * then report the real branch as foreign and never push it.
-     *
-     * DEFERRED out of the constructor deliberately, and this is the whole point
-     * of the method existing. Resolving there made the throw land during `new
-     * CmsWorker(...)` (canopycms-cdk/worker/index.ts constructs before it calls
-     * start()), which is BEFORE the only code that writes `lastFatalError` --
-     * start()'s catch. The result was billed as "a loud startup exit" but was
-     * nothing of the kind: with systemd `Type=simple` + `Restart=always` and no
-     * cfn-signal, an invalid deployment name produced an invisible ~5s
-     * crash-loop that `cdk deploy` reported as success while the admin panel
-     * showed the worker as 'absent' with no fatal error to explain it. Resolving
-     * inside start()'s try block instead means the same throw is recorded to
-     * worker-status.json and surfaces in the admin panel.
-     *
-     * Lazy rather than start()-only so the value is still available to unit tests
-     * that drive pushSettingsBranches() directly without calling start() -- the
-     * same reason ensureStatusReport() above is shaped this way. Idempotent: the
+     * follows, and the only place the resolved value is validated. Without it the
+     * worker can silently own a different settings branch than the Lambda writing
+     * to the same workspace, and pushSettingsBranches then reports the real branch
+     * as foreign and never pushes it.
+     *
+     * DEFERRED out of the constructor deliberately, which is the whole point of
+     * the method existing: canopycms-cdk/worker/index.ts constructs the worker
+     * before calling start(), so a throw during `new CmsWorker(...)` lands BEFORE
+     * the only code that writes `lastFatalError` -- start()'s catch. Under
+     * systemd `Type=simple` + `Restart=always` with no cfn-signal, that is an
+     * invisible ~5s crash-loop that `cdk deploy` reports as success while the
+     * admin panel shows the worker 'absent' with no fatal error to explain it.
+     *
+     * Lazy rather than start()-only so unit tests driving pushSettingsBranches()
+     * still see the value, exactly as ensureStatusReport() above. Idempotent: the
      * resolver is pure, so a later call returns the identical string.
      */
     private ensureSettingsBranch;
@@ -146,15 +130,11 @@ export declare class CmsWorker {
      * Build the {@link WorkerContext} handed to the extracted clusters
      * (task-runner.ts, git-sync.ts, rebase.ts, history-rewrite.ts).
      *
-     * Built FRESH on every call rather than once in the constructor, and the
-     * instance-backed members are functions rather than copied values. Both
-     * choices exist for the same reason: the test suite drives this class by
-     * replacing `octokit` and `buildGitHubUrl` ON THE INSTANCE, by setting
-     * `running` directly, and by subclassing to override the two rebase test
-     * hooks. A context that captured any of those at construction time would hand
-     * the extracted code the pre-test value -- which for `buildGitHubUrl` means a
-     * test's push going to github.com for real instead of its local fixture repo.
-     * See WorkerContext's doc comment for the full list.
+     * Built FRESH on every call, with instance-backed members as functions rather
+     * than copied values. See WorkerContext's INVARIANT: a context that captured
+     * any of them at construction time would hand the extracted code the pre-test
+     * value, which for `buildGitHubUrl` means a test's push going to github.com
+     * for real instead of its local fixture repo.
      */
     private ctx;
     start(): Promise<void>;
@@ -163,50 +143,45 @@ export declare class CmsWorker {
      * Acquire the cross-host worker lock (DEP-C2).
      *
      * The task queue is single-consumer (see task-queue/task-queue.ts): two
-     * concurrent workers would double-process tasks (duplicate pushes, duplicate
-     * PRs). The workspace lives on a shared filesystem (EFS), so mutual
-     * exclusion must be sound ACROSS HOSTS — a PID liveness probe
-     * (`process.kill(pid, 0)`) only means something on the holder's own machine
-     * and must never participate in staleness decisions.
+     * concurrent workers would double-process tasks, duplicating pushes and PRs.
+     * The workspace lives on EFS, so mutual exclusion must be sound ACROSS HOSTS
+     * — a PID liveness probe (`process.kill(pid, 0)`) means something only on the
+     * holder's own machine and must NEVER participate in staleness decisions.
      *
      * proper-lockfile provides a heartbeat lease with no PID involved: the lock
      * is a directory created atomically (mkdir — atomic on NFS/EFS), the holder
-     * refreshes its mtime every lockStaleMs/2, and the lock is considered
-     * abandoned — and taken over — only when that heartbeat is older than
-     * lockStaleMs. Liveness is judged purely by heartbeat freshness.
+     * refreshes its mtime every lockStaleMs/2, and the lock is abandoned, and
+     * taken over, only once that heartbeat is older than lockStaleMs.
      *
      * No acquire retries: a second worker exits immediately, matching daemon
-     * semantics (the supervisor restarts it later). After a crash, the dead
-     * holder's heartbeat expires within lockStaleMs and the next start succeeds.
+     * semantics. After a crash the dead holder's heartbeat expires within
+     * lockStaleMs and the next start succeeds.
      *
-     * Staleness is judged by comparing the lock's mtime against the local
-     * clock, so correct cross-host takeover assumes reasonable clock agreement
-     * between hosts (e.g. NTP); with the default TTL, ordinary clock skew is
-     * negligible, but a host with a badly wrong clock could misjudge liveness.
+     * Staleness compares the lock's mtime against the LOCAL clock, so correct
+     * cross-host takeover assumes reasonable clock agreement (NTP). Ordinary skew
+     * is negligible at the default TTL; a badly wrong clock misjudges liveness.
      */
     private acquireLock;
     private releaseLock;
     /**
-     * Schedule a function to run repeatedly with setTimeout chaining.
-     * The next invocation starts `interval` ms after the previous one completes,
-     * preventing overlapping executions.
+     * Run `fn` repeatedly, the next invocation starting `interval` ms after the
+     * previous one COMPLETES. setTimeout chaining rather than setInterval, so
+     * executions cannot overlap when one runs longer than the interval.
      */
     private scheduleLoop;
     /**
      * Whether the bare repo at `gitDir` has a local `refs/heads/<baseBranch>`.
      *
-     * Uses an explicit `--git-dir` invocation rather than `simpleGit({ baseDir
-     * })` so this also works in sandboxed/CI git environments that set
-     * `safe.bareRepository=explicit` (which refuses cwd-based discovery of
-     * bare repos but expressly allows `--git-dir` — see
-     * GitManager.bareRemoteHasBranch for the same pattern).
+     * Explicit `--git-dir` rather than `simpleGit({ baseDir })`, so this also
+     * works where `safe.bareRepository=explicit` refuses cwd-based discovery of
+     * bare repos but expressly allows `--git-dir` (same pattern as
+     * GitManager.bareRemoteHasBranch).
      *
-     * Deliberately omits `--quiet`: simple-git only treats a task as failed
-     * when the process both exits non-zero AND writes to stderr
-     * (isTaskError), so a quiet, silent-on-failure `--verify` would leave a
-     * missing branch indistinguishable from success. Without `--quiet`,
-     * `rev-parse --verify` writes its "fatal: ..." to stderr on failure, which
-     * is what makes simple-git reject the promise here.
+     * Deliberately omits `--quiet`: simple-git treats a task as failed only when
+     * the process exits non-zero AND writes to stderr, so a silent-on-failure
+     * `--verify` would leave a missing branch indistinguishable from success.
+     * Without `--quiet`, `rev-parse --verify` writes "fatal: ..." to stderr,
+     * which is what makes simple-git reject the promise here.
      */
     private verifyBaseBranchExists;
     /**
@@ -215,36 +190,31 @@ export declare class CmsWorker {
      *
      * `git clone https://x-access-token:<token>@github.com/...` records that URL
      * verbatim as `remote.origin.url`, and for `remote.git` that config lives on
-     * shared EFS. The security model in docs/deploying-to-aws.md -- "If Lambda is
-     * compromised, an attacker can read/write content on EFS but cannot push to
-     * GitHub", "Secrets stay on the worker" -- is false while that string is
-     * there: a compromised Lambda could read the token off EFS and, despite
-     * having no egress of its own, exfiltrate it by writing it into branch
-     * content the worker then pushes to GitHub.
+     * shared EFS. The security model in docs/deploying-to-aws.md -- a compromised
+     * Lambda can read/write EFS content but cannot push to GitHub, secrets stay
+     * on the worker -- is false while that string is there: the Lambda could read
+     * the token off EFS and, with no egress of its own, exfiltrate it by writing
+     * it into branch content the worker then pushes to GitHub.
      *
      * Nothing needs the remote: every push passes the URL explicitly as an
-     * argument (see the `git.push(this.buildGitHubUrl(), ...)` call sites), and
-     * `verifyBaseBranchExists` reads local refs.
+     * argument, and `verifyBaseBranchExists` reads local refs.
      *
      * VERIFIES rather than assuming: it re-reads the config and throws if the URL
-     * survives, because the previous code's `.catch(() => {})` meant a failed
-     * scrub was indistinguishable from a successful one.
+     * survives, so a failed scrub is never indistinguishable from a clean one.
      */
     private scrubPersistedRemote;
     /**
-     * Ensure remote.git bare repo exists.
-     * On first run, clone from GitHub as a bare repo.
+     * Ensure the remote.git bare repo exists, cloning it from GitHub on first
+     * run.
      *
      * Empty-remote guard: simple-git's bare clone of an EMPTY GitHub repo (no
-     * commits, or a base branch that's never been pushed) exits 0 and produces
-     * a refs-less bare repo — HEAD points at an unborn branch. `fs.stat`
-     * cannot distinguish this from a healthy clone, so left unchecked it
-     * silently poisons remote.git: every later branch operation (Lambda-side
-     * clone provisioning, worker pushes) breaks, and the fs.stat short-circuit
-     * means it never heals on its own. We verify the base branch exists right
-     * after cloning and again on the already-exists fast path, since a
-     * previous run could have left a poisoned remote.git behind before this
-     * guard existed.
+     * commits, or a base branch never pushed) exits 0 and produces a refs-less
+     * bare repo whose HEAD points at an unborn branch. `fs.stat` cannot tell that
+     * from a healthy clone, so left unchecked it silently poisons remote.git —
+     * every later branch operation breaks and the fs.stat short-circuit means it
+     * never heals. The base branch is therefore verified right after cloning AND
+     * on the already-exists fast path, since a previous run can have left a
+     * poisoned remote.git behind.
      */
     private ensureRemoteGit;
     processTaskQueue(): Promise<void>;
@@ -256,47 +226,37 @@ export declare class CmsWorker {
      * Octokit client from it.
      *
      * DEFERRED out of the constructor deliberately, exactly as
-     * `ensureSettingsBranch()` is, and for the same reason that method records:
+     * `ensureSettingsBranch()` is and for the reason that method records:
      * `resolveWorkerGitHubAuth` throws for a half-configured credential (both
-     * set, neither set, an unusable mint timeout or refresh interval), and a throw during
-     * `new CmsWorker(...)` lands BEFORE the only code that writes
-     * `lastFatalError` — start()'s catch. The AWS entrypoint constructs the
-     * worker and calls start() separately, and its `main().catch()` only logs
-     * and exits, so a constructor throw is an invisible ~5s systemd crash-loop
-     * that `cdk deploy` reports as success while the admin panel shows the
-     * worker 'absent' with no fatal error to explain it. That is a shipped
-     * regression this codebase has already paid for once (#198).
+     * set, neither set, an unusable mint timeout or refresh interval), and a
+     * throw during `new CmsWorker(...)` lands BEFORE the only code that writes
+     * `lastFatalError` — start()'s catch.
      *
      * Idempotent, and it does NOT replace an `octokit` a test has already
      * assigned onto the instance — see the field's comment.
      */
     private ensureGitHubAuth;
     /**
-     * The Octokit client, built on first use.
-     *
-     * Every read goes through here rather than touching the field, because the
-     * field is no longer populated by the constructor: a method reached without
-     * start() would otherwise see `undefined`. `rebaseActiveBranches()` is
-     * exactly that case — apps/test-app's e2e route calls it directly, and its
-     * `pollMergeState` dispatch reads `ctx.octokit()`.
+     * The Octokit client, built on first use. Every read goes through here rather
+     * than touching the field, which the constructor does not populate: a method
+     * reached without start() would otherwise see `undefined`.
+     * `rebaseActiveBranches()` is exactly that case — apps/test-app's e2e route
+     * calls it directly, and its `pollMergeState` dispatch reads `ctx.octokit()`.
      */
     private octokitClient;
     /**
-     * The single seam through which every git-over-HTTPS credential reaches a
-     * git command. The only other consumer of the credential is Octokit, built
-     * from the same resolution by `ensureGitHubAuth()` above.
+     * The single seam through which every git-over-HTTPS credential reaches a git
+     * command. The only other consumer is Octokit, built from the same resolution
+     * by `ensureGitHubAuth()` above.
      *
-     * Async because the credential need not be a value the worker already
-     * holds: under GitHub App auth `resolveGitToken` mints an installation
-     * token, which lasts about an hour. Nothing may cache what this returns —
-     * a URL built from an installation token goes stale with it. Resolving per
-     * use is cheap: `@octokit/auth-app` answers from its own cache until the
-     * token is near expiry, so the usual cost is a resolved microtask, and the
-     * token path is a bare `async` return.
+     * Async because under GitHub App auth `resolveGitToken` mints an installation
+     * token lasting about an hour. NOTHING may cache what this returns — a URL
+     * built from an installation token goes stale with it — and resolving per use
+     * is cheap, since `@octokit/auth-app` answers from its own cache until the
+     * token is near expiry.
      *
      * A mint failure propagates AS THROWN, carrying the `.status` that
-     * `isPermanentTaskFailure` (task-runner.ts:92) classifies on — see
-     * github-auth.ts.
+     * `isPermanentTaskFailure` classifies on — see github-auth.ts.
      *
      * Do NOT add a parallel token accessor alongside it. Every instance-backed
      * WorkerContext member stays a function precisely so tests can replace it
@@ -307,53 +267,47 @@ export declare class CmsWorker {
     /**
      * Prove the GitHub App credential works before anything depends on it.
      *
-     * Without this the first failure comes out of `ensureRemoteGit`'s bare
-     * clone below, whose catch reads "the GitHub repository may be empty, or
-     * the base branch may not exist" — which would send an operator holding a
-     * bad private key to go looking for a repository problem that does not
-     * exist. Called from start()'s try, so the failure is also recorded as
-     * `lastFatalError` in worker-status.json and reaches the admin panel.
-     *
-     * No-op on the token path: a PAT is a literal, so there is nothing to
-     * check that the first real request would not check anyway.
-     *
-     * FATAL UNLESS THE FAILURE POSITIVELY LOOKS TRANSIENT. Both halves of that
-     * are load-bearing.
-     *
-     * Not always fatal, because the two credential paths must degrade alike: on
-     * the token path a GitHub 502 during boot is absorbed (a warm `remote.git`
-     * short-circuits `ensureRemoteGit`, and `Promise.allSettled` swallows the
-     * initial `syncGit`), so the worker starts and its loops retry. Rethrowing
-     * every error class would make the App path exit instead, and systemd
-     * (Restart=always) would crash-loop it until GitHub recovered — each
-     * iteration telling the operator to go and check their private key.
+     * Without this the first failure comes out of `ensureRemoteGit`'s bare clone
+     * below, whose catch blames the repository ("may be empty, or the base branch
+     * may not exist") and sends an operator holding a bad private key looking for
+     * a problem that does not exist. Called from start()'s try, so the failure is
+     * also recorded as `lastFatalError` and reaches the admin panel. No-op on the
+     * token path: a PAT is a literal, so the first real request checks everything
+     * this could.
+     *
+     * FATAL UNLESS THE FAILURE POSITIVELY LOOKS TRANSIENT. Both halves are
+     * load-bearing. Not always fatal, because the two credential paths must
+     * degrade alike: on the token path a GitHub 502 during boot is absorbed (a
+     * warm `remote.git` short-circuits `ensureRemoteGit`, `Promise.allSettled`
+     * swallows the initial `syncGit`) so the worker starts and its loops retry,
+     * while rethrowing every error class would make the App path exit and systemd
+     * crash-loop it until GitHub recovered — each iteration telling the operator
+     * to check their private key.
      *
      * But fail CLOSED, via `isTransientAuthFailure` rather than the inverse of
-     * `isPermanentTaskFailure`. That classifier defaults an error with no HTTP
-     * status to transient, which is right on the task path (bounded by
-     * `maxRetries`) and wrong here (bounded by nothing): a key that never
-     * reaches GitHub at all — the wrong key type, or one too mangled to sign
-     * with — fails locally and status-lessly, so "default to transient" would
-     * boot a worker with a dead credential, record no `lastFatalError`, and show
-     * healthy in the admin panel while every task and every sync failed. See
-     * isTransientAuthFailure in github-auth.ts.
+     * `isPermanentTaskFailure`: that classifier defaults a status-less error to
+     * transient, which is right on the task path (bounded by `maxRetries`) and
+     * wrong here (bounded by nothing). A key that never reaches GitHub at all —
+     * the wrong type, or too mangled to sign with — fails locally and
+     * status-lessly, so defaulting to transient would boot a worker with a dead
+     * credential, record no `lastFatalError`, and show healthy in the admin panel
+     * while every task and every sync failed.
      */
     private preflightGitHubAppAuth;
     /**
-     * The workspace directory for a branch named by its GIT REF name -- the
-     * form task payloads carry (`context.branch.name`), not the directory form.
+     * The workspace directory for a branch named by its GIT REF name -- the form
+     * task payloads carry (`context.branch.name`), not the directory form.
      *
      * These differ for any name outside `[A-Za-z0-9._-]`, `/` being the obvious
      * one: workspaces are provisioned under `sanitizeBranchName(...)` (see
      * paths/branch.ts's `resolveBranchPaths`), so `feature/x` lives in
-     * `feature-x`. Joining the raw name instead silently addresses a directory
-     * that does not exist -- which for the metadata writers below meant the
-     * update was quietly dropped, and for the leased push meant the
-     * history-rewrite marker read as absent and the push went out unleased,
-     * wedging exactly the branch this workstream exists to unwedge.
+     * `feature-x`. Joining the RAW name instead silently addresses a directory
+     * that does not exist -- which drops the metadata writers' updates, and makes
+     * the leased push read the history-rewrite marker as absent and go out
+     * unleased, wedging the branch.
      *
-     * `name` inside the metadata itself stays the raw ref name; only the path
-     * is sanitized.
+     * `name` inside the metadata itself stays the raw ref name; only the path is
+     * sanitized.
      */
     private branchWorkspacePath;
     /**
@@ -362,19 +316,18 @@ export declare class CmsWorker {
      * `checkout --theirs` resolution loop overwrites them. No-op in production.
      *
      * A test subclass overrides this to land a real `ContentStore` write at
-     * exactly the instant the rebase is mid-flight -- the window the old TOCTOU
-     * comment above the dirty check wrongly called safe -- without any sleeps or
-     * shell rendezvous. See the "Deterministic interleavings" testing pattern in
+     * exactly the instant the rebase is mid-flight, with no sleeps or shell
+     * rendezvous. See the "Deterministic interleavings" pattern in
      * docs/concurrency.md, and `ContentStore.afterPrePassForTesting()` for the
      * same idiom on the write side.
      */
     protected afterConflictDetectedForTesting(): Promise<void>;
     /**
-     * Test seam, sibling of {@link afterConflictDetectedForTesting}: runs at the
+     * Test seam, sibling of {@link afterConflictDetectedForTesting}: runs the
      * instant a rebase round has succeeded, before the completion path (cache
-     * invalidation, conflict metadata, [SYNC-H1] marker) executes. Exists so a
-     * test can lose the content-write lock at exactly the point where bailing out
-     * would strand a rewritten history.
+     * invalidation, conflict metadata, [SYNC-H1] marker) executes, so a test can
+     * lose the content-write lock at exactly the point where bailing out would
+     * strand a rewritten history.
      */
     protected afterRebaseCompletedForTesting(): Promise<void>;
     private rebaseActiveBranches;
@@ -384,10 +337,10 @@ export declare class CmsWorker {
      *
      * One of `refreshGitHubCredential`'s two call sites, and the one that works
      * when nobody is publishing: it fetches from GitHub every `gitSyncInterval`
-     * (default 5 minutes) whether or not anyone is editing, so a credential that
-     * has stopped working surfaces here even with no push queued for days.
+     * whether or not anyone is editing, so a credential that has stopped working
+     * surfaces here even with no push queued for days.
      *
-     * The sync failure is what propagates to `scheduleLoop`'s catch.
+     * The SYNC failure is what propagates to `scheduleLoop`'s catch;
      * `refreshGitHubCredential` never throws, so nothing it does can replace it.
      */
     private syncGitWithCredentialRefresh;
@@ -397,42 +350,29 @@ export declare class CmsWorker {
      * **Two call sites, each covering what the other cannot.** The git-sync loop
      * (`syncGitWithCredentialRefresh`) notices a dead credential when nobody is
      * publishing. `processTaskQueue`'s per-task catch is what saves a publish: a
-     * push task spends its retry budget on a 5s/10s/20s backoff
-     * (task-queue/task-queue.ts), well inside one 5-minute sync interval, so with
-     * the sync loop as the only trigger a publish that met a rotated token failed
-     * permanently while the working one was already in the secret store.
-     *
-     * Every consumer reaches the credential through `ensureGitHubAuth()`, which
-     * reads it per use — the sync fetch, `pushBranchToGitHub`,
-     * `pushSettingsBranches`, `ensureRemoteGit`'s clone, and every Octokit call —
-     * so a refresh from either site repairs all of them for their NEXT use, with
-     * nothing to invalidate. It cannot rescue an attempt that has already failed,
-     * so a task `isPermanentTaskFailure` fails fast is not saved; the task after
-     * it is.
-     *
-     * NOT gated on the error looking auth-shaped, at either site. There is nothing
-     * to classify on: a `git fetch` or `git push` rejected for a dead token throws
-     * a plain simple-git error — exit 128, no HTTP `.status` — which
-     * `isPermanentTaskFailure` reads as transient, so a gate keyed on it would
-     * never fire. Two floors bound the cost instead: core's own
-     * `refreshGitHubTokenMinIntervalMs` (default 60s, enforced by
-     * `refreshCredential` in github-auth.ts), and whatever floor the provider
-     * keeps — the AWS one reads at most once per five minutes and returns
-     * `undefined` for an unchanged value (canopycms-cdk/worker/credential-refresh.ts).
-     * On the GitHub App path the refresh is a no-op. Both call sites share both
-     * floors, so a read issued by one throttles the other.
-     *
-     * **Never throws.** Both callers are already reporting a failure, and that
-     * failure is the one that must reach the log.
-     *
-     * **Bounded by `taskTimeoutMs`**, because the task loop awaits it, and a read
-     * that never settled would stop every publish queued behind it. An adopter's
-     * provider may have no bound at all, and the AWS one, bounded as it is
-     * (canopycms-cdk/worker/secrets.ts), can still take up to 87s for one
-     * `getSecret` — longer than the 60s default here. A read that loses the race
-     * is not cancelled, and
-     * may still land later; `refreshCredential` discards a result older than one
-     * it has already applied, so a late landing cannot put a stale token back.
+     * push task spends its retry budget on a 5s/10s/20s backoff, well inside one
+     * 5-minute sync interval, so with the sync loop as the only trigger a publish
+     * meeting a rotated token fails permanently while the working one is already
+     * in the secret store. Every consumer reaches the credential through
+     * `ensureGitHubAuth()`, which reads it per use, so a refresh from either site
+     * repairs all of them for their NEXT use — but not an attempt already failed.
+     *
+     * NOT gated on the error looking auth-shaped, at either site: a `git
+     * fetch`/`push` rejected for a dead token throws a plain simple-git error
+     * (exit 128, no HTTP `.status`) that `isPermanentTaskFailure` reads as
+     * transient, so a gate keyed on it would never fire. Two floors bound the
+     * cost instead — core's `refreshGitHubTokenMinIntervalMs` (default 60s,
+     * enforced by `refreshCredential` in github-auth.ts) and whatever floor the
+     * provider keeps (the AWS one reads at most once per five minutes) — and both
+     * call sites share both, so a read issued by one throttles the other. On the
+     * GitHub App path the refresh is a no-op.
+     *
+     * **Never throws**: both callers are already reporting the failure that must
+     * reach the log. **Bounded by `taskTimeoutMs`**, because the task loop awaits
+     * it and a read that never settled would stop every publish queued behind it
+     * (an adopter's provider may have no bound at all; the AWS one can take 87s
+     * for one `getSecret`). A losing read is not cancelled and may land later, but
+     * `refreshCredential` discards a result older than one already applied.
      */
     private refreshGitHubCredential;
     private pushSettingsBranches;