merge-steward 0.14.2 → 0.15.0

package/README.md

@@ -266,6 +266,7 @@ merge-steward doctor --repo app
 merge-steward service status
 merge-steward service restart
 merge-steward dashboard
+merge-steward pr status               # from a git checkout; resolves repo + PR automatically
 merge-steward queue status --repo app
 merge-steward queue show --repo app --pr 123
 merge-steward service logs --lines 100
@@ -275,10 +276,25 @@ Use them this way:
 
 - `doctor` checks config, GitHub auth, branch rules, and required checks.
 - `dashboard` is the best live operator view across all configured projects.
+- `pr status` gives a single agent-friendly verdict on one PR (queue entry when it exists, GitHub state otherwise) with a stable exit code so scripts can chain with `&&`. Supports `--wait` to poll until a terminal state is reached.
 - `queue status` is the fastest text snapshot when you need one repo in a shell script or over SSH.
 - `queue show --pr <number>` is the most direct way to inspect one PR's queue events and incidents.
 - `service logs` helps when the queue is not reacting to webhooks, GitHub auth is failing, or reconcile ticks are erroring.
 
+### Resolving --repo and --pr from the current checkout
+
+`pr status`, `queue status`, `queue show`, and `queue reconcile` accept `--repo` and `--pr` but you can omit them when running from inside a git checkout. `merge-steward` reads `origin`'s remote URL, matches it to an attached repoId, and uses `gh pr view` to find the PR for the current branch. Pass `--cwd <path>` to resolve from a different directory.
+
+### Exit codes (pr status)
+
+| code | meaning |
+|-|-|
+| 0 | merged / approved with green required checks |
+| 2 | changes_requested / failing required checks / evicted / closed |
+| 3 | still in flight (queued, preparing, validating, merging, pending) |
+| 4 | `--wait` timed out before a terminal state was reached |
+| 1 | usage or configuration error |
+
 ### systemd
 
 ```ini

package/dist/cli/args.js

@@ -100,19 +100,28 @@ export function validateFlags(parsed) {
                     assertKnownFlags(parsed, "service", []);
                     return;
             }
+        case "pr":
+            switch (subcommand) {
+                case "status":
+                    assertKnownFlags(parsed, "root", ["repo", "pr", "cwd", "wait", "timeout", "poll", "json"]);
+                    return;
+                default:
+                    assertKnownFlags(parsed, "root", []);
+                    return;
+            }
         case "queue":
             switch (subcommand) {
                 case "dashboard":
                     assertKnownFlags(parsed, "queue", ["repo", "pr"]);
                     return;
                 case "status":
-                    assertKnownFlags(parsed, "queue", ["repo", "events", "json"]);
+                    assertKnownFlags(parsed, "queue", ["repo", "pr", "cwd", "events", "json"]);
                     return;
                 case "show":
-                    assertKnownFlags(parsed, "queue", ["repo", "entry", "pr", "events", "json"]);
+                    assertKnownFlags(parsed, "queue", ["repo", "entry", "pr", "cwd", "events", "json"]);
                     return;
                 case "reconcile":
-                    assertKnownFlags(parsed, "queue", ["repo", "json"]);
+                    assertKnownFlags(parsed, "queue", ["repo", "cwd", "json"]);
                     return;
                 default:
                     assertKnownFlags(parsed, "queue", []);

package/dist/cli/commands/pr-github.d.ts

@@ -0,0 +1,22 @@
+import type { ResolveCommandRunner } from "../resolve.ts";
+export interface PrGitHubCheck {
+    name: string;
+    status: "success" | "failure" | "pending";
+    required: boolean;
+    detailsUrl?: string;
+}
+export type PrGitHubState = "OPEN" | "CLOSED" | "MERGED";
+export type PrGitHubReviewDecision = "APPROVED" | "CHANGES_REQUESTED" | "REVIEW_REQUIRED" | "COMMENTED" | "";
+export interface PrGitHubOverview {
+    number: number;
+    branch: string;
+    headSha: string;
+    state: PrGitHubState;
+    merged: boolean;
+    reviewDecision: PrGitHubReviewDecision;
+    mergeStateStatus?: string;
+    labels: string[];
+    checks: PrGitHubCheck[];
+}
+export declare function parsePrView(raw: string): PrGitHubOverview;
+export declare function fetchPrGitHubOverview(repoFullName: string, prNumber: number, runCommand: ResolveCommandRunner): Promise<PrGitHubOverview>;

package/dist/cli/commands/pr-github.js

@@ -0,0 +1,81 @@
+function classifyCheck(node) {
+    const typename = node.__typename ?? "";
+    if (typename === "StatusContext") {
+        const state = (node.state ?? "").toUpperCase();
+        if (state === "SUCCESS" || state === "EXPECTED")
+            return "success";
+        if (state === "FAILURE" || state === "ERROR")
+            return "failure";
+        return "pending";
+    }
+    const status = (node.status ?? "").toUpperCase();
+    if (status !== "COMPLETED")
+        return "pending";
+    const conclusion = (node.conclusion ?? "").toUpperCase();
+    switch (conclusion) {
+        case "SUCCESS":
+        case "NEUTRAL":
+        case "SKIPPED":
+            return "success";
+        case "FAILURE":
+        case "CANCELLED":
+        case "TIMED_OUT":
+        case "STALE":
+        case "ACTION_REQUIRED":
+            return "failure";
+        default:
+            return "pending";
+    }
+}
+function deriveCheckName(node) {
+    if (typeof node.name === "string" && node.name)
+        return node.name;
+    if (typeof node.context === "string" && node.context)
+        return node.context;
+    return undefined;
+}
+export function parsePrView(raw) {
+    const data = JSON.parse(raw);
+    const state = (data.state ?? "OPEN").toUpperCase();
+    const reviewDecision = (data.reviewDecision ?? "").toUpperCase();
+    const labels = Array.isArray(data.labels) ? data.labels.map((label) => label.name).filter(Boolean) : [];
+    const rollup = Array.isArray(data.statusCheckRollup) ? data.statusCheckRollup : [];
+    const checks = rollup
+        .map((node) => {
+        const name = deriveCheckName(node);
+        if (!name)
+            return undefined;
+        const detailsUrl = node.detailsUrl ?? node.targetUrl;
+        return {
+            name,
+            status: classifyCheck(node),
+            required: node.isRequired === true,
+            ...(detailsUrl ? { detailsUrl } : {}),
+        };
+    })
+        .filter((c) => c !== undefined);
+    return {
+        number: data.number,
+        branch: data.headRefName,
+        headSha: data.headRefOid,
+        state,
+        merged: state === "MERGED",
+        reviewDecision,
+        ...(data.mergeStateStatus ? { mergeStateStatus: data.mergeStateStatus } : {}),
+        labels,
+        checks,
+    };
+}
+export async function fetchPrGitHubOverview(repoFullName, prNumber, runCommand) {
+    const result = await runCommand("gh", [
+        "pr", "view", String(prNumber),
+        "--repo", repoFullName,
+        "--json",
+        "number,headRefName,headRefOid,state,reviewDecision,mergeStateStatus,labels,statusCheckRollup",
+    ]);
+    if (result.exitCode !== 0) {
+        const message = result.stderr.trim() || result.stdout.trim() || `gh pr view exited with ${result.exitCode}`;
+        throw new Error(`Unable to fetch PR #${prNumber} from GitHub: ${message}`);
+    }
+    return parsePrView(result.stdout);
+}

