merge-steward 0.10.2 → 0.10.4

package/README.md

@@ -58,7 +58,7 @@ Add one repo-scoped steward instance:
 merge-steward attach owner/repo
 ```
 
-That writes `~/.config/merge-steward/repos/<derived-id>.json`. By default, `attach` derives the repo id from the GitHub repo name, discovers the default branch and required status checks from GitHub, and stores the discovered values into local config.
+That writes `~/.config/merge-steward/repos/<derived-id>.json`. By default, `attach` derives the repo id from the GitHub repo name and discovers the default branch from GitHub. Required checks are not stored locally; the running steward reads GitHub branch protection as the source of truth.
 
 If you also use `review-quill`, its `review-quill/verdict` check can be added to
 the repository's required checks if you want machine review to be part of the
@@ -145,7 +145,6 @@ The CLI is a thin local client and does not need direct access to secret credent
   "clonePath": "~/.local/state/merge-steward/repos/app",
   "maxRetries": 2,
   "flakyRetries": 1,
-  "requiredChecks": ["test", "lint"],
   "pollIntervalMs": 30000,
   "admissionLabel": "queue",
   "mergeQueueCheckName": "merge-steward/queue",
@@ -167,7 +166,6 @@ The CLI is a thin local client and does not need direct access to secret credent
 | `clonePath` | Local clone directory (created on first run) |
 | `maxRetries` | Rebase/CI retry attempts before eviction |
 | `flakyRetries` | CI-only retries before counting toward maxRetries |
-| `requiredChecks` | Check names that must pass for admission (empty = any green) |
 | `pollIntervalMs` | Reconciliation loop interval |
 | `admissionLabel` | Optional GitHub label used as a manual/operator admission nudge |
 | `mergeQueueCheckName` | GitHub check run name emitted on eviction |
@@ -176,9 +174,8 @@ The CLI is a thin local client and does not need direct access to secret credent
 
 - `repoId` defaults to the repo name portion of `owner/repo`
 - `baseBranch` defaults to the GitHub default branch
-- `requiredChecks` default to the active `required_status_checks` branch rules for the configured base branch
 
-Pass `--refresh` to re-discover base branch and required checks for an existing repo config. `merge-steward doctor --repo <id>` compares the stored config to GitHub and warns on drift.
+Pass `--refresh` to re-discover the base branch for an existing repo config. `merge-steward doctor --repo <id>` reports the GitHub-required checks currently enforced for that branch.
 
 ### GitHub Webhook
 
@@ -187,7 +184,7 @@ Configure one webhook on the repository pointing to the steward:
 - **Payload URL:** `https://queue.example.com/webhooks/github`
 - **Content type:** `application/json`
 - **Secret:** same as `MERGE_STEWARD_WEBHOOK_SECRET` or the `merge-steward-webhook-secret` systemd credential
-- **Events:** Pull requests, Pull request reviews, Check suites, Pushes
+- **Events:** Pull requests, Pull request reviews, Check suites, Pushes, Branch protection rules, Repository rulesets
 
 The steward uses a single multi-repo webhook endpoint and routes events by `repository.full_name`.
 
@@ -197,9 +194,14 @@ It can wake up on:
 - review approvals
 - successful check-suite completion
 - pushes to the base branch
+- branch protection edits
+- repository ruleset edits
 
-Even without a webhook, startup and periodic reconcile will still scan open PRs
-and admit anything that already satisfies the gate.
+On startup, the steward reconciles GitHub protection for every attached repo. Policy changes are normally learned from GitHub policy webhooks. If a merge is rejected unexpectedly, the steward performs a guarded one-shot policy refresh to recover from a missed webhook without polling GitHub continuously.
+
+The dashboard project view and `merge-steward queue status --repo <id>` also show the live GitHub-required checks and the last policy refresh, so an operator can tell whether a queue pause came from a policy change or from the branch state itself.
+
+Current policy decision: Merge Steward uses the same GitHub-required check names for both PR/spec admission and current-`main` drift detection. For example, if branch protection requires `Tests`, the steward treats `Tests` as both the merge gate for candidate commits and the signal that current `main` is still in-policy. This is an explicit simplification for now and may be split into separate merge-gate and main-health signals later.
 
 ### Running
 
