patchrelay 0.10.7 → 0.12.0

package/dist/build-info.json

@@ -1,6 +1,6 @@
 {
   "service": "patchrelay",
-  "version": "0.10.7",
-  "commit": "6593575e7ee8",
-  "builtAt": "2026-03-22T22:06:15.644Z"
+  "version": "0.12.0",
+  "commit": "bcd6dfd26901",
+  "builtAt": "2026-03-24T12:39:09.276Z"
 }

package/dist/config.js

@@ -3,6 +3,7 @@ import { isIP } from "node:net";
 import path from "node:path";
 import { z } from "zod";
 import { getDefaultConfigPath, getDefaultDatabasePath, getDefaultLogPath, getDefaultRuntimeEnvPath, getDefaultServiceEnvPath, getPatchRelayDataDir, } from "./runtime-paths.js";
+import { resolveSecret } from "./resolve-secret.js";
 import { ensureAbsolutePath } from "./utils.js";
 const LINEAR_OAUTH_CALLBACK_PATH = "/oauth/linear/callback";
 const REPO_SETTINGS_DIRNAME = ".patchrelay";
@@ -32,6 +33,7 @@ const projectSchema = z.object({
     github: z.object({
         webhook_secret: z.string().min(1).optional(),
         repo_full_name: z.string().min(1).optional(),
+        base_branch: z.string().min(1).optional(),
     }).optional(),
 });
 const configSchema = z.object({
@@ -284,12 +286,12 @@ export function loadConfig(configPath = process.env.PATCHRELAY_CONFIG ?? getDefa
     const parsedFile = parseJsonFile(requestedPath, "config file");
     const parsed = configSchema.parse(withSectionDefaults(expandEnv(parsedFile, env)));
     const requirements = getLoadProfileRequirements(profile);
-    const webhookSecret = env[parsed.linear.webhook_secret_env];
-    const tokenEncryptionKey = env[parsed.linear.token_encryption_key_env];
-    const oauthClientId = env[parsed.linear.oauth.client_id_env];
-    const oauthClientSecret = env[parsed.linear.oauth.client_secret_env];
+    const webhookSecret = resolveSecret("linear-webhook-secret", parsed.linear.webhook_secret_env, env);
+    const tokenEncryptionKey = resolveSecret("token-encryption-key", parsed.linear.token_encryption_key_env, env);
+    const oauthClientId = resolveSecret("linear-oauth-client-id", parsed.linear.oauth.client_id_env, env);
+    const oauthClientSecret = resolveSecret("linear-oauth-client-secret", parsed.linear.oauth.client_secret_env, env);
     const operatorApiToken = parsed.operator_api.bearer_token_env
-        ? env[parsed.operator_api.bearer_token_env]
+        ? resolveSecret("operator-api-token", parsed.operator_api.bearer_token_env, env)
         : undefined;
     if (requirements.requireWebhookSecret && !webhookSecret) {
         throw new Error(`Missing env var ${parsed.linear.webhook_secret_env}`);
@@ -393,6 +395,7 @@ export function loadConfig(configPath = process.env.PATCHRELAY_CONFIG ?? getDefa
                     github: {
                         ...(project.github.webhook_secret ? { webhookSecret: project.github.webhook_secret } : {}),
                         ...(project.github.repo_full_name ? { repoFullName: project.github.repo_full_name } : {}),
+                        ...(project.github.base_branch ? { baseBranch: project.github.base_branch } : {}),
                     },
                 } : {}),
             };

package/dist/db/migrations.js

@@ -129,4 +129,12 @@ export function runPatchRelayMigrations(connection) {
     connection.exec(schema);
     // Clean up stale dedupe-only webhook records (no payload, never processable)
     connection.prepare("UPDATE webhook_events SET processing_status = 'processed' WHERE processing_status = 'pending' AND payload_json IS NULL").run();
+    // Add pending_merge_prep column for merge queue stewardship
+    addColumnIfMissing(connection, "issues", "pending_merge_prep", "INTEGER NOT NULL DEFAULT 0");
+}
+function addColumnIfMissing(connection, table, column, definition) {
+    const cols = connection.prepare(`PRAGMA table_info(${table})`).all();
+    if (cols.some((c) => c.name === column))
+        return;
+    connection.exec(`ALTER TABLE ${table} ADD COLUMN ${column} ${definition}`);
 }

package/dist/db.js

@@ -149,6 +149,10 @@ export class PatchRelayDatabase {
                 sets.push("queue_repair_attempts = @queueRepairAttempts");
                 values.queueRepairAttempts = params.queueRepairAttempts;
             }
+            if (params.pendingMergePrep !== undefined) {
+                sets.push("pending_merge_prep = @pendingMergePrep");
+                values.pendingMergePrep = params.pendingMergePrep ? 1 : 0;
+            }
             this.connection.prepare(`UPDATE issues SET ${sets.join(", ")} WHERE project_id = @projectId AND linear_issue_id = @linearIssueId`).run(values);
         }
         else {
@@ -206,13 +210,19 @@ export class PatchRelayDatabase {
     }
     listIssuesReadyForExecution() {
         const rows = this.connection
-            .prepare("SELECT project_id, linear_issue_id FROM issues WHERE pending_run_type IS NOT NULL AND active_run_id IS NULL")
+            .prepare("SELECT project_id, linear_issue_id FROM issues WHERE (pending_run_type IS NOT NULL OR pending_merge_prep = 1) AND active_run_id IS NULL")
             .all();
         return rows.map((row) => ({
             projectId: String(row.project_id),
             linearIssueId: String(row.linear_issue_id),
         }));
     }
+    listIssuesByState(projectId, state) {
+        const rows = this.connection
+            .prepare("SELECT * FROM issues WHERE project_id = ? AND factory_state = ? ORDER BY pr_number ASC")
+            .all(projectId, state);
+        return rows.map(mapIssueRow);
+    }
     // ─── Runs ─────────────────────────────────────────────────────────
     createRun(params) {
         const now = isoNow();
@@ -365,6 +375,7 @@ function mapIssueRow(row) {
         ...(row.pr_check_status !== null && row.pr_check_status !== undefined ? { prCheckStatus: String(row.pr_check_status) } : {}),
         ciRepairAttempts: Number(row.ci_repair_attempts ?? 0),
         queueRepairAttempts: Number(row.queue_repair_attempts ?? 0),
+        pendingMergePrep: Boolean(row.pending_merge_prep),
     };
 }
 function mapRunRow(row) {

package/dist/factory-state.js

@@ -19,7 +19,7 @@ export const ALLOWED_TRANSITIONS = {
     changes_requested: ["implementing", "awaiting_input", "escalated"],
     repairing_ci: ["pr_open", "awaiting_review", "escalated", "failed"],
     awaiting_queue: ["done", "repairing_queue", "repairing_ci"],
-    repairing_queue: ["pr_open", "awaiting_review", "escalated", "failed"],
+    repairing_queue: ["pr_open", "awaiting_review", "awaiting_queue", "escalated", "failed"],
     awaiting_input: ["implementing", "delegated", "escalated"],
     escalated: [],
     done: [],
@@ -38,9 +38,13 @@ export function resolveFactoryStateFromGitHub(triggerEvent, current) {
         case "review_commented":
             return undefined; // informational only
         case "check_passed":
+            if (current === "repairing_queue")
+                return "awaiting_queue";
             return current === "repairing_ci" ? "pr_open" : undefined;
         case "check_failed":
-            return current === "pr_open" || current === "awaiting_review" ? "repairing_ci" : undefined;
+            return current === "pr_open" || current === "awaiting_review" || current === "awaiting_queue"
+                ? "repairing_ci"
+                : undefined;
         case "pr_merged":
             return "done";
         case "pr_closed":

package/dist/github-app-token.js

@@ -0,0 +1,205 @@
+import { createSign } from "node:crypto";
+import { writeFile, mkdir } from "node:fs/promises";
+import path from "node:path";
+import { resolveSecret } from "./resolve-secret.js";
+import { getPatchRelayDataDir } from "./runtime-paths.js";
+const TOKEN_REFRESH_MS = 30 * 60_000; // 30 minutes (tokens last 1 hour)
+/**
+ * Resolve credentials from environment. Returns undefined if not configured.
+ *
+ * The private key is resolved via the provider-agnostic `resolveSecret`:
+ *   1. `$CREDENTIALS_DIRECTORY/github-app-pem`  (systemd-creds)
+ *   2. `$PATCHRELAY_GITHUB_APP_PRIVATE_KEY_FILE` (explicit file path)
+ *   3. `$PATCHRELAY_GITHUB_APP_PRIVATE_KEY`      (direct env var)
+ */
+export function resolveGitHubAppCredentials() {
+    const appId = process.env.PATCHRELAY_GITHUB_APP_ID;
+    const privateKey = resolveSecret("github-app-pem", "PATCHRELAY_GITHUB_APP_PRIVATE_KEY");
+    if (!appId || !privateKey)
+        return undefined;
+    const installationId = process.env.PATCHRELAY_GITHUB_APP_INSTALLATION_ID;
+    return {
+        appId,
+        privateKey,
+        ...(installationId ? { installationId } : {}),
+    };
+}
+/**
+ * Well-known paths for the token file and the gh wrapper.
+ */
+export function getGitHubAppPaths() {
+    const shareDir = getPatchRelayDataDir();
+    return {
+        tokenFile: path.join(shareDir, "gh-token"),
+        binDir: path.join(shareDir, "bin"),
+        ghWrapper: path.join(shareDir, "bin", "gh"),
+    };
+}
+/**
+ * Create the gh wrapper script that reads the token file.
+ * Idempotent — safe to call on every startup.
+ */
+export async function ensureGhWrapper(logger) {
+    const { binDir, ghWrapper, tokenFile } = getGitHubAppPaths();
+    await mkdir(binDir, { recursive: true });
+    const script = `#!/bin/bash
+# PatchRelay gh wrapper — uses GitHub App token when available.
+# Falls through to the user's own gh auth if the token file is missing.
+TOKEN_FILE="${tokenFile}"
+if [ -f "$TOKEN_FILE" ]; then
+  export GH_TOKEN=$(cat "$TOKEN_FILE")
+fi
+exec /usr/bin/gh "$@"
+`;
+    await writeFile(ghWrapper, script, { mode: 0o755 });
+    logger.debug({ path: ghWrapper }, "Wrote gh wrapper script");
+}
+/**
+ * Generate a GitHub App JWT (RS256, 10-minute lifetime).
+ */
+function generateJwt(appId, privateKey) {
+    const now = Math.floor(Date.now() / 1000);
+    const header = Buffer.from(JSON.stringify({ alg: "RS256", typ: "JWT" })).toString("base64url");
+    const payload = Buffer.from(JSON.stringify({
+        iat: now - 60, // 60s clock drift allowance
+        exp: now + 600, // 10 minutes
+        iss: appId,
+    })).toString("base64url");
+    const signer = createSign("RSA-SHA256");
+    signer.update(`${header}.${payload}`);
+    const signature = signer.sign(privateKey, "base64url");
+    return `${header}.${payload}.${signature}`;
+}
+/**
+ * Exchange a JWT for an installation access token (1-hour lifetime).
+ */
+async function fetchInstallationToken(jwt, installationId) {
+    const response = await fetch(`https://api.github.com/app/installations/${installationId}/access_tokens`, {
+        method: "POST",
+        headers: {
+            Authorization: `Bearer ${jwt}`,
+            Accept: "application/vnd.github+json",
+            "X-GitHub-Api-Version": "2022-11-28",
+        },
+    });
+    if (!response.ok) {
+        const body = await response.text();
+        throw new Error(`Failed to fetch installation token (${response.status}): ${body}`);
+    }
+    const data = await response.json();
+    return data.token;
+}
+/**
+ * Find the first installation ID for this app. Called once if installationId
+ * is not pre-configured.
+ */
+async function resolveInstallationId(jwt) {
+    const response = await fetch("https://api.github.com/app/installations", {
+        headers: {
+            Authorization: `Bearer ${jwt}`,
+            Accept: "application/vnd.github+json",
+            "X-GitHub-Api-Version": "2022-11-28",
+        },
+    });
+    if (!response.ok) {
+        const body = await response.text();
+        throw new Error(`Failed to list installations (${response.status}): ${body}`);
+    }
+    const installations = await response.json();
+    const first = installations[0];
+    if (!first) {
+        throw new Error("GitHub App has no installations. Install it on a repository first.");
+    }
+    return String(first.id);
+}
+/**
+ * Creates a token manager that writes a fresh GitHub App installation token
+ * to a well-known file every 30 minutes. The gh wrapper script reads this file.
+ *
+ * Returns undefined if credentials are not configured (optional feature).
+ */
+export function createGitHubAppTokenManager(credentials, logger) {
+    const { tokenFile } = getGitHubAppPaths();
+    let timer;
+    let resolvedInstallationId = credentials.installationId;
+    let cachedToken;
+    let resolvedBotIdentity;
+    async function refresh() {
+        try {
+            const jwt = generateJwt(credentials.appId, credentials.privateKey);
+            if (!resolvedInstallationId) {
+                resolvedInstallationId = await resolveInstallationId(jwt);
+                logger.info({ installationId: resolvedInstallationId }, "Resolved GitHub App installation ID");
+            }
+            if (!resolvedBotIdentity) {
+                resolvedBotIdentity = await resolveBotIdentity(jwt);
+                logger.info({ botName: resolvedBotIdentity.name, botEmail: resolvedBotIdentity.email }, "Resolved GitHub App bot identity");
+            }
+            const token = await fetchInstallationToken(jwt, resolvedInstallationId);
+            await mkdir(path.dirname(tokenFile), { recursive: true });
+            await writeFile(tokenFile, token, { mode: 0o600 });
+            cachedToken = token;
+            logger.debug("Refreshed GitHub App installation token");
+        }
+        catch (error) {
+            logger.warn({ error: error instanceof Error ? error.message : String(error) }, "Failed to refresh GitHub App token (will retry in 30 minutes)");
+        }
+    }
+    function schedule() {
+        timer = setTimeout(() => {
+            void refresh().finally(schedule);
+        }, TOKEN_REFRESH_MS);
+        timer.unref?.();
+    }
+    return {
+        async start() {
+            await refresh();
+            schedule();
+        },
+        stop() {
+            if (timer) {
+                clearTimeout(timer);
+                timer = undefined;
+            }
+        },
+        currentToken() {
+            return cachedToken;
+        },
+        botIdentity() {
+            return resolvedBotIdentity;
+        },
+    };
+}
+/**
+ * Resolve the bot user identity (name + noreply email) from the GitHub API.
+ * The bot user ID (not the App ID) is required for the noreply email —
+ * using the App ID causes the [bot] badge to not render on commits.
+ */
+async function resolveBotIdentity(jwt) {
+    const response = await fetch("https://api.github.com/app", {
+        headers: {
+            Authorization: `Bearer ${jwt}`,
+            Accept: "application/vnd.github+json",
+            "X-GitHub-Api-Version": "2022-11-28",
+        },
+    });
+    if (!response.ok) {
+        const body = await response.text();
+        throw new Error(`Failed to fetch app info (${response.status}): ${body}`);
+    }
+    const app = await response.json();
+    const botLogin = `${app.slug}[bot]`;
+    // Fetch the bot user to get the user ID (different from App ID)
+    const userResponse = await fetch(`https://api.github.com/users/${encodeURIComponent(botLogin)}`, {
+        headers: { Accept: "application/vnd.github+json", "X-GitHub-Api-Version": "2022-11-28" },
+    });
+    if (!userResponse.ok) {
+        const body = await userResponse.text();
+        throw new Error(`Failed to fetch bot user ${botLogin} (${userResponse.status}): ${body}`);
+    }
+    const user = await userResponse.json();
+    return {
+        name: user.login,
+        email: `${user.id}+${user.login}@users.noreply.github.com`,
+    };
+}

package/dist/github-webhook-handler.js

@@ -1,18 +1,53 @@
 import { resolveFactoryStateFromGitHub } from "./factory-state.js";
 import { normalizeGitHubWebhook, verifyGitHubWebhookSignature } from "./github-webhooks.js";
+import { resolveSecret } from "./resolve-secret.js";
 import { safeJsonParse } from "./utils.js";
+/**
+ * GitHub sends both check_run and check_suite completion events.
+ * A single CI run generates 10+ individual check_run events as each job finishes,
+ * but only 1 check_suite event when the entire suite completes. Reacting to
+ * individual check_run events causes the factory state to flicker rapidly
+ * between pr_open and repairing_ci. We only drive state transitions and reactive
+ * runs from check_suite events. Individual check_run events still update PR
+ * metadata (prCheckStatus) for observability.
+ */
+function isMetadataOnlyCheckEvent(event) {
+    return event.eventSource === "check_run"
+        && (event.triggerEvent === "check_passed" || event.triggerEvent === "check_failed");
+}
+/**
+ * Codex sometimes closes and immediately reopens a PR (e.g. to change the
+ * base branch or fix the title). A pr_closed event during an active run
+ * should not transition to "failed" — the reopened event will follow.
+ * Without this guard, the state gets stuck at "failed" because
+ * failed → pr_open is not an allowed transition.
+ */
+function shouldSuppressCloseTransition(newState, event, issue) {
+    return newState === "failed" && event.triggerEvent === "pr_closed" && issue.activeRunId !== undefined;
+}
+/**
+ * After a CI repair succeeds and CI passes, the resolver returns pr_open.
+ * If the PR is already approved, fast-track to awaiting_queue so the merge
+ * queue picks it up again. This avoids a dead state where the PR is approved
+ * and CI-green but nobody advances the merge queue.
+ */
+function shouldFastTrackToQueue(newState, issue) {
+    return newState === "pr_open" && issue.prReviewState === "approved";
+}
 export class GitHubWebhookHandler {
     config;
     db;
     linearProvider;
     enqueueIssue;
+    mergeQueue;
     logger;
     feed;
-    constructor(config, db, linearProvider, enqueueIssue, logger, feed) {
+    constructor(config, db, linearProvider, enqueueIssue, mergeQueue, logger, feed) {
         this.config = config;
         this.db = db;
         this.linearProvider = linearProvider;
         this.enqueueIssue = enqueueIssue;
+        this.mergeQueue = mergeQueue;
         this.logger = logger;
         this.feed = feed;
     }
@@ -39,7 +74,7 @@ export class GitHubWebhookHandler {
             ? this.config.projects.find((p) => p.github?.repoFullName === repoName)
             : undefined;
         // Verify signature using global GitHub App webhook secret
-        const webhookSecret = process.env.GITHUB_APP_WEBHOOK_SECRET;
+        const webhookSecret = resolveSecret("github-app-webhook-secret", "GITHUB_APP_WEBHOOK_SECRET");
         if (webhookSecret) {
             if (!verifyGitHubWebhookSignature(params.rawBody, webhookSecret, params.signature)) {
                 return { status: 401, body: { ok: false, reason: "invalid_signature" } };
@@ -63,6 +98,24 @@ export class GitHubWebhookHandler {
         const payload = safeJsonParse(params.rawBody);
         if (!payload || typeof payload !== "object")
             return;
+        // Push to a base branch advances the merge queue for affected projects.
+        // This catches external merges (human PRs, direct pushes) that PatchRelay
+        // does not track as issues but that make queued branches stale.
+        if (params.eventType === "push") {
+            const pushPayload = payload;
+            const ref = pushPayload.ref;
+            const repoFullName = pushPayload.repository?.full_name;
+            if (ref && repoFullName) {
+                const branchName = ref.replace("refs/heads/", "");
+                for (const project of this.config.projects) {
+                    const baseBranch = project.github?.baseBranch ?? "main";
+                    if (project.github?.repoFullName === repoFullName && branchName === baseBranch) {
+                        this.mergeQueue.advanceQueue(project.id);
+                    }
+                }
+            }
+            return;
+        }
         const event = normalizeGitHubWebhook({
             eventType: params.eventType,
             payload: payload,
@@ -87,28 +140,40 @@ export class GitHubWebhookHandler {
             ...(event.reviewState !== undefined ? { prReviewState: event.reviewState } : {}),
             ...(event.checkStatus !== undefined ? { prCheckStatus: event.checkStatus } : {}),
         });
-        // Individual check_run events only update PR metadata, not factory state.
-        // State transitions and reactive runs are driven by check_suite completion
-        // to avoid flickering when multiple checks run in parallel.
-        const isIndividualCheckRun = event.eventSource === "check_run"
-            && (event.triggerEvent === "check_passed" || event.triggerEvent === "check_failed");
-        // Drive factory state transitions from GitHub events
-        if (!isIndividualCheckRun) {
-            let newState = resolveFactoryStateFromGitHub(event.triggerEvent, issue.factoryState);
-            // Don't transition to failed on pr_closed when a run is active —
-            // Codex sometimes closes and reopens PRs during its workflow.
-            if (newState === "failed" && event.triggerEvent === "pr_closed" && issue.activeRunId !== undefined) {
+        if (!isMetadataOnlyCheckEvent(event)) {
+            // Re-read issue after PR metadata upsert so fast-track sees fresh prReviewState
+            const afterMetadata = this.db.getIssue(issue.projectId, issue.linearIssueId) ?? issue;
+            let newState = resolveFactoryStateFromGitHub(event.triggerEvent, afterMetadata.factoryState);
+            if (shouldSuppressCloseTransition(newState, event, afterMetadata)) {
                 newState = undefined;
             }
-            if (newState && newState !== issue.factoryState) {
+            if (shouldFastTrackToQueue(newState, afterMetadata)) {
+                newState = "awaiting_queue";
+            }
+            // Only transition and notify when the state actually changes.
+            // Multiple check_suite events can arrive for the same outcome.
+            if (newState && newState !== afterMetadata.factoryState) {
                 this.db.upsertIssue({
                     projectId: issue.projectId,
                     linearIssueId: issue.linearIssueId,
                     factoryState: newState,
                 });
-                this.logger.info({ issueKey: issue.issueKey, from: issue.factoryState, to: newState, trigger: event.triggerEvent }, "Factory state transition from GitHub event");
+                this.logger.info({ issueKey: issue.issueKey, from: afterMetadata.factoryState, to: newState, trigger: event.triggerEvent }, "Factory state transition from GitHub event");
                 // Emit Linear activity for significant state changes
                 void this.emitLinearActivity(issue, newState, event);
+                // Schedule merge prep when entering awaiting_queue
+                if (newState === "awaiting_queue") {
+                    this.db.upsertIssue({
+                        projectId: issue.projectId,
+                        linearIssueId: issue.linearIssueId,
+                        pendingMergePrep: true,
+                    });
+                    this.enqueueIssue(issue.projectId, issue.linearIssueId);
+                }
+                // Advance the merge queue when a PR merges
+                if (newState === "done" && event.triggerEvent === "pr_merged") {
+                    this.mergeQueue.advanceQueue(issue.projectId);
+                }
             }
         }
         // Reset repair counters on new push
@@ -133,8 +198,7 @@ export class GitHubWebhookHandler {
             summary: `GitHub: ${event.triggerEvent}${event.prNumber ? ` on PR #${event.prNumber}` : ""}`,
             detail: event.checkName ?? event.reviewBody?.slice(0, 200) ?? undefined,
         });
-        // Trigger reactive runs if applicable (skip individual check_run events)
-        if (!isIndividualCheckRun) {
+        if (!isMetadataOnlyCheckEvent(event)) {
             this.maybeEnqueueReactiveRun(freshIssue, event);
         }
     }
@@ -189,10 +253,10 @@ export class GitHubWebhookHandler {
             return;
         const messages = {
             pr_open: `PR #${event.prNumber ?? ""} opened.${event.prUrl ? ` ${event.prUrl}` : ""}`,
-            awaiting_queue: "PR approved. Awaiting merge queue.",
+            awaiting_queue: "PR approved. Preparing merge.",
             changes_requested: `Review requested changes.${event.reviewerName ? ` Reviewer: ${event.reviewerName}` : ""}`,
             repairing_ci: `CI check failed${event.checkName ? `: ${event.checkName}` : ""}. Starting repair.`,
-            repairing_queue: "Merge queue failed. Starting repair.",
+            repairing_queue: "Merge conflict with base branch. Starting repair.",
             done: `PR merged and deployed.${event.prNumber ? ` PR #${event.prNumber}` : ""}`,
             failed: "PR was closed without merging.",
         };

package/dist/merge-queue.js

@@ -0,0 +1,161 @@
+import { execCommand } from "./utils.js";
+/**
+ * Merge queue steward — keeps PatchRelay-managed PR branches up to date
+ * with the base branch and enables auto-merge so GitHub merges when CI passes.
+ *
+ * Serialization: all calls are routed through the issue queue, and
+ * prepareForMerge checks front-of-queue before acting. The issue processor
+ * in service.ts checks pendingRunType before pendingMergePrep, so repair
+ * runs always take priority over merge prep.
+ */
+export class MergeQueue {
+    config;
+    db;
+    enqueueIssue;
+    logger;
+    feed;
+    constructor(config, db, enqueueIssue, logger, feed) {
+        this.config = config;
+        this.db = db;
+        this.enqueueIssue = enqueueIssue;
+        this.logger = logger;
+        this.feed = feed;
+    }
+    /**
+     * Prepare the front-of-queue issue for merge:
+     * 1. Enable auto-merge
+     * 2. Update the branch to latest base (git merge)
+     * 3. Push (triggers CI; auto-merge fires when CI passes)
+     *
+     * On conflict: abort merge, transition to repairing_queue, enqueue queue_repair.
+     * On transient failure: leave pendingMergePrep set so the next event retries.
+     */
+    async prepareForMerge(issue, project) {
+        // Only prepare the front-of-queue issue for this project
+        const queue = this.db.listIssuesByState(project.id, "awaiting_queue");
+        const front = queue.find((i) => i.activeRunId === undefined && i.pendingRunType === undefined);
+        if (!front || front.id !== issue.id) {
+            this.db.upsertIssue({ projectId: issue.projectId, linearIssueId: issue.linearIssueId, pendingMergePrep: false });
+            return;
+        }
+        if (!issue.worktreePath || !issue.prNumber) {
+            this.logger.warn({ issueKey: issue.issueKey }, "Merge prep skipped: missing worktree or PR number");
+            this.db.upsertIssue({ projectId: issue.projectId, linearIssueId: issue.linearIssueId, pendingMergePrep: false });
+            return;
+        }
+        const repoFullName = project.github?.repoFullName;
+        const baseBranch = project.github?.baseBranch ?? "main";
+        const gitBin = this.config.runner.gitBin;
+        // Enable auto-merge (idempotent)
+        const autoMergeOk = repoFullName ? await this.enableAutoMerge(issue, repoFullName) : false;
+        // Fetch latest base branch
+        const fetchResult = await execCommand(gitBin, ["-C", issue.worktreePath, "fetch", "origin", baseBranch], {
+            timeoutMs: 60_000,
+        });
+        if (fetchResult.exitCode !== 0) {
+            // Transient failure — leave pendingMergePrep set so the next event retries.
+            this.logger.warn({ issueKey: issue.issueKey, stderr: fetchResult.stderr?.slice(0, 300) }, "Merge prep: fetch failed, will retry on next event");
+            return;
+        }
+        // Merge base branch into the PR branch
+        const mergeResult = await execCommand(gitBin, ["-C", issue.worktreePath, "merge", `origin/${baseBranch}`, "--no-edit"], {
+            timeoutMs: 60_000,
+        });
+        if (mergeResult.exitCode !== 0) {
+            // Conflict — abort and trigger queue_repair
+            await execCommand(gitBin, ["-C", issue.worktreePath, "merge", "--abort"], { timeoutMs: 10_000 });
+            this.logger.info({ issueKey: issue.issueKey }, "Merge prep: conflict detected, triggering queue repair");
+            this.db.upsertIssue({
+                projectId: issue.projectId,
+                linearIssueId: issue.linearIssueId,
+                factoryState: "repairing_queue",
+                pendingRunType: "queue_repair",
+                pendingRunContextJson: JSON.stringify({ failureReason: "merge_conflict" }),
+                pendingMergePrep: false,
+            });
+            this.enqueueIssue(issue.projectId, issue.linearIssueId);
+            this.feed?.publish({
+                level: "warn",
+                kind: "workflow",
+                issueKey: issue.issueKey,
+                projectId: issue.projectId,
+                stage: "repairing_queue",
+                status: "conflict",
+                summary: `Merge conflict with ${baseBranch} — queue repair enqueued`,
+            });
+            return;
+        }
+        // Check if merge was a no-op (already up to date)
+        if (mergeResult.stdout?.includes("Already up to date")) {
+            this.logger.debug({ issueKey: issue.issueKey }, "Merge prep: branch already up to date");
+            this.db.upsertIssue({ projectId: issue.projectId, linearIssueId: issue.linearIssueId, pendingMergePrep: false });
+            if (!autoMergeOk) {
+                this.feed?.publish({
+                    level: "warn",
+                    kind: "workflow",
+                    issueKey: issue.issueKey,
+                    projectId: issue.projectId,
+                    stage: "awaiting_queue",
+                    status: "blocked",
+                    summary: "Branch up to date but auto-merge not enabled — check gh auth and repo settings",
+                });
+            }
+            return;
+        }
+        // Push the merged branch
+        const pushResult = await execCommand(gitBin, ["-C", issue.worktreePath, "push"], {
+            timeoutMs: 60_000,
+        });
+        if (pushResult.exitCode !== 0) {
+            // Push failed — leave pendingMergePrep set so the next event retries.
+            this.logger.warn({ issueKey: issue.issueKey, stderr: pushResult.stderr?.slice(0, 300) }, "Merge prep: push failed, will retry on next event");
+            return;
+        }
+        this.logger.info({ issueKey: issue.issueKey, baseBranch }, "Merge prep: branch updated and pushed");
+        this.db.upsertIssue({ projectId: issue.projectId, linearIssueId: issue.linearIssueId, pendingMergePrep: false });
+        this.feed?.publish({
+            level: "info",
+            kind: "workflow",
+            issueKey: issue.issueKey,
+            projectId: issue.projectId,
+            stage: "awaiting_queue",
+            status: "prepared",
+            summary: `Branch updated to latest ${baseBranch} — CI will run`,
+        });
+    }
+    /**
+     * Seed the merge queue on startup: for each project, ensure the front-of-queue
+     * issue has pendingMergePrep set. Catches issues that entered awaiting_queue
+     * but whose merge prep was never triggered or was lost to a crash/restart.
+     */
+    seedOnStartup() {
+        for (const project of this.config.projects) {
+            this.advanceQueue(project.id);
+        }
+    }
+    /**
+     * Advance the queue: find the next awaiting_queue issue and prepare it.
+     * Called when a PR merges (pr_merged event) and on startup.
+     */
+    advanceQueue(projectId) {
+        const queue = this.db.listIssuesByState(projectId, "awaiting_queue");
+        const next = queue.find((i) => i.activeRunId === undefined && i.pendingRunType === undefined && !i.pendingMergePrep);
+        if (!next)
+            return;
+        this.logger.info({ issueKey: next.issueKey, projectId }, "Advancing merge queue");
+        this.db.upsertIssue({ projectId: next.projectId, linearIssueId: next.linearIssueId, pendingMergePrep: true });
+        this.enqueueIssue(next.projectId, next.linearIssueId);
+    }
+    /** Returns true if auto-merge was successfully enabled (or already enabled). */
+    async enableAutoMerge(issue, repoFullName) {
+        // Uses the host's existing gh auth — same credentials Codex uses to create PRs.
+        const result = await execCommand("gh", ["pr", "merge", String(issue.prNumber), "--repo", repoFullName, "--auto", "--squash"], {
+            timeoutMs: 30_000,
+        });
+        if (result.exitCode !== 0) {
+            this.logger.warn({ issueKey: issue.issueKey, stderr: result.stderr?.slice(0, 200) }, "Merge prep: auto-merge enablement failed");
+            return false;
+        }
+        return true;
+    }
+}

package/dist/resolve-secret.js

@@ -0,0 +1,38 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+/**
+ * Resolve a secret value using a three-level fallback:
+ *
+ * 1. `$CREDENTIALS_DIRECTORY/<credentialName>` — systemd-creds, Docker secrets,
+ *    or any provider that mounts secrets as files in a private directory.
+ * 2. `${envKey}_FILE` — reads the secret from an arbitrary file path.
+ *    Works with any file-based provider (age, sops, mounted volumes).
+ * 3. `$envKey` — direct environment variable (dev, `op run`, `sops exec-env`,
+ *    or the legacy `service.env` EnvironmentFile).
+ *
+ * Returns `undefined` when the secret is not found at any level.
+ */
+export function resolveSecret(credentialName, envKey, env = process.env) {
+    // 1. systemd credentials directory (private mount, highest trust)
+    const credDir = process.env.CREDENTIALS_DIRECTORY;
+    if (credDir) {
+        try {
+            return readFileSync(path.join(credDir, credentialName), "utf8").trim();
+        }
+        catch {
+            // credential not in this directory — fall through
+        }
+    }
+    // 2. _FILE convention (works with any file-based provider)
+    const filePath = env[`${envKey}_FILE`];
+    if (filePath) {
+        try {
+            return readFileSync(filePath, "utf8").trim();
+        }
+        catch {
+            // file not readable — fall through
+        }
+    }
+    // 3. Direct env var
+    return env[envKey] || undefined;
+}

package/dist/run-orchestrator.js

@@ -5,6 +5,7 @@ import { buildRunningSessionPlan, buildCompletedSessionPlan, buildFailedSessionP
 import { buildStageReport, countEventMethods, extractTurnId, resolveRunCompletionStatus, summarizeCurrentThread, } from "./run-reporting.js";
 import { WorktreeManager } from "./worktree-manager.js";
 import { resolveAuthoritativeLinearStopState } from "./linear-workflow.js";
+import { execCommand } from "./utils.js";
 const DEFAULT_CI_REPAIR_BUDGET = 2;
 const DEFAULT_QUEUE_REPAIR_BUDGET = 2;
 function slugify(value) {
@@ -66,6 +67,7 @@ export class RunOrchestrator {
     logger;
     feed;
     worktreeManager;
+    botIdentity;
     constructor(config, db, codex, linearProvider, enqueueIssue, logger, feed) {
         this.config = config;
         this.db = db;
@@ -155,6 +157,12 @@ export class RunOrchestrator {
         try {
             // Ensure worktree
             await this.worktreeManager.ensureIssueWorktree(project.repoPath, project.worktreeRoot, worktreePath, branchName, { allowExistingOutsideRoot: issue.branchName !== undefined });
+            // Set bot git identity when GitHub App is configured
+            if (this.botIdentity) {
+                const gitBin = this.config.runner.gitBin;
+                await execCommand(gitBin, ["-C", worktreePath, "config", "user.name", this.botIdentity.name], { timeoutMs: 5_000 });
+                await execCommand(gitBin, ["-C", worktreePath, "config", "user.email", this.botIdentity.email], { timeoutMs: 5_000 });
+            }
             // Run prepare-worktree hook
             const hookEnv = buildHookEnv(issue.issueKey ?? issue.linearIssueId, branchName, runType, worktreePath);
             const prepareResult = await runProjectHook(project.repoPath, "prepare-worktree", { cwd: worktreePath, env: hookEnv });

package/dist/service.js

@@ -1,6 +1,8 @@
+import { resolveGitHubAppCredentials, createGitHubAppTokenManager, ensureGhWrapper, } from "./github-app-token.js";
 import { GitHubWebhookHandler } from "./github-webhook-handler.js";
 import { IssueQueryService } from "./issue-query-service.js";
 import { LinearOAuthService } from "./linear-oauth-service.js";
+import { MergeQueue } from "./merge-queue.js";
 import { RunOrchestrator } from "./run-orchestrator.js";
 import { OperatorEventFeed } from "./operator-feed.js";
 import { buildSessionStatusUrl, createSessionStatusToken, deriveSessionStatusSigningSecret, verifySessionStatusToken, } from "./public-agent-session-status.js";
@@ -14,6 +16,8 @@ export class PatchRelayService {
     logger;
     linearProvider;
     orchestrator;
+    mergeQueue;
+    githubAppTokenManager;
     webhookHandler;
     githubWebhookHandler;
     oauthService;
@@ -31,21 +35,60 @@ export class PatchRelayService {
             throw new Error("Service runtime enqueueIssue is not initialized");
         };
         this.orchestrator = new RunOrchestrator(config, db, codex, this.linearProvider, (projectId, issueId) => enqueueIssue(projectId, issueId), logger, this.feed);
+        this.mergeQueue = new MergeQueue(config, db, (projectId, issueId) => enqueueIssue(projectId, issueId), logger, this.feed);
         this.webhookHandler = new WebhookHandler(config, db, this.linearProvider, codex, (projectId, issueId) => enqueueIssue(projectId, issueId), logger, this.feed);
-        this.githubWebhookHandler = new GitHubWebhookHandler(config, db, this.linearProvider, (projectId, issueId) => enqueueIssue(projectId, issueId), logger, this.feed);
-        const runtime = new ServiceRuntime(codex, logger, this.orchestrator, { listIssuesReadyForExecution: () => db.listIssuesReadyForExecution() }, this.webhookHandler, { processIssue: (item) => this.orchestrator.run(item) });
+        this.githubWebhookHandler = new GitHubWebhookHandler(config, db, this.linearProvider, (projectId, issueId) => enqueueIssue(projectId, issueId), this.mergeQueue, logger, this.feed);
+        const runtime = new ServiceRuntime(codex, logger, this.orchestrator, { listIssuesReadyForExecution: () => db.listIssuesReadyForExecution() }, this.webhookHandler, {
+            processIssue: async (item) => {
+                const issue = db.getIssue(item.projectId, item.issueId);
+                // Repairs take priority over merge prep — a check_failed or
+                // review_changes_requested that arrived while merge prep was
+                // queued must not be swallowed.
+                if (issue?.pendingRunType) {
+                    await this.orchestrator.run(item);
+                    return;
+                }
+                if (issue?.pendingMergePrep) {
+                    const project = config.projects.find((p) => p.id === item.projectId);
+                    if (project)
+                        await this.mergeQueue.prepareForMerge(issue, project);
+                    // Re-check: a repair run may have been enqueued during prep
+                    const after = db.getIssue(item.projectId, item.issueId);
+                    if (after?.pendingRunType) {
+                        runtime.enqueueIssue(item.projectId, item.issueId);
+                    }
+                    return;
+                }
+                await this.orchestrator.run(item);
+            },
+        });
         enqueueIssue = (projectId, issueId) => runtime.enqueueIssue(projectId, issueId);
         this.oauthService = new LinearOAuthService(config, { linearInstallations: db.linearInstallations }, logger);
         this.queryService = new IssueQueryService(db, codex, this.orchestrator);
         this.runtime = runtime;
+        // Optional GitHub App token management for bot identity
+        const ghAppCredentials = resolveGitHubAppCredentials();
+        if (ghAppCredentials) {
+            this.githubAppTokenManager = createGitHubAppTokenManager(ghAppCredentials, logger);
+        }
         this.codex.on("notification", (notification) => {
             void this.orchestrator.handleCodexNotification(notification);
         });
     }
     async start() {
+        if (this.githubAppTokenManager) {
+            await ensureGhWrapper(this.logger);
+            await this.githubAppTokenManager.start();
+            const identity = this.githubAppTokenManager.botIdentity();
+            if (identity) {
+                this.orchestrator.botIdentity = identity;
+            }
+        }
         await this.runtime.start();
+        this.mergeQueue.seedOnStartup();
     }
     stop() {
+        this.githubAppTokenManager?.stop();
         this.runtime.stop();
     }
     async createLinearOAuthStart(params) {

package/infra/patchrelay.service

@@ -1,5 +1,5 @@
 [Unit]
-Description=PatchRelay (systemd user service)
+Description=PatchRelay
 After=network-online.target
 Wants=network-online.target
 StartLimitIntervalSec=60
@@ -7,24 +7,47 @@ StartLimitBurst=8
 
 [Service]
 Type=simple
+User=your-user
+Group=your-user
 WorkingDirectory=/home/your-user
+
+# Non-secret config: runtime overrides (paths, log level) and
+# service-only identifiers (GitHub App IDs, etc.)
 EnvironmentFile=-/home/your-user/.config/patchrelay/runtime.env
-EnvironmentFile=/home/your-user/.config/patchrelay/service.env
+EnvironmentFile=-/home/your-user/.config/patchrelay/service.env
 Environment=NODE_ENV=production
 Environment=PATCHRELAY_CONFIG=/home/your-user/.config/patchrelay/patchrelay.json
-Environment=PATH=/home/your-user/.local/bin:/usr/local/bin:/usr/bin:/bin
+Environment=PATH=/home/your-user/.local/share/patchrelay/bin:/home/your-user/.local/bin:/usr/local/bin:/usr/bin:/bin
+
+# Secrets — encrypted at rest via systemd-creds, decrypted into a private
+# ramfs at $CREDENTIALS_DIRECTORY visible only to this service.
+# See docs/secrets.md for setup instructions.
+#
+# When credstore is not configured, PatchRelay falls back to reading secrets
+# from env vars (EnvironmentFile, op run, etc.) via the resolve-secret module.
+LoadCredentialEncrypted=linear-webhook-secret
+LoadCredentialEncrypted=token-encryption-key
+LoadCredentialEncrypted=linear-oauth-client-id
+LoadCredentialEncrypted=linear-oauth-client-secret
+# Uncomment when GitHub App integration is configured:
+# LoadCredentialEncrypted=github-app-pem
+# LoadCredentialEncrypted=github-app-webhook-secret
+
 ExecStart=/usr/bin/env patchrelay serve
 Restart=on-failure
 RestartSec=5
+
+# Hardening
 NoNewPrivileges=true
 PrivateTmp=true
-ProtectSystem=full
+PrivateMounts=true
+ProtectSystem=strict
 ProtectHome=false
 ReadWritePaths=/home/your-user/.config/patchrelay /home/your-user/.local/state/patchrelay /home/your-user/.local/share/patchrelay
 
-# PatchRelay is intended to run as your real user so Codex inherits your
-# existing git, SSH, and local tool permissions.
-# Add your managed repository roots to ReadWritePaths if you keep hardening enabled.
+# PatchRelay runs as your real user so Codex inherits your existing git,
+# SSH, and local tool permissions.
+# Add your managed repository roots to ReadWritePaths.
 
 [Install]
-WantedBy=default.target
+WantedBy=multi-user.target

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "patchrelay",
-  "version": "0.10.7",
+  "version": "0.12.0",
   "license": "MIT",
   "type": "module",
   "repository": {

package/service.env.example

@@ -1,7 +1,25 @@
-# PatchRelay service secrets.
-# Keep these values at the machine level for this PatchRelay instance.
+# PatchRelay service-only configuration.
+#
+# Secrets in this file are generated by `patchrelay init` for initial setup.
+# For production, encrypt them with systemd-creds and remove the plaintext
+# values below.  See docs/secrets.md.
+#
+# Non-secret service identifiers (GitHub App IDs) stay here permanently.
 
 LINEAR_WEBHOOK_SECRET=replace-with-linear-webhook-secret
 PATCHRELAY_TOKEN_ENCRYPTION_KEY=replace-with-long-random-secret
 LINEAR_OAUTH_CLIENT_ID=replace-with-linear-oauth-client-id
 LINEAR_OAUTH_CLIENT_SECRET=replace-with-linear-oauth-client-secret
+
+# Optional: GitHub App for bot identity.
+# When configured, PatchRelay generates short-lived installation tokens
+# and writes a gh wrapper so Codex operates as app-name[bot].
+# Create a GitHub App at Settings > Developer settings > GitHub Apps.
+#
+# The private key resolves through the provider-agnostic fallback:
+#   1. $CREDENTIALS_DIRECTORY/github-app-pem      (systemd-creds)
+#   2. PATCHRELAY_GITHUB_APP_PRIVATE_KEY_FILE      (path to PEM file)
+#   3. PATCHRELAY_GITHUB_APP_PRIVATE_KEY           (inline PEM string)
+#
+# PATCHRELAY_GITHUB_APP_ID=123456
+# PATCHRELAY_GITHUB_APP_INSTALLATION_ID=optional-skip-auto-discovery