merge-steward 0.27.0 → 0.28.0

package/dist/cli/commands/attach.js

@@ -52,13 +52,12 @@ export async function handleAttach(parsed, stdout, runCommand) {
     const warnings = [];
     if (needsDiscovery) {
         try {
-            const response = await fetchServiceRepoDiscovery(repoFullName, {
-                ...(explicitBaseBranch
-                    ? { baseBranch: explicitBaseBranch }
-                    : existing?.baseBranch && !shouldDiscoverBaseBranch
-                        ? { baseBranch: existing.baseBranch }
-                        : {}),
-            });
+            const discoveryOptions = explicitBaseBranch
+                ? { baseBranch: explicitBaseBranch }
+                : existing?.baseBranch && !shouldDiscoverBaseBranch
+                    ? { baseBranch: existing.baseBranch }
+                    : {};
+            const response = await fetchServiceRepoDiscovery(repoFullName, discoveryOptions);
             discovered = response.discovery;
         }
         catch (error) {

package/dist/exec.js

@@ -58,6 +58,25 @@ function shouldRetryWithoutRuntimeGitHubAuth(command, githubEnv, failure) {
     }
     return (failure.stderr ?? "").includes(WORKFLOW_PERMISSION_REJECTION);
 }
+// Markers that indicate GitHub rejected our credentials (stale/expired installation token).
+const AUTH_FAILURE_MARKERS = [
+    "Bad credentials",
+    "Invalid username or token",
+    "Authentication failed",
+    "could not read Username",
+    "401 Unauthorized",
+    "HTTP 401",
+];
+function isGitHubAuthFailure(command, githubEnv, failure) {
+    if (command !== "git" && command !== "gh")
+        return false;
+    if (Object.keys(githubEnv).length === 0)
+        return false;
+    if (failure.timedOut)
+        return false;
+    const text = `${failure.stderr ?? ""}\n${failure.stdout ?? ""}\n${failure.message ?? ""}`;
+    return AUTH_FAILURE_MARKERS.some((marker) => text.includes(marker));
+}
 async function runExecFile(command, args, env, options) {
     return await new Promise((resolve, reject) => {
         execFile(command, args, {
@@ -103,7 +122,7 @@ async function runExecFile(command, args, env, options) {
 export async function exec(command, args, options) {
     const baseEnv = {
         ...process.env,
-        ...(options?.env ?? {}),
+        ...options?.env,
     };
     const githubEnv = resolveGitHubCommandEnv(command, baseEnv, {
         ...(options?.githubRepoFullName ? { githubRepoFullName: options.githubRepoFullName } : {}),
@@ -118,6 +137,25 @@ export async function exec(command, args, options) {
     }
     catch (error) {
         const failure = error;
+        // Self-heal on broken auth: record the failure, proactively re-mint the installation
+        // token, and retry once with a fresh credential before giving up.
+        const repoFullName = options?.githubRepoFullName;
+        if (repoFullName
+            && isGitHubAuthFailure(command, githubEnv, failure)
+            && runtimeGitHubAuthProvider?.refreshTokenForRepo) {
+            runtimeGitHubAuthProvider.recordAuthFailure?.(repoFullName, (failure.stderr ?? failure.message ?? "").slice(0, 200));
+            try {
+                await runtimeGitHubAuthProvider.refreshTokenForRepo(repoFullName, "github_401");
+                const refreshedGithubEnv = resolveGitHubCommandEnv(command, baseEnv, {
+                    githubRepoFullName: repoFullName,
+                    runtimeAuthProvider: runtimeGitHubAuthProvider,
+                });
+                return await runExecFile(command, args, { ...baseEnv, ...refreshedGithubEnv }, options);
+            }
+            catch {
+                // Fall through to the original error / workflow-permission fallback below.
+            }
+        }
         if (!shouldRetryWithoutRuntimeGitHubAuth(command, githubEnv, failure)) {
             throw error;
         }

package/dist/github/actions-runner.d.ts

@@ -9,8 +9,7 @@ import type { CIStatus } from "../types.ts";
 export declare class GitHubActionsRunner implements CIRunner {
     private readonly repoFullName;
     private readonly getRequiredChecks;
-    private readonly shouldRequireAllChecksOnEmptyRequiredSet;
-    constructor(repoFullName: string, getRequiredChecks?: () => string[], shouldRequireAllChecksOnEmptyRequiredSet?: () => boolean);
+    constructor(repoFullName: string, getRequiredChecks?: () => string[], _shouldRequireAllChecksOnEmptyRequiredSet?: () => boolean);
     triggerRun(_branch: string, sha: string): Promise<string>;
     getStatus(runId: string): Promise<CIStatus>;
     cancelRun(_runId: string): Promise<void>;

package/dist/github/actions-runner.js

@@ -11,11 +11,9 @@ function normalizeCheckName(name) {
 export class GitHubActionsRunner {
     repoFullName;
     getRequiredChecks;
-    shouldRequireAllChecksOnEmptyRequiredSet;
-    constructor(repoFullName, getRequiredChecks = () => [], shouldRequireAllChecksOnEmptyRequiredSet = () => false) {
+    constructor(repoFullName, getRequiredChecks = () => [], _shouldRequireAllChecksOnEmptyRequiredSet = () => false) {
         this.repoFullName = repoFullName;
         this.getRequiredChecks = getRequiredChecks;
-        this.shouldRequireAllChecksOnEmptyRequiredSet = shouldRequireAllChecksOnEmptyRequiredSet;
     }
     async triggerRun(_branch, sha) {
         // CI is triggered by the push. Return the SHA as the poll key.
@@ -37,7 +35,6 @@ export class GitHubActionsRunner {
             const requiredChecks = this.getRequiredChecks();
             const normalizedRequired = requiredChecks.map(normalizeCheckName);
             const hasRequired = requiredChecks.length > 0;
-            const requireAllChecks = !hasRequired && this.shouldRequireAllChecksOnEmptyRequiredSet();
             const relevant = hasRequired
                 ? checkRuns.filter((c) => normalizedRequired.includes(normalizeCheckName(c.name)))
                 : checkRuns;

package/dist/github-auth.d.ts

@@ -14,12 +14,35 @@ export type GitHubAuthConfig = {
 } | {
     mode: "none";
 };
+export type GitHubAuthRefreshReason = "startup" | "scheduled" | "before_use" | "github_401" | "manual";
+export interface GitHubInstallationAuthStatus {
+    installationId: string;
+    repoFullNames: string[];
+    hasToken: boolean;
+    expiresAt: string | null;
+    lastRefreshAt: string | null;
+    lastRefreshError: string | null;
+    fresh: boolean;
+}
+export interface GitHubAuthRuntimeStatus {
+    ready: boolean;
+    lastRefreshAt: string | null;
+    lastRefreshError: string | null;
+    recentAuthFailureCount: number;
+    lastAuthFailureAt: string | null;
+    installations: GitHubInstallationAuthStatus[];
+}
 export interface RuntimeGitHubAuthProvider {
     currentTokenForRepo(repoFullName?: string): string | undefined;
+    refreshTokenForRepo?(repoFullName: string, reason: GitHubAuthRefreshReason): Promise<void>;
+    recordAuthFailure?(repoFullName: string, message: string): void;
 }
 export interface GitHubAppTokenManager extends RuntimeGitHubAuthProvider {
     start(): Promise<void>;
     stop(): void;
+    refreshTokenForRepo(repoFullName: string, reason: GitHubAuthRefreshReason): Promise<void>;
+    recordAuthFailure(repoFullName: string, message: string): void;
+    authStatus(): GitHubAuthRuntimeStatus;
 }
 export declare function generateJwt(appId: string, privateKey: string): string;
 export declare function resolveAppSlug(credentials: GitHubAppCredentials): Promise<string>;

package/dist/github-auth.js

@@ -2,6 +2,9 @@ import { Buffer } from "node:buffer";
 import { createSign } from "node:crypto";
 import { resolveSecretWithSource } from "./resolve-secret.js";
 const TOKEN_REFRESH_MS = 30 * 60_000;
+const TOKEN_EXPIRY_MARGIN_MS = 5 * 60_000;
+const RECENT_AUTH_FAILURE_WINDOW_MS = 15 * 60_000;
+const MAX_AUTH_FAILURES_TO_KEEP = 50;
 export function generateJwt(appId, privateKey) {
     const now = Math.floor(Date.now() / 1000);
     const header = Buffer.from(JSON.stringify({ alg: "RS256", typ: "JWT" })).toString("base64url");
@@ -36,10 +39,7 @@ export async function resolveAppSlug(credentials) {
     return data.slug;
 }
 async function resolveInstallationIdForRepo(jwt, repoFullName) {
-    const encodedRepo = repoFullName
-        .split("/")
-        .map((segment) => encodeURIComponent(segment))
-        .join("/");
+    const encodedRepo = repoFullName.split("/").map((segment) => encodeURIComponent(segment)).join("/");
     const data = await fetchJson(`https://api.github.com/repos/${encodedRepo}/installation`, { headers: githubHeaders(jwt) });
     return String(data.id);
 }
@@ -52,11 +52,11 @@ async function resolveFirstInstallationId(jwt) {
     return String(first.id);
 }
 async function fetchInstallationToken(jwt, installationId) {
-    const data = await fetchJson(`https://api.github.com/app/installations/${installationId}/access_tokens`, {
-        method: "POST",
-        headers: githubHeaders(jwt),
-    });
-    return data.token;
+    const data = await fetchJson(`https://api.github.com/app/installations/${installationId}/access_tokens`, { method: "POST", headers: githubHeaders(jwt) });
+    return {
+        token: data.token,
+        ...(typeof data.expires_at === "string" ? { expiresAt: data.expires_at } : {}),
+    };
 }
 export async function issueGitHubAppToken(credentials, options) {
     const jwt = generateJwt(credentials.appId, credentials.privateKey);
@@ -64,7 +64,7 @@ export async function issueGitHubAppToken(credentials, options) {
         ?? (options?.repoFullName
             ? await resolveInstallationIdForRepo(jwt, options.repoFullName)
             : await resolveFirstInstallationId(jwt));
-    const token = await fetchInstallationToken(jwt, installationId);
+    const { token } = await fetchInstallationToken(jwt, installationId);
     return { installationId, token };
 }
 export function resolveGitHubAppCredentials(env = process.env) {
@@ -85,10 +85,7 @@ export function resolveGitHubAppCredentials(env = process.env) {
 }
 export function resolveGitHubAuthConfig(env = process.env) {
     const app = resolveGitHubAppCredentials(env);
-    if (app) {
-        return { mode: "app", credentials: app };
-    }
-    return { mode: "none" };
+    return app ? { mode: "app", credentials: app } : { mode: "none" };
 }
 function unique(values) {
     return [...new Set(values)];
@@ -97,38 +94,120 @@ export function createGitHubAppTokenManager(credentials, repoFullNames, logger)
     let timer;
     const repoInstallationIds = new Map();
     const installationTokens = new Map();
+    const installationRefreshErrors = new Map();
+    const authFailures = [];
+    let lastRefreshAt = null;
+    let lastRefreshError = null;
+    function rememberInstallationRepo(installationId, repoFullName) {
+        repoInstallationIds.set(repoFullName, installationId);
+    }
+    function reposForInstallation(installationId) {
+        return repoFullNames.filter((repoFullName) => (repoInstallationIds.get(repoFullName) ?? credentials.installationId) === installationId);
+    }
+    function isTokenFresh(token) {
+        if (!token)
+            return false;
+        if (!token.expiresAt)
+            return true;
+        const expiresAtMs = Date.parse(token.expiresAt);
+        if (!Number.isFinite(expiresAtMs))
+            return false;
+        return expiresAtMs - Date.now() > TOKEN_EXPIRY_MARGIN_MS;
+    }
+    function recordRefreshSuccess(installationId, token) {
+        const refreshedAt = new Date().toISOString();
+        installationTokens.set(installationId, {
+            token: token.token,
+            ...(token.expiresAt ? { expiresAt: token.expiresAt } : {}),
+            lastRefreshAt: refreshedAt,
+            lastRefreshError: null,
+        });
+        installationRefreshErrors.delete(installationId);
+        lastRefreshAt = refreshedAt;
+        lastRefreshError = null;
+    }
+    function recordRefreshFailure(installationId, message) {
+        lastRefreshError = message;
+        if (!installationId)
+            return;
+        installationRefreshErrors.set(installationId, message);
+        const existing = installationTokens.get(installationId);
+        if (existing) {
+            installationTokens.set(installationId, { ...existing, lastRefreshError: message });
+        }
+    }
+    async function resolveInstallationForRepo(jwt, repoFullName) {
+        const existing = repoInstallationIds.get(repoFullName) ?? credentials.installationId;
+        if (existing) {
+            rememberInstallationRepo(existing, repoFullName);
+            return existing;
+        }
+        const installationId = await resolveInstallationIdForRepo(jwt, repoFullName);
+        rememberInstallationRepo(installationId, repoFullName);
+        logger.info({ repoFullName, installationId }, "Resolved GitHub App installation for repo");
+        return installationId;
+    }
+    async function refreshInstallation(installationId, jwt, reason) {
+        const token = await fetchInstallationToken(jwt, installationId);
+        recordRefreshSuccess(installationId, token);
+        // Transparency: every rotation is logged so operators can see gh/git auth staying fresh.
+        logger.info({ installationId, expiresAt: token.expiresAt ?? null, reason }, "Rotated GitHub App installation token (gh + git authenticate as the bot with a fresh token)");
+    }
+    function escalateIfDegraded() {
+        const status = authStatus();
+        if (!status.ready) {
+            logger.error({ lastRefreshError: status.lastRefreshError, installations: status.installations }, "GitHub App auth is degraded — gh/git operations will fail until a fresh token is minted");
+        }
+    }
     async function refresh(options) {
         const throwOnError = options?.throwOnError ?? false;
+        const reason = options?.reason ?? "scheduled";
         try {
             const jwt = generateJwt(credentials.appId, credentials.privateKey);
             const installationIds = new Set();
-            if (credentials.installationId) {
+            if (credentials.installationId)
                 installationIds.add(credentials.installationId);
-            }
             for (const repoFullName of repoFullNames) {
-                let installationId = repoInstallationIds.get(repoFullName) ?? credentials.installationId;
-                if (!installationId) {
-                    installationId = await resolveInstallationIdForRepo(jwt, repoFullName);
-                    repoInstallationIds.set(repoFullName, installationId);
-                    logger.info({ repoFullName, installationId }, "Resolved GitHub App installation for repo");
-                }
+                const installationId = await resolveInstallationForRepo(jwt, repoFullName);
                 installationIds.add(installationId);
             }
             for (const installationId of unique(installationIds)) {
-                const token = await fetchInstallationToken(jwt, installationId);
-                installationTokens.set(installationId, token);
-            }
-            if (installationTokens.size === 0 && !credentials.installationId && repoFullNames.length === 0) {
-                logger.warn("GitHub App auth configured, but no repositories are attached yet");
+                try {
+                    await refreshInstallation(installationId, jwt, reason);
+                }
+                catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    recordRefreshFailure(installationId, message);
+                    if (throwOnError)
+                        throw error;
+                    logger.warn({ installationId, error: message }, "Failed to refresh GitHub App installation token");
+                }
             }
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
-            if (throwOnError) {
+            recordRefreshFailure(undefined, message);
+            if (throwOnError)
                 throw new Error(`Failed to initialize GitHub App auth: ${message}`);
-            }
             logger.warn({ error: message }, "Failed to refresh GitHub App installation token");
         }
+        finally {
+            escalateIfDegraded();
+        }
+    }
+    async function refreshTokenForRepo(repoFullName, reason) {
+        const jwt = generateJwt(credentials.appId, credentials.privateKey);
+        let installationId;
+        try {
+            installationId = await resolveInstallationForRepo(jwt, repoFullName);
+            await refreshInstallation(installationId, jwt, reason);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            recordRefreshFailure(installationId, message);
+            logger.warn({ repoFullName, installationId, reason, error: message }, "Failed to refresh GitHub App installation token");
+            throw error;
+        }
     }
     function schedule() {
         timer = setTimeout(() => {
@@ -136,29 +215,83 @@ export function createGitHubAppTokenManager(credentials, repoFullNames, logger)
         }, TOKEN_REFRESH_MS);
         timer.unref?.();
     }
+    function recentAuthFailures() {
+        const cutoff = Date.now() - RECENT_AUTH_FAILURE_WINDOW_MS;
+        return authFailures.filter((entry) => Date.parse(entry.at) >= cutoff);
+    }
+    function currentTokenForRepo(repoFullName) {
+        if (repoFullName) {
+            const installationId = repoInstallationIds.get(repoFullName) ?? credentials.installationId;
+            if (installationId) {
+                const token = installationTokens.get(installationId);
+                return token && isTokenFresh(token) ? token.token : undefined;
+            }
+        }
+        if (credentials.installationId) {
+            const token = installationTokens.get(credentials.installationId);
+            return token && isTokenFresh(token) ? token.token : undefined;
+        }
+        const first = installationTokens.values().next();
+        if (first.done)
+            return undefined;
+        const token = first.value;
+        return isTokenFresh(token) ? token.token : undefined;
+    }
+    function authStatus() {
+        const installationIds = unique([
+            ...installationTokens.keys(),
+            ...installationRefreshErrors.keys(),
+            ...(credentials.installationId ? [credentials.installationId] : []),
+            ...repoFullNames.flatMap((repoFullName) => {
+                const installationId = repoInstallationIds.get(repoFullName);
+                return installationId ? [installationId] : [];
+            }),
+        ]);
+        const installations = installationIds.map((installationId) => {
+            const token = installationTokens.get(installationId);
+            const refreshError = token?.lastRefreshError ?? installationRefreshErrors.get(installationId) ?? null;
+            return {
+                installationId,
+                repoFullNames: reposForInstallation(installationId),
+                hasToken: Boolean(token),
+                expiresAt: token?.expiresAt ?? null,
+                lastRefreshAt: token?.lastRefreshAt ?? null,
+                lastRefreshError: refreshError,
+                fresh: isTokenFresh(token) && !refreshError,
+            };
+        });
+        const failures = recentAuthFailures();
+        const missingRepoToken = repoFullNames.some((repoFullName) => !currentTokenForRepo(repoFullName));
+        const tokenRefreshFailing = installations.some((installation) => installation.lastRefreshError !== null && !installation.fresh);
+        return {
+            ready: !missingRepoToken && !tokenRefreshFailing,
+            lastRefreshAt,
+            lastRefreshError,
+            recentAuthFailureCount: failures.length,
+            lastAuthFailureAt: failures.at(-1)?.at ?? null,
+            installations,
+        };
+    }
     return {
         async start() {
-            await refresh({ throwOnError: true });
+            await refresh({ throwOnError: true, reason: "startup" });
             schedule();
         },
         stop() {
-            if (timer) {
+            if (timer)
                 clearTimeout(timer);
-                timer = undefined;
-            }
+            timer = undefined;
         },
-        currentTokenForRepo(repoFullName) {
-            if (repoFullName) {
-                const installationId = repoInstallationIds.get(repoFullName) ?? credentials.installationId;
-                if (installationId) {
-                    return installationTokens.get(installationId);
-                }
-            }
-            if (credentials.installationId) {
-                return installationTokens.get(credentials.installationId);
+        currentTokenForRepo,
+        async refreshTokenForRepo(repoFullName, reason) {
+            await refreshTokenForRepo(repoFullName, reason);
+        },
+        recordAuthFailure(repoFullName, message) {
+            authFailures.push({ repoFullName, message, at: new Date().toISOString() });
+            if (authFailures.length > MAX_AUTH_FAILURES_TO_KEEP) {
+                authFailures.splice(0, authFailures.length - MAX_AUTH_FAILURES_TO_KEEP);
             }
-            const first = installationTokens.values().next();
-            return first.done ? undefined : first.value;
         },
+        authStatus,
     };
 }

package/dist/install.js

@@ -3,7 +3,7 @@ import { existsSync } from "node:fs";
 import { mkdir, readFile, writeFile, readdir } from "node:fs/promises";
 import { homedir } from "node:os";
 import { DEFAULT_MERGE_QUEUE_CHECK_NAME, parseConfig } from "./config.js";
-import { getBuiltCliEntryPath, getDefaultConfigPath, getDefaultRepoConfigDir, getDefaultRuntimeEnvPath, getDefaultServiceEnvPath, getDefaultStateDir, getMergeStewardPathLayout, getRepoConfigPath, getSystemdUnitPath, readBundledAsset } from "./runtime-paths.js";
+import { getBuiltCliEntryPath, getDefaultConfigPath, getDefaultRuntimeEnvPath, getDefaultServiceEnvPath, getDefaultStateDir, getMergeStewardPathLayout, getRepoConfigPath, getSystemdUnitPath, readBundledAsset } from "./runtime-paths.js";
 import { parseHomeConfigObject, stringifyJson } from "./steward-home.js";
 function renderTemplate(template, replacements) {
     const home = homedir();
@@ -53,7 +53,7 @@ async function applyPublicBaseUrlToConfig(configPath, publicBaseUrl) {
     const next = {
         ...document,
         server: {
-            ...(document.server ?? {}),
+            ...document.server,
             public_base_url: publicBaseUrl,
         },
     };

package/dist/reconciler.js

@@ -1,5 +1,5 @@
 import { TERMINAL_STATUSES } from "./types.js";
-import { CLEAN_CI, CLEAN_SPEC, emit } from "./reconciler-core.js";
+import { emit } from "./reconciler-core.js";
 import { sanitizeEntry } from "./reconciler-sanitize.js";
 import { prepareEntry } from "./reconciler-prepare.js";
 import { checkValidation } from "./reconciler-validate.js";

package/dist/server.js

@@ -13,7 +13,7 @@ import { parseHomeConfigObject } from "./steward-home.js";
 import { getMergeStewardPathLayout } from "./runtime-paths.js";
 import { createGitHubAppTokenManager, generateJwt, resolveGitHubAuthConfig, resolveAppSlug } from "./github-auth.js";
 import { discoverRepoSettings } from "./github-repo-discovery.js";
-import { resolveSecret, resolveSecretWithSource } from "./resolve-secret.js";
+import { resolveSecretWithSource } from "./resolve-secret.js";
 import { setRuntimeGitHubAuthProvider } from "./exec.js";
 import { readFileSync, existsSync } from "node:fs";
 async function createRepoInstance(config, policy, logger, botIdentity) {
@@ -158,9 +158,8 @@ export async function startMultiServer() {
                 if (githubAuth.mode !== "app") {
                     throw new Error("GitHub App auth is not configured in the merge-steward service.");
                 }
-                return await discoverRepoSettings(githubAuth.credentials, params.repoFullName, {
-                    ...(params.baseBranch ? { baseBranch: params.baseBranch } : {}),
-                });
+                const discoveryOptions = params.baseBranch ? { baseBranch: params.baseBranch } : {};
+                return await discoverRepoSettings(githubAuth.credentials, params.repoFullName, discoveryOptions);
             },
             async checkRepoAccess(params) {
                 if (!githubAppTokenManager) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "merge-steward",
-  "version": "0.27.0",
+  "version": "0.28.0",
   "description": "Serial merge queue for GitHub — rebase, CI-gate, and merge PRs one at a time",
   "type": "module",
   "repository": {