@@ -230,6 +232,7 @@ The first screen shows all configured projects with:
 - readable queue stats
 - a compact queue chain like `#123 ●  #124 ○`
 - clear bad states such as blocked, stuck, or needs attention
+- explicit startup states such as `Initializing` and `Init failed` for repo-local boot problems
 
 Press `Enter` on a project to open the second screen. That project detail view shows:
 
@@ -238,6 +241,7 @@ Press `Enter` on a project to open the second screen. That project detail view s
 - recent queue activity in plain language
 - incidents for evicted PRs
 - direct actions like reconcile and dequeue
+- live GitHub-required checks plus the last policy refresh
 
 Use `merge-steward dashboard --repo <id>` to open the project detail screen directly. Use `--pr <number>` to preselect a PR when you already know what you need to inspect.
 
@@ -253,6 +257,8 @@ Controls:
 
 ### Validation, Visibility, And Troubleshooting
 
+The gateway binds its HTTP port before repo initialization finishes. Each repo then initializes independently in the background, so a bad clone or GitHub discovery problem stays local to that repo instead of taking down the whole dashboard.
+
 These are the first commands to reach for after setup or when a queue looks wrong:
 
 ```bash

package/dist/admin-types.d.ts

@@ -1,4 +1,20 @@
 import type { DiscoveredRepoSettings } from "./github-repo-discovery.ts";
+export type RepoRuntimeState = "initializing" | "ready" | "failed";
+export interface RepoRuntimeStatus {
+    repoId: string;
+    repoFullName: string;
+    baseBranch: string;
+    state: RepoRuntimeState;
+    startedAt: string;
+    readyAt?: string | undefined;
+    failedAt?: string | undefined;
+    lastError?: string | undefined;
+}
+export interface ServiceHealthResponse {
+    ok: boolean;
+    startupComplete: boolean;
+    repos: RepoRuntimeStatus[];
+}
 export interface ServiceGitHubAuthStatus {
     mode: "none" | "app";
     configured: boolean;
@@ -27,4 +43,5 @@ export interface ServiceGitHubRepoAccessResponse {
 export interface ServiceErrorResponse {
     ok: false;
     error: string;
+    code?: string;
 }

package/dist/cli/args.d.ts

@@ -3,5 +3,4 @@ export declare function parseArgs(argv: string[]): ParsedArgs;
 export declare function hasHelpFlag(parsed: ParsedArgs): boolean;
 export declare function assertKnownFlags(parsed: ParsedArgs, helpTopic: HelpTopic, allowedFlags: string[]): void;
 export declare function validateFlags(parsed: ParsedArgs): void;
-export declare function parseCsvFlag(value: string | boolean | undefined): string[];
 export declare function parseIntegerFlag(value: string | boolean | undefined, label: string): number | undefined;

package/dist/cli/args.js

@@ -63,7 +63,7 @@ export function validateFlags(parsed) {
             assertKnownFlags(parsed, "root", ["repo", "pr"]);
             return;
         case "attach":
-            assertKnownFlags(parsed, "repos", ["base-branch", "required-check", "label", "merge-queue-check-name", "refresh", "json"]);
+            assertKnownFlags(parsed, "repos", ["base-branch", "label", "merge-queue-check-name", "refresh", "json"]);
             return;
         case "repos":
             assertKnownFlags(parsed, "repos", ["json"]);
@@ -76,7 +76,7 @@ export function validateFlags(parsed) {
                     assertKnownFlags(parsed, "repo", ["json"]);
                     return;
                 case "attach":
-                    assertKnownFlags(parsed, "repo", ["base-branch", "required-check", "label", "merge-queue-check-name", "refresh", "json"]);
+                    assertKnownFlags(parsed, "repo", ["base-branch", "label", "merge-queue-check-name", "refresh", "json"]);
                     return;
                 default:
                     assertKnownFlags(parsed, "repo", []);
@@ -122,11 +122,6 @@ export function validateFlags(parsed) {
             assertKnownFlags(parsed, "root", []);
     }
 }
-export function parseCsvFlag(value) {
-    if (typeof value !== "string")
-        return [];
-    return value.split(",").map((entry) => entry.trim()).filter(Boolean);
-}
 export function parseIntegerFlag(value, label) {
     if (typeof value !== "string")
         return undefined;

package/dist/cli/commands/attach.js

@@ -1,6 +1,5 @@
 import { upsertRepoConfig } from "../../install.js";
 import { UsageError } from "../types.js";
-import { parseCsvFlag } from "../args.js";
 import { formatJson, writeOutput } from "../output.js";
 import { runSystemctl } from "../system.js";
 import { fetchServiceRepoDiscovery, listRepoConfigs } from "../system.js";
@@ -42,15 +41,13 @@ export async function handleAttach(parsed, stdout, runCommand) {
     const { repoId, repoFullName } = parseAttachTarget(parsed);
     const existing = listRepoConfigs().find((repo) => repo.repoId === repoId || repo.repoFullName === repoFullName);
     const explicitBaseBranch = typeof parsed.flags.get("base-branch") === "string" ? String(parsed.flags.get("base-branch")) : undefined;
-    const explicitRequiredChecks = parseCsvFlag(parsed.flags.get("required-check"));
     const admissionLabel = typeof parsed.flags.get("label") === "string" ? String(parsed.flags.get("label")) : undefined;
     const mergeQueueCheckName = typeof parsed.flags.get("merge-queue-check-name") === "string"
         ? String(parsed.flags.get("merge-queue-check-name"))
         : undefined;
     const refresh = parsed.flags.get("refresh") === true;
     const shouldDiscoverBaseBranch = !explicitBaseBranch && (!existing || refresh);
-    const shouldDiscoverRequiredChecks = explicitRequiredChecks.length === 0 && (!existing || refresh || !!explicitBaseBranch);
-    const needsDiscovery = shouldDiscoverBaseBranch || shouldDiscoverRequiredChecks;
+    const needsDiscovery = shouldDiscoverBaseBranch || refresh;
     let discovered;
     const warnings = [];
     if (needsDiscovery) {
@@ -70,14 +67,10 @@ export async function handleAttach(parsed, stdout, runCommand) {
     }
     const baseBranch = explicitBaseBranch
         ?? (shouldDiscoverBaseBranch ? discovered?.branch : undefined);
-    const requiredChecks = explicitRequiredChecks.length > 0
-        ? explicitRequiredChecks
-        : (shouldDiscoverRequiredChecks ? discovered?.requiredChecks : undefined);
     const result = await upsertRepoConfig({
         id: repoId,
         repoFullName,
         ...(baseBranch ? { baseBranch } : {}),
-        ...(requiredChecks ? { requiredChecks } : {}),
         ...(admissionLabel ? { admissionLabel } : {}),
         ...(mergeQueueCheckName ? { mergeQueueCheckName } : {}),
     });
@@ -97,7 +90,6 @@ export async function handleAttach(parsed, stdout, runCommand) {
         `Base branch: ${result.repo.baseBranch}`,
         `Admission label: ${result.repo.admissionLabel}`,
         `Queue eviction check: ${result.repo.mergeQueueCheckName}`,
-        `Required checks: ${result.repo.requiredChecks.length > 0 ? result.repo.requiredChecks.join(", ") : "(any green check)"}`,
         ...warnings.map((warning) => `Warning: ${warning}`),
         ...(discovered?.warnings.map((warning) => `Warning: ${warning}`) ?? []),
         restartState.ok

package/dist/cli/commands/doctor.js

@@ -2,7 +2,6 @@ import { spawnSync } from "node:child_process";
 import { accessSync, constants, existsSync, mkdirSync, statSync } from "node:fs";
 import path from "node:path";
 import { loadConfig } from "../../config.js";
-import { normalizeCheckList } from "../../github-repo-discovery.js";
 import { getDefaultConfigPath, getDefaultRepoConfigDir, getDefaultRuntimeEnvPath, getDefaultServiceEnvPath, getDefaultStateDir, getSystemdUnitPath, } from "../../runtime-paths.js";
 import { formatJson, writeOutput } from "../output.js";
 import { fetchServiceGitHubAuthStatus, fetchServiceRepoAccess, fetchServiceRepoDiscovery, getHomeEnv, loadRepoConfigById, } from "../system.js";
@@ -189,24 +188,10 @@ export async function handleDoctor(parsed, stdout) {
                                 ? `Local base branch matches GitHub default branch (${discovered.defaultBranch})`
                                 : `Local base branch is ${config.baseBranch}, but GitHub default branch is ${discovered.defaultBranch}`,
                         });
-                        const configuredChecks = normalizeCheckList(config.requiredChecks);
-                        const discoveredChecks = normalizeCheckList(discovered.requiredChecks);
-                        const configuredSet = new Set(configuredChecks);
-                        const discoveredSet = new Set(discoveredChecks);
-                        const missingFromLocal = discoveredChecks.filter((value) => !configuredSet.has(value));
-                        const extraLocal = configuredChecks.filter((value) => !discoveredSet.has(value));
-                        const checksMatch = missingFromLocal.length === 0 && extraLocal.length === 0;
-                        const localSuperset = missingFromLocal.length === 0 && extraLocal.length > 0;
                         checks.push({
-                            status: checksMatch || localSuperset ? "pass" : "warn",
+                            status: "pass",
                             scope: `repo:${repoId}:github-required-checks`,
-                            message: checksMatch
-                                ? (configuredChecks.length > 0
-                                    ? `Local required checks match GitHub for ${config.baseBranch}`
-                                    : `No required checks configured locally and GitHub does not require status checks for ${config.baseBranch}`)
-                                : localSuperset
-                                    ? `Local required checks extend GitHub for ${config.baseBranch} with additional gates [${extraLocal.join(", ")}]`
-                                    : `Local required checks [${configuredChecks.join(", ") || "(none)"}] differ from GitHub [${discoveredChecks.join(", ") || "(none)"}] for ${config.baseBranch}${discoveredSource === "gh" ? " (via gh fallback)" : ""}`,
+                            message: `GitHub requires [${discovered.requiredChecks.join(", ") || "(none)"}] for ${config.baseBranch}${discoveredSource === "gh" ? " (via gh fallback)" : ""}`,
                         });
                         for (const warning of discovered.warnings ?? []) {
                             checks.push({

package/dist/cli/commands/queue.js

@@ -1,27 +1,40 @@
 import { SqliteStore } from "../../db/sqlite-store.js";
-import { buildSummary } from "../../service.js";
 import { TERMINAL_STATUSES } from "../../types.js";
 import { UsageError } from "../types.js";
 import { parseIntegerFlag } from "../args.js";
 import { formatJson, writeOutput } from "../output.js";
-import { loadRepoConfigById, resolveRepoId, fetchLocalJson } from "../system.js";
+import { ServiceApiError, loadRepoConfigById, resolveRepoId, fetchLocalJson } from "../system.js";
+import { buildQueueSummary } from "../../watch/dashboard-model.js";
 async function readQueueSnapshot(config, eventLimit) {
     try {
         const query = new URLSearchParams({ eventLimit: String(eventLimit) });
         const snapshot = await fetchLocalJson(config.repoId, `/queue/watch?${query.toString()}`);
-        return { source: "service", snapshot };
+        return { kind: "snapshot", source: "service", snapshot };
     }
-    catch {
+    catch (error) {
+        if (error instanceof ServiceApiError && error.code === "repo_initializing") {
+            return { kind: "repo_unavailable", state: "initializing", message: error.message };
+        }
+        if (error instanceof ServiceApiError && error.code === "repo_init_failed") {
+            return { kind: "repo_unavailable", state: "failed", message: error.message };
+        }
         const store = new SqliteStore(config.database.path);
         try {
             const entries = store.listAll(config.repoId);
             return {
+                kind: "snapshot",
                 source: "database",
                 snapshot: {
                     repoId: config.repoId,
                     repoFullName: config.repoFullName,
                     baseBranch: config.baseBranch,
-                    summary: buildSummary(entries),
+                    githubPolicy: {
+                        requiredChecks: [],
+                        fetchedAt: null,
+                        lastRefreshReason: null,
+                        lastRefreshChanged: null,
+                    },
+                    summary: buildQueueSummary(entries),
                     runtime: {
                         tickInProgress: false,
                         lastTickStartedAt: null,
@@ -47,10 +60,18 @@ function firstLine(text) {
     return line ? line : null;
 }
 export function formatQueueStatusText(source, snapshot) {
+    const githubPolicy = snapshot.githubPolicy ?? {
+        requiredChecks: [],
+        fetchedAt: null,
+        lastRefreshReason: null,
+        lastRefreshChanged: null,
+    };
     return [
         `Repo: ${snapshot.repoId} (${snapshot.repoFullName})`,
         `Source: ${source}`,
         `Base branch: ${snapshot.baseBranch}`,
+        `GitHub required checks: ${githubPolicy.requiredChecks.length > 0 ? githubPolicy.requiredChecks.join(", ") : "(none)"}`,
+        ...(githubPolicy.fetchedAt ? [`GitHub policy fetched: ${githubPolicy.fetchedAt}`] : []),
         `Active entries: ${snapshot.summary.active}`,
         `Queued: ${snapshot.summary.queued}  preparing: ${snapshot.summary.preparingHead}  validating: ${snapshot.summary.validating}  merging: ${snapshot.summary.merging}`,
         `Merged: ${snapshot.summary.merged}  evicted: ${snapshot.summary.evicted}  dequeued: ${snapshot.summary.dequeued}`,
@@ -64,6 +85,7 @@ export function formatQueueStatusText(source, snapshot) {
         ...(snapshot.queueBlock
             ? [
                 `Queue blocked: ${snapshot.queueBlock.reason} on ${snapshot.queueBlock.baseBranch}${snapshot.queueBlock.baseSha ? ` @ ${snapshot.queueBlock.baseSha.slice(0, 8)}` : ""}`,
+                `Missing required: ${snapshot.queueBlock.missingRequiredChecks.length > 0 ? snapshot.queueBlock.missingRequiredChecks.join(", ") : "(none)"}`,
                 `Base failures: ${snapshot.queueBlock.failingChecks.length > 0 ? snapshot.queueBlock.failingChecks.map((check) => check.name).join(", ") : "(none)"}`,
                 ...(snapshot.queueBlock.pendingChecks.length > 0
                     ? [`Base pending: ${snapshot.queueBlock.pendingChecks.map((check) => check.name).join(", ")}`]
@@ -127,7 +149,27 @@ export async function handleQueue(parsed, stdout) {
     const { config } = loadRepoConfigById(repoId);
     if (subcommand === "status") {
         const eventLimit = parseIntegerFlag(parsed.flags.get("events"), "--events") ?? 20;
-        const { source, snapshot } = await readQueueSnapshot(config, eventLimit);
+        const result = await readQueueSnapshot(config, eventLimit);
+        if (result.kind === "repo_unavailable") {
+            if (parsed.flags.get("json") === true) {
+                writeOutput(stdout, formatJson({
+                    repoId: config.repoId,
+                    repoFullName: config.repoFullName,
+                    source: "service",
+                    state: result.state,
+                    error: result.message,
+                }));
+                return 0;
+            }
+            writeOutput(stdout, [
+                `Repo: ${config.repoId} (${config.repoFullName})`,
+                "Source: service",
+                `State: ${result.state}`,
+                result.message,
+            ].join("\n") + "\n");
+            return 0;
+        }
+        const { source, snapshot } = result;
         const payload = { source, ...snapshot };
         if (parsed.flags.get("json") === true) {
             writeOutput(stdout, formatJson(payload));

package/dist/cli/commands/repos.js

@@ -23,7 +23,6 @@ export async function handleRepos(parsed, stdout) {
         repoId: config.repoId,
         repoFullName: config.repoFullName,
         baseBranch: config.baseBranch,
-        requiredChecks: config.requiredChecks,
         admissionLabel: config.admissionLabel,
         mergeQueueCheckName: config.mergeQueueCheckName,
         configPath,
@@ -40,7 +39,6 @@ export async function handleRepos(parsed, stdout) {
         `GitHub repo: ${config.repoFullName}`,
         `Config path: ${configPath}`,
         `Base branch: ${config.baseBranch}`,
-        `Required checks: ${config.requiredChecks.length > 0 ? config.requiredChecks.join(", ") : "(any green check)"}`,
         `Admission label: ${config.admissionLabel}`,
         `Queue eviction check: ${config.mergeQueueCheckName}`,
         webhookUrl ? `Webhook URL: ${webhookUrl}` : undefined,

package/dist/cli/help.js

@@ -15,7 +15,7 @@ function rootHelpText() {
         "  5. merge-steward queue status --repo <id>",
         "",
         "Everyday commands:",
-        "  repo attach <owner/repo> [--base-branch <branch>] [--required-check <checks>] [--label <label>] [--refresh] [--json]",
+        "  repo attach <owner/repo> [--base-branch <branch>] [--label <label>] [--refresh] [--json]",
         "                                                          Create or update a repo config, auto-discover GitHub defaults, and restart the service",
         "  repo list [--json]                                     List attached repositories",
         "  repo show <id> [--json]                                Show one repo config",
@@ -56,11 +56,10 @@ function repoHelpText() {
         "",
         "Options for `repo attach`:",
         "  --base-branch <branch>       Base branch to land into (default: main)",
-        "  --required-check <checks>    Comma-separated required check names",
         "  --label <label>              Admission label (default: queue)",
         "  --merge-queue-check-name <name>",
         "                               Eviction check run name (default: merge-steward/queue)",
-        "  --refresh                    Re-discover base branch and required checks from GitHub",
+        "  --refresh                    Re-discover the base branch from GitHub",
         "  --json                       Emit structured JSON",
         "",
         "Compatibility aliases:",

package/dist/cli/system.d.ts

@@ -1,6 +1,6 @@
 import { type StewardConfig } from "../config.ts";
 import { parseHomeConfigObject } from "../steward-home.ts";
-import type { ServiceGitHubAuthStatus, ServiceGitHubDiscoverResponse, ServiceGitHubRepoAccessResponse } from "../admin-types.ts";
+import type { ServiceHealthResponse, ServiceGitHubAuthStatus, ServiceGitHubDiscoverResponse, ServiceGitHubRepoAccessResponse } from "../admin-types.ts";
 import type { ParsedArgs, HelpTopic, CommandResult, CommandRunner } from "./types.ts";
 export declare function readEnvFile(filePath: string): Record<string, string>;
 export declare function getHomeEnv(): Record<string, string | undefined>;
@@ -12,7 +12,6 @@ export declare function listRepoConfigs(): Array<{
     repoId: string;
     repoFullName: string;
     baseBranch: string;
-    requiredChecks: string[];
     admissionLabel: string;
     mergeQueueCheckName: string;
     port: number;
@@ -36,6 +35,11 @@ export declare function runSystemctl(runCommand: CommandRunner, args: string[]):
     result: CommandResult;
 }>;
 export declare function getGatewayBaseUrl(): string;
+export declare class ServiceApiError extends Error {
+    readonly status?: number | undefined;
+    readonly code?: string | undefined;
+    constructor(message: string, status?: number | undefined, code?: string | undefined);
+}
 export declare function fetchGatewayJson<T>(relativePath: string, options?: {
     method?: string;
     body?: unknown;
@@ -44,6 +48,7 @@ export declare function fetchServiceHealthStatus(): Promise<{
     reachable: true;
     ok: boolean;
     status: number;
+    health?: ServiceHealthResponse;
 } | {
     reachable: false;
     error: string;

package/dist/cli/system.js

@@ -62,7 +62,6 @@ export function listRepoConfigs() {
             repoId: config.repoId,
             repoFullName: config.repoFullName,
             baseBranch: config.baseBranch,
-            requiredChecks: config.requiredChecks,
             admissionLabel: config.admissionLabel,
             mergeQueueCheckName: config.mergeQueueCheckName,
             port: config.server.port,
@@ -165,6 +164,16 @@ export function getGatewayBaseUrl() {
     const port = homeConfig.server.gateway_port ?? (homeConfig.server.port_base - 1);
     return `http://${bind}:${port}`;
 }
+export class ServiceApiError extends Error {
+    status;
+    code;
+    constructor(message, status, code) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.name = "ServiceApiError";
+    }
+}
 async function requestGatewayJson(url, options) {
     const response = await fetch(url, {
         method: options?.method ?? "GET",
@@ -177,7 +186,7 @@ async function requestGatewayJson(url, options) {
         try {
             const payload = JSON.parse(text);
             if (typeof payload.error === "string" && payload.error) {
-                throw new Error(payload.error);
+                throw new ServiceApiError(payload.error, response.status, payload.code);
             }
         }
         catch (error) {
@@ -199,8 +208,10 @@ export async function fetchServiceHealthStatus() {
             signal: AbortSignal.timeout(2_000),
         });
         let ok = response.ok;
+        let health;
         try {
             const body = await response.json();
+            health = body;
             if (typeof body.ok === "boolean") {
                 ok = response.ok && body.ok;
             }
@@ -212,6 +223,7 @@ export async function fetchServiceHealthStatus() {
             reachable: true,
             ok,
             status: response.status,
+            ...(health ? { health } : {}),
         };
     }
     catch (error) {

package/dist/config.d.ts

@@ -9,7 +9,6 @@ export declare const stewardConfigSchema: z.ZodObject<{
     maxRetries: z.ZodDefault<z.ZodNumber>;
     flakyRetries: z.ZodDefault<z.ZodNumber>;
     speculativeDepth: z.ZodDefault<z.ZodNumber>;
-    requiredChecks: z.ZodDefault<z.ZodArray<z.ZodString>>;
     pollIntervalMs: z.ZodDefault<z.ZodNumber>;
     server: z.ZodDefault<z.ZodObject<{
         bind: z.ZodDefault<z.ZodString>;

package/dist/config.js

@@ -15,7 +15,6 @@ export const stewardConfigSchema = z.object({
     flakyRetries: z.number().int().min(0).default(1),
     /** Max speculative branches to maintain in parallel. 1 = serial mode. */
     speculativeDepth: z.number().int().min(1).default(10),
-    requiredChecks: z.array(z.string()).default([]),
     pollIntervalMs: z.number().int().min(1000).default(30_000),
     server: z.object({
         bind: z.string().default("127.0.0.1"),

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

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

package/dist/github/actions-runner.js

@@ -10,10 +10,10 @@ function normalizeCheckName(name) {
  */
 export class GitHubActionsRunner {
     repoFullName;
-    requiredChecks;
-    constructor(repoFullName, requiredChecks = []) {
+    getRequiredChecks;
+    constructor(repoFullName, getRequiredChecks = () => []) {
         this.repoFullName = repoFullName;
-        this.requiredChecks = requiredChecks;
+        this.getRequiredChecks = getRequiredChecks;
     }
     async triggerRun(_branch, sha) {
         // CI is triggered by the push. Return the SHA as the poll key.
@@ -32,8 +32,9 @@ export class GitHubActionsRunner {
             const checkRuns = JSON.parse(result.stdout);
             if (checkRuns.length === 0)
                 return "pending";
-            const normalizedRequired = this.requiredChecks.map(normalizeCheckName);
-            const relevant = this.requiredChecks.length > 0
+            const requiredChecks = this.getRequiredChecks();
+            const normalizedRequired = requiredChecks.map(normalizeCheckName);
+            const relevant = requiredChecks.length > 0
                 ? checkRuns.filter((c) => normalizedRequired.includes(normalizeCheckName(c.name)))
                 : checkRuns;
             if (relevant.length === 0)

package/dist/github-policy.d.ts

@@ -0,0 +1,39 @@
+import type { Logger } from "pino";
+import type { DiscoveredRepoSettings } from "./github-repo-discovery.ts";
+export interface GitHubPolicySnapshot {
+    requiredChecks: string[];
+    fetchedAt: string | null;
+    lastRefreshReason: string | null;
+    lastRefreshChanged: boolean | null;
+}
+export interface GitHubPolicyRefreshResult {
+    attempted: boolean;
+    changed: boolean;
+    previousRequiredChecks: string[];
+    requiredChecks: string[];
+    fetchedAt: string | null;
+    skippedReason?: string | undefined;
+}
+interface GitHubPolicyCacheOptions {
+    repoFullName: string;
+    initialRequiredChecks: string[];
+    logger: Logger;
+    refreshPolicy(): Promise<DiscoveredRepoSettings>;
+    issueRefreshCooldownMs?: number;
+}
+export declare class GitHubPolicyCache {
+    private readonly options;
+    private requiredChecks;
+    private fetchedAt;
+    private lastIssueRefreshAt;
+    private readonly issueRefreshCooldownMs;
+    private lastRefreshReason;
+    private lastRefreshChanged;
+    constructor(options: GitHubPolicyCacheOptions);
+    getSnapshot(): GitHubPolicySnapshot;
+    getRequiredChecks(): string[];
+    refreshFromWebhook(reason: string): Promise<GitHubPolicyRefreshResult>;
+    refreshOnIssue(reason: string): Promise<GitHubPolicyRefreshResult>;
+    private refresh;
+}
+export {};

package/dist/github-policy.js

@@ -0,0 +1,78 @@
+function normalizeChecks(values) {
+    return [...new Set(values.map((value) => value.trim()).filter(Boolean))]
+        .sort((left, right) => left.localeCompare(right));
+}
+function equalChecks(left, right) {
+    if (left.length !== right.length) {
+        return false;
+    }
+    return left.every((value, index) => value === right[index]);
+}
+export class GitHubPolicyCache {
+    options;
+    requiredChecks;
+    fetchedAt;
+    lastIssueRefreshAt = 0;
+    issueRefreshCooldownMs;
+    lastRefreshReason = null;
+    lastRefreshChanged = null;
+    constructor(options) {
+        this.options = options;
+        this.requiredChecks = normalizeChecks(options.initialRequiredChecks);
+        this.fetchedAt = new Date().toISOString();
+        this.issueRefreshCooldownMs = options.issueRefreshCooldownMs ?? 5 * 60_000;
+    }
+    getSnapshot() {
+        return {
+            requiredChecks: [...this.requiredChecks],
+            fetchedAt: this.fetchedAt,
+            lastRefreshReason: this.lastRefreshReason,
+            lastRefreshChanged: this.lastRefreshChanged,
+        };
+    }
+    getRequiredChecks() {
+        return [...this.requiredChecks];
+    }
+    async refreshFromWebhook(reason) {
+        return await this.refresh(reason, { force: true, issueTriggered: false });
+    }
+    async refreshOnIssue(reason) {
+        const now = Date.now();
+        if (now - this.lastIssueRefreshAt < this.issueRefreshCooldownMs) {
+            return {
+                attempted: false,
+                changed: false,
+                previousRequiredChecks: [...this.requiredChecks],
+                requiredChecks: [...this.requiredChecks],
+                fetchedAt: this.fetchedAt,
+                skippedReason: "cooldown",
+            };
+        }
+        this.lastIssueRefreshAt = now;
+        return await this.refresh(reason, { force: false, issueTriggered: true });
+    }
+    async refresh(reason, options) {
+        const previousRequiredChecks = [...this.requiredChecks];
+        const discovered = await this.options.refreshPolicy();
+        const nextRequiredChecks = normalizeChecks(discovered.requiredChecks);
+        const changed = !equalChecks(previousRequiredChecks, nextRequiredChecks);
+        this.requiredChecks = nextRequiredChecks;
+        this.fetchedAt = new Date().toISOString();
+        this.lastRefreshReason = reason;
+        this.lastRefreshChanged = changed;
+        this.options.logger.info({
+            repoFullName: this.options.repoFullName,
+            reason,
+            changed,
+            requiredChecks: this.requiredChecks,
+            policyRefreshSource: options.issueTriggered ? "issue" : (options.force ? "webhook" : "manual"),
+        }, "Refreshed GitHub protection policy");
+        return {
+            attempted: true,
+            changed,
+            previousRequiredChecks,
+            requiredChecks: [...this.requiredChecks],
+            fetchedAt: this.fetchedAt,
+        };
+    }
+}