@blogic-cz/agent-tools 1.7.1 → 1.7.3

package/src/gh-tool/pr/check-status-cache.ts

@@ -0,0 +1,142 @@
+import { Context } from "effect";
+import { createHash, randomUUID } from "node:crypto";
+import { chmod, mkdir, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import type { CheckResult } from "#gh/types";
+
+const CACHE_TTL_MS = 30_000;
+const WATCH_PENDING_TTL_MS = 5_000;
+const CACHE_DIR = join(homedir(), ".cache", "agent-tools", "gh-check-status-v1");
+
+export const CheckStatusCacheDirectory = Context.Reference<string | undefined>(
+  "@agent-tools/CheckStatusCacheDirectory",
+  { defaultValue: () => CACHE_DIR },
+);
+
+type CacheEntry = { fetchedAt: number; checks: CheckResult[] };
+
+const keyFor = (identity: string, repo: string, pr: number, headSha: string) =>
+  createHash("sha256")
+    .update(`${identity}\n${repo.toLowerCase()}\n${pr}\n${headSha}`)
+    .digest("hex");
+
+const validChecks = (value: unknown): value is CheckResult[] =>
+  Array.isArray(value) &&
+  value.every(
+    (item) =>
+      item !== null &&
+      typeof item === "object" &&
+      typeof item.name === "string" &&
+      typeof item.state === "string" &&
+      typeof item.bucket === "string" &&
+      typeof item.link === "string",
+  );
+
+export const readCheckStatusCache = async (
+  identity: string,
+  repo: string,
+  pr: number,
+  headSha: string,
+  now: number,
+  watchPending = false,
+  directory = CACHE_DIR,
+): Promise<CheckResult[] | null> => {
+  try {
+    const prefix = keyFor(identity, repo, pr, headSha);
+    const files = (await readdir(directory)).filter((name) => name.startsWith(`${prefix}.`));
+    let latest: CacheEntry | null = null;
+    const entries = await Promise.all(
+      files.map(async (name) => {
+        try {
+          return {
+            name,
+            value: JSON.parse(await readFile(join(directory, name), "utf8")) as unknown,
+          };
+        } catch {
+          return { name, value: null };
+        }
+      }),
+    );
+    const staleFiles: string[] = [];
+    for (const { name, value: entry } of entries) {
+      if (!name.endsWith(".json")) continue;
+      if (entry === null || typeof entry !== "object") continue;
+      const candidate = entry as Partial<CacheEntry>;
+      const fetchedAt = candidate.fetchedAt;
+      if (
+        typeof fetchedAt !== "number" ||
+        !Number.isFinite(fetchedAt) ||
+        !validChecks(candidate.checks) ||
+        candidate.checks.length === 0
+      ) {
+        staleFiles.push(join(directory, name));
+        continue;
+      }
+      if (fetchedAt > now || now - fetchedAt > CACHE_TTL_MS) {
+        staleFiles.push(join(directory, name));
+        continue;
+      }
+      if (watchPending && !candidate.checks.some((check) => check.bucket === "pending")) continue;
+      if (latest === null || fetchedAt > latest.fetchedAt)
+        latest = { fetchedAt, checks: candidate.checks };
+    }
+    await Promise.all(staleFiles.map((path) => rm(path, { force: true }).catch(() => undefined)));
+    if (latest === null || (watchPending && now - latest.fetchedAt > WATCH_PENDING_TTL_MS))
+      return null;
+    return latest.checks;
+  } catch {
+    return null;
+  }
+};
+
+export const writeCheckStatusCache = async (
+  identity: string,
+  repo: string,
+  pr: number,
+  headSha: string,
+  checks: CheckResult[],
+  fetchedAt: number,
+  directory = CACHE_DIR,
+): Promise<void> => {
+  if (checks.length === 0) return;
+  try {
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    await chmod(directory, 0o700);
+    await Promise.all(
+      (await readdir(directory))
+        .filter((name) => name.endsWith(".json"))
+        .map(async (name) => {
+          const path = join(directory, name);
+          try {
+            const entry: unknown = JSON.parse(await readFile(path, "utf8"));
+            if (
+              entry !== null &&
+              typeof entry === "object" &&
+              "fetchedAt" in entry &&
+              typeof entry.fetchedAt === "number" &&
+              Number.isFinite(entry.fetchedAt) &&
+              fetchedAt - entry.fetchedAt <= CACHE_TTL_MS
+            )
+              return;
+            await rm(path, { force: true });
+          } catch {
+            /* Another writer can remove a stale snapshot first. */
+          }
+        }),
+    );
+    const prefix = keyFor(identity, repo, pr, headSha);
+    const temporary = join(directory, `${prefix}.${process.pid}.${randomUUID()}.tmp`);
+    const destination = join(
+      directory,
+      `${prefix}.${fetchedAt}.${process.pid}.${randomUUID()}.json`,
+    );
+    await writeFile(temporary, JSON.stringify({ fetchedAt, checks } satisfies CacheEntry), {
+      mode: 0o600,
+    });
+    await rename(temporary, destination);
+  } catch {
+    // A cache write must never replace a successful GitHub response with an error.
+  }
+};

package/src/gh-tool/pr/commands.ts

@@ -22,6 +22,7 @@ import {
 } from "#gh/text-input";
 import {
   CI_CHECK_WATCH_TIMEOUT_MS,
+  PR_WATCH_TIMEOUT_SECONDS,
   DEFAULT_DELETE_BRANCH,
   DEFAULT_MERGE_STRATEGY,
   DEFAULT_REVIEW_EVENT,
@@ -190,6 +191,12 @@ export const classifyReviewTriage = (
 ): ReviewTriageClassification => {
   const reasons = [
     ...(checks.some((check) => check.bucket === "fail") ? ["failed_checks"] : []),
+    ...(checks.some((check) => check.bucket === "cancel") ? ["cancelled_checks"] : []),
+    ...(checks.some(
+      (check) => !["pass", "fail", "pending", "skipping", "cancel"].includes(check.bucket),
+    )
+      ? ["unknown_checks"]
+      : []),
     ...(summary.visibleOpenReviewThreadsCount > 0 ? ["visible_open_review_threads"] : []),
     ...(summary.unrepliedReviewThreadsCount > 0 ? ["unreplied_review_threads"] : []),
     ...(summary.unresolvedReviewThreadsCount > 0 ? ["unresolved_review_threads"] : []),
@@ -412,6 +419,14 @@ export const fetchReviewTriage = Effect.fn("pr.fetchReviewTriage")(function* (
   if (info.mergeable !== "MERGEABLE") blocking.push(`mergeable=${info.mergeable || "UNKNOWN"}`);
   if (checks.some((check) => check.bucket === "fail")) blocking.push("failing_checks");
   if (checks.some((check) => check.bucket === "pending")) blocking.push("pending_checks");
+  if (checks.some((check) => check.bucket === "cancel")) blocking.push("cancelled_checks");
+  if (
+    checks.some(
+      (check) => !["pass", "fail", "pending", "skipping", "cancel"].includes(check.bucket),
+    )
+  ) {
+    blocking.push("unknown_checks");
+  }
   if (summary.unresolvedReviewThreadsCount > 0) blocking.push("unresolved_threads");
   if (info.reviewDecision !== "" && info.reviewDecision !== "APPROVED") {
     blocking.push(`review=${info.reviewDecision}`);
@@ -899,18 +914,20 @@ export const prChecksFailedCommand = Command.make(
     ),
     repo: repoOption,
     withLogs: Flag.Boolean("with-logs").pipe(
-      Flag.withDescription(
-        "Inline the failed-step logs for each failed check so no follow-up job-logs call is needed",
-      ),
+      Flag.withDescription("Inline a short summary from each failed step"),
+      Flag.withDefault(false),
+    ),
+    fullLogs: Flag.Boolean("full-logs").pipe(
+      Flag.withDescription("Inline all failed-step log lines; implies --with-logs"),
       Flag.withDefault(false),
     ),
   },
-  ({ format, pr, repo, withLogs }) =>
+  ({ format, pr, repo, withLogs, fullLogs }) =>
     withRepo(
       repo,
       Effect.gen(function* () {
         const prNumber = Option.getOrNull(pr);
-        const checks = yield* fetchFailedChecks(prNumber, withLogs);
+        const checks = yield* fetchFailedChecks(prNumber, withLogs, fullLogs);
         yield* logFormatted(checks, format);
       }),
     ),
@@ -924,13 +941,17 @@ export const prWatchCommand = Command.make(
     format: Flag.Literals("format", ["jsonl"]).pipe(Flag.withDefault("jsonl")),
     interval: Flag.Int("interval").pipe(
       Flag.withDefault(5),
+      Flag.withDescription("Polling interval in seconds (default: 5, range: 1..86400)"),
       Flag.filter(
-        (n) => n >= 1 && n <= 60,
-        () => "--interval must be 1..60 seconds",
+        (n) => n >= 1 && n <= 86400,
+        () => "--interval must be 1..86400 seconds",
       ),
     ),
     timeout: Flag.Int("timeout").pipe(
-      Flag.withDefault(CI_CHECK_WATCH_TIMEOUT_MS / 1000),
+      Flag.withDefault(PR_WATCH_TIMEOUT_SECONDS),
+      Flag.withDescription(
+        "Timeout in seconds (default: 1800, minimum 1); timeout is not a CI verdict",
+      ),
       Flag.filter(
         (n) => n >= 1,
         () => "--timeout must be at least 1 second",

package/src/gh-tool/pr/core.ts

@@ -1,4 +1,5 @@
 import { Clock, Console, Duration, Effect, Option, Result } from "effect";
+import { createHash } from "node:crypto";
 
 import type {
   BranchPRDetail,
@@ -17,10 +18,11 @@ import type {
 } from "#gh/types";
 
 import type { GitHubAuthError, GitHubNotFoundError } from "#gh/errors";
-import { GitHubCommandError, GitHubMergeError } from "#gh/errors";
+import { GitHubCommandError, GitHubMergeError, GitHubTimeoutError } from "#gh/errors";
 import { GitHubService } from "#gh/service";
+import { resolveGitHubToken } from "#gh/api";
 import type { GhResult } from "#gh/service";
-import { logText } from "#shared";
+import { logFormatted, logText } from "#shared";
 import { redactSensitiveText } from "#shared/content-security";
 
 import type { ButStatusJson, PRViewJsonResult } from "./helpers";
@@ -35,7 +37,13 @@ import {
   formatLogEntries,
   listDispatchedRuns,
   parseRawJobLogs,
+  readJobLogApi,
 } from "#gh/workflow";
+import {
+  CheckStatusCacheDirectory,
+  readCheckStatusCache,
+  writeCheckStatusCache,
+} from "./check-status-cache";
 
 const CHECK_JSON_FIELDS = "name,state,bucket,link";
 const LONG_LIVED_BRANCHES = new Set(["main", "master", "develop", "staging", "production"]);
@@ -218,7 +226,7 @@ const fetchWorkflowRunFailureContext = Effect.fn("pr.fetchWorkflowRunFailureCont
       "view",
       String(runId),
       "--json",
-      "databaseId,attempt,url,workflowName,status,conclusion,jobs",
+      "databaseId,attempt,headSha,url,workflowName,status,conclusion,jobs",
     ])
     .pipe(Effect.catchTag("GitHubCommandError", () => Effect.succeed(null)));
 
@@ -244,14 +252,16 @@ const fetchWorkflowRunFailureContext = Effect.fn("pr.fetchWorkflowRunFailureCont
   const context: FailedCheckRunContext = {
     runId: run.databaseId,
     attempt: run.attempt ?? null,
+    headSha: run.headSha ?? null,
     url: run.url,
     workflowName: run.workflowName,
     status: run.status,
     conclusion: run.conclusion,
     failedJobs,
   };
+  const stepsByJob = new Map(run.jobs.map((job) => [job.databaseId, job.steps] as const));
 
-  return context;
+  return { context, stepsByJob };
 });
 
 // `gh pr checks` exits 1 on an *empty* result ("no checks reported on the 'x' branch"). Zero checks
@@ -265,7 +275,35 @@ export const NO_CHECKS_REPORTED_RE = /no checks reported/i;
 const CHECK_REGISTRATION_POLL_SECONDS = 5;
 const CHECK_REGISTRATION_GRACE_SECONDS = 60;
 
-export const fetchCheckResults = Effect.fn("pr.fetchCheckResults")(function* (pr: number | null) {
+const summarizeFailedStepEntries = (entries: Array<{ step: string; message: string }>) => {
+  const selected = entries
+    .map((entry, index) => ({
+      entry,
+      index,
+      rank: /assert|expected|received|actual|failed|failure|error|exception|fatal/i.test(
+        entry.message,
+      )
+        ? 0
+        : 1,
+    }))
+    .toSorted((a, b) => a.rank - b.rank || b.index - a.index)
+    .slice(0, 20)
+    .toSorted((a, b) => a.index - b.index);
+  const kept: Array<{ step: string; message: string }> = [];
+  for (const { entry } of selected.toReversed()) {
+    const clipped = { step: entry.step.slice(0, 80), message: entry.message.slice(0, 150) };
+    if (formatLogEntries([clipped, ...kept]).length <= 3_900) kept.unshift(clipped);
+  }
+  let output = formatLogEntries(kept);
+  if (kept.length < entries.length)
+    output += `\n… ${entries.length - kept.length} log lines omitted`;
+  return output;
+};
+
+export const fetchCheckResults = Effect.fn("pr.fetchCheckResults")(function* (
+  pr: number | null,
+  cache?: { headSha: string; watchPending?: boolean },
+) {
   const gh = yield* GitHubService;
 
   const args = ["pr", "checks"];
@@ -273,7 +311,43 @@ export const fetchCheckResults = Effect.fn("pr.fetchCheckResults")(function* (pr
     args.push(String(pr));
   }
 
-  return yield* gh
+  const directory = yield* CheckStatusCacheDirectory;
+  const now = yield* Clock.currentTimeMillis;
+  let repo: string | null = null;
+  let identity: string | null = null;
+  if (cache !== undefined && pr !== null && directory !== undefined) {
+    const repoInfo = yield* gh.getRepoInfo().pipe(Effect.result);
+    const token = yield* resolveGitHubToken().pipe(Effect.result);
+    if (Result.isSuccess(repoInfo) && Result.isSuccess(token)) {
+      const host = yield* Effect.try({
+        try: () => new URL(repoInfo.success.url).host,
+        catch: () => "",
+      }).pipe(Effect.orElseSucceed(() => ""));
+      if (host.length > 0) {
+        const cacheRepo = `${host}/${repoInfo.success.owner}/${repoInfo.success.name}`;
+        const cacheIdentity = createHash("sha256").update(token.success).digest("hex");
+        const cached = yield* Effect.tryPromise({
+          try: () =>
+            readCheckStatusCache(
+              cacheIdentity,
+              cacheRepo,
+              pr,
+              cache.headSha,
+              now,
+              cache.watchPending,
+              directory,
+            ),
+          catch: () => null,
+        }).pipe(Effect.orElseSucceed(() => null));
+        if (cached !== null) return cached;
+        repo = cacheRepo;
+        identity = cacheIdentity;
+      }
+    }
+  }
+
+  const fetchedAt = yield* Clock.currentTimeMillis;
+  const checks = yield* gh
     .runGhJson<CheckResult[]>([...args, "--json", CHECK_JSON_FIELDS])
     .pipe(
       Effect.catchTag("GitHubCommandError", (error) =>
@@ -282,6 +356,20 @@ export const fetchCheckResults = Effect.fn("pr.fetchCheckResults")(function* (pr
           : Effect.fail(error),
       ),
     );
+  if (
+    cache !== undefined &&
+    pr !== null &&
+    repo !== null &&
+    identity !== null &&
+    checks.length > 0
+  ) {
+    yield* Effect.tryPromise({
+      try: () =>
+        writeCheckStatusCache(identity, repo, pr, cache.headSha, checks, fetchedAt, directory),
+      catch: () => undefined,
+    }).pipe(Effect.orElseSucceed(() => undefined));
+  }
+  return checks;
 });
 
 const buildFailedChecksReport = Effect.fn("pr.buildFailedChecksReport")(function* (
@@ -289,6 +377,7 @@ const buildFailedChecksReport = Effect.fn("pr.buildFailedChecksReport")(function
   checks: CheckResult[],
   options: {
     withLogs: boolean;
+    fullLogs?: boolean;
     evidence?: { headSha: string | null; baseSha: string | null } | null;
   } = { withLogs: false },
 ) {
@@ -311,26 +400,22 @@ const buildFailedChecksReport = Effect.fn("pr.buildFailedChecksReport")(function
       Effect.catchTag("GitHubCommandError", () => Effect.succeed(null)),
     ));
 
-  const runContexts = new Map<number, FailedCheckRunContext | null>();
-  const contexts = yield* Effect.forEach(
-    runIds,
-    (runId) =>
-      fetchWorkflowRunFailureContext(runId).pipe(
-        Effect.map((context) => [runId, context] as const),
-      ),
-    { concurrency: "unbounded" },
+  const runContexts = new Map(
+    yield* Effect.forEach(
+      runIds,
+      (runId) =>
+        fetchWorkflowRunFailureContext(runId).pipe(Effect.map((found) => [runId, found] as const)),
+      { concurrency: "unbounded" },
+    ),
   );
 
-  for (const [runId, context] of contexts) {
-    runContexts.set(runId, context);
-  }
-
   const enrichedFailedChecks: FailedCheckDetail[] = yield* Effect.forEach(
     failedChecks,
     (check) =>
       Effect.gen(function* () {
         const runId = extractRunIdFromCheckLink(check.link);
-        const run = runId === null ? null : (runContexts.get(runId) ?? null);
+        const found = runId === null ? null : (runContexts.get(runId) ?? null);
+        const run = found?.context ?? null;
         const detail: FailedCheckDetail = { ...check, runId, run };
 
         if (!options.withLogs || runId === null) {
@@ -347,6 +432,7 @@ const buildFailedChecksReport = Effect.fn("pr.buildFailedChecksReport")(function
           job: matchedJob.name,
           jobId: matchedJob.databaseId,
           failedStepNames: matchedJob.failedSteps,
+          steps: found?.stepsByJob.get(matchedJob.databaseId) ?? [],
           failedStepsOnly: true,
           format: "json",
           repo: null,
@@ -355,12 +441,20 @@ const buildFailedChecksReport = Effect.fn("pr.buildFailedChecksReport")(function
         if (failedStepLogs === null || !("entries" in failedStepLogs) || !failedStepLogs.entries) {
           return detail;
         }
-        const formatted = formatLogEntries(failedStepLogs.entries);
+        const formatted = options.fullLogs
+          ? formatLogEntries(failedStepLogs.entries)
+          : summarizeFailedStepEntries(failedStepLogs.entries);
         return formatted.length > 0
           ? {
               ...detail,
               failedStepLogs: formatted,
-              diagnosis: diagnoseLogEntries(failedStepLogs.entries),
+              ...(run?.headSha !== null &&
+              run?.headSha !== undefined &&
+              evidence?.headSha !== null &&
+              evidence?.headSha !== undefined &&
+              run.headSha !== evidence.headSha
+                ? {}
+                : { diagnosis: diagnoseLogEntries(failedStepLogs.entries) }),
             }
           : detail;
       }),
@@ -376,10 +470,12 @@ const buildFailedChecksReport = Effect.fn("pr.buildFailedChecksReport")(function
         }
 
         const commands = [`bun agent-tools-gh workflow view --run ${check.runId}`];
-        const firstFailedJob = check.run?.failedJobs[0];
-        if (firstFailedJob) {
+        const matchedJob = check.run
+          ? matchFailedJobForCheck(check.name, check.run.failedJobs)
+          : null;
+        if (matchedJob) {
           commands.push(
-            `bun agent-tools-gh workflow job-logs --run ${check.runId} --job ${JSON.stringify(firstFailedJob.name)} --failed-steps-only`,
+            `bun agent-tools-gh workflow job-logs --run ${check.runId} --job ${JSON.stringify(matchedJob.name)} --failed-steps-only`,
           );
         }
 
@@ -398,6 +494,20 @@ const buildFailedChecksReport = Effect.fn("pr.buildFailedChecksReport")(function
         ? `Detected ${failedChecks.length} failed check(s) while ${pendingChecks.length} check(s) are still running.`
         : `Detected ${failedChecks.length} failed check(s).`;
 
+  let remainingLogCharacters = 16_000;
+  const reportFailedChecks = options.fullLogs
+    ? enrichedFailedChecks
+    : enrichedFailedChecks.map((check) => {
+        if (check.failedStepLogs === undefined) return check;
+        const limit = Math.max(0, remainingLogCharacters);
+        remainingLogCharacters -= check.failedStepLogs.length;
+        return check.failedStepLogs.length <= limit
+          ? check
+          : Object.assign({}, check, {
+              failedStepLogs: `${check.failedStepLogs.slice(0, Math.max(0, limit - 40))}\n… report log summary omitted`,
+            });
+      });
+
   const hint =
     failedChecks.length === 0
       ? pendingChecks.length > 0
@@ -417,7 +527,7 @@ const buildFailedChecksReport = Effect.fn("pr.buildFailedChecksReport")(function
       pending: pendingChecks.length,
       passed: passedChecks.length,
     },
-    failedChecks: enrichedFailedChecks,
+    failedChecks: reportFailedChecks,
     pendingChecks,
     hint,
     nextCommands,
@@ -1432,13 +1542,8 @@ export const fetchChecks = Effect.fn("pr.fetchChecks")(function* (
       watchArgs.push("--fail-fast");
     }
 
-    // Block for the caller's requested --timeout (no artificial cap — blocking isn't the problem;
-    // --timeout is validated >= 1s at the CLI boundary). On timeout return a snapshot, never
-    // nothing — that was the actual token-wasting bug.
-    // A push registers its checks a moment after the ref lands, and `gh pr checks --watch`
-    // exits non-zero in that window. A watch was asked to wait, so keep waiting: the outer
-    // timeout still bounds it, and a PR that genuinely has no checks returns an empty
-    // snapshot at that deadline rather than an error.
+    // A push can register checks after the ref lands. Wait through that window
+    // within the caller's timeout, then report the final snapshot.
     let watchResult: GhResult | null = null;
     let registered = false;
     let graceExpired = false;
@@ -1489,12 +1594,14 @@ export const fetchChecks = Effect.fn("pr.fetchChecks")(function* (
           `likely dropped, and re-watching will find nothing again — dispatch them on the PR ` +
           `head instead:\n   agent-tools-gh pr trigger-checks --pr ${prRef} --workflow <file.yml>`,
       );
-    } else if (!quiet && watchOutcome === null && results.some((c) => c.bucket === "pending")) {
-      const pending = results.filter((c) => c.bucket === "pending").length;
-      yield* Console.warn(
-        `ℹ️  Watch timed out after ${timeoutSeconds}s; ${pending} check(s) still pending (snapshot returned). ` +
-          `Re-run to keep watching:\n   ${buildChecksCommand(pr, true)}`,
-      );
+    }
+    if (watchOutcome === null && results.some((check) => check.bucket === "pending")) {
+      const pending = results.filter((check) => check.bucket === "pending").length;
+      yield* logFormatted(results, quiet ? "json" : "toon");
+      return yield* new GitHubTimeoutError({
+        message: `Watch timed out, ${pending} pending after ${timeoutSeconds}s. This is not a CI verdict.`,
+        timeoutMs: timeoutSeconds * 1000,
+      });
     }
     return results;
   }
@@ -1592,6 +1699,7 @@ export const collectWithStableState = <S, A, E1, R1, E2, R2>(
 export const fetchFailedChecks = Effect.fn("pr.fetchFailedChecks")(function* (
   pr: number | null,
   withLogs = false,
+  fullLogs = false,
 ) {
   const initial = yield* viewPR(pr);
   const snapshot = yield* collectWithStableState(
@@ -1605,7 +1713,8 @@ export const fetchFailedChecks = Effect.fn("pr.fetchFailedChecks")(function* (
   );
   if (snapshot !== null) {
     return yield* buildFailedChecksReport(snapshot.state.number, snapshot.value, {
-      withLogs,
+      withLogs: withLogs || fullLogs,
+      fullLogs,
       evidence: { headSha: snapshot.state.headSha, baseSha: snapshot.state.baseSha },
     });
   }
@@ -1711,7 +1820,14 @@ export const watchPRs = Effect.fn("pr.watchPRs")(function* (
       const initial = yield* watchPRState(pr);
       const stableResult = yield* collectWithStableState(
         initial,
-        () => requireDeadline.pipe(Effect.andThen(fetchCheckResults(pr))),
+        (state) =>
+          requireDeadline.pipe(
+            Effect.andThen(
+              state.headRefOid
+                ? fetchCheckResults(pr, { headSha: state.headRefOid, watchPending: true })
+                : fetchCheckResults(pr),
+            ),
+          ),
         () => requireDeadline.pipe(Effect.andThen(watchPRState(pr))),
         (before, after) => before.headRefOid === after.headRefOid && before.state === after.state,
       ).pipe(Effect.result);
@@ -1770,7 +1886,13 @@ export const watchPRs = Effect.fn("pr.watchPRs")(function* (
             timedOut = true;
             break;
           }
-          const state = yield* snapshot(number);
+          const remainingMs = Math.max(1, deadline - Number(yield* Clock.currentTimeMillis));
+          const state = yield* snapshot(number).pipe(
+            Effect.timeoutOrElse({
+              duration: remainingMs,
+              orElse: () => Effect.succeed("timeout" as const),
+            }),
+          );
           if (state === "timeout") {
             timedOut = true;
             break;
@@ -1870,12 +1992,27 @@ export const watchPRs = Effect.fn("pr.watchPRs")(function* (
       }),
     step: () => undefined,
   });
+  const watcherTimedOut = terminal.size < prs.length;
   yield* emit({
     type: "watcher_terminal",
     repo: `${repo.owner}/${repo.name}`,
-    status: terminal.size === prs.length ? "terminal" : "timeout",
+    status: watcherTimedOut ? "timeout" : "terminal",
     terminal: [...terminal].toSorted((a, b) => a - b),
+    ...(watcherTimedOut
+      ? {
+          verdict: null,
+          message: `Watch timed out, ${prs.length - terminal.size} pending. This is not a CI verdict.`,
+          timeoutSeconds: options.timeoutSeconds,
+          pending: prs.filter((number) => !terminal.has(number)).toSorted((a, b) => a - b),
+        }
+      : {}),
   });
+  if (watcherTimedOut) {
+    return yield* new GitHubTimeoutError({
+      message: `Watch timed out, ${prs.length - terminal.size} pending. This is not a CI verdict.`,
+      timeoutMs: options.timeoutSeconds * 1000,
+    });
+  }
 });
 
 type RerunDiscovery = RerunCheckAttempt & { status?: string };
@@ -1906,14 +2043,13 @@ const readJobDiagnosis = Effect.fn("pr.readJobDiagnosis")(function* (
   attempt: number,
   repo: string,
 ) {
-  const gh = yield* GitHubService;
   const jobs = yield* fetchAttemptJobs(runId, attempt, repo);
   if (jobs === null) return null;
   const matches = jobs.filter((job) => job.name === jobName);
   if (matches.length !== 1) return null;
-  const logs = yield* gh
-    .runGh(["api", `repos/${repo}/actions/jobs/${matches[0]?.id}/logs`])
-    .pipe(Effect.catchTag("GitHubCommandError", () => Effect.succeed(null)));
+  const logs = yield* readJobLogApi(`repos/${repo}/actions/jobs/${matches[0]?.id}/logs`).pipe(
+    Effect.catchTag("GitHubCommandError", () => Effect.succeed(null)),
+  );
   return logs === null ? null : diagnoseLogEntries(parseRawJobLogs(logs.stdout));
 });
 

package/src/gh-tool/service.ts

@@ -224,6 +224,35 @@ export class GitHubService extends Context.Service<
               });
             }
 
+            if (/rate limit|abuse detection|HTTP 429/i.test(result.stderr)) {
+              const resource =
+                args[0] === "api"
+                  ? args[1]?.replace(/^\//, "") === "graphql"
+                    ? "graphql"
+                    : args[1]?.replace(/^\//, "").startsWith("search/")
+                      ? "search"
+                      : "core"
+                  : undefined;
+              const quotaFilter =
+                resource === undefined
+                  ? '.resources | to_entries[] | "\\(.key): reset time: \\(.value.reset | todateiso8601); remaining quota: \\(.value.remaining)"'
+                  : `.resources.${resource} | "reset time: \\(.reset | todateiso8601); remaining quota: \\(.remaining)"`;
+              const quota = yield* executeGh(["api", "rate_limit", "--jq", quotaFilter]).pipe(
+                Effect.orElseSucceed(() => null),
+              );
+              const detail =
+                quota?.exitCode === 0 && quota.stdout.trim()
+                  ? quota.stdout.trim()
+                  : "reset time: unavailable; remaining quota: unavailable (quota lookup failed)";
+              return yield* new GitHubCommandError({
+                message: `${result.stderr.trim()}; ${detail}`,
+                command: `gh ${args.join(" ")}`,
+                exitCode: result.exitCode,
+                stderr: result.stderr,
+                hint: "Wait until the quota resets before you retry. The failed command was not replayed.",
+              });
+            }
+
             // Transient network/5xx — flag retryable so the wrapper below can replay safe reads.
             if (NETWORK_ERROR_RE.test(result.stderr)) {
               return yield* new GitHubCommandError({