@trim21/personal-pi-extensions 0.1.520 → 0.1.522

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trim21/personal-pi-extensions",
-  "version": "0.1.520",
+  "version": "0.1.522",
   "type": "module",
   "description": "Custom pi coding-agent extensions: bwrap sandbox, workspace guard, opencode edit, and more",
   "keywords": [

package/src/gh-readonly.ts

@@ -19,6 +19,7 @@
  *   - list-github-releases: List releases
  *   - read-github-release: Get release details
  *   - wait-github-pr-checks: Watch PR CI checks
+ *   - wait-github-commit-checks: Watch CI checks of a commit (no PR required)
  *   - watch-github-run: Watch a workflow run
  *
  * Install:
@@ -35,10 +36,19 @@ import { homedir } from "node:os";
 import { delimiter, dirname, join, resolve } from "node:path";
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { type Static, Type } from "typebox";
+import { Type } from "typebox";
 import { Value } from "typebox/value";
 
-import { createGithubSearch, type GithubSearch, renderHits } from "./lib/github.js";
+import {
+  type ActionJob,
+  type CheckRun,
+  type CommitStatus,
+  createGithubChecks,
+  createGithubSearch,
+  type GithubChecksClient,
+  type GithubSearch,
+  renderHits,
+} from "./lib/github.js";
 import { type ToolPendant } from "./lib/pendant.js";
 import { createSeqState } from "./lib/seq-state.js";
 
@@ -234,6 +244,15 @@ function repoArgs(repo?: string): string[] {
   return repo ? ["--repo", repo] : [];
 }
 
+/** Split `OWNER/REPO`; throws when the name doesn't have exactly one slash. */
+function splitRepo(nameWithOwner: string): { owner: string; repo: string } {
+  const slash = nameWithOwner.indexOf("/");
+  if (slash <= 0 || slash === nameWithOwner.length - 1 || nameWithOwner.includes("/", slash + 1)) {
+    throw new Error(`invalid repository: ${nameWithOwner} (expected OWNER/REPO)`);
+  }
+  return { owner: nameWithOwner.slice(0, slash), repo: nameWithOwner.slice(slash + 1) };
+}
+
 // ── runtime validation schemas for JSON.parse results ───────────────────────
 
 const repoViewSchema = Type.Object({ nameWithOwner: Type.String() });
@@ -258,31 +277,6 @@ const jobsResponseSchema = Type.Object({ jobs: Type.Array(jobRunSchema) });
 
 const prHeadSchema = Type.Object({ headRefOid: Type.String() });
 
-const workflowRunSchema = Type.Object({
-  id: Type.Number(),
-  name: Type.String(),
-  html_url: Type.String(),
-});
-
-const workflowRunsSchema = Type.Object({ workflow_runs: Type.Array(workflowRunSchema) });
-
-/**
- * One entry of `gh pr checks --json`. In JSON mode gh exits 0 once it could
- * fetch the checks (real errors still exit non-zero); pass/fail/pending is
- * only conveyed by the `bucket` field, never by the exit code.
- */
-const prCheckSchema = Type.Object({
-  name: Type.String(),
-  state: Type.String(),
-  bucket: Type.String(),
-  startedAt: Type.Union([Type.String(), Type.Null()]),
-  completedAt: Type.Union([Type.String(), Type.Null()]),
-  link: Type.Union([Type.String(), Type.Null()]),
-  workflow: Type.Union([Type.String(), Type.Null()]),
-});
-
-type PrCheck = Static<typeof prCheckSchema>;
-
 function truncate(
   text: string,
   maxLines = 2000,
@@ -1130,34 +1124,119 @@ export async function writeLogFile(
 
 // ── pr checks watch (pure rendering + poll loop) ────────────────────────────
 
-const PR_CHECKS_JSON_FIELDS = "name,state,bucket,startedAt,completedAt,link,workflow";
 const CHECKS_POLL_INTERVAL_MS = 30_000;
 const CHECKS_WATCH_DEADLINE_MS = 600_000;
 
+export type CheckBucket = "pass" | "skipped" | "fail" | "pending";
+
+/**
+ * One judged CI check of a commit: a single commit status or check run, kept
+ * distinct — same-named checks from different sources (push vs pull_request
+ * events, status vs check run channels) stay separate entries, like the
+ * GitHub checks UI.
+ */
+export interface MergedCheck {
+  readonly name: string;
+  readonly bucket: CheckBucket;
+  readonly startedAt: string | null;
+  readonly link: string | null;
+  /** Triggering workflow event (push, pull_request, ...); null when unknown. */
+  readonly event: string | null;
+}
+
+function statusBucket(state: string): CheckBucket {
+  if (state === "success") return "pass";
+  if (state === "failure" || state === "error") return "fail";
+  // pending, expected, and anything unknown must not end the wait
+  return "pending";
+}
+
+function checkRunBucket(run: CheckRun): CheckBucket {
+  if (run.status !== "completed" || run.conclusion === null) return "pending";
+  switch (run.conclusion) {
+    case "success": {
+      return "pass";
+    }
+    case "skipped":
+    case "neutral":
+    case "stale":
+    case "action_required": {
+      // awaiting maintainer approval: it will never run, so waiting for it is
+      // meaningless — treat like skipped
+      return "skipped";
+    }
+    case "failure":
+    case "timed_out":
+    case "cancelled":
+    case "startup_failure": {
+      return "fail";
+    }
+    default: {
+      return "pending";
+    }
+  }
+}
+
+/**
+ * Judge the commit's statuses and check runs into individual checks, keeping
+ * same-named entries distinct so the wait verdict (any fail / all
+ * pass-or-skipped across every entry) can never lose a failure. Pure — no
+ * network.
+ */
+export function mergeChecks(
+  statuses: readonly CommitStatus[],
+  checkRuns: readonly CheckRun[],
+): MergedCheck[] {
+  return [
+    ...statuses.map((status) => ({
+      name: status.context,
+      bucket: statusBucket(status.state),
+      startedAt: null,
+      link: status.targetUrl,
+      event: null,
+    })),
+    ...checkRuns.map((run) => ({
+      name: run.name,
+      bucket: checkRunBucket(run),
+      startedAt: run.startedAt,
+      link: run.url,
+      event: run.event,
+    })),
+  ];
+}
+
+/** Display name of a check; the trigger event is labelled like the GitHub UI (`build (pull_request)`). */
+export function checkDisplayName(check: MergedCheck): string {
+  return check.event ? `${check.name} (${check.event})` : check.name;
+}
+
 /**
- * Render one polling round of `gh pr checks` as a compact bullet list of the
- * checks still in flight: running ones first (`- [>]`), queued ones after
- * (`- [ ]`). Completed checks are hidden — the header already reports the
- * completion count. Pure — no network.
+ * Render one polling round as a compact bullet list of the checks still in
+ * flight: running ones first (`- [>]`), queued ones after (`- [ ]`). Completed
+ * checks are hidden — the header already reports the completion count.
+ * Pure — no network.
  */
 export function renderPrChecksList(options: {
-  prNumber: number | string;
+  /** Report subject, e.g. `PR #7` or `commit 5a7c407`. */
+  subject: string;
   round: number;
-  checks: readonly PrCheck[];
+  checks: readonly MergedCheck[];
 }): string {
-  const { prNumber, round, checks } = options;
+  const { subject, round, checks } = options;
   const completed = checks.filter((c) => c.bucket !== "pending").length;
 
   const pending = checks.filter((c) => c.bucket === "pending");
   const ordered = [...pending.filter((c) => c.startedAt), ...pending.filter((c) => !c.startedAt)];
   const lines = ordered.map((check) => {
-    const name = check.link ? `[${check.name}](${check.link})` : check.name;
+    const name = check.link
+      ? `[${checkDisplayName(check)}](${check.link})`
+      : checkDisplayName(check);
     return `- [${check.startedAt ? ">" : " "}] ${name}`;
   });
   const body =
     checks.length === 0 ? "- _no checks reported_" : lines.length > 0 ? lines.join("\n") : "";
 
-  return `### PR #${prNumber} checks — round ${round}: ${completed}/${checks.length} complete${body ? `\n\n${body}` : ""}`;
+  return `${subject} checks — round ${round}: ${completed}/${checks.length} complete${body ? `\n\n${body}` : ""}`;
 }
 
 function sleepInterruptibly(ms: number, signal: AbortSignal | undefined): Promise<void> {
@@ -1178,12 +1257,30 @@ function sleepInterruptibly(ms: number, signal: AbortSignal | undefined): Promis
   });
 }
 
+export type ChecksPollOutcome = "completed" | "fail_fast" | "timeout";
+
+export interface ChecksPollResult {
+  readonly outcome: ChecksPollOutcome;
+  readonly checks: readonly MergedCheck[];
+  readonly elapsedMs: number;
+}
+
 export interface PollPrChecksOptions {
-  prNumber: number | string;
-  repo?: string;
+  /** Report subject for progress lines, e.g. `PR #7` or `commit 5a7c407`. */
+  subject: string;
+  owner: string;
+  repo: string;
+  headSha: string;
   failFast: boolean;
-  cwd?: string;
-  signal?: AbortSignal;
+  checks: GithubChecksClient;
+  /**
+   * When set, only check runs triggered by this workflow event (e.g. push)
+   * are judged; commit statuses have an unknown trigger event and are
+   * excluded. Unset means all checks of the commit.
+   */
+  event?: string;
+  /** Owned by the caller; the poll loop observes it but never aborts it. */
+  signal: AbortSignal;
   /** Test overrides. */
   intervalMs?: number;
   deadlineMs?: number;
@@ -1191,52 +1288,158 @@ export interface PollPrChecksOptions {
 }
 
 /**
- * Poll `gh pr checks --json` until no check is pending (or a fail-fast
- * failure, or the deadline), emitting a compact list of in-flight checks via
- * `onUpdate` each round. In JSON mode gh exits 0 whenever it could fetch the
- * checks —
- * completion is judged from the `bucket` field, not the exit code. A non-zero
- * exit (no checks reported, auth, network) is not fatal here: the caller
- * proceeds to the Actions API verification, which either produces the final
- * report or surfaces the error.
+ * Poll the commit's combined-status and check-runs APIs until the wait
+ * semantics are met: return on any failure (immediately under fail-fast) or
+ * when every check is complete (pass/skipped). Emits a compact list of
+ * in-flight checks via `onUpdate` each round.
+ *
+ * A failed round (network, auth) does not end the wait — the error is kept
+ * and polling continues, so a transient blip or a CI system that has not
+ * reported anything yet cannot be mistaken for a completed check set. Only
+ * when no round ever succeeded by the deadline is the last error thrown.
  */
-export async function pollPrChecks(options: PollPrChecksOptions): Promise<void> {
-  const { prNumber, repo, failFast, cwd, signal, onUpdate } = options;
+export async function pollPrChecks(options: PollPrChecksOptions): Promise<ChecksPollResult> {
+  const { subject, owner, repo, headSha, failFast, checks, signal, onUpdate } = options;
   const intervalMs = options.intervalMs ?? CHECKS_POLL_INTERVAL_MS;
   const deadlineMs = options.deadlineMs ?? CHECKS_WATCH_DEADLINE_MS;
-  const args = [
-    "pr",
-    "checks",
-    String(prNumber),
-    ...repoArgs(repo),
-    "--json",
-    PR_CHECKS_JSON_FIELDS,
-  ];
 
   const watchStart = Date.now();
+  let lastChecks: readonly MergedCheck[] = [];
+  let lastError: unknown;
+  let everSucceeded = false;
+
   for (let round = 1; ; round++) {
-    const result = await runGh(args, { cwd, signal });
-    if (result.killed) {
-      throw new Error(
-        result.reason === "timeout" ? "gh pr checks poll timed out" : "gh pr checks was aborted",
-      );
+    if (signal.aborted) throw new Error("PR checks polling was aborted");
+    try {
+      const [statuses, runs] = await Promise.all([
+        checks.statuses(owner, repo, headSha, signal),
+        checks.checkRuns(owner, repo, headSha, signal),
+      ]);
+      everSucceeded = true;
+      lastChecks = mergeChecks(statuses, runs);
+      if (options.event) {
+        lastChecks = lastChecks.filter((c) => c.event === options.event);
+      }
+      onUpdate?.({
+        content: [
+          { type: "text", text: renderPrChecksList({ subject, round, checks: lastChecks }) },
+        ],
+        details: {},
+      });
+      if (lastChecks.every((c) => c.bucket !== "pending")) {
+        return { outcome: "completed", checks: lastChecks, elapsedMs: Date.now() - watchStart };
+      }
+      if (failFast && lastChecks.some((c) => c.bucket === "fail")) {
+        return { outcome: "fail_fast", checks: lastChecks, elapsedMs: Date.now() - watchStart };
+      }
+    } catch (error) {
+      // 不用 if (signal.aborted)：循环顶部的同名字段检查把它收窄成 false，
+      // TS 会在 catch 里维持这个收窄。
+      signal.throwIfAborted();
+      lastError = error;
     }
-    if (result.code !== 0) {
-      return;
+    if (Date.now() - watchStart >= deadlineMs) {
+      if (!everSucceeded) {
+        const message = lastError instanceof Error ? lastError.message : String(lastError);
+        throw new Error(`PR checks polling failed before any round succeeded: ${message}`);
+      }
+      return { outcome: "timeout", checks: lastChecks, elapsedMs: Date.now() - watchStart };
     }
-    const checks: PrCheck[] = Value.Parse(Type.Array(prCheckSchema), JSON.parse(result.stdout));
+    await sleepInterruptibly(intervalMs, signal);
+  }
+}
 
-    onUpdate?.({
-      content: [{ type: "text", text: renderPrChecksList({ prNumber, round, checks }) }],
-      details: {},
-    });
+/** One Actions job that did not succeed, for the FAILED report details. */
+export interface FailedActionJob {
+  readonly runId: number;
+  readonly runName: string;
+  readonly runUrl: string;
+  readonly jobId: number;
+  readonly jobName: string;
+  readonly conclusion: string;
+  readonly jobUrl?: string;
+}
 
-    const hasPending = checks.some((c) => c.bucket === "pending");
-    if (!hasPending) return;
-    if (failFast && checks.some((c) => c.bucket === "fail")) return;
-    if (Date.now() - watchStart >= deadlineMs) return;
-    await sleepInterruptibly(intervalMs, signal);
+export interface ChecksVerdict {
+  readonly status: "success" | "failure" | "pending";
+  readonly text: string;
+  readonly failedJobs: readonly FailedActionJob[];
+}
+
+/**
+ * Turn a poll result into the final report. Verdict comes from the checks
+ * buckets alone (so external CI such as Azure counts); Actions jobs are
+ * display-only enrichment. Pure — no network.
+ */
+export function renderChecksVerdict(options: {
+  /** Report subject, e.g. `PR #123` or `commit 5a7c407`. */
+  subject: string;
+  poll: ChecksPollResult;
+  /** All Actions jobs of the head commit; failed/incomplete ones are listed. */
+  actionJobs?: readonly ActionJob[];
+  /** Set when the Actions job fetch failed; the verdict stays untouched. */
+  enrichmentError?: string;
+}): ChecksVerdict {
+  const { subject, poll, actionJobs, enrichmentError } = options;
+  const totalChecks = poll.checks.length;
+  const failed = poll.checks.filter((c) => c.bucket === "fail");
+  const pending = poll.checks.filter((c) => c.bucket === "pending");
+
+  if (failed.length === 0 && poll.outcome === "completed") {
+    return {
+      status: "success",
+      text: `## ${subject} CI Checks - PASSED\n\nAll ${totalChecks} check(s) passed.`,
+      failedJobs: [],
+    };
   }
+
+  if (failed.length > 0) {
+    const failedJobs: FailedActionJob[] = (actionJobs ?? [])
+      .filter((j) => !j.conclusion || FAILED_JOB_CONCLUSIONS.has(j.conclusion))
+      .map((j) => ({
+        runId: j.runId,
+        runName: j.runName,
+        runUrl: j.runUrl,
+        jobId: j.jobId,
+        jobName: j.jobName,
+        conclusion: j.conclusion ?? "in_progress",
+        ...(j.jobUrl && { jobUrl: j.jobUrl }),
+      }));
+
+    const lines = failed.map(
+      (c) =>
+        `- ${statusIcon("failure")} **${checkDisplayName(c)}**${c.link ? ` — [view check](${c.link})` : ""}`,
+    );
+    for (const j of failedJobs) {
+      lines.push(
+        `  - ${statusIcon(j.conclusion)} job **${j.jobName}** (${j.conclusion}) — [job #${j.jobId}](${j.jobUrl ?? j.runUrl})`,
+        `    - workflow: [${j.runName} (#${j.runId})](${j.runUrl})`,
+      );
+    }
+    if (enrichmentError) lines.push(`  - _Actions job details unavailable: ${enrichmentError}_`);
+    if (pending.length > 0) lines.push(`\n_${pending.length} other check(s) still in flight._`);
+
+    return {
+      status: "failure",
+      text:
+        `## ${subject} CI Checks - FAILED\n\n` +
+        `${failed.length} of ${totalChecks} check(s) failed:\n\n${lines.join("\n")}`,
+      failedJobs,
+    };
+  }
+
+  const waitedMinutes = Math.max(1, Math.round(poll.elapsedMs / 60_000));
+  const pendingLines = pending.map(
+    (c) => `- [${c.startedAt ? ">" : " "}] ${c.link ? `[${c.name}](${c.link})` : c.name}`,
+  );
+  return {
+    status: "pending",
+    text:
+      `## ${subject} CI Checks - STILL IN FLIGHT\n\n` +
+      `${pending.length} of ${totalChecks} check(s) still incomplete after ~${waitedMinutes}m:\n\n` +
+      (pendingLines.length > 0 ? pendingLines.join("\n") : "- _no checks reported_"),
+    failedJobs: [],
+  };
 }
 
 // ── tools ────────────────────────────────────────────────────────────────────
@@ -1265,6 +1468,70 @@ export default function ghReadonlyTools(pi: ExtensionAPI) {
   }
 
   const githubSearch = createGithubSearch();
+  const githubChecks = createGithubChecks();
+
+  /**
+   * Shared wait core of `wait-github-pr-checks` and
+   * `wait-github-commit-checks`: poll the commit's checks, enrich FAILED
+   * reports with Actions job details (display-only), render the verdict.
+   * The caller resolves repo/headSha; `subject` formats the report header.
+   */
+  async function waitChecksReport(options: {
+    subject: string;
+    owner: string;
+    repo: string;
+    headSha: string;
+    failFast: boolean;
+    event?: string;
+    signal: AbortSignal | undefined;
+    onUpdate: ((msg: CiLogsResult) => void) | undefined;
+    params: unknown;
+    pendant?: ToolPendant;
+  }) {
+    const { subject, owner, repo, headSha, failFast, event, signal, onUpdate, params, pendant } =
+      options;
+
+    // 轮询层要求非空 signal；框架可能不给时构造一个占位的（从不取消）。
+    const pollSignal = signal ?? new AbortController().signal;
+
+    const poll = await pollPrChecks({
+      subject,
+      owner,
+      repo,
+      headSha,
+      failFast,
+      event,
+      checks: githubChecks,
+      signal: pollSignal,
+      onUpdate,
+    });
+
+    // Actions job 详情只做展示补充，不影响判定（判定来自 checks bucket，
+    // 覆盖 Azure 等外部 CI）。抓取失败时降级为提示，不推翻结论。
+    let actionJobs: readonly ActionJob[] | undefined;
+    let enrichmentError: string | undefined;
+    if (poll.checks.some((c) => c.bucket === "fail")) {
+      try {
+        actionJobs = await githubChecks.actionJobs(owner, repo, headSha, pollSignal);
+      } catch (error) {
+        enrichmentError =
+          error instanceof Error ? error.message : "Actions job details unavailable";
+      }
+    }
+
+    const verdict = renderChecksVerdict({ subject, poll, actionJobs, enrichmentError });
+    return {
+      content: [{ type: "text" as const, text: verdict.text }],
+      details: {
+        status: verdict.status,
+        totalChecks: poll.checks.length,
+        checks: poll.checks,
+        failedJobs: verdict.failedJobs,
+        input: params,
+        ...(pendant && { pendant }),
+      },
+    };
+  }
 
   // ── read-github-issue ──────────────────────────────────────────────────────
   pi.registerTool({
@@ -1794,8 +2061,10 @@ export default function ghReadonlyTools(pi: ExtensionAPI) {
     name: "wait-github-pr-checks",
     label: "Watch GitHub PR Checks",
     description:
-      "Watch CI status checks for a PR until they complete. Blocks until all checks finish or one fails. " +
-      "Each polling round streams a compact bullet list of the checks still in flight via onUpdate. " +
+      "Watch CI status checks for a PR until they complete. Blocks until all checks pass (or are skipped) or one fails. " +
+      "Covers both commit statuses (Azure DevOps, Jenkins, ...) and GitHub Actions check runs. " +
+      "Each polling round streams a compact bullet list of the checks still in flight via onUpdate; " +
+      "on timeout the still-in-flight snapshot is returned instead of a verdict. " +
       "Use this when you need to wait for CI to complete and see the final result.",
     promptSnippet: "Watch and wait for GitHub PR CI checks to complete",
     parameters: Type.Object({
@@ -1814,121 +2083,84 @@ export default function ghReadonlyTools(pi: ExtensionAPI) {
         details: {},
       });
 
-      // 轮询 `gh pr checks --json`（每轮经 onUpdate 流式输出 GitHub Web UI 风格
-      // 的检查表），结束后再用 Actions API 抓取该 PR head 提交关联的所有
-      // workflow job，以 job 的真实 conclusion 为准判断成功/失败。
-      await pollPrChecks({
-        prNumber: number,
-        repo,
-        failFast: fail_fast === true,
-        cwd: ctx.cwd,
-        signal,
-        onUpdate,
-      });
-
       const effectiveRepo = await resolveRepo(repo, signal, ctx.cwd, params);
+      const { owner, repo: repoName } = splitRepo(effectiveRepo);
+
       const prOut = await ghExec(
         ["pr", "view", String(number), "--repo", effectiveRepo, "--json", "headRefOid"],
         { cwd: ctx.cwd, signal, input: params },
       );
       const { headRefOid } = Value.Parse(prHeadSchema, JSON.parse(prOut));
 
+      return waitChecksReport({
+        subject: `PR #${number}`,
+        owner,
+        repo: repoName,
+        headSha: headRefOid,
+        failFast: fail_fast === true,
+        signal,
+        onUpdate,
+        params,
+        pendant,
+      });
+    },
+  });
+
+  // ── wait-github-commit-checks ──────────────────────────────────────────────
+  pi.registerTool({
+    name: "wait-github-commit-checks",
+    label: "Watch GitHub Commit Checks",
+    description:
+      "Watch CI status checks for a commit until they complete — no pull request required. " +
+      "Same semantics as wait-github-pr-checks: returns when any check fails (immediately under fail_fast) " +
+      "or all checks pass/skip; on timeout the still-in-flight snapshot is returned. " +
+      "With `event`, only check runs triggered by that workflow event (e.g. push) are judged; " +
+      "commit statuses have an unknown trigger event and are excluded under a filter. " +
+      "Use this to wait for the runs a commit's push triggered, or for checks on an arbitrary ref.",
+    promptSnippet: "Watch and wait for GitHub commit CI checks to complete",
+    parameters: Type.Object({
+      commit: Type.Union([Type.Number(), Type.String()], {
+        description:
+          "Commit to wait for: full or partial SHA, branch name, or tag name (resolved to the commit's SHA)",
+      }),
+      repo: Type.Optional(Type.String({ description: "OWNER/REPO" })),
+      event: Type.Optional(
+        Type.String({
+          description:
+            "Only judge check runs triggered by this workflow event (e.g. push, pull_request)",
+        }),
+      ),
+      fail_fast: Type.Optional(
+        Type.Boolean({ description: "Exit immediately when any check fails (default: false)" }),
+      ),
+    }),
+    async execute(_id, params, signal, onUpdate, ctx) {
+      const { commit, repo, event, fail_fast } = params;
+
+      const pendant = subtitlePendant(params, "commit");
       onUpdate?.({
-        content: [{ type: "text", text: `Fetching workflow jobs for PR #${number}...` }],
+        content: [{ type: "text", text: `Watching CI checks for commit ${commit}...` }],
         details: {},
       });
 
-      const runsOut = await ghExec(
-        ["api", `/repos/${effectiveRepo}/actions/runs?head_sha=${headRefOid}&per_page=100`],
-        { cwd: ctx.cwd, signal, input: params },
-      );
-      const { workflow_runs } = Value.Parse(workflowRunsSchema, JSON.parse(runsOut));
-
-      const failedJobs: {
-        runId: number;
-        runName: string;
-        runUrl: string;
-        jobId: number;
-        jobName: string;
-        conclusion: string;
-        jobUrl?: string;
-      }[] = [];
-      let totalJobs = 0;
-
-      for (const run of workflow_runs) {
-        const jobsOut = await ghExec(
-          ["api", `/repos/${effectiveRepo}/actions/runs/${run.id}/jobs?per_page=100`],
-          { cwd: ctx.cwd, signal, input: params },
-        );
-        const { jobs } = Value.Parse(jobsResponseSchema, JSON.parse(jobsOut));
-        totalJobs += jobs.length;
-
-        for (const job of jobs) {
-          if (!job.conclusion || FAILED_JOB_CONCLUSIONS.has(job.conclusion)) {
-            failedJobs.push({
-              runId: run.id,
-              runName: run.name,
-              runUrl: run.html_url,
-              jobId: job.id,
-              jobName: job.name,
-              conclusion: job.conclusion ?? "in_progress",
-              jobUrl: job.html_url,
-            });
-          }
-        }
-      }
+      const effectiveRepo = await resolveRepo(repo, signal, ctx.cwd, params);
+      const { owner, repo: repoName } = splitRepo(effectiveRepo);
 
-      if (totalJobs === 0) {
-        return {
-          content: [
-            {
-              type: "text",
-              text: `## PR #${number} CI Checks\n\nNo workflow runs found for head commit ${headRefOid.slice(0, 7)}.`,
-            },
-          ],
-          details: {
-            status: "no-jobs",
-            totalJobs: 0,
-            input: params,
-            ...(pendant && { pendant }),
-          },
-        };
-      }
+      const pollSignal = signal ?? new AbortController().signal;
+      const sha = await githubChecks.headSha(owner, repoName, String(commit), pollSignal);
 
-      if (failedJobs.length > 0) {
-        const lines = failedJobs.map(
-          (j) =>
-            `- ${statusIcon(j.conclusion)} **${j.jobName}** (${j.conclusion}) — [job #${j.jobId}](${j.jobUrl ?? j.runUrl})\n` +
-            `  - workflow: [${j.runName} (#${j.runId})](${j.runUrl})`,
-        );
-        return {
-          content: [
-            {
-              type: "text",
-              text:
-                `## PR #${number} CI Checks - FAILED\n\n` +
-                `${failedJobs.length} of ${totalJobs} job(s) did not succeed:\n\n${lines.join("\n")}`,
-            },
-          ],
-          details: {
-            status: "failure",
-            totalJobs,
-            failedJobs,
-            input: params,
-            ...(pendant && { pendant }),
-          },
-        };
-      }
-
-      return {
-        content: [
-          {
-            type: "text",
-            text: `## PR #${number} CI Checks - PASSED\n\nAll ${totalJobs} job(s) succeeded.`,
-          },
-        ],
-        details: { status: "success", totalJobs, input: params, ...(pendant && { pendant }) },
-      };
+      return waitChecksReport({
+        subject: `commit ${sha.slice(0, 7)}`,
+        owner,
+        repo: repoName,
+        headSha: sha,
+        failFast: fail_fast === true,
+        event,
+        signal,
+        onUpdate,
+        params,
+        pendant,
+      });
     },
   });
 

package/src/lib/github.ts

@@ -243,16 +243,18 @@ function describeHttpError(status: number | undefined): string {
   return `GitHub API error${status === undefined ? "" : ` (HTTP ${status})`}`;
 }
 
-export interface GithubSearch {
-  search(kind: SearchKind, params: SearchParams): Promise<SearchHit[]>;
+export interface GithubApi {
+  /** Run an octokit request; retries once with a fresh token on 401. */
+  call<T>(fn: (octokit: Octokit) => Promise<T>): Promise<T>;
 }
 
 /**
- * Create a search client. The octokit instance (and its auth token) is cached
- * in the returned closure, so repeated searches reuse the same client without
- * module-level state.
+ * Create a shared octokit accessor. The client (and its auth token) is cached
+ * in the returned closure, so repeated calls reuse the same client without
+ * module-level state. A stale cached token can produce 401s; the cache is
+ * dropped and the request retried once in that case.
  */
-export function createGithubSearch(): GithubSearch {
+export function createGithubApi(): GithubApi {
   let client: Octokit | undefined;
 
   async function getClient(): Promise<Octokit> {
@@ -261,34 +263,222 @@ export function createGithubSearch(): GithubSearch {
   }
 
   return {
-    async search(kind, params) {
-      const limit = Math.min(Math.max(params.limit ?? 30, 1), 100);
-      const effective = { ...params, limit };
-
+    async call(fn) {
       for (let attempt = 0; ; attempt += 1) {
         try {
-          const octokit = await getClient();
-          if (effective.assignee === "@me") {
-            const { data } = await octokit.rest.users.getAuthenticated();
-            effective.assignee = data.login;
-          }
-          const q = buildSearchQuery(kind, effective);
-          const { data } = await octokit.rest.search.issuesAndPullRequests({
-            q,
-            per_page: limit,
-          });
-          return data.items.map((item) => normalize(item as unknown as RawSearchItem));
+          return await fn(await getClient());
         } catch (error) {
           const status = (error as { status?: number }).status;
-          // A stale cached token can produce 401s; drop the cache and retry once.
           if (status === 401 && attempt === 0 && client) {
             client = undefined;
             continue;
           }
-          const message = (error as { message?: string }).message ?? String(error);
-          throw new GithubSearchError(`${describeHttpError(status)}: ${message}`, params, status);
+          throw error;
         }
       }
     },
   };
 }
+
+export interface GithubSearch {
+  search(kind: SearchKind, params: SearchParams): Promise<SearchHit[]>;
+}
+
+/**
+ * Create a search client backed by a cached octokit instance.
+ */
+export function createGithubSearch(): GithubSearch {
+  const api = createGithubApi();
+
+  return {
+    async search(kind, params) {
+      const limit = Math.min(Math.max(params.limit ?? 30, 1), 100);
+      const effective = { ...params, limit };
+
+      try {
+        const octokit = await api.call(async (client) => {
+          if (effective.assignee === "@me") {
+            const { data } = await client.rest.users.getAuthenticated();
+            effective.assignee = data.login;
+          }
+          return client;
+        });
+        const q = buildSearchQuery(kind, effective);
+        const { data } = await octokit.rest.search.issuesAndPullRequests({
+          q,
+          per_page: limit,
+        });
+        return data.items.map((item) => normalize(item as unknown as RawSearchItem));
+      } catch (error) {
+        const status = (error as { status?: number }).status;
+        const message = (error as { message?: string }).message ?? String(error);
+        throw new GithubSearchError(`${describeHttpError(status)}: ${message}`, params, status);
+      }
+    },
+  };
+}
+
+/** One entry of the combined status API for a commit (classic commit status). */
+export interface CommitStatus {
+  readonly context: string;
+  readonly state: string;
+  readonly targetUrl: string | null;
+}
+
+/** One check run of the check-runs API for a commit (GitHub Actions, GitHub Apps). */
+export interface CheckRun {
+  readonly name: string;
+  readonly status: string;
+  readonly conclusion: string | null;
+  readonly startedAt: string | null;
+  readonly url: string | null;
+  /** Triggering workflow event (push, pull_request, ...); null when unknown. */
+  readonly event: string | null;
+}
+
+/** One Actions job flattened with its workflow run metadata. */
+export interface ActionJob {
+  readonly runId: number;
+  readonly runName: string;
+  readonly runUrl: string;
+  readonly jobId: number;
+  readonly jobName: string;
+  readonly conclusion: string | null;
+  readonly jobUrl?: string;
+}
+
+export interface GithubChecksClient {
+  statuses(
+    owner: string,
+    repo: string,
+    ref: string,
+    signal: AbortSignal,
+  ): Promise<readonly CommitStatus[]>;
+  checkRuns(
+    owner: string,
+    repo: string,
+    ref: string,
+    signal: AbortSignal,
+  ): Promise<readonly CheckRun[]>;
+  /** All Actions jobs across the workflow runs of one head commit. */
+  actionJobs(
+    owner: string,
+    repo: string,
+    headSha: string,
+    signal: AbortSignal,
+  ): Promise<readonly ActionJob[]>;
+  /** Resolve a SHA, branch name, or tag name to the commit's full SHA. */
+  headSha(owner: string, repo: string, ref: string, signal: AbortSignal): Promise<string>;
+}
+
+/**
+ * Create a client for PR CI checks, backed by a cached octokit instance.
+ * Covers both check sources GitHub exposes for a commit — classic commit
+ * statuses (Azure DevOps, Jenkins, ...) and check runs (GitHub Actions,
+ * GitHub Apps) — so external CI is visible to the caller.
+ */
+const ACTIONS_RUN_URL_RE = /\/actions\/runs\/(\d+)/;
+export function createGithubChecks(): GithubChecksClient {
+  const api = createGithubApi();
+
+  return {
+    async statuses(owner, repo, ref, signal) {
+      const { data } = await api.call((octokit) =>
+        octokit.rest.repos.getCombinedStatusForRef({ owner, repo, ref, request: { signal } }),
+      );
+      return data.statuses.map((status) => ({
+        context: status.context,
+        state: status.state,
+        targetUrl: status.target_url,
+      }));
+    },
+
+    async checkRuns(owner, repo, ref, signal) {
+      const runs = await api.call((octokit) =>
+        octokit.paginate(octokit.rest.checks.listForRef, {
+          owner,
+          repo,
+          ref,
+          per_page: 100,
+          request: { signal },
+        }),
+      );
+      // The check run object itself carries no event field. Its details_url
+      // contains the workflow run id, and every run of this commit (push and
+      // pull_request events alike) shows up under actions/runs?head_sha=, so
+      // one extra request resolves run id -> event for the suffix display.
+      const runIds = new Set(
+        runs
+          .map((run) => ACTIONS_RUN_URL_RE.exec(run.details_url ?? "")?.[1])
+          .filter((id): id is string => id !== undefined),
+      );
+      const events = new Map<string, string>();
+      if (runIds.size > 0) {
+        const { data } = await api.call((octokit) =>
+          octokit.rest.actions.listWorkflowRunsForRepo({
+            owner,
+            repo,
+            head_sha: ref,
+            per_page: 100,
+            request: { signal },
+          }),
+        );
+        for (const run of data.workflow_runs) {
+          const id = String(run.id);
+          if (runIds.has(id)) events.set(id, run.event);
+        }
+      }
+      return runs.map((run) => ({
+        name: run.name,
+        status: run.status,
+        conclusion: run.conclusion,
+        startedAt: run.started_at,
+        url: run.html_url ?? run.details_url ?? null,
+        event: events.get(ACTIONS_RUN_URL_RE.exec(run.details_url ?? "")?.[1] ?? "") ?? null,
+      }));
+    },
+
+    async actionJobs(owner, repo, headSha, signal) {
+      const { data } = await api.call((octokit) =>
+        octokit.rest.actions.listWorkflowRunsForRepo({
+          owner,
+          repo,
+          head_sha: headSha,
+          per_page: 100,
+          request: { signal },
+        }),
+      );
+      const jobs: ActionJob[] = [];
+      for (const run of data.workflow_runs) {
+        const { data: jobsData } = await api.call((octokit) =>
+          octokit.rest.actions.listJobsForWorkflowRun({
+            owner,
+            repo,
+            run_id: run.id,
+            per_page: 100,
+            request: { signal },
+          }),
+        );
+        for (const job of jobsData.jobs) {
+          jobs.push({
+            runId: run.id,
+            runName: run.name ?? "",
+            runUrl: run.html_url,
+            jobId: job.id,
+            jobName: job.name,
+            conclusion: job.conclusion,
+            ...(job.html_url && { jobUrl: job.html_url }),
+          });
+        }
+      }
+      return jobs;
+    },
+
+    async headSha(owner, repo, ref, signal) {
+      const { data } = await api.call((octokit) =>
+        octokit.rest.repos.getCommit({ owner, repo, ref, request: { signal } }),
+      );
+      return data.sha;
+    },
+  };
+}