merge-steward 0.9.4 → 0.9.6

package/README.md

@@ -1,18 +1,30 @@
 # merge-steward
 
-Serial merge queue service. Rebases PRs onto main one at a time, waits for CI, and merges when green. Evicts on failure and reports incidents via GitHub check runs.
+Speculative merge queue service. It admits approved PRs whose required checks
+are green, builds cumulative speculative branches, waits for CI on those exact
+integrated SHAs, and then fast-forwards `main` to the tested result. On
+failure, it evicts with a durable incident record and GitHub check run.
 
-Fully independent of PatchRelay. Communicates through GitHub — PRs, labels, check runs, branches.
+Fully independent of PatchRelay. Communicates through GitHub — PRs, reviews,
+checks, labels, branches.
+
+Shared protocol:
+
+- [../../docs/design-docs/pr-automation-loop.md](../../docs/design-docs/pr-automation-loop.md)
 
 ## How it works
 
-1. A PR gets the `queue` label (manually, by PatchRelay, or by any automation)
-2. The steward sees the label via GitHub webhook
-3. If the PR is approved and CI is green, it enters the queue
-4. The steward processes the queue head: fetch → rebase onto main → push → wait for CI → merge
-5. On failure: retry (gated on base SHA change), then evict with a durable incident record and GitHub check run
-6. PatchRelay (or any agent) sees the check run failure and can fix the branch
-7. When the branch is fixed and CI passes again, adding the `queue` label re-admits it
+1. A PR becomes eligible when GitHub says it is approved and its required checks are green
+2. The steward notices that through webhook wakeups or startup/reconcile scans
+3. It admits the PR into the queue; the optional `queue` label is just an operator-friendly nudge, not the sole trigger
+4. The steward builds a speculative branch:
+   - head of queue: `main + PR`
+   - downstream entries: cumulative specs like `main + A + B`
+5. CI runs on that speculative SHA
+6. If the queue head's speculative SHA is still a fast-forward from current `main`, the steward pushes that exact SHA to `main`
+7. On failure: retry (gated on base SHA change), then evict with a durable incident record and GitHub check run
+8. PatchRelay (or any agent) sees the check run failure and can fix the branch
+9. When the branch is fixed and CI passes again, the PR can be re-admitted
 
 ## Setup
 
@@ -46,6 +58,12 @@ 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.
 
+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
+merge gate. Steward will naturally follow whatever required checks the repo
+configuration uses, but its primary admission gate is still GitHub's formal
+review state plus those required checks.
+
 Validate the setup:
 
 ```bash
@@ -90,6 +108,20 @@ In practice, use:
 
 When GitHub App auth is configured, Merge Steward mints short-lived installation tokens and uses them for both `gh` API calls and `git clone/fetch/push` over HTTPS. In multi-repo setups it resolves the installation per repository, so repos in different GitHub App installations can still coexist.
 
+Recommended GitHub App repository permissions:
+
+- `Contents: Read and write`
+- `Pull requests: Read and write`
+- `Checks: Read and write`
+- `Metadata: Read-only`
+- `Administration: Read-only`
+
+`Contents: Read and write` is the important merge-path permission because the
+steward lands tested speculative SHAs by fast-forward pushing `main`.
+`Administration: Read-only` is not required for merging itself, but it lets the
+doctor and attach/refresh flows discover branch rules and required checks
+without falling back to a local `gh` user token.
+
 The machine-level env files created by `merge-steward init` are:
 
 - `~/.config/merge-steward/runtime.env`
@@ -135,7 +167,7 @@ The CLI is a thin local client and does not need direct access to secret credent
 | `flakyRetries` | CI-only retries before counting toward maxRetries |
 | `requiredChecks` | Check names that must pass for admission (empty = any green) |
 | `pollIntervalMs` | Reconciliation loop interval |
-| `admissionLabel` | GitHub label that triggers queue admission |
+| `admissionLabel` | Optional GitHub label used as a manual/operator admission nudge |
 | `mergeQueueCheckName` | GitHub check run name emitted on eviction |
 
 `attach` discovers these values from GitHub when possible:
@@ -157,6 +189,16 @@ Configure one webhook on the repository pointing to the steward:
 
 The steward uses a single multi-repo webhook endpoint and routes events by `repository.full_name`.
 
+It can wake up on:
+
+- PR label changes
+- review approvals
+- successful check-suite completion
+- pushes to the base branch
+
+Even without a webhook, startup and periodic reconcile will still scan open PRs
+and admit anything that already satisfies the gate.
+
 ### Running
 
 ```bash
@@ -248,6 +290,22 @@ queued → preparing_head → validating → merging → merged
 - **evicted**: failed after retry budget, incident created
 - **dequeued**: manually removed
 
+## Merge Gate
+
+For the steward path, the real gate is:
+
+- GitHub says the PR review state is approved
+- the configured required checks are green
+- the steward's speculative integrated branch also passes CI
+
+`review-quill/verdict` only matters if you choose to include it in the repo's
+required checks.
+
+GitHub branch protection is still useful as defense in depth, but steward does
+not merge by pressing GitHub's merge button. It fast-forwards `main` to the
+already-tested speculative SHA, so successful queue merges also depend on the
+steward App being allowed to push that result to the protected branch.
+
 ## Interaction with PatchRelay
 
 The steward and PatchRelay are independent services that communicate through GitHub:
@@ -263,7 +321,7 @@ Neither service calls the other's API. GitHub is the shared bus.
 ## Current scope
 
 What's implemented:
-- **Speculative execution**: cumulative branches (`main+A`, `main+A+B`, `main+A+B+C`) tested in parallel. Configurable depth (default 3, set `speculativeDepth: 1` for serial mode).
+- **Speculative execution**: cumulative branches (`main+A`, `main+A+B`, `main+A+B+C`) tested in parallel. Configurable depth (default 10, set `speculativeDepth: 1` for serial mode).
 - **Speculative consistency**: when head merges, downstream entries that already passed don't re-test.
 - **Cascade invalidation**: when mid-chain entry fails, downstream speculative branches are rebuilt without it.
 - Non-spinning conflict retry: gated on base SHA change

package/dist/admin-types.d.ts

@@ -12,6 +12,18 @@ export interface ServiceGitHubDiscoverResponse {
     ok: true;
     discovery: DiscoveredRepoSettings;
 }
+export interface ServiceGitHubRepoAccessResponse {
+    ok: true;
+    repoFullName: string;
+    baseBranch: string;
+    permissions: {
+        contents: "none" | "read" | "write";
+        pull: boolean;
+        push: boolean;
+        admin: boolean;
+    };
+    branchProtected: boolean;
+}
 export interface ServiceErrorResponse {
     ok: false;
     error: string;

package/dist/cli/args.js

@@ -63,6 +63,20 @@ export function validateFlags(parsed) {
         case "repos":
             assertKnownFlags(parsed, "repos", ["json"]);
             return;
+        case "repo":
+            switch (subcommand) {
+                case undefined:
+                case "list":
+                case "show":
+                    assertKnownFlags(parsed, "repo", ["json"]);
+                    return;
+                case "attach":
+                    assertKnownFlags(parsed, "repo", ["base-branch", "required-check", "label", "merge-queue-check-name", "refresh", "json"]);
+                    return;
+                default:
+                    assertKnownFlags(parsed, "repo", []);
+                    return;
+            }
         case "service":
             switch (subcommand) {
                 case "install":

package/dist/cli/commands/doctor.js

@@ -3,9 +3,9 @@ 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, getRepoConfigPath, getSystemdUnitPath, } from "../../runtime-paths.js";
+import { getDefaultConfigPath, getDefaultRepoConfigDir, getDefaultRuntimeEnvPath, getDefaultServiceEnvPath, getDefaultStateDir, getSystemdUnitPath, } from "../../runtime-paths.js";
 import { formatJson, writeOutput } from "../output.js";
-import { fetchServiceGitHubAuthStatus, fetchServiceRepoDiscovery, getHomeEnv } from "../system.js";
+import { fetchServiceGitHubAuthStatus, fetchServiceRepoAccess, fetchServiceRepoDiscovery, getHomeEnv, loadRepoConfigById, } from "../system.js";
 function checkPath(scope, targetPath, writable = false) {
     if (!existsSync(targetPath)) {
         return { status: "fail", scope, message: `Missing path: ${targetPath}` };
@@ -35,6 +35,33 @@ async function checkExecutable(scope, command) {
     }
     return { status: "fail", scope, message: `${command} is not available in PATH` };
 }
+function runGhApiJson(pathArg) {
+    const result = spawnSync("gh", ["api", pathArg], { encoding: "utf8" });
+    if (result.status !== 0) {
+        throw new Error(result.stderr.trim() || result.stdout.trim() || `gh api ${pathArg} failed`);
+    }
+    return JSON.parse(result.stdout);
+}
+function discoverRepoSettingsViaGhCli(repoFullName, branch) {
+    const repo = runGhApiJson(`repos/${repoFullName}`);
+    const protection = runGhApiJson(`repos/${repoFullName}/branches/${branch}/protection`);
+    const requiredChecks = new Set();
+    for (const context of protection.required_status_checks?.contexts ?? []) {
+        const trimmed = context?.trim();
+        if (trimmed)
+            requiredChecks.add(trimmed);
+    }
+    for (const check of protection.required_status_checks?.checks ?? []) {
+        const trimmed = check.context?.trim();
+        if (trimmed)
+            requiredChecks.add(trimmed);
+    }
+    return {
+        defaultBranch: repo.default_branch?.trim() || branch,
+        branch,
+        requiredChecks: [...requiredChecks].sort((left, right) => left.localeCompare(right)),
+    };
+}
 export async function handleDoctor(parsed, stdout) {
     const repoId = typeof parsed.flags.get("repo") === "string" ? String(parsed.flags.get("repo")) : undefined;
     const checks = [];
@@ -109,13 +136,24 @@ export async function handleDoctor(parsed, stdout) {
     }
     let repoConfigPath;
     if (repoId) {
-        repoConfigPath = getRepoConfigPath(repoId);
-        if (!existsSync(repoConfigPath)) {
-            checks.push({ status: "fail", scope: `repo:${repoId}`, message: `Repo config not found: ${repoConfigPath}` });
+        let loaded;
+        try {
+            loaded = loadRepoConfigById(repoId);
+            repoConfigPath = loaded.configPath;
+        }
+        catch (error) {
+            checks.push({
+                status: "fail",
+                scope: `repo:${repoId}`,
+                message: error instanceof Error ? error.message : String(error),
+            });
+        }
+        if (!loaded) {
+            // already reported above
         }
         else {
             try {
-                const config = loadConfig(repoConfigPath);
+                const config = loaded.config;
                 mkdirSync(path.dirname(config.database.path), { recursive: true });
                 mkdirSync(path.dirname(config.clonePath), { recursive: true });
                 checks.push({ status: "pass", scope: `repo:${repoId}`, message: `Repo config is valid for ${config.repoFullName}` });
@@ -128,8 +166,22 @@ export async function handleDoctor(parsed, stdout) {
                 checks.push(checkPath(`repo:${repoId}:clone-parent`, path.dirname(config.clonePath), true));
                 if (serviceGitHubStatus) {
                     try {
-                        const response = await fetchServiceRepoDiscovery(config.repoFullName, { baseBranch: config.baseBranch });
-                        const discovered = response.discovery;
+                        let discoveredSource;
+                        let discovered;
+                        try {
+                            const response = await fetchServiceRepoDiscovery(config.repoFullName, { baseBranch: config.baseBranch });
+                            discovered = response.discovery;
+                            discoveredSource = "service";
+                        }
+                        catch (error) {
+                            discovered = discoverRepoSettingsViaGhCli(config.repoFullName, config.baseBranch);
+                            discoveredSource = "gh";
+                            checks.push({
+                                status: "warn",
+                                scope: `repo:${repoId}:github-discovery`,
+                                message: `Service discovery failed, used local gh fallback: ${error instanceof Error ? error.message : String(error)}`,
+                            });
+                        }
                         checks.push({
                             status: discovered.defaultBranch === config.baseBranch ? "pass" : "warn",
                             scope: `repo:${repoId}:github-default-branch`,
@@ -139,24 +191,49 @@ export async function handleDoctor(parsed, stdout) {
                         });
                         const configuredChecks = normalizeCheckList(config.requiredChecks);
                         const discoveredChecks = normalizeCheckList(discovered.requiredChecks);
-                        const checksMatch = configuredChecks.length === discoveredChecks.length
-                            && configuredChecks.every((value, index) => value === discoveredChecks[index]);
+                        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 ? "pass" : "warn",
+                            status: checksMatch || localSuperset ? "pass" : "warn",
                             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}`)
-                                : `Local required checks [${configuredChecks.join(", ") || "(none)"}] differ from GitHub [${discoveredChecks.join(", ") || "(none)"}] 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)" : ""}`,
                         });
-                        for (const warning of discovered.warnings) {
+                        for (const warning of discovered.warnings ?? []) {
                             checks.push({
                                 status: "warn",
                                 scope: `repo:${repoId}:github-discovery`,
                                 message: warning,
                             });
                         }
+                        try {
+                            const access = await fetchServiceRepoAccess(config.repoFullName, { baseBranch: config.baseBranch });
+                            checks.push({
+                                status: access.permissions.push ? "pass" : "fail",
+                                scope: `repo:${repoId}:github-push-access`,
+                                message: access.permissions.push
+                                    ? access.branchProtected
+                                        ? `Steward App has Contents:${access.permissions.contents} for ${config.repoFullName}; ${config.baseBranch} is protected, so final fast-forward pushes still depend on branch rules allowing the App`
+                                        : `Steward App has Contents:${access.permissions.contents} for ${config.repoFullName}`
+                                    : `Steward App does not have Contents:write for ${config.repoFullName}; queue merges to ${config.baseBranch} will fail`,
+                            });
+                        }
+                        catch (error) {
+                            checks.push({
+                                status: "warn",
+                                scope: `repo:${repoId}:github-push-access`,
+                                message: `Could not verify steward push access: ${error instanceof Error ? error.message : String(error)}`,
+                            });
+                        }
                     }
                     catch (error) {
                         checks.push({

package/dist/cli/commands/queue.d.ts

@@ -1,2 +1,4 @@
+import { type QueueWatchSnapshot } from "../../types.ts";
 import type { ParsedArgs, Output } from "../types.ts";
+export declare function formatQueueStatusText(source: "service" | "database", snapshot: QueueWatchSnapshot): string;
 export declare function handleQueue(parsed: ParsedArgs, stdout: Output): Promise<number>;

package/dist/cli/commands/queue.js

@@ -1,6 +1,6 @@
 import { SqliteStore } from "../../db/sqlite-store.js";
-import { getRepoConfigPath } from "../../runtime-paths.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";
@@ -40,12 +40,57 @@ async function readQueueSnapshot(config, eventLimit) {
         }
     }
 }
+function firstLine(text) {
+    if (!text)
+        return null;
+    const line = text.split(/\r?\n/, 1)[0]?.trim();
+    return line ? line : null;
+}
+export function formatQueueStatusText(source, snapshot) {
+    return [
+        `Repo: ${snapshot.repoId} (${snapshot.repoFullName})`,
+        `Source: ${source}`,
+        `Base branch: ${snapshot.baseBranch}`,
+        `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}`,
+        snapshot.summary.headPrNumber ? `Head PR: #${snapshot.summary.headPrNumber}` : "Head PR: none",
+        ...(snapshot.runtime.lastTickOutcome === "failed"
+            ? [
+                "Last tick: failed",
+                ...(firstLine(snapshot.runtime.lastTickError) ? [`Last error: ${firstLine(snapshot.runtime.lastTickError)}`] : []),
+            ]
+            : []),
+        ...(snapshot.queueBlock
+            ? [
+                `Queue blocked: ${snapshot.queueBlock.reason} on ${snapshot.queueBlock.baseBranch}${snapshot.queueBlock.baseSha ? ` @ ${snapshot.queueBlock.baseSha.slice(0, 8)}` : ""}`,
+                `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(", ")}`]
+                    : []),
+            ]
+            : []),
+        "",
+        "Entries:",
+        ...(snapshot.entries.length > 0
+            ? snapshot.entries.map((entry) => `- #${entry.prNumber} ${entry.status} pos=${entry.position} branch=${entry.branch}`)
+            : ["- (none)"]),
+    ].join("\n") + "\n";
+}
 function findEntryForInspect(store, repoId, options) {
     if (options.entryId) {
         return store.getEntry(options.entryId);
     }
     if (options.prNumber !== undefined) {
-        return store.listAll(repoId).find((entry) => entry.prNumber === options.prNumber);
+        const matches = store.listAll(repoId).filter((entry) => entry.prNumber === options.prNumber);
+        matches.sort((left, right) => {
+            const leftActive = TERMINAL_STATUSES.includes(left.status) ? 0 : 1;
+            const rightActive = TERMINAL_STATUSES.includes(right.status) ? 0 : 1;
+            if (leftActive !== rightActive)
+                return rightActive - leftActive;
+            return right.position - left.position;
+        });
+        return matches[0];
     }
     return undefined;
 }
@@ -73,8 +118,9 @@ export async function handleQueue(parsed, stdout) {
     }
     if (subcommand === "watch") {
         const repoId = resolveRepoId(parsed, 2, "queue");
+        const { configPath } = loadRepoConfigById(repoId);
         const { startWatch } = await import("../../watch/index.js");
-        await startWatch(getRepoConfigPath(repoId), parseIntegerFlag(parsed.flags.get("pr"), "--pr"));
+        await startWatch(configPath, parseIntegerFlag(parsed.flags.get("pr"), "--pr"));
         return 0;
     }
     const repoId = resolveRepoId(parsed, 2, "queue");
@@ -87,29 +133,7 @@ export async function handleQueue(parsed, stdout) {
             writeOutput(stdout, formatJson(payload));
             return 0;
         }
-        writeOutput(stdout, [
-            `Repo: ${snapshot.repoId} (${snapshot.repoFullName})`,
-            `Source: ${source}`,
-            `Base branch: ${snapshot.baseBranch}`,
-            `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}`,
-            snapshot.summary.headPrNumber ? `Head PR: #${snapshot.summary.headPrNumber}` : "Head PR: none",
-            ...(snapshot.queueBlock
-                ? [
-                    `Queue blocked: ${snapshot.queueBlock.reason} on ${snapshot.queueBlock.baseBranch}${snapshot.queueBlock.baseSha ? ` @ ${snapshot.queueBlock.baseSha.slice(0, 8)}` : ""}`,
-                    `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(", ")}`]
-                        : []),
-                ]
-                : []),
-            "",
-            "Entries:",
-            ...(snapshot.entries.length > 0
-                ? snapshot.entries.map((entry) => `- #${entry.prNumber} ${entry.status} pos=${entry.position} branch=${entry.branch}`)
-                : ["- (none)"]),
-        ].join("\n") + "\n");
+        writeOutput(stdout, formatQueueStatusText(source, snapshot));
         return 0;
     }
     if (subcommand === "show") {

package/dist/cli/help.js

@@ -9,15 +9,16 @@ function rootHelpText() {
         "",
         "Happy path:",
         "  1. merge-steward init <public-base-url>",
-        "  2. merge-steward attach <owner/repo>",
+        "  2. merge-steward repo attach <owner/repo>",
         "  3. merge-steward doctor --repo <id>",
         "  4. merge-steward service status",
         "  5. merge-steward queue status --repo <id>",
         "",
         "Everyday commands:",
-        "  attach <owner/repo> [--base-branch <branch>] [--required-check <checks>] [--label <label>] [--refresh] [--json]",
+        "  repo attach <owner/repo> [--base-branch <branch>] [--required-check <checks>] [--label <label>] [--refresh] [--json]",
         "                                                          Create or update a repo config, auto-discover GitHub defaults, and restart the service",
-        "  repos [<id>] [--json]                                  List attached repositories or show one repo config",
+        "  repo list [--json]                                     List attached repositories",
+        "  repo show <id> [--json]                                Show one repo config",
         "  doctor [--repo <id>] [--json]                          Validate config, secrets, auth, and required binaries",
         "  service status [--json]                                Show systemd state",
         "  service logs [--lines <count>] [--json]                Show recent journal logs",
@@ -40,18 +41,20 @@ function rootHelpText() {
         "",
         "Command help:",
         "  merge-steward help",
-        "  merge-steward help repos",
+        "  merge-steward help repo",
         "  merge-steward help service",
         "  merge-steward help queue",
     ].join("\n");
 }
-function reposHelpText() {
+function repoHelpText() {
     return [
         "Usage:",
-        "  merge-steward attach <owner/repo> [options]",
-        "  merge-steward repos [<id>] [--json]",
+        "  merge-steward repo attach <owner/repo> [options]",
+        "  merge-steward repo attach <id> <owner/repo> [options]",
+        "  merge-steward repo list [--json]",
+        "  merge-steward repo show <id> [--json]",
         "",
-        "Options for `attach`:",
+        "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)",
@@ -60,12 +63,16 @@ function reposHelpText() {
         "  --refresh                    Re-discover base branch and required checks from GitHub",
         "  --json                       Emit structured JSON",
         "",
+        "Compatibility aliases:",
+        "  merge-steward attach ...     Alias for `merge-steward repo attach ...`",
+        "  merge-steward repos ...      Alias for `merge-steward repo list/show ...`",
+        "",
         "Examples:",
-        "  merge-steward attach owner/repo",
-        "  merge-steward attach owner/repo --refresh",
-        "  merge-steward attach owner/repo --label queue",
-        "  merge-steward repos",
-        "  merge-steward repos app",
+        "  merge-steward repo attach owner/repo",
+        "  merge-steward repo attach owner/repo --refresh",
+        "  merge-steward repo attach owner/repo --label queue",
+        "  merge-steward repo list",
+        "  merge-steward repo show app",
     ].join("\n");
 }
 function serviceHelpText() {
@@ -95,8 +102,9 @@ function queueHelpText() {
 }
 export function helpTextFor(topic) {
     switch (topic) {
+        case "repo":
         case "repos":
-            return reposHelpText();
+            return repoHelpText();
         case "service":
             return serviceHelpText();
         case "queue":

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 } from "../admin-types.ts";
+import type { 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>;
@@ -47,3 +47,6 @@ export declare function fetchServiceGitHubAuthStatus(): Promise<ServiceGitHubAut
 export declare function fetchServiceRepoDiscovery(repoFullName: string, options?: {
     baseBranch?: string;
 }): Promise<ServiceGitHubDiscoverResponse>;
+export declare function fetchServiceRepoAccess(repoFullName: string, options: {
+    baseBranch: string;
+}): Promise<ServiceGitHubRepoAccessResponse>;

package/dist/cli/system.js

@@ -70,10 +70,25 @@ export function listRepoConfigs() {
         };
     });
 }
+function findConfiguredRepoConfig(repoRef) {
+    const normalized = repoRef.trim();
+    if (!normalized)
+        return undefined;
+    return listRepoConfigs().find((repo) => (repo.repoId === normalized
+        || repo.repoFullName === normalized));
+}
 export function loadRepoConfigById(repoId) {
-    const configPath = getRepoConfigPath(repoId);
+    const exactPath = getRepoConfigPath(repoId);
+    const resolved = existsSync(exactPath)
+        ? { configPath: exactPath, repoId }
+        : findConfiguredRepoConfig(repoId);
+    const configPath = resolved?.configPath ?? exactPath;
     if (!existsSync(configPath)) {
-        throw new UsageError(`Repo config not found: ${configPath}. Run \`merge-steward attach ${repoId} <owner/repo>\` first.`, "repos");
+        const configured = listRepoConfigs();
+        const configuredHint = configured.length > 0
+            ? ` Configured repos: ${configured.map((repo) => repo.repoId).join(", ")}.`
+            : "";
+        throw new UsageError(`Repo config not found for ${repoId}: ${configPath}. Run \`merge-steward attach ${repoId} <owner/repo>\` first.${configuredHint}`, "repos");
     }
     return {
         configPath,
@@ -193,3 +208,12 @@ export async function fetchServiceRepoDiscovery(repoFullName, options) {
         },
     });
 }
+export async function fetchServiceRepoAccess(repoFullName, options) {
+    return await fetchGatewayJson("/admin/github/repo-access", {
+        method: "POST",
+        body: {
+            repoFullName,
+            baseBranch: options.baseBranch,
+        },
+    });
+}

package/dist/cli/types.d.ts

@@ -2,7 +2,7 @@ export interface ParsedArgs {
     positionals: string[];
     flags: Map<string, string | boolean>;
 }
-export type HelpTopic = "root" | "repos" | "service" | "queue";
+export type HelpTopic = "root" | "repo" | "repos" | "service" | "queue";
 export interface Output {
     write(chunk: string): boolean;
 }