@blogic-cz/agent-tools 1.11.1 → 1.12.0

package/src/credential-guard/shell-oracle.ts

@@ -0,0 +1,187 @@
+import { formatLiteralPrintf } from "./literal-output";
+import { parseBash } from "./bash";
+import { judge } from "./policy";
+import { splitXargsInput, type XargsInput } from "./xargs";
+
+const quote = (text: string): string => "'" + text.replaceAll("'", "'\\''") + "'";
+const receipt: Record<string, { checked: number; refused: number; mismatches: unknown[] }> = {};
+async function compare(
+  family: string,
+  shell: string,
+  source: string,
+  modeled: readonly string[] | null,
+) {
+  const count = (receipt[family] ??= { checked: 0, refused: 0, mismatches: [] });
+  const child = Bun.spawn([shell, "-c", source], {
+    stdout: "pipe",
+    stderr: "pipe",
+    env: { PATH: "/usr/bin:/bin", HOME: "/tmp" },
+  });
+  const actual = await new Response(child.stdout).text();
+  await new Response(child.stderr).text();
+  await child.exited;
+  count.checked++;
+  if (modeled === null) count.refused++;
+  else if (family === "termination") {
+    const reached = actual.split("\n").includes("[reached]");
+    if (reached && !modeled.some((output) => output.includes("[reached]")))
+      count.mismatches.push({ shell, source, actual, modeled });
+  } else if (!modeled.includes(actual)) count.mismatches.push({ shell, source, actual, modeled });
+}
+function modeledOutput(source: string): readonly string[] | null {
+  const outputs: string[] = [];
+  let unresolved = false;
+  const decision = judge(parseBash(source), {
+    home: "/home/dev",
+    cwd: "/tmp",
+    onInvocation(executable, argv) {
+      if (executable === "/usr/bin/printf" && argv[1] === "[%s]\\n") {
+        if (argv.some((word) => word === undefined)) unresolved = true;
+        outputs.push(
+          (argv.length > 2 ? argv.slice(2) : [""]).map((word) => `[${word}]\n`).join(""),
+        );
+      }
+    },
+  });
+  return decision.kind === "pass" && !unresolved
+    ? outputs.length
+      ? [...outputs, outputs.join("")]
+      : [""]
+    : null;
+}
+const jobs: Array<() => Promise<void>> = [];
+const shells = ["/bin/bash", "/bin/sh", "/bin/zsh", "/bin/dash"];
+const available = await Promise.all(
+  shells.map(async (shell) => ({ shell, exists: await Bun.file(shell).exists() })),
+);
+for (const { shell, exists } of available) {
+  if (!exists) {
+    console.log(`SKIP missing shell ${shell}`);
+    continue;
+  }
+  const braces = [
+    "{a,}",
+    "{,}",
+    "{,b}",
+    "x{,b}",
+    "{a,b}{,c}",
+    "'{a,b}'",
+    '"{a,b}"',
+    "{a,{b,c}}",
+    "{a,}''",
+    "''{,b}",
+  ];
+  for (const left of ["a", "", "b"])
+    for (const right of ["", "c", "d"]) braces.push(`{${left},${right}}`, `p{${left},${right}}q`);
+  for (const words of braces) {
+    const source = `/usr/bin/printf '[%s]\\n' seed ${words}`;
+    const model =
+      shell.endsWith("/sh") || shell.endsWith("/dash")
+        ? `sh -c ${quote(source)}`
+        : shell.endsWith("/bash")
+          ? `bash -c ${quote(source)}`
+          : source;
+    jobs.push(() => compare("brace", shell, source, modeledOutput(model)));
+  }
+  for (const format of ["%s\\n", "%s ", "%s", "%s:%s\\n"])
+    for (const words of [[], ["alpha"], ["alpha", "beta"], ["", "beta"], ["a b", "c"]]) {
+      const source = `printf ${quote(format)} ${words.map(quote).join(" ")}`;
+      const modeled = formatLiteralPrintf([format, ...words]);
+      jobs.push(() => compare("printf", shell, source, modeled === null ? null : [modeled]));
+    }
+  for (const compound of [
+    "{ exit 0; }",
+    "(exit 0)",
+    "if true; then exit 0; fi",
+    "case x in x) exit 0;; esac",
+    "for x in a; do exit 0; done",
+    "while true; do exit 0; done",
+    "exit 0 && true",
+    "exit 0 || true",
+    "exit 0 && false || true",
+    "exit 0 || false && true",
+    "{ exit 0; } && true",
+    "! { exit 0; } || true",
+  ])
+    for (const redirect of ["&>/dev/null", "&>>/dev/null"]) {
+      const source = `${compound} ${redirect}; /usr/bin/printf '[%s]\\n' reached`;
+      jobs.push(() =>
+        compare(
+          "termination",
+          shell,
+          source,
+          modeledOutput(
+            `${shell.endsWith("/bash") || shell.endsWith("/zsh") ? "bash" : "sh"} -c ${quote(source)}`,
+          ),
+        ),
+      );
+    }
+  for (const command of ["exit", "return"])
+    for (const redirect of [
+      "",
+      " 2>/dev/null",
+      " &>/dev/null",
+      " &>>/dev/null",
+      " </tmp/guard-oracle-missing/input",
+      " >/dev/null/x",
+      " 2>&1",
+      " 2>&99",
+      " 1>&- 2>&1",
+    ])
+      for (const op of [";", "||"]) {
+        const source = `${command} 0${redirect} ${op} /usr/bin/printf '[%s]\\n' reached`;
+        jobs.push(() =>
+          compare(
+            "termination",
+            shell,
+            source,
+            modeledOutput(
+              `${shell.endsWith("/bash") || shell.endsWith("/zsh") ? "bash" : "sh"} -c ${quote(source)}`,
+            ),
+          ),
+        );
+      }
+}
+const modes: XargsInput[] = [
+  { replacement: null, maxArgs: null, maxLines: null },
+  { replacement: "{}", maxArgs: null, maxLines: null },
+  { replacement: null, maxArgs: 1, maxLines: null },
+  { replacement: null, maxArgs: null, maxLines: 1 },
+];
+const inputs = [
+  "a\nb\n",
+  "a b\n",
+  "'' word\n",
+  '"" word\n',
+  "a  b\n",
+  "a\tb\n",
+  "  a\n",
+  "a\n\nb\n",
+  "'a b'\n",
+  "a\\ b\n",
+];
+for (const a of ["a", "''", '""', " "])
+  for (const b of [" ", "  ", "\t", "\n"]) inputs.push(a + b + "b\n");
+for (const mode of modes)
+  for (const input of inputs) {
+    const groups = splitXargsInput(input, mode);
+    const output =
+      groups === null
+        ? null
+        : groups
+            .flatMap((words) => (words.length ? words : [""]).map((word) => `[${word}]\n`))
+            .join("");
+    const flags = mode.replacement ? "-I{}" : mode.maxArgs ? "-n1" : mode.maxLines ? "-L1" : "";
+    const source = `printf '%s' ${quote(input)} | /usr/bin/xargs ${flags} /usr/bin/printf '[%s]\\n' ${mode.replacement ? "'{}'" : ""}`;
+    jobs.push(() =>
+      compare(
+        `xargs-${flags || "default"}`,
+        "/bin/bash",
+        source,
+        output === null ? null : [output],
+      ),
+    );
+  }
+await jobs.reduce((previous, run) => previous.then(run), Promise.resolve());
+console.log(JSON.stringify(receipt, null, 2));
+if (Object.values(receipt).some((family) => family.mismatches.length)) process.exitCode = 1;

package/src/credential-guard/xargs.ts

@@ -0,0 +1,65 @@
+export type XargsInput = {
+  readonly replacement: string | null;
+  readonly maxArgs: number | null;
+  readonly maxLines: number | null;
+};
+
+export function splitXargsInput(text: string, mode: XargsInput): readonly string[][] | null {
+  if (/[^\t\n\x20-\x7e]/.test(text)) return null;
+  if (mode.replacement !== null && /['"\t]| {2}|^ |\n |\\/.test(text)) return null;
+  const lines: string[][] = [];
+  let words: string[] = [];
+  let word = "";
+  let started = false;
+  let quote = "";
+  const finishWord = () => {
+    if (started) words.push(word);
+    word = "";
+    started = false;
+  };
+  for (let index = 0; index < text.length; index++) {
+    const ch = text[index] ?? "";
+    if (ch === "\n") {
+      if (
+        quote ||
+        ((mode.maxLines !== null || mode.replacement !== null) &&
+          /[ \t]/.test(text[index - 1] ?? ""))
+      )
+        return null;
+      finishWord();
+      if (words.length) lines.push(words);
+      words = [];
+    } else if (ch === "\\" && !quote) {
+      const next = text[++index];
+      if (next === undefined || next === "\n") return null;
+      word += next;
+      started = true;
+    } else if ((ch === "'" || ch === '"') && (!quote || ch === quote)) {
+      quote = quote ? "" : ch;
+      started = true;
+    } else if (!quote && /[ \t]/.test(ch) && mode.replacement === null) {
+      finishWord();
+    } else if (mode.replacement !== null && !started && /[ \t]/.test(ch)) {
+      continue;
+    } else {
+      word += ch;
+      started = true;
+    }
+  }
+  if (quote) return null;
+  finishWord();
+  if (words.length) lines.push(words);
+  const result: string[][] = [];
+  if (mode.replacement !== null) result.push(...lines);
+  else if (mode.maxLines !== null) {
+    for (let index = 0; index < lines.length; index += mode.maxLines)
+      result.push(lines.slice(index, index + mode.maxLines).flat());
+  } else {
+    const all = lines.flat();
+    const size = mode.maxArgs ?? Math.max(all.length, 1);
+    for (let index = 0; index < all.length; index += size)
+      result.push(all.slice(index, index + size));
+  }
+  if (result.length > 64 || result.some((args) => args.length > 64)) return null;
+  return result.length ? result : null;
+}

package/src/gh-tool/main.ts

@@ -4,7 +4,8 @@ import { BunRuntime, BunServices } from "@effect/platform-bun";
 import { Effect, Layer } from "effect";
 
 import { makeSchemaCommand, renderCauseToStderr, VERSION } from "#shared";
-import { AuditServiceLayer, withAudit } from "#shared/audit";
+import { AuditService, AuditServiceLayer, withAudit } from "#shared/audit";
+import { openRequestTelemetry } from "#gh/read/telemetry-store";
 import { withRedactedOutput } from "#shared/output-boundary";
 import { ConfigServiceLayer } from "#config";
 import {
@@ -80,7 +81,9 @@ import {
 import { labelCreateCommand } from "./label";
 import { GitHubService } from "./read/transport";
 import { withReadCache } from "./read";
-import { cacheCommand } from "./read/commands";
+import { Telemetry } from "./read/telemetry";
+import { telemetryCommand } from "./read/telemetry-command";
+import { cacheCommand, rateLimitCommand } from "./read/commands";
 import {
   workflowAnnotationsCommand,
   workflowCancelCommand,
@@ -221,6 +224,7 @@ const mainCommand = Command.make("gh-tool", {}).pipe(
 
 Wraps the GitHub CLI (gh) with structured output for AI agents.
 Supports PR management, issue management, reviews, CI checks, and repo info.
+Use 'rate-limit' to inspect GitHub API quota without consuming it.
 
 WORKFLOW FOR AI AGENTS:
   1. Use 'pr view' to inspect current PR
@@ -250,6 +254,8 @@ WORKFLOW FOR AI AGENTS:
   24. Use 'gist list/view' to read gists and 'gist create --files a.ts --desc "..."' to share snippets`,
   ),
   Command.withSubcommands([
+    rateLimitCommand,
+    telemetryCommand,
     prCommand,
     issueCommand,
     repoCommand,
@@ -274,10 +280,28 @@ const MainLayer = GitHubService.layer.pipe(
   Layer.provideMerge(ConfigServiceLayer),
 );
 
-const program = withReadCache(withRedactedOutput(withAudit("gh", cli))).pipe(
-  Effect.provide(MainLayer),
-  Effect.tapCause(renderCauseToStderr),
-);
+const observed = Effect.gen(function* () {
+  const audit = yield* AuditService;
+  let store = null;
+  try {
+    store = openRequestTelemetry(audit.dbPath);
+  } catch {
+    /* Telemetry is optional. */
+  }
+  return yield* withReadCache(withRedactedOutput(withAudit("gh", cli))).pipe(
+    Effect.provideService(Telemetry, store),
+    Effect.ensuring(
+      Effect.sync(() => {
+        try {
+          store?.close();
+        } catch {
+          /* Best effort. */
+        }
+      }),
+    ),
+  );
+});
+const program = observed.pipe(Effect.provide(MainLayer), Effect.tapCause(renderCauseToStderr));
 
 BunRuntime.runMain(program, {
   disableErrorReporting: true,

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

@@ -524,8 +524,15 @@ export const prStatusCommand = Command.make(
     withRepo(
       repo,
       Effect.gen(function* () {
-        const result: PRStatusResult = yield* detectPRStatus();
-        yield* logFormatted(result, format);
+        const [result, rateLimit] = yield* Effect.all([
+          detectPRStatus(),
+          reads.getPRStatusRateLimit(),
+        ]);
+        const status: PRStatusResult & { readonly rateLimit: typeof rateLimit } = {
+          ...result,
+          rateLimit,
+        };
+        yield* logFormatted(status, format);
       }),
     ),
 ).pipe(

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

@@ -248,12 +248,12 @@ const fetchWorkflowRunFailureContext = Effect.fn("pr.fetchWorkflowRunFailureCont
 
 // `gh pr checks` exits 1 on an *empty* result ("no checks reported on the 'x' branch"). Zero checks
 // is an ordinary state, so it is not an error, but it is also not an empty list: a PR with green
-// checks (sabservis/nexus-be#1396) once came back empty.
+// checks (example/example-be#1396) once came back empty.
 export const NO_CHECKS_REPORTED_RE = /no checks reported/i;
 // `gh` reports "no checks reported" both for the seconds after a push, before its checks
 // register, and forever for a PR that has none — the message cannot tell them apart. So the
 // wait for registration gets its own short budget: long enough to cover the race (measured
-// at roughly 40s on blogic-cz/agent-tools#134), short enough that a check-less PR is not held
+// at roughly 40 seconds), short enough that a check-less PR is not held
 // for the caller's whole --timeout.
 const CHECK_REGISTRATION_POLL_SECONDS = 5;
 const CHECK_REGISTRATION_GRACE_SECONDS = 60;

package/src/gh-tool/read/api.ts

@@ -1,3 +1,5 @@
+import { CacheRequest, recordRequest } from "./telemetry";
+
 import { Clock, Context, Effect } from "effect";
 
 import { registerResolvedSecret } from "#shared/content-security";
@@ -24,6 +26,36 @@ export type GitHubApiResponse<T> = {
   rateLimitUsed?: string;
 };
 
+export type GitHubRateLimitHeaders = {
+  readonly resource?: string;
+  readonly limit?: number;
+  readonly used?: number;
+  readonly remaining?: number;
+  readonly reset?: number;
+};
+
+const headerInteger = (headers: Headers, name: string) => {
+  const value = headers.get(name);
+  if (value === null || !/^\d+$/.test(value)) return undefined;
+  const parsed = Number(value);
+  return Number.isSafeInteger(parsed) ? parsed : undefined;
+};
+
+export const parseRateLimitHeaders = (headers: Headers): GitHubRateLimitHeaders => {
+  const resource = headers.get("x-ratelimit-resource");
+  const limit = headerInteger(headers, "x-ratelimit-limit");
+  const used = headerInteger(headers, "x-ratelimit-used");
+  const remaining = headerInteger(headers, "x-ratelimit-remaining");
+  const reset = headerInteger(headers, "x-ratelimit-reset");
+  return {
+    ...(resource === null ? {} : { resource }),
+    ...(limit === undefined ? {} : { limit }),
+    ...(used === undefined ? {} : { used }),
+    ...(remaining === undefined ? {} : { remaining }),
+    ...(reset === undefined ? {} : { reset }),
+  };
+};
+
 const authFailure = (message: string) =>
   new GitHubAuthError({
     message,
@@ -106,6 +138,8 @@ const githubApiAttempt = Effect.fn("gh.githubApiAttempt")(function* <T>(
   const token = yield* resolveGitHubToken();
   const url = `${GITHUB_API_ROOT}/${opts.path.replace(/^\//, "")}`;
 
+  const cached = yield* CacheRequest;
+  const started = new Date().toISOString();
   const response = yield* Effect.tryPromise({
     try: () =>
       fetch(url, {
@@ -128,8 +162,41 @@ const githubApiAttempt = Effect.fn("gh.githubApiAttempt")(function* <T>(
         retryable: true,
         hint: "Check network connectivity and VPN state, then retry.",
       }),
-  });
+  }).pipe(
+    Effect.tapError(() =>
+      recordRequest({
+        ts: started,
+        method,
+        endpoint: opts.path,
+        status: null,
+        outcome: "error",
+        resource: null,
+        used: null,
+        remaining: null,
+        reset: null,
+      }),
+    ),
+  );
 
+  const quota = parseRateLimitHeaders(response.headers);
+  yield* recordRequest({
+    ts: started,
+    method,
+    endpoint: opts.path,
+    status: response.status,
+    outcome:
+      response.status === 304
+        ? "304"
+        : response.status >= 400
+          ? "error"
+          : cached
+            ? "200"
+            : "bypass",
+    resource: quota.resource ?? null,
+    used: quota.used ?? null,
+    remaining: quota.remaining ?? null,
+    reset: quota.reset ?? null,
+  });
   const text = yield* Effect.tryPromise({
     try: () => response.text(),
     catch: (cause) =>
@@ -176,7 +243,8 @@ const githubApiAttempt = Effect.fn("gh.githubApiAttempt")(function* <T>(
   }
 
   const now = yield* Clock.currentTimeMillis;
-  const resetSeconds = Number(response.headers.get("x-ratelimit-reset"));
+  const rateLimitHeaders = parseRateLimitHeaders(response.headers);
+  const resetSeconds = rateLimitHeaders.reset ?? Number.NaN;
   const resetDelay =
     Number.isFinite(resetSeconds) && resetSeconds > 0
       ? Math.max(0, resetSeconds * 1000 - now + 1000)
@@ -200,18 +268,17 @@ const githubApiAttempt = Effect.fn("gh.githubApiAttempt")(function* <T>(
         /rate limit|secondary rate limit|abuse detection/i.test(
           apiErrorMessage(parsed, response.status),
         )));
-
   const error = new GitHubCommandError({
     message: rateLimit
-      ? `${apiErrorMessage(parsed, response.status)}; reset time: ${resetDelay === undefined ? "unavailable" : new Date(resetSeconds * 1000).toISOString()}; remaining quota: ${response.headers.get("x-ratelimit-remaining") ?? "unavailable"}`
+      ? `${apiErrorMessage(parsed, response.status)}; resource: ${rateLimitHeaders.resource ?? "unavailable"}; reset time: ${rateLimitHeaders.reset === undefined ? "unavailable" : new Date(resetSeconds * 1000).toISOString()}; remaining quota: ${rateLimitHeaders.remaining ?? "unavailable"}`
       : apiErrorMessage(parsed, response.status),
     command: `${method} ${opts.path}`,
     exitCode: response.status,
     stderr: text,
     ...(rateLimit
       ? {
-          hint: "Wait for the reset before retrying. Check the remaining quota once with the shown command; it does not consume the quota.",
-          nextCommand: "gh api rate_limit",
+          hint: "Wait for the reset before retrying. Check the named resource with the shown command; the lookup does not consume quota.",
+          nextCommand: "gh-tool rate-limit",
         }
       : {}),
     ...(response.status >= 500 || (rateLimit && canWait) ? { retryable: true } : {}),

package/src/gh-tool/read/cache.ts

@@ -1,3 +1,4 @@
+import { CacheRequest, cacheEvent, recordRequest } from "./telemetry";
 import { Console, Context, Effect } from "effect";
 import { resolveGitHubToken, SessionCredential } from "#gh/read/api";
 import { GitHubCommandError } from "#gh/errors";
@@ -86,16 +87,23 @@ export const cachedRead = <A, E, R>(opts: {
       ),
     );
     if (prepared === null) return yield* direct();
-    if (prepared.kind === "hit") return prepared.value;
+    if (prepared.kind === "hit") {
+      yield* recordRequest(cacheEvent(opts.key.op));
+      return prepared.value;
+    }
     return yield* Effect.gen(function* () {
       yield* safe(session, () => store.record(opts.key.op, "fetch"));
       const previousValid =
         prepared.previous === null
           ? false
           : yield* safe(session, () => store.canServeStale(prepared));
-      const fetched = yield* opts.fetch(
-        prepared.previous === null ? null : { ...prepared.previous, valid: previousValid === true },
-      );
+      const fetched = yield* opts
+        .fetch(
+          prepared.previous === null
+            ? null
+            : { ...prepared.previous, valid: previousValid === true },
+        )
+        .pipe(Effect.provideService(CacheRequest, true));
       if (fetched.kind === "unchanged") {
         if (prepared.previous === null)
           return yield* Effect.die(new Error("304 without a cached value"));
@@ -131,6 +139,7 @@ export const cachedRead = <A, E, R>(opts: {
             session.staleWarned = true;
             yield* Console.error(`gh-tool: served cached ${opts.key.op} (rate limited)`);
           }
+          yield* recordRequest(cacheEvent(opts.key.op));
           yield* safe(session, () => store.record(opts.key.op, "stale"));
           return prepared.previous.value;
         }),

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

@@ -2,7 +2,23 @@ import { Effect, Option } from "effect";
 import { Command, Flag } from "effect/cli";
 import { formatOption, logFormatted } from "#shared";
 import { cacheStats, clearCache } from "./cache";
-import { resolveRepo } from "./reads";
+import { getRateLimit, resolveRepo } from "./reads";
+
+export const rateLimitCommand = Command.make(
+  "rate-limit",
+  {
+    resource: Flag.String("resource").pipe(
+      Flag.withDescription("Show one GitHub rate-limit resource"),
+      Flag.optional,
+    ),
+    format: formatOption,
+  },
+  ({ resource, format }) =>
+    Effect.gen(function* () {
+      const summary = yield* getRateLimit(Option.getOrUndefined(resource));
+      yield* logFormatted(summary, format);
+    }),
+).pipe(Command.withDescription("Show GitHub API rate-limit resources and reset times"));
 
 const stats = Command.make("stats", { format: formatOption }, ({ format }) =>
   Effect.gen(function* () {

package/src/gh-tool/read/reads.ts

@@ -1,4 +1,4 @@
-import { Effect, Schema } from "effect";
+import { Clock, Effect, Result, Schema } from "effect";
 import { GitHubService } from "#gh/read/transport";
 import { GitHubCommandError } from "#gh/errors";
 import type { CheckRunAnnotation } from "#gh/types";
@@ -21,6 +21,87 @@ import {
 
 export type JobRef = { readonly id: number; readonly status: string };
 
+const RateLimitResponse = Schema.Struct({
+  resources: Schema.Record(
+    Schema.String,
+    Schema.Struct({
+      limit: Schema.Int,
+      used: Schema.Int,
+      remaining: Schema.Int,
+      reset: Schema.Int,
+    }),
+  ),
+});
+
+export type RateLimitResource = {
+  readonly limit: number;
+  readonly used: number;
+  readonly remaining: number;
+  readonly reset: string;
+  readonly secondsUntilReset: number;
+};
+
+export type RateLimitSummary = Readonly<Record<string, RateLimitResource>>;
+export type PRStatusRateLimit =
+  | Readonly<{ core: RateLimitResource; graphql: RateLimitResource }>
+  | Readonly<{ error: string }>;
+
+export const getRateLimit = Effect.fn("reads.getRateLimit")(function* (resource?: string) {
+  const gh = yield* GitHubService;
+  const response = yield* gh.runGhJson<unknown>(["api", "rate_limit"]);
+  const parsed = yield* Effect.try({
+    try: () => parsePreserving(RateLimitResponse)(response),
+    catch: (cause) =>
+      new GitHubCommandError({
+        message: `GitHub rate-limit response was invalid: ${String(cause)}`,
+        command: "gh-tool rate-limit",
+        exitCode: 1,
+        stderr: String(cause),
+      }),
+  });
+  const names = Object.keys(parsed.resources).toSorted();
+  const now = (yield* Clock.currentTimeMillis) / 1000;
+  const selected = resource === undefined ? names : [resource];
+  const entries: Array<[string, RateLimitResource]> = [];
+  for (const name of selected) {
+    const bucket = parsed.resources[name];
+    if (bucket === undefined) {
+      return yield* new GitHubCommandError({
+        message: `Unknown rate-limit resource '${name}'. Available resources: ${names.join(", ")}`,
+        command: "gh-tool rate-limit",
+        exitCode: 1,
+        stderr: "",
+        hint: "Select a resource returned by GitHub, or omit --resource to show all resources.",
+      });
+    }
+    entries.push([
+      name,
+      {
+        limit: bucket.limit,
+        used: bucket.used,
+        remaining: bucket.remaining,
+        reset: new Date(bucket.reset * 1000).toISOString(),
+        secondsUntilReset: Math.max(0, Math.ceil(bucket.reset - now)),
+      },
+    ]);
+  }
+  return Object.fromEntries(entries) satisfies RateLimitSummary;
+});
+
+export const getPRStatusRateLimit = Effect.fn("reads.getPRStatusRateLimit")(function* () {
+  const result = yield* getRateLimit().pipe(Effect.result);
+  if (Result.isFailure(result))
+    return { error: result.failure.message } satisfies PRStatusRateLimit;
+
+  const { core, graphql } = result.success;
+  if (core === undefined || graphql === undefined) {
+    return {
+      error: "GitHub rate-limit response omitted the core or graphql resource.",
+    } satisfies PRStatusRateLimit;
+  }
+  return { core, graphql } satisfies PRStatusRateLimit;
+});
+
 const completedAttemptJobs = Effect.fn("reads.completedAttemptJobs")(function* (
   repo: RepoRef,
   runId: number,
@@ -282,6 +363,8 @@ const jobIdentity = Effect.fn("reads.jobIdentity")(function* (repo: RepoRef, job
 });
 
 export const reads = {
+  getRateLimit,
+  getPRStatusRateLimit,
   completedAttemptJobs,
   jobIdentity,
   reviewGuards,