canopycms 0.0.68-int.111 → 0.0.68-int.113

package/dist/worker/cms-worker.js

@@ -4,18 +4,17 @@ import os from 'node:os';
 import path from 'node:path';
 import lockfile from 'proper-lockfile';
 import { recoverOrphanedTasks, cmsTaskQueueLogger } from '../task-queue/cms-task-queue.js';
-import { createCanopyOctokit } from '../github-service.js';
-import { isTransientAuthFailure, resolveWorkerGitHubAuth, } from './github-auth.js';
-import { ensureRemoteGitConfig } from '../git-manager.js';
+import { resolveWorkerGitHubAuth } from './github-auth.js';
+import { createLocalGitHubGateway, } from './github-gateway.js';
+import { GITHUB_TRACKING_REF_PREFIX, ensureRemoteGitConfig, failOnSignalExit } from '../git-manager.js';
 import { readHeadBranch } from '../utils/git.js';
-import { sanitizeBranchName, RESERVED_SETTINGS_BRANCH_PREFIX } from '../paths/branch-name.js';
+import { isSettingsBranchName, sanitizeBranchName, RESERVED_SETTINGS_BRANCH_PREFIX, } from '../paths/branch-name.js';
 import { resolveDeploymentName } from '../operating-mode/deployment-name.js';
 import { getErrorMessage, isNodeError, redactCredentials } from '../utils/error.js';
 import { readCarriedOverStatus, readWorkerStatusStartedAt, writeWorkerStatus, } from '../task-queue/worker-status.js';
 import { CANOPYCMS_VERSION } from '../version.js';
 import { workerLog, workerLogWarn, workerLogError } from './log.js';
 import { DEFAULT_SCHEMA_HOLD_MAX_MS, readCarriedBaseHold } from './schema-gate.js';
-import { GitHubMirror } from './github-mirror.js';
 import { SharedRepoRefusalError, UntrustedRepoConfigError, assertSharedRepoConfig, sharedRepoGit, } from './shared-repo-git.js';
 import { executeTask, orphanRecoveryMaxAgeMs, processTaskQueue, pushBranchToGitHub, updateBranchMetadata, } from './task-runner.js';
 import { pollMergeState, runRebaseCycle } from './rebase.js';
@@ -33,28 +32,49 @@ export { workerLog, workerLogWarn, workerLogError, installWorkerLogger } from '.
 // see github-auth.ts) and needs the shape to inject and the key normalizer to
 // apply.
 export { normalizeGitHubAppPrivateKey, DEFAULT_GIT_TOKEN_MINT_TIMEOUT_MS, DEFAULT_GITHUB_TOKEN_REFRESH_MIN_INTERVAL_MS, } from './github-auth.js';
-/** `target` with symlinks resolved as far as it exists, so a link cannot hide where it lands. */
-async function realpathOfNearest(target) {
-    const missing = [];
-    let current = path.resolve(target);
-    for (;;) {
-        try {
-            return path.join(await fs.realpath(current), ...missing.reverse());
-        }
-        catch {
-            const parent = path.dirname(current);
-            if (parent === current)
-                return path.resolve(target);
-            missing.push(path.basename(current));
-            current = parent;
-        }
-    }
-}
 /** Per workspace, so two workers on one host (tests, dev) never share a mirror. */
 function defaultStateDirectory(workspacePath) {
     const key = createHash('sha256').update(path.resolve(workspacePath)).digest('hex').slice(0, 16);
     return path.join(os.tmpdir(), `canopycms-worker-${key}`);
 }
+/** How many refs a refusal to replace remote.git names before summarising the rest. */
+const MAX_REFS_LISTED = 20;
+/** A refusal to replace a poisoned remote.git because it holds work GitHub does not have. */
+class RemoteGitKeptError extends Error {
+}
+/**
+ * Every ref in the bare repo at `gitDir` outside the GitHub tracking namespace, which only ever
+ * holds GitHub's own branches, mapped to the object it names. A ref missing from this list is one
+ * a replacement would discard unchecked, so it throws when git reports anything on stderr
+ * (`for-each-ref` skips a ref it cannot read with only a warning and exit 0) and when git is killed
+ * by a signal, which simple-git otherwise resolves as empty output. A dangling symbolic ref is
+ * skipped without a warning, and names nothing to lose.
+ */
+async function listRemoteGitRefs(gitDir) {
+    let stderr = '';
+    const output = await sharedRepoGit(gitDir, 'bare', { errors: failOnSignalExit })
+        .outputHandler((_command, _stdout, err) => {
+        err.on('data', (chunk) => {
+            stderr += String(chunk);
+        });
+    })
+        .raw(['for-each-ref', '--format=%(objectname) %(refname)']);
+    if (stderr.trim() !== '')
+        throw new Error(stderr.trim());
+    const refs = new Map();
+    for (const line of output.split('\n')) {
+        const space = line.indexOf(' ');
+        if (space === -1)
+            continue;
+        const ref = line.slice(space + 1);
+        if (!ref.startsWith(GITHUB_TRACKING_REF_PREFIX))
+            refs.set(ref, line.slice(0, space));
+    }
+    return refs;
+}
+function sameRefs(a, b) {
+    return a.size === b.size && [...a].every(([ref, id]) => b.get(ref) === id);
+}
 const DEFAULT_TASK_TIMEOUT = 60_000;
 const DEFAULT_MAX_RETRIES = 3;
 const DEFAULT_LOCK_STALE_MS = 60_000;
@@ -207,7 +227,6 @@ export class CmsWorker {
         this.drainDeadlineMs = config.drainDeadlineMs ?? DEFAULT_DRAIN_DEADLINE_MS;
         this.contentRoot = config.contentRoot ?? 'content';
         this.schemaHoldMaxMs = config.schemaHoldMaxMs ?? DEFAULT_SCHEMA_HOLD_MAX_MS;
-        this.githubMirror = new GitHubMirror(this.stateDirectory, this.remoteGitPath, this.taskTimeoutMs);
     }
     /**
      * This worker's self-reported status object, initialized on first use.
@@ -265,13 +284,11 @@ export class CmsWorker {
      * 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.
+     * value, which for the GitHub gateway means a test's push going to
+     * github.com for real instead of its local fixture repo.
      */
     ctx() {
         return {
-            githubOwner: this.config.githubOwner,
-            githubRepo: this.config.githubRepo,
             baseBranch: this.baseBranch,
             sanitizedBaseBranch: this.sanitizedBaseBranch,
             taskDir: this.taskDir,
@@ -283,10 +300,7 @@ export class CmsWorker {
             maxTasksPerCycle: this.maxTasksPerCycle,
             maxRetries: this.maxRetries,
             log: this.log,
-            octokit: () => this.octokitClient(),
-            buildGitHubUrl: () => this.buildGitHubUrl(),
-            githubMirror: () => this.githubMirror,
-            refreshGitHubCredential: () => this.refreshGitHubCredential(),
+            github: () => this.github(),
             branchWorkspacePath: (branchRefName) => this.branchWorkspacePath(branchRefName),
             executeTask: (task, signal) => this.executeTask(task, signal),
             pushBranchToGitHub: (branch, signal) => this.pushBranchToGitHub(branch, signal),
@@ -366,7 +380,7 @@ export class CmsWorker {
             // Same shape, same reason: a half-configured credential throws HERE,
             // inside the try, rather than out of `new CmsWorker(...)` where nothing
             // could record it.
-            this.ensureGitHubAuth();
+            const github = this.github();
             // Same again. NaN would never expire a schema hold, which is the one
             // thing the bound exists to prevent.
             if (!Number.isFinite(this.schemaHoldMaxMs) || this.schemaHoldMaxMs < 0) {
@@ -374,10 +388,8 @@ export class CmsWorker {
             }
             // BEFORE ensureRemoteGit(): its clone is the first thing to use the
             // credential, and its catch blames the repository rather than the
-            // credential. See preflightGitHubAppAuth().
-            await this.preflightGitHubAppAuth();
-            await this.ensureStateDirectoryIsPrivate();
-            await this.githubMirror.ensure();
+            // credential. See GitHubGateway.prepare().
+            await github.prepare();
             await this.resolveBaseBranch();
             await this.ensureRemoteGit();
             await this.recordBaseBranchInRemoteHead();
@@ -410,7 +422,7 @@ export class CmsWorker {
             report.lastFatalError = {
                 // [REDACT] Persisted to worker-status.json and served to the browser by
                 // the admin panel -- must never carry the bot token a poisoned or
-                // failed git URL (buildGitHubUrl()) can embed.
+                // failed git URL (the gateway's) can embed.
                 message: redactCredentials(getErrorMessage(err)),
                 at: new Date().toISOString(),
                 phase: 'startup',
@@ -430,11 +442,7 @@ export class CmsWorker {
         const taskInterval = this.config.taskPollInterval ?? 5_000;
         const gitInterval = this.config.gitSyncInterval ?? 5 * 60_000;
         this.scheduleLoop('task queue', () => this.processTaskQueue(), taskInterval);
-        // The wrapper, not syncGit() itself: a failed sync is where a rotated or
-        // revoked GitHub credential is noticed. start()'s own initial syncGit()
-        // above stays unwrapped -- there is no stale credential to refresh one line
-        // after reading it at boot.
-        this.scheduleLoop('git sync', () => this.syncGitWithCredentialRefresh(), gitInterval);
+        this.scheduleLoop('git sync', () => this.syncGit(), gitInterval);
         if (this.config.refreshAuthCache) {
             const cacheInterval = this.config.authCacheRefreshInterval ?? 15 * 60_000;
             this.scheduleLoop('auth cache refresh', () => this.refreshAuthCache(), cacheInterval);
@@ -675,7 +683,9 @@ export class CmsWorker {
     /**
      * An unconfigured base branch is the one remote.git's HEAD names, which is what the Lambda
      * reads too (GitManager.detectBaseBranch); before remote.git exists, it is GitHub's default
-     * branch, which the clone then records as that HEAD. Never assumes 'main'.
+     * branch, which the clone then records as that HEAD. So it is too when remote.git has no branch
+     * outside the settings namespace: no base branch is there for HEAD to name, and ensureRemoteGit
+     * replaces it from GitHub unless something in it is at stake. Never assumes 'main'.
      */
     async resolveBaseBranch() {
         if (this.resolvedBaseBranch)
@@ -698,15 +708,13 @@ export class CmsWorker {
         // Before the first git to read it, and on its own: a refusal is recorded as itself, not as a
         // base branch to configure or a remote.git to delete.
         if (remoteGitExists)
-            await assertSharedRepoConfig(this.remoteGitPath, 'bare');
+            await this.assertRemoteGitConfig();
         let name;
         try {
-            name = remoteGitExists
+            const fromRemoteGit = remoteGitExists && (await this.hasContentBranch(this.remoteGitPath));
+            name = fromRemoteGit
                 ? await readHeadBranch(this.remoteGitPath, sharedRepoGit(this.remoteGitPath, 'bare'))
-                : (await this.octokitClient().repos.get({
-                    owner: this.config.githubOwner,
-                    repo: this.config.githubRepo,
-                })).data.default_branch;
+                : await this.github().defaultBranch();
         }
         catch (err) {
             throw undetermined(err);
@@ -714,6 +722,33 @@ export class CmsWorker {
         this.setBaseBranch(name);
         workerLog(`Base branch: '${name}' (detected; CANOPYCMS_BASE_BRANCH is not set)`);
     }
+    /**
+     * Check remote.git's config at boot. A refusal is never a case for replacement: it reports that
+     * something wrote there, and listing the refs a replacement would lose means running git under
+     * that config. The message says so, so System health does not read it as a routine failure.
+     */
+    async assertRemoteGitConfig() {
+        try {
+            await assertSharedRepoConfig(this.remoteGitPath, 'bare');
+        }
+        catch (err) {
+            if (!(err instanceof SharedRepoRefusalError))
+                throw err;
+            throw new SharedRepoRefusalError(`${err.message.replace(/\.$/, '')}. This needs an operator: the worker never repairs or ` +
+                `replaces a remote.git whose config was tampered with or cannot be read.`);
+        }
+    }
+    /** Whether the bare repo at `gitDir` has a branch that is not a settings branch. */
+    async hasContentBranch(gitDir) {
+        const branches = await sharedRepoGit(gitDir, 'bare', { errors: failOnSignalExit }).raw([
+            'for-each-ref',
+            '--format=%(refname:strip=2)',
+            'refs/heads/',
+        ]);
+        return branches
+            .split('\n')
+            .some((branch) => branch !== '' && !isSettingsBranchName(branch, this.ensureSettingsBranch()));
+    }
     /**
      * Point remote.git's HEAD at the base branch this worker uses, so a Lambda left to detect it
      * (GitManager.detectBaseBranch) reads the same name. Only the worker writes it, at boot under
@@ -843,7 +878,7 @@ export class CmsWorker {
      * pushed) succeeds and leaves a refs-less repo that `fs.stat` cannot tell from a healthy one, so
      * left unchecked it silently poisons remote.git and the stat short-circuit means it never heals.
      * The base branch is therefore verified right after seeding AND on the already-exists fast
-     * path, since a previous run can have left a poisoned remote.git behind.
+     * path, where a poisoned remote.git is replaced (`replacePoisonedRemoteGit`).
      */
     async ensureRemoteGit() {
         let exists;
@@ -857,7 +892,7 @@ export class CmsWorker {
         if (exists) {
             // At boot, so a refusal lands in worker-status.json as a startup failure, and first: the
             // scrub is git reading this config too.
-            await assertSharedRepoConfig(this.remoteGitPath, 'bare');
+            await this.assertRemoteGitConfig();
             // SELF-HEAL, before anything else changes this repo: a remote.git cloned from GitHub by an
             // older worker recorded the token-bearing clone URL in its config.
             await this.scrubPersistedRemote(this.remoteGitPath);
@@ -866,31 +901,135 @@ export class CmsWorker {
             }
             catch (err) {
                 workerLogError(`remote.git base branch verification failed: ${getErrorMessage(err)}`);
-                // Do NOT auto-delete: an existing remote.git can hold unpushed
-                // canopycms-settings-* branches or other state worth preserving, so
-                // deletion is the operator's call.
-                throw new Error(`remote.git at ${this.remoteGitPath} has no branch '${this.baseBranch}' (likely cloned while the GitHub repo was empty). Delete ${this.remoteGitPath} and restart the worker to re-clone.`);
+                await this.replacePoisonedRemoteGit();
+                return;
             }
             await this.applyRemoteGitConfig(this.remoteGitPath);
             return; // Already exists and has the base branch
         }
         workerLog('Initializing remote.git from GitHub...');
+        const stagingPath = await this.seedRemoteGitStaging();
+        await fs.rename(stagingPath, this.remoteGitPath);
+        workerLog('remote.git initialized');
+    }
+    /**
+     * Replace an existing remote.git that has no base branch with a fresh seed from GitHub, but only
+     * when every ref in it names a commit a GitHub branch contains, so replacing it loses no commit;
+     * a branch name GitHub lacks, such as a merged branch deleted there, goes. Otherwise refuse,
+     * naming the refs at stake: unpushed work such as a settings branch.
+     *
+     * The refs are compared in the same mirror session that fetches GitHub and seeds the
+     * replacement, and listed again just before the swap, since the Lambda can push into remote.git
+     * while the seed runs. The swap is two renames, so the name remote.git resolves to the old repo,
+     * the new one, or for an instant nothing, never a half-built or half-deleted one.
+     */
+    async replacePoisonedRemoteGit() {
+        const poisoned = `remote.git at ${this.remoteGitPath} has no branch '${this.baseBranch}' (cloned while the ` +
+            `GitHub repository was empty, or the base branch is set to one it never had)`;
+        const notReplaced = (reason) => new Error(`${poisoned}, and it was not replaced: ${reason}`);
+        let refs;
+        try {
+            refs = await listRemoteGitRefs(this.remoteGitPath);
+        }
+        catch (err) {
+            throw notReplaced(`its refs could not all be read (${redactCredentials(getErrorMessage(err)).trim()}), so ` +
+                `the worker cannot tell whether replacing it would lose work. Deleting ` +
+                `${this.remoteGitPath} and restarting the worker re-clones it and discards every ref in it.`);
+        }
+        // Only a base branch the listing confirms absent: a check that failed for any other reason
+        // is no evidence the repo is poisoned.
+        if (refs.has(`refs/heads/${this.baseBranch}`)) {
+            throw new Error(`remote.git at ${this.remoteGitPath} has branch '${this.baseBranch}', but git could not ` +
+                `verify it, so the worker will not replace remote.git. Restarting the worker checks again.`);
+        }
+        workerLog(`remote.git has no branch '${this.baseBranch}': replacing it if GitHub has every ref in it`);
+        const stagingPath = await this.seedRemoteGitStaging(async (github) => {
+            const onGitHub = await github.onGitHub([...refs.values()]);
+            const unpushed = [];
+            for (const [ref, id] of refs) {
+                if (!onGitHub.has(id))
+                    unpushed.push(ref);
+            }
+            if (unpushed.length === 0)
+                return;
+            const shown = unpushed.slice(0, MAX_REFS_LISTED);
+            const more = unpushed.length - shown.length;
+            throw new RemoteGitKeptError(`${poisoned}, and it holds ${unpushed.length === 1 ? 'a ref' : `${unpushed.length} refs`} ` +
+                `GitHub does not have, so the worker will not replace it: ${shown.join(', ')}` +
+                `${more > 0 ? ` and ${more} more` : ''}. Deleting ${this.remoteGitPath} and restarting ` +
+                `the worker re-clones it and discards ${unpushed.length === 1 ? 'that ref' : 'those refs'}.`);
+        }).catch((err) => {
+            if (err instanceof RemoteGitKeptError)
+                throw err;
+            throw notReplaced(redactCredentials(getErrorMessage(err)));
+        });
+        const discardStaging = () => fs.rm(stagingPath, { recursive: true, force: true });
+        let current;
+        try {
+            current = await listRemoteGitRefs(this.remoteGitPath);
+        }
+        catch (err) {
+            await discardStaging();
+            throw notReplaced(`its refs could not all be read again (${getErrorMessage(err).trim()}). Restarting the ` +
+                `worker checks again.`);
+        }
+        if (!sameRefs(refs, current)) {
+            await discardStaging();
+            throw notReplaced('its refs changed while the worker seeded its replacement. Restarting the worker checks again.');
+        }
+        const replaced = `${this.remoteGitPath}.replaced-${Date.now()}`;
+        try {
+            await fs.rename(this.remoteGitPath, replaced);
+        }
+        catch (err) {
+            await discardStaging();
+            throw err;
+        }
+        try {
+            await fs.rename(stagingPath, this.remoteGitPath);
+        }
+        catch (err) {
+            await fs.rename(replaced, this.remoteGitPath);
+            await discardStaging();
+            throw err;
+        }
+        // A push that resolved remote.git before the rename can still land in the old repo. One that
+        // lands before this listing keeps it; a later one is lost from remote.git, though the clone
+        // that pushed still has its commit.
+        const after = await listRemoteGitRefs(replaced).catch(() => null);
+        if (after !== null && sameRefs(refs, after)) {
+            // remote.git is already replaced, so a push still writing here costs only this directory.
+            await fs
+                .rm(replaced, { recursive: true, force: true, maxRetries: 3 })
+                .catch((err) => {
+                workerLogWarn(`Could not remove the replaced remote.git at ${replaced}: ${getErrorMessage(err)}`);
+            });
+        }
+        else {
+            workerLogError(`Kept the replaced remote.git at ${replaced}: its refs changed as it was swapped out, so ` +
+                `it may hold work GitHub does not have.`);
+        }
+        workerLog('remote.git replaced');
+    }
+    /**
+     * Seed a new bare repo from GitHub at `<remote.git>.cloning`, verified and configured, and
+     * return its path for the caller to rename into place. `check` runs in the mirror session right
+     * after the GitHub fetch, and its throw stops the seed. Throws with the staging directory gone.
+     */
+    async seedRemoteGitStaging(check) {
         // Seeded under a TEMP name and renamed into place only once verified, so a crash mid-seed
         // leaves only this staging directory, which the next boot deletes, rather than a poisoned
         // `remote.git` that fs.stat cannot distinguish from a healthy one.
         const stagingPath = `${this.remoteGitPath}.cloning`;
         await fs.rm(stagingPath, { recursive: true, force: true });
         try {
-            const githubUrl = await this.buildGitHubUrl();
-            await this.githubMirror.exclusive(async (mirror) => {
-                await mirror.fetchFromGitHub(githubUrl);
-                if ((await mirror.branchTip(this.baseBranch)) === null) {
-                    throw new Error(`GitHub has no branch '${this.baseBranch}'`);
-                }
-                await fs.mkdir(stagingPath);
-                const staging = sharedRepoGit(stagingPath, 'bare');
-                await staging.raw(['init', '--quiet', '--bare']);
-                await mirror.seedBareRepository(stagingPath);
+            await this.github().seedBareRepository(stagingPath, {
+                baseBranch: this.baseBranch,
+                beforeSeed: check,
+                createRepository: async () => {
+                    await fs.mkdir(stagingPath);
+                    await sharedRepoGit(stagingPath, 'bare').raw(['init', '--quiet', '--bare']);
+                },
             });
             // The staging path is predictable, and so writable by the Lambda while seeding runs.
             await assertSharedRepoConfig(stagingPath, 'bare');
@@ -899,11 +1038,15 @@ export class CmsWorker {
             await this.applyRemoteGitConfig(stagingPath);
         }
         catch (err) {
-            workerLogError(`remote.git seeding failed: ${redactCredentials(getErrorMessage(err))}`);
+            if (!(err instanceof RemoteGitKeptError)) {
+                workerLogError(`remote.git seeding failed: ${redactCredentials(getErrorMessage(err))}`);
+            }
             // Deleting before throwing is what makes this recoverable: the next
             // start() sees no remote.git and re-clones, instead of sticking forever
             // behind a poisoned bare repo fs.stat alone cannot detect.
             await fs.rm(stagingPath, { recursive: true, force: true });
+            if (err instanceof RemoteGitKeptError)
+                throw err;
             if (err instanceof SharedRepoRefusalError) {
                 // Not the refusal's own advice: the directory it names is gone.
                 throw new SharedRepoRefusalError(`Refusing to run git in ${stagingPath}: something wrote to it while the worker seeded ` +
@@ -915,22 +1058,7 @@ export class CmsWorker {
             }
             throw new Error(`remote.git clone of ${this.config.githubOwner}/${this.config.githubRepo} failed or has no branch '${this.baseBranch}' - the GitHub repository may be empty, or the base branch may not exist. Push an initial commit to '${this.baseBranch}' and restart the worker (systemd will retry automatically).`);
         }
-        await fs.rename(stagingPath, this.remoteGitPath);
-        workerLog('remote.git initialized');
-    }
-    /**
-     * Refuse a state directory on the shared filesystem: the mirror there would be as writable by
-     * the Lambda as remote.git is.
-     */
-    async ensureStateDirectoryIsPrivate() {
-        const workspace = await realpathOfNearest(this.config.workspacePath);
-        const state = await realpathOfNearest(this.stateDirectory);
-        const relative = path.relative(workspace, state);
-        if (relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative))) {
-            throw new Error(`The worker's state directory (${this.stateDirectory}) is inside its shared workspace ` +
-                `(${this.config.workspacePath}). It holds the repository the GitHub credential is used ` +
-                `in, so it must be somewhere the CMS Lambda cannot write.`);
-        }
+        return stagingPath;
     }
     // --- Task-queue cluster (worker/task-runner.ts) ------------------------
     //
@@ -959,113 +1087,28 @@ export class CmsWorker {
         return pushBranchToGitHub(this.ctx(), branch, signal);
     }
     /**
-     * Resolve which GitHub credential this worker uses, once, and build the
-     * Octokit client from it.
-     *
-     * DEFERRED out of the constructor deliberately, exactly as
-     * `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 start()'s catch, which
-     * records `lastFatalError` for every entrypoint.
-     *
-     * Idempotent, and it does NOT replace an `octokit` a test has already
-     * assigned onto the instance — see the field's comment.
-     */
-    ensureGitHubAuth() {
-        if (!this.githubAuth) {
-            this.githubAuth = resolveWorkerGitHubAuth(this.config);
-        }
-        if (!this.octokit) {
-            this.octokit = createCanopyOctokit(this.githubAuth.octokitAuth);
-        }
-        return this.githubAuth;
-    }
-    /**
-     * 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()`.
-     */
-    octokitClient() {
-        this.ensureGitHubAuth();
-        return this.octokit;
-    }
-    /**
-     * 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 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` 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
-     * through the instance (worker-context.ts's INVARIANT); a second credential
-     * path would be one nothing stubs.
+     * The worker's GitHub gateway, created on first use: inside start()'s try, or wherever a test
+     * entry point first reaches it. Creating it resolves the credential, which throws for a
+     * half-configured one (both set, neither set, an unusable mint timeout or refresh interval) --
+     * never in the constructor, for the reason `ensureSettingsBranch()` gives. Keeps a gateway a
+     * test installed.
      */
-    async buildGitHubUrl() {
-        const token = await this.ensureGitHubAuth().resolveGitToken();
-        return `https://x-access-token:${token}@github.com/${this.config.githubOwner}/${this.config.githubRepo}.git`;
+    github() {
+        this.gateway ??= createLocalGitHubGateway(this.localGitHubGatewayOptions());
+        return this.gateway;
     }
-    /**
-     * 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 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 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.
-     */
-    async preflightGitHubAppAuth() {
-        if (!this.config.githubAppAuth)
-            return;
-        try {
-            await this.ensureGitHubAuth().resolveGitToken();
-        }
-        catch (err) {
-            // [REDACT] Both messages below reach worker-status.json and the browser.
-            const detail = redactCredentials(getErrorMessage(err));
-            if (isTransientAuthFailure(err)) {
-                workerLogWarn(`Could not verify GitHub App authentication at startup: ${detail}. ` +
-                    'Continuing — this looks transient, and the credential is minted again on first use.');
-                return;
-            }
-            // Re-thrown WITH context, unlike buildGitHubUrl() above, which must
-            // preserve the error identity for task classification. Nothing classifies
-            // a startup failure -- start()'s catch records the message and the
-            // process exits -- so the operator-facing wording wins here.
-            throw new Error(`GitHub App authentication failed: ${detail}. ` +
-                'Check the app id, the installation id, and that the private key belongs to that app.');
-        }
-        workerLog('GitHub App authentication verified');
+    /** What the in-process gateway is built from; test-utils/worker-gateway.ts builds from it too. */
+    localGitHubGatewayOptions() {
+        return {
+            githubOwner: this.config.githubOwner,
+            githubRepo: this.config.githubRepo,
+            auth: resolveWorkerGitHubAuth(this.config),
+            githubApp: Boolean(this.config.githubAppAuth),
+            stateDirectory: this.stateDirectory,
+            workspacePath: this.config.workspacePath,
+            remoteGitPath: this.remoteGitPath,
+            timeoutMs: this.taskTimeoutMs,
+        };
     }
     /**
      * The workspace directory for a branch named by its GIT REF name -- the form
@@ -1130,78 +1173,8 @@ export class CmsWorker {
     async syncGit() {
         return syncGit(this.ctx());
     }
-    /**
-     * `syncGit`, plus "the credential may have rotated" on the way out.
-     *
-     * One of `refreshGitHubCredential`'s two call sites, and the one that works
-     * when nobody is publishing: it fetches from GitHub every `gitSyncInterval`
-     * 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;
-     * `refreshGitHubCredential` never throws, so nothing it does can replace it.
-     */
-    async syncGitWithCredentialRefresh() {
-        try {
-            await this.syncGit();
-        }
-        catch (err) {
-            await this.refreshGitHubCredential();
-            throw err;
-        }
-    }
-    /**
-     * Re-read the GitHub credential, because an operation using it just failed.
-     *
-     * **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, 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.
-     */
-    async refreshGitHubCredential() {
-        let timer;
-        const timedOut = new Promise((_, reject) => {
-            timer = setTimeout(() => reject(new Error(`the re-read did not settle within ${this.taskTimeoutMs}ms`)), this.taskTimeoutMs);
-        });
-        try {
-            // `ensureGitHubAuth()` inside the try: it throws for a half-configured
-            // credential, and that has to be logged like any other refresh failure.
-            await Promise.race([this.ensureGitHubAuth().refreshCredential(), timedOut]);
-        }
-        catch (err) {
-            // [REDACT] The message can name the secret and, on a malformed-secret
-            // path, quote what was read. Console only, but the rule is uniform --
-            // see redactCredentials in utils/error.ts.
-            workerLogError('Failed to re-read the GitHub credential after a failure:', redactCredentials(getErrorMessage(err)));
-        }
-        finally {
-            clearTimeout(timer);
-        }
-    }
-    async pushSettingsBranches(git, trackedNames) {
-        return pushSettingsBranches(this.ctx(), git, trackedNames);
+    async pushSettingsBranches(git, trackedTips) {
+        return pushSettingsBranches(this.ctx(), git, trackedTips);
     }
     async refreshBaseBranchWorkspace() {
         return refreshBaseBranchWorkspace(this.ctx());