package/dist/cli/commands/pr-status.d.ts

@@ -0,0 +1,55 @@
+import type { QueueEntry } from "../../types.ts";
+import type { Output, ParsedArgs } from "../types.ts";
+import { type ResolveCommandRunner } from "../resolve.ts";
+import { type PrGitHubOverview } from "./pr-github.ts";
+export type PrStatusKind = "merged" | "merged_outside_queue" | "queued" | "preparing_head" | "validating" | "merging" | "evicted" | "dequeued" | "closed" | "changes_requested" | "checks_failing" | "checks_pending" | "approved_clean" | "not_queued";
+export type PrStatusSource = "queue" | "github";
+export interface PrStatusReport {
+    repoId: string;
+    repoFullName: string;
+    prNumber: number;
+    source: PrStatusSource;
+    kind: PrStatusKind;
+    terminal: boolean;
+    exitCode: number;
+    reason?: string;
+    queueEntry?: QueueEntry;
+    github?: PrGitHubOverview;
+    checkedAt: string;
+}
+export declare function classifyQueueEntry(entry: QueueEntry): PrStatusReport["kind"];
+export declare function classifyGitHubOverview(overview: PrGitHubOverview): {
+    kind: PrStatusReport["kind"];
+    reason?: string;
+};
+export interface BuildReportOptions {
+    repoId: string;
+    repoFullName: string;
+    prNumber: number;
+    queueEntry?: QueueEntry | undefined;
+    github?: PrGitHubOverview | undefined;
+}
+export declare function buildPrStatusReport(options: BuildReportOptions): PrStatusReport;
+export interface HandlePrStatusOptions {
+    parsed: ParsedArgs;
+    stdout: Output;
+    resolveCommand?: ResolveCommandRunner | undefined;
+    /** For tests: inject a custom fetcher instead of shelling to `gh`. */
+    fetchGitHub?: ((repoFullName: string, prNumber: number) => Promise<PrGitHubOverview>) | undefined;
+    /** For tests: inject a clock. Defaults to Date.now. */
+    now?: (() => number) | undefined;
+    /** For tests: inject a sleep. Defaults to setTimeout. */
+    sleep?: ((ms: number) => Promise<void>) | undefined;
+}
+export interface WaitOptions {
+    timeoutMs: number;
+    pollMs: number;
+    now: () => number;
+    sleep: (ms: number) => Promise<void>;
+}
+export declare function resolveWaitOptions(parsed: ParsedArgs, overrides?: Partial<Pick<WaitOptions, "now" | "sleep">>): WaitOptions;
+export declare function waitForTerminalReport(build: () => Promise<PrStatusReport>, options: WaitOptions): Promise<{
+    report: PrStatusReport;
+    timedOut: boolean;
+}>;
+export declare function handlePrStatus(options: HandlePrStatusOptions): Promise<number>;

package/dist/cli/commands/pr-status.js

@@ -0,0 +1,272 @@
+import { SqliteStore } from "../../db/sqlite-store.js";
+import { formatJson, writeOutput } from "../output.js";
+import { ServiceApiError, fetchLocalJson, loadRepoConfigById } from "../system.js";
+import { resolvePrNumber, resolveRepo } from "../resolve.js";
+import { parseIntegerFlag } from "../args.js";
+import { fetchPrGitHubOverview } from "./pr-github.js";
+export function classifyQueueEntry(entry) {
+    switch (entry.status) {
+        case "merged": return "merged";
+        case "queued": return "queued";
+        case "preparing_head": return "preparing_head";
+        case "validating": return "validating";
+        case "merging": return "merging";
+        case "evicted": return "evicted";
+        case "dequeued": return "dequeued";
+    }
+}
+function exitCodeForKind(kind) {
+    switch (kind) {
+        case "merged":
+        case "merged_outside_queue":
+        case "approved_clean":
+            return 0;
+        case "closed":
+        case "changes_requested":
+        case "checks_failing":
+        case "evicted":
+        case "dequeued":
+            return 2;
+        case "queued":
+        case "preparing_head":
+        case "validating":
+        case "merging":
+        case "checks_pending":
+        case "not_queued":
+            return 3;
+    }
+}
+function isTerminalKind(kind) {
+    return exitCodeForKind(kind) !== 3;
+}
+export function classifyGitHubOverview(overview) {
+    if (overview.state === "MERGED" || overview.merged) {
+        return { kind: "merged_outside_queue" };
+    }
+    if (overview.state === "CLOSED") {
+        return { kind: "closed", reason: "PR is closed without merge" };
+    }
+    if (overview.reviewDecision === "CHANGES_REQUESTED") {
+        return { kind: "changes_requested", reason: "A reviewer requested changes" };
+    }
+    const requiredChecks = overview.checks.filter((c) => c.required);
+    const checkPool = requiredChecks.length > 0 ? requiredChecks : overview.checks;
+    const failing = checkPool.filter((c) => c.status === "failure").map((c) => c.name);
+    if (failing.length > 0) {
+        return { kind: "checks_failing", reason: `Failing checks: ${failing.join(", ")}` };
+    }
+    const pending = checkPool.filter((c) => c.status === "pending").map((c) => c.name);
+    if (pending.length > 0) {
+        return { kind: "checks_pending", reason: `Pending checks: ${pending.join(", ")}` };
+    }
+    if (overview.reviewDecision === "APPROVED") {
+        return { kind: "approved_clean", reason: "Approved with green checks; not admitted to queue" };
+    }
+    return { kind: "not_queued", reason: "PR is not admitted to the merge queue" };
+}
+function findEntryForPr(snapshot, prNumber) {
+    const matches = snapshot.entries.filter((entry) => entry.prNumber === prNumber);
+    if (matches.length === 0)
+        return undefined;
+    matches.sort((left, right) => {
+        const leftTerminal = ["merged", "evicted", "dequeued"].includes(left.status) ? 1 : 0;
+        const rightTerminal = ["merged", "evicted", "dequeued"].includes(right.status) ? 1 : 0;
+        if (leftTerminal !== rightTerminal)
+            return leftTerminal - rightTerminal;
+        return right.position - left.position;
+    });
+    return matches[0];
+}
+async function loadQueueEntry(config, prNumber) {
+    try {
+        const snapshot = await fetchLocalJson(config.repoId, "/queue/watch?eventLimit=1");
+        const entry = findEntryForPr(snapshot, prNumber);
+        return entry ? { kind: "found", entry, source: "service" } : { kind: "not_found" };
+    }
+    catch (error) {
+        if (error instanceof ServiceApiError) {
+            return { kind: "unavailable" };
+        }
+        const store = new SqliteStore(config.database.path);
+        try {
+            const entries = store.listAll(config.repoId).filter((entry) => entry.prNumber === prNumber);
+            if (entries.length === 0)
+                return { kind: "not_found" };
+            entries.sort((left, right) => {
+                const leftTerminal = ["merged", "evicted", "dequeued"].includes(left.status) ? 1 : 0;
+                const rightTerminal = ["merged", "evicted", "dequeued"].includes(right.status) ? 1 : 0;
+                if (leftTerminal !== rightTerminal)
+                    return leftTerminal - rightTerminal;
+                return right.position - left.position;
+            });
+            return { kind: "found", entry: entries[0], source: "database" };
+        }
+        finally {
+            store.close();
+        }
+    }
+}
+export function buildPrStatusReport(options) {
+    const checkedAt = new Date().toISOString();
+    if (options.queueEntry) {
+        const kind = classifyQueueEntry(options.queueEntry);
+        return {
+            repoId: options.repoId,
+            repoFullName: options.repoFullName,
+            prNumber: options.prNumber,
+            source: "queue",
+            kind,
+            terminal: isTerminalKind(kind),
+            exitCode: exitCodeForKind(kind),
+            queueEntry: options.queueEntry,
+            checkedAt,
+        };
+    }
+    if (options.github) {
+        const { kind, reason } = classifyGitHubOverview(options.github);
+        return {
+            repoId: options.repoId,
+            repoFullName: options.repoFullName,
+            prNumber: options.prNumber,
+            source: "github",
+            kind,
+            terminal: isTerminalKind(kind),
+            exitCode: exitCodeForKind(kind),
+            ...(reason ? { reason } : {}),
+            github: options.github,
+            checkedAt,
+        };
+    }
+    throw new Error("buildPrStatusReport requires either queueEntry or github overview");
+}
+function formatReportText(report) {
+    const lines = [
+        `Repo: ${report.repoFullName} (${report.repoId})`,
+        `PR: #${report.prNumber}`,
+        `Source: ${report.source}`,
+        `State: ${report.kind}`,
+        `Terminal: ${report.terminal ? "yes" : "no"}`,
+    ];
+    if (report.reason)
+        lines.push(`Reason: ${report.reason}`);
+    if (report.queueEntry) {
+        const entry = report.queueEntry;
+        lines.push(`Queue position: ${entry.position}`);
+        lines.push(`Branch: ${entry.branch}`);
+        lines.push(`Head SHA: ${entry.headSha}`);
+        if (entry.waitDetail)
+            lines.push(`Wait detail: ${entry.waitDetail}`);
+    }
+    if (report.github) {
+        const gh = report.github;
+        lines.push(`Review decision: ${gh.reviewDecision || "(none)"}`);
+        if (gh.mergeStateStatus)
+            lines.push(`Merge state: ${gh.mergeStateStatus}`);
+        if (gh.labels.length > 0)
+            lines.push(`Labels: ${gh.labels.join(", ")}`);
+        if (gh.checks.length > 0) {
+            const required = gh.checks.filter((c) => c.required);
+            const summary = required.length > 0 ? required : gh.checks;
+            const bySt = {
+                success: summary.filter((c) => c.status === "success").length,
+                failure: summary.filter((c) => c.status === "failure").length,
+                pending: summary.filter((c) => c.status === "pending").length,
+            };
+            lines.push(`Checks (${required.length > 0 ? "required" : "all"}): ${bySt.success} ok, ${bySt.failure} failing, ${bySt.pending} pending`);
+            for (const check of summary) {
+                lines.push(`  - [${check.status}] ${check.name}${check.required ? " (required)" : ""}`);
+            }
+        }
+    }
+    return lines.join("\n") + "\n";
+}
+const DEFAULT_WAIT_TIMEOUT_MS = 30 * 60_000;
+const MAX_WAIT_TIMEOUT_MS = 2 * 60 * 60_000;
+const MIN_WAIT_TIMEOUT_MS = 1_000;
+const DEFAULT_POLL_MS = 5_000;
+const MIN_POLL_MS = 1_000;
+const MAX_POLL_MS = 5 * 60_000;
+export function resolveWaitOptions(parsed, overrides) {
+    const timeoutSeconds = parseIntegerFlag(parsed.flags.get("timeout"), "--timeout");
+    const pollSeconds = parseIntegerFlag(parsed.flags.get("poll"), "--poll");
+    const timeoutMs = clamp(timeoutSeconds !== undefined ? timeoutSeconds * 1000 : DEFAULT_WAIT_TIMEOUT_MS, MIN_WAIT_TIMEOUT_MS, MAX_WAIT_TIMEOUT_MS);
+    const pollMs = clamp(pollSeconds !== undefined ? pollSeconds * 1000 : DEFAULT_POLL_MS, MIN_POLL_MS, MAX_POLL_MS);
+    return {
+        timeoutMs,
+        pollMs,
+        now: overrides?.now ?? (() => Date.now()),
+        sleep: overrides?.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms))),
+    };
+}
+function clamp(value, min, max) {
+    return Math.max(min, Math.min(max, value));
+}
+export async function waitForTerminalReport(build, options) {
+    const deadline = options.now() + options.timeoutMs;
+    let report = await build();
+    while (!report.terminal) {
+        const remaining = deadline - options.now();
+        if (remaining <= 0) {
+            return { report, timedOut: true };
+        }
+        const waitMs = Math.min(options.pollMs, remaining);
+        if (waitMs > 0)
+            await options.sleep(waitMs);
+        report = await build();
+    }
+    return { report, timedOut: false };
+}
+export async function handlePrStatus(options) {
+    const { parsed, stdout } = options;
+    const resolveCommand = options.resolveCommand;
+    const resolvedRepo = await resolveRepo({ parsed, helpTopic: "root", runCommand: resolveCommand });
+    const resolvedPr = await resolvePrNumber({ parsed, helpTopic: "root", runCommand: resolveCommand });
+    const { config } = loadRepoConfigById(resolvedRepo.repoId);
+    const fetchGh = options.fetchGitHub
+        ?? ((repoFullName, prNumber) => fetchPrGitHubOverview(repoFullName, prNumber, resolveCommand ?? (async () => ({
+            exitCode: 127,
+            stdout: "",
+            stderr: "no resolveCommand provided",
+        }))));
+    const buildReport = async () => {
+        const queueResult = await loadQueueEntry(config, resolvedPr.prNumber);
+        if (queueResult.kind === "found") {
+            return buildPrStatusReport({
+                repoId: resolvedRepo.repoId,
+                repoFullName: resolvedRepo.repoFullName,
+                prNumber: resolvedPr.prNumber,
+                queueEntry: queueResult.entry,
+            });
+        }
+        const overview = await fetchGh(resolvedRepo.repoFullName, resolvedPr.prNumber);
+        return buildPrStatusReport({
+            repoId: resolvedRepo.repoId,
+            repoFullName: resolvedRepo.repoFullName,
+            prNumber: resolvedPr.prNumber,
+            github: overview,
+        });
+    };
+    const shouldWait = parsed.flags.get("wait") === true || typeof parsed.flags.get("wait") === "string";
+    let report;
+    let timedOut = false;
+    if (shouldWait) {
+        const waitOptions = resolveWaitOptions(parsed, {
+            ...(options.now ? { now: options.now } : {}),
+            ...(options.sleep ? { sleep: options.sleep } : {}),
+        });
+        const result = await waitForTerminalReport(buildReport, waitOptions);
+        report = result.report;
+        timedOut = result.timedOut;
+    }
+    else {
+        report = await buildReport();
+    }
+    const payload = timedOut ? { ...report, timedOut: true } : report;
+    if (parsed.flags.get("json") === true) {
+        writeOutput(stdout, formatJson(payload));
+    }
+    else {
+        writeOutput(stdout, formatReportText(report) + (timedOut ? "Timed out waiting for terminal state.\n" : ""));
+    }
+    return timedOut ? 4 : report.exitCode;
+}

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

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

package/dist/cli/commands/queue.js

@@ -3,8 +3,15 @@ import { TERMINAL_STATUSES } from "../../types.js";
 import { UsageError } from "../types.js";
 import { parseIntegerFlag } from "../args.js";
 import { formatJson, writeOutput } from "../output.js";
-import { ServiceApiError, loadRepoConfigById, resolveRepoId, fetchLocalJson } from "../system.js";
+import { ServiceApiError, loadRepoConfigById, fetchLocalJson } from "../system.js";
+import { resolveRepo } from "../resolve.js";
 import { buildQueueSummary } from "../../watch/dashboard-model.js";
+async function resolveRepoIdWithCwdFallback(parsed, positionalIndex, resolveCommand) {
+    const positional = parsed.positionals[positionalIndex];
+    if (positional)
+        return positional;
+    return (await resolveRepo({ parsed, helpTopic: "queue", runCommand: resolveCommand })).repoId;
+}
 async function readQueueSnapshot(config, eventLimit) {
     try {
         const query = new URLSearchParams({ eventLimit: String(eventLimit) });
@@ -133,7 +140,7 @@ function readQueueEntryDetail(config, options) {
         store.close();
     }
 }
-export async function handleQueue(parsed, stdout) {
+export async function handleQueue(parsed, stdout, resolveCommand) {
     const subcommand = parsed.positionals[1];
     if (!subcommand) {
         throw new UsageError("merge-steward queue requires a subcommand.", "queue");
@@ -145,7 +152,7 @@ export async function handleQueue(parsed, stdout) {
         const { handleDashboard } = await import("./dashboard.js");
         return await handleDashboard(parsed);
     }
-    const repoId = resolveRepoId(parsed, 2, "queue");
+    const repoId = await resolveRepoIdWithCwdFallback(parsed, 2, resolveCommand);
     const { config } = loadRepoConfigById(repoId);
     if (subcommand === "status") {
         const eventLimit = parseIntegerFlag(parsed.flags.get("events"), "--events") ?? 20;

package/dist/cli/help.js

@@ -22,11 +22,27 @@ function rootHelpText() {
         "  doctor [--repo <id>] [--json]                          Validate config, secrets, auth, and required binaries",
         "  service status [--json]                                Show systemd state and local health",
         "  service logs [--lines <count>] [--json]                Show recent journal logs",
-        "  queue status --repo <id> [--json]                      Show queue summary and current entries",
-        "  queue show --repo <id> (--entry <id> | --pr <num>) [--events <count>] [--json]",
+        "  pr status [--repo <id>] [--pr <num>] [--wait] [--timeout <s>] [--poll <s>] [--json]",
+        "                                                          Classify a single PR; exit 0 terminal ok, 2 terminal failure, 3 still in flight, 4 --wait timeout",
+        "  queue status [--repo <id>] [--cwd <path>] [--json]     Show queue summary and current entries",
+        "  queue show [--repo <id>] (--entry <id> | --pr <num>) [--events <count>] [--json]",
         "                                                          Show one queue entry with events and incidents",
         "  dashboard [--repo <id>] [--pr <number>]                Open the multi-repo merge queue dashboard",
         "",
+        "Resolution:",
+        "  --repo and --pr are optional when you run the command inside a git",
+        "  checkout. Without them, merge-steward reads `origin`'s remote URL,",
+        "  matches it to an attached repoId, and uses `gh pr view` to find the",
+        "  PR for the current branch. Pass --cwd <path> to resolve from a",
+        "  specific directory instead of process.cwd().",
+        "",
+        "Exit codes (pr status):",
+        "  0  merged / approved with green required checks",
+        "  2  changes_requested / failing required checks / evicted / closed",
+        "  3  still in flight (queued, preparing, validating, merging, pending)",
+        "  4  --wait timed out before a terminal state was reached",
+        "  1  usage or configuration error",
+        "",
         "Service management:",
         "  service install [--force] [--json]                     Reinstall the systemd unit",
         "  service restart [--json]                               Reload-or-restart the service",
@@ -94,9 +110,11 @@ function queueHelpText() {
         "",
         "Commands:",
         "  dashboard [--repo <id>] [--pr <number>]            Open the multi-repo merge queue dashboard",
-        "  status --repo <id>                                 Show queue summary and entries",
-        "  show --repo <id> (--entry <id> | --pr <num>)       Show one queue entry with events and incidents",
-        "  reconcile --repo <id> [--json]                     Ask the service to reconcile immediately",
+        "  status [--repo <id>] [--cwd <path>]                Show queue summary and entries",
+        "  show [--repo <id>] (--entry <id> | --pr <num>)     Show one queue entry with events and incidents",
+        "  reconcile [--repo <id>] [--cwd <path>] [--json]    Ask the service to reconcile immediately",
+        "",
+        "--repo is inferred from `origin`'s remote in the current git checkout.",
     ].join("\n");
 }
 export function helpTextFor(topic) {

package/dist/cli/resolve.d.ts

@@ -0,0 +1,31 @@
+import type { ParsedArgs, HelpTopic } from "./types.ts";
+export interface ResolveCommandResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}
+export type ResolveCommandRunner = (command: string, args: string[], options?: {
+    cwd?: string;
+}) => Promise<ResolveCommandResult>;
+export declare function defaultResolveRunner(command: string, args: string[], options?: {
+    cwd?: string;
+}): Promise<ResolveCommandResult>;
+export type RepoRefSource = "flag" | "cwd";
+export interface ResolvedRepo {
+    repoId: string;
+    repoFullName: string;
+    source: RepoRefSource;
+}
+export interface ResolveOptions {
+    parsed: ParsedArgs;
+    runCommand?: ResolveCommandRunner | undefined;
+    cwd?: string | undefined;
+    helpTopic?: HelpTopic | undefined;
+}
+export declare function resolveRepo(options: ResolveOptions): Promise<ResolvedRepo>;
+export type PrRefSource = "flag" | "cwd";
+export interface ResolvedPr {
+    prNumber: number;
+    source: PrRefSource;
+}
+export declare function resolvePrNumber(options: ResolveOptions): Promise<ResolvedPr>;

package/dist/cli/resolve.js

@@ -0,0 +1,100 @@
+import { spawnSync } from "node:child_process";
+import { listRepoConfigs } from "./system.js";
+import { UsageError } from "./types.js";
+export function defaultResolveRunner(command, args, options) {
+    const result = spawnSync(command, args, {
+        encoding: "utf8",
+        ...(options?.cwd ? { cwd: options.cwd } : {}),
+    });
+    return Promise.resolve({
+        exitCode: result.status ?? 1,
+        stdout: result.stdout ?? "",
+        stderr: result.stderr ?? "",
+    });
+}
+function parseOwnerRepoFromRemote(remoteUrl) {
+    const trimmed = remoteUrl.trim();
+    if (!trimmed)
+        return undefined;
+    const sshMatch = trimmed.match(/^git@[^:]+:([^/]+\/[^.]+?)(?:\.git)?$/);
+    if (sshMatch?.[1])
+        return sshMatch[1];
+    const httpsMatch = trimmed.match(/^https?:\/\/[^/]+\/([^/]+\/[^/]+?)(?:\.git)?\/?$/);
+    if (httpsMatch?.[1])
+        return httpsMatch[1];
+    const sshProto = trimmed.match(/^ssh:\/\/[^/]+\/([^/]+\/[^/]+?)(?:\.git)?$/);
+    if (sshProto?.[1])
+        return sshProto[1];
+    return undefined;
+}
+async function resolveGitRemote(runCommand, cwd) {
+    const result = await runCommand("git", ["remote", "get-url", "origin"], { cwd });
+    if (result.exitCode !== 0)
+        return undefined;
+    return parseOwnerRepoFromRemote(result.stdout);
+}
+export async function resolveRepo(options) {
+    const parsed = options.parsed;
+    const helpTopic = options.helpTopic ?? "root";
+    const runCommand = options.runCommand ?? defaultResolveRunner;
+    const cwd = options.cwd ?? (typeof parsed.flags.get("cwd") === "string" ? String(parsed.flags.get("cwd")) : process.cwd());
+    const flagValue = parsed.flags.get("repo");
+    const flagString = typeof flagValue === "string" ? flagValue.trim() : "";
+    if (flagString) {
+        const match = findAttachedRepo(flagString);
+        if (!match) {
+            throw new UsageError(attachHint(flagString), helpTopic);
+        }
+        return { repoId: match.repoId, repoFullName: match.repoFullName, source: "flag" };
+    }
+    const ownerRepo = await resolveGitRemote(runCommand, cwd);
+    if (!ownerRepo) {
+        throw new UsageError("Unable to resolve a repo: pass --repo <id> or run from a git checkout with an origin remote.", helpTopic);
+    }
+    const match = findAttachedRepo(ownerRepo);
+    if (!match) {
+        throw new UsageError(attachHint(ownerRepo), helpTopic);
+    }
+    return { repoId: match.repoId, repoFullName: match.repoFullName, source: "cwd" };
+}
+function findAttachedRepo(ref) {
+    const normalized = ref.trim();
+    if (!normalized)
+        return undefined;
+    const lower = normalized.toLowerCase();
+    return listRepoConfigs().find((repo) => repo.repoId === normalized
+        || repo.repoFullName === normalized
+        || repo.repoFullName.toLowerCase() === lower);
+}
+function attachHint(ref) {
+    const attached = listRepoConfigs();
+    const attachedHint = attached.length > 0
+        ? ` Attached repos: ${attached.map((r) => r.repoId).join(", ")}.`
+        : "";
+    return `Repo ${ref} is not attached to merge-steward. Run \`merge-steward repo attach ${ref}\` first.${attachedHint}`;
+}
+export async function resolvePrNumber(options) {
+    const parsed = options.parsed;
+    const helpTopic = options.helpTopic ?? "root";
+    const runCommand = options.runCommand ?? defaultResolveRunner;
+    const cwd = options.cwd ?? (typeof parsed.flags.get("cwd") === "string" ? String(parsed.flags.get("cwd")) : process.cwd());
+    const flagValue = parsed.flags.get("pr");
+    if (typeof flagValue === "string" && flagValue.trim()) {
+        const flagNumber = parseInt(flagValue.trim(), 10);
+        if (!Number.isFinite(flagNumber) || flagNumber <= 0) {
+            throw new UsageError("--pr must be a positive integer.", helpTopic);
+        }
+        return { prNumber: flagNumber, source: "flag" };
+    }
+    const result = await runCommand("gh", ["pr", "view", "--json", "number", "-q", ".number"], { cwd });
+    if (result.exitCode !== 0) {
+        const hint = result.stderr.trim() || "no PR for the current branch";
+        throw new UsageError(`Unable to resolve PR from cwd (${hint}). Pass --pr <number>.`, helpTopic);
+    }
+    const raw = result.stdout.trim();
+    const prNumber = parseInt(raw, 10);
+    if (!Number.isFinite(prNumber) || prNumber <= 0) {
+        throw new UsageError(`\`gh pr view\` returned no PR number (got: ${JSON.stringify(raw)}). Pass --pr <number>.`, helpTopic);
+    }
+    return { prNumber, source: "cwd" };
+}

package/dist/cli/system.d.ts

@@ -1,7 +1,7 @@
 import { type StewardConfig } from "../config.ts";
 import { parseHomeConfigObject } from "../steward-home.ts";
 import type { ServiceHealthResponse, ServiceGitHubAuthStatus, ServiceGitHubDiscoverResponse, ServiceGitHubRepoAccessResponse } from "../admin-types.ts";
-import type { ParsedArgs, HelpTopic, CommandResult, CommandRunner } from "./types.ts";
+import type { CommandResult, CommandRunner } from "./types.ts";
 export declare function readEnvFile(filePath: string): Record<string, string>;
 export declare function getHomeEnv(): Record<string, string | undefined>;
 export declare function readHomeConfig(): {
@@ -22,7 +22,6 @@ export declare function loadRepoConfigById(repoId: string): {
     config: StewardConfig;
 };
 export declare function buildWebhookUrl(): string | undefined;
-export declare function resolveRepoId(parsed: ParsedArgs, positionalIndex?: number, helpTopic?: HelpTopic): string;
 export declare function defaultRunCommand(command: string, args: string[]): Promise<CommandResult>;
 export declare function formatCommandFailure(result: CommandResult, fallback: string): string;
 export declare function parseSystemctlShowOutput(raw: string): Record<string, string>;

package/dist/cli/system.js

@@ -103,17 +103,6 @@ export function buildWebhookUrl() {
     const publicBaseUrl = homeConfig.server.public_base_url;
     return publicBaseUrl ? `${publicBaseUrl.replace(/\/$/, "")}/webhooks/github` : undefined;
 }
-export function resolveRepoId(parsed, positionalIndex = 2, helpTopic = "root") {
-    const positional = parsed.positionals[positionalIndex];
-    if (positional) {
-        return positional;
-    }
-    const flagged = parsed.flags.get("repo");
-    if (typeof flagged === "string" && flagged.trim()) {
-        return flagged.trim();
-    }
-    throw new UsageError("Repo id is required.", helpTopic);
-}
 export function defaultRunCommand(command, args) {
     const result = spawnSync(command, args, {
         encoding: "utf8",

package/dist/cli/types.d.ts

@@ -16,6 +16,9 @@ export interface RunCliOptions {
     stdout?: Output;
     stderr?: Output;
     runCommand?: CommandRunner;
+    resolveCommand?: (command: string, args: string[], options?: {
+        cwd?: string;
+    }) => Promise<CommandResult>;
 }
 export declare class UsageError extends Error {
     readonly helpTopic: HelpTopic;

package/dist/cli.js

@@ -71,8 +71,16 @@ export async function runCli(argv, options) {
                 return await (await import("./cli/commands/dashboard.js")).handleDashboard(parsed);
             case "service":
                 return await (await import("./cli/commands/service.js")).handleService(parsed, stdout, runCommand);
+            case "pr": {
+                const subcommand = parsed.positionals[1];
+                if (subcommand !== "status") {
+                    throw new UsageError(`Unknown pr command: ${subcommand ?? "(none)"}. Try \`merge-steward pr status\`.`);
+                }
+                const { handlePrStatus } = await import("./cli/commands/pr-status.js");
+                return await handlePrStatus({ parsed, stdout, resolveCommand: options?.resolveCommand });
+            }
             case "queue":
-                return await (await import("./cli/commands/queue.js")).handleQueue(parsed, stdout);
+                return await (await import("./cli/commands/queue.js")).handleQueue(parsed, stdout, options?.resolveCommand);
             default:
                 throw new UsageError(`Unknown command: ${command}`);
         }

package/dist/service-runtime.d.ts

@@ -22,6 +22,8 @@ export declare class MergeStewardRuntime {
     private lastTickOutcome;
     private lastTickError;
     private currentQueueBlock;
+    private readonly waitingMainInfoAt;
+    private static readonly WAITING_MAIN_INFO_INTERVAL_MS;
     constructor(config: StewardConfig, policy: GitHubPolicyCache, store: QueueStore, git: GitOperations, ci: CIRunner, github: GitHubPRApi, eviction: EvictionReporter, specBuilder: SpeculativeBranchBuilder, logger: Logger, beforeTick?: (() => Promise<void>) | undefined);
     start(): Promise<void>;
     stop(): Promise<void>;

package/dist/service-runtime.js

@@ -17,6 +17,12 @@ export class MergeStewardRuntime {
     lastTickOutcome = "idle";
     lastTickError = null;
     currentQueueBlock = null;
+    // Per-entry timestamp of the last info-level `merge_waiting_main` log.
+    // The event fires every tick while the gate waits, so subsequent ticks
+    // log at debug to avoid spamming; a re-emission of info every ~5 min keeps
+    // long waits visible in `service logs` without drowning it out.
+    waitingMainInfoAt = new Map();
+    static WAITING_MAIN_INFO_INTERVAL_MS = 5 * 60 * 1000;
     constructor(config, policy, store, git, ci, github, eviction, specBuilder, logger, beforeTick) {
         this.config = config;
         this.policy = policy;
@@ -101,8 +107,23 @@ export class MergeStewardRuntime {
                         || event.action === "ci_failed"
                         || event.action === "merge_rejected" || event.action === "budget_exhausted";
                     const isDebug = event.action === "ci_pending" || event.action === "retry_gated"
-                        || event.action === "fetch_started" || event.action === "merge_waiting_main";
-                    const level = isWarn ? "warn" : isDebug ? "debug" : "info";
+                        || event.action === "fetch_started";
+                    let level = isWarn ? "warn" : isDebug ? "debug" : "info";
+                    if (event.action === "merge_waiting_main") {
+                        // The event fires every ~tick while the gate waits on main's own
+                        // CI.  Log at info the first time (so an operator can see *why*
+                        // the head entry is parked in merging) and once every interval
+                        // after, debug on the intermediate ticks to avoid spamming.
+                        const last = this.waitingMainInfoAt.get(event.entryId);
+                        const now = Date.now();
+                        if (last === undefined || now - last >= MergeStewardRuntime.WAITING_MAIN_INFO_INTERVAL_MS) {
+                            level = "info";
+                            this.waitingMainInfoAt.set(event.entryId, now);
+                        }
+                        else {
+                            level = "debug";
+                        }
+                    }
                     this.logger[level]({ ...event }, `Queue: ${event.action} PR #${event.prNumber}`);
                     if (event.action === "main_broken" && tickQueueBlockEvent === null) {
                         tickQueueBlockEvent = event;

package/package.json

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