pr-shepherd 0.7.0 → 0.8.0

package/bin/commands/monitor.mjs

@@ -0,0 +1,78 @@
+import { getCurrentPrNumber } from "../github/client.mjs";
+import { loadConfig } from "../config/load.mjs";
+export async function runMonitor(opts) {
+    const config = loadConfig();
+    const prNumber = opts.prNumber ?? (await getCurrentPrNumber());
+    if (prNumber === null) {
+        throw new Error("No open PR found for current branch. Pass a PR number explicitly.");
+    }
+    const { interval, maxTurns, expiresHours } = config.watch;
+    if (typeof interval !== "string" || !/^\d+[smhd]$/.test(interval)) {
+        throw new Error(`Invalid config: watch.interval must be a duration string like "4m" or "1h", got ${JSON.stringify(interval)}`);
+    }
+    if (!Number.isFinite(expiresHours) || expiresHours <= 0 || !Number.isInteger(expiresHours)) {
+        throw new Error(`Invalid config: watch.expiresHours must be a positive integer, got ${JSON.stringify(expiresHours)}`);
+    }
+    if (!Number.isFinite(maxTurns) || maxTurns <= 0 || !Number.isInteger(maxTurns)) {
+        throw new Error(`Invalid config: watch.maxTurns must be a positive integer, got ${JSON.stringify(maxTurns)}`);
+    }
+    const loopTag = `# pr-shepherd-loop:pr=${prNumber}`;
+    const loopPrompt = buildLoopPrompt(prNumber, loopTag, opts.readyDelaySuffix);
+    const loopArgs = `${interval} --max-turns ${maxTurns} --expires ${expiresHours}h`;
+    return { prNumber, loopTag, loopArgs, loopPrompt };
+}
+// ---------------------------------------------------------------------------
+// Formatters
+// ---------------------------------------------------------------------------
+export function formatMonitorResult(result) {
+    const { prNumber, loopTag, loopArgs, loopPrompt } = result;
+    return [
+        `# PR #${prNumber} [MONITOR]`,
+        "",
+        `Loop tag: \`${loopTag}\``,
+        `Loop args: \`${loopArgs}\``,
+        "",
+        "## Loop prompt",
+        "",
+        loopPrompt,
+        "",
+        "## Instructions",
+        "",
+        `1. Run \`CronList\`. If any job's prompt contains \`${loopTag}\`, run the \`## Loop prompt\` body once inline (as if it were a cron tick) then stop — do not create a duplicate loop.`,
+        `2. Otherwise, invoke the \`/loop\` skill via the Skill tool. Build the \`args\` parameter as: only the value inside the backticks on the \`Loop args\` line above (the interval/flags string — not the \`Loop args:\` label), then a blank line, then the full \`## Loop prompt\` body.`,
+    ].join("\n");
+}
+// ---------------------------------------------------------------------------
+// Internal
+// ---------------------------------------------------------------------------
+function validateReadyDelaySuffix(readyDelaySuffix) {
+    if (readyDelaySuffix === undefined)
+        return undefined;
+    const trimmed = readyDelaySuffix.trim();
+    if (!/^\d+(?:m|min|minutes?|h|hours?)$/.test(trimmed)) {
+        throw new Error(`Invalid --ready-delay: ${readyDelaySuffix}. Expected a duration like 5m, 2h, 10m, or 1h.`);
+    }
+    return trimmed;
+}
+function buildLoopPrompt(prNumber, loopTag, readyDelaySuffix) {
+    const validatedDelay = validateReadyDelaySuffix(readyDelaySuffix);
+    const iterateCmd = validatedDelay
+        ? `npx pr-shepherd iterate ${prNumber} --no-cache --ready-delay ${validatedDelay}`
+        : `npx pr-shepherd iterate ${prNumber} --no-cache`;
+    return [
+        loopTag,
+        "",
+        "**IMPORTANT — recurrence rules:**",
+        "- **Do NOT call `ScheduleWakeup` or `/loop`.** This session is fired by a recurring cron job. Either call creates a duplicate runner, causing concurrent git operations and `.git/index.lock` collisions.",
+        "- End the turn cleanly after completing the actions below. The cron job handles the next fire.",
+        "",
+        `**Self-dedup:** Run \`CronList\`. If more than one job contains \`${loopTag}\`, keep the lowest job ID and \`CronDelete\` the rest (ignore errors — a concurrent runner may have already deleted them).`,
+        "",
+        "Run in a single Bash call:",
+        `  ${iterateCmd}`,
+        "",
+        `Exit codes 0–3 are all valid. If the command crashes (non-zero exit, no markdown output starting with \`# PR #${prNumber} [\`), log the first line of stderr and continue — do not cancel the loop. The next cron fire will retry.`,
+        "",
+        "The output is Markdown. The first line is an H1 heading of the form `# PR #<N> [<ACTION>]`. Every output ends with a `## Instructions` section — follow those numbered steps exactly.",
+    ].join("\n");
+}

package/bin/commands/ready-delay.mjs

@@ -2,7 +2,7 @@
  * Ready-delay state machine for the shepherd iterate loop.
  *
  * When all READY conditions hold, shepherd writes a `ready-since.txt` marker
- * to the cache dir. The loop continues until the PR has been READY for
+ * to the state dir. The loop continues until the PR has been READY for
  * `readyDelaySeconds` consecutively. Any not-READY result resets the timer.
  */
 import { readFile, writeFile, mkdir, unlink } from "node:fs/promises";
@@ -47,8 +47,7 @@ export async function updateReadyDelay(prNumber, isReady, readyDelaySeconds, own
     const elapsed = now - readySince;
     const remaining = readyDelaySeconds - elapsed;
     if (remaining <= 0) {
-        // Leave the marker in place so future sweeps also return shouldCancel:true
-        // until the PR drops out of READY state (which resets via safeUnlink above).
+        await safeUnlink(markerPath);
         return { isReady: true, shouldCancel: true, remainingSeconds: 0 };
     }
     return { isReady: true, shouldCancel: false, remainingSeconds: remaining };
@@ -65,7 +64,7 @@ function readySincePath(pr, owner, repo) {
             throw new Error(`Invalid path segment "${field}": ${value}`);
         }
     }
-    const base = process.env["PR_SHEPHERD_CACHE_DIR"] ?? join(tmpdir(), "pr-shepherd-cache");
+    const base = process.env["PR_SHEPHERD_STATE_DIR"] ?? join(tmpdir(), "pr-shepherd-state");
     return join(base, `${owner}-${repo}`, String(pr), "ready-since.txt");
 }
 async function safeUnlink(path) {

package/bin/commands/resolve-instructions.mjs

@@ -0,0 +1,39 @@
+/**
+ * Build the numbered triage/fix/resolve instruction steps for the agent to follow.
+ * Steps are conditionally emitted based on what the fetch returned (mirrors
+ * `buildFixInstructions` in `commands/iterate/render.mts`).
+ */
+export function buildFetchInstructions(prNumber, result) {
+    const { actionableThreads, actionableComments, changesRequestedReviews, reviewSummaries, commitSuggestionsEnabled, } = result;
+    const total = actionableThreads.length +
+        actionableComments.length +
+        changesRequestedReviews.length +
+        reviewSummaries.length;
+    if (total === 0) {
+        return ["No actionable items — end this invocation."];
+    }
+    const hasCodeItems = actionableThreads.length > 0 ||
+        actionableComments.length > 0 ||
+        changesRequestedReviews.length > 0;
+    const hasSuggestions = commitSuggestionsEnabled && actionableThreads.some((t) => t.suggestion != null);
+    const instructions = [];
+    instructions.push(`Classify every item listed above into exactly one of: Fixed / Actionable / Not relevant / Outdated / Acknowledge. Do not silently skip any item. Bot-authored review summaries (authors whose name contains \`[bot]\` or matches \`copilot-pull-request-reviewer\`, \`gemini-code-assist\`) default to Acknowledge with reason "bot summary — no actionable content" unless the body calls out an unaddressed issue.`);
+    if (hasSuggestions) {
+        instructions.push(`For each Actionable thread marked \`[suggestion]\` in \`## Actionable Review Threads\` above: run \`npx pr-shepherd commit-suggestion ${prNumber} --thread-id <id> --message "<one-sentence headline>" --format=json\`, one thread at a time. On \`applied: true\` mark it Fixed — the CLI already resolved the thread, so exclude the ID from \`--resolve-thread-ids\`. On \`applied: false\` read \`reason\` and \`patch\`, then fall through to the manual fix step — do not retry the same command. Optionally pass \`--dry-run\` (omitting \`--message\`) if you want to inspect the unified diff before it mutates the working tree — the CLI validates with \`git apply --check\`, returns the patch and \`valid: true/false\`, and exits \`1\` on drift without committing or resolving the thread.`);
+    }
+    if (hasCodeItems) {
+        instructions.push(`Read and edit each file referenced under \`## Actionable Review Threads\`, \`## Actionable PR Comments\`, and \`## Pending CHANGES_REQUESTED reviews\` above. Reclassify each fixed item as Fixed. If an item is too complex to address, leave it as Actionable for the final report.`);
+        instructions.push(`Commit changed files: \`git add <files>\` (not \`git add -A\`) \`&& git commit -m "<descriptive message>"\`. If the fixes alter the PR's scope or intent, run \`gh pr edit ${prNumber} --title "<new title>" --body "<new body>"\` to reflect them. Then rebase and push: \`BASE_BRANCH=$(gh pr view ${prNumber} --json baseRefName --jq .baseRefName) && git fetch origin && git rebase "origin/$BASE_BRANCH" && git push --force-with-lease\`. Cancel stale in-progress runs: \`BRANCH=$(git rev-parse --abbrev-ref HEAD) && gh run list --branch "$BRANCH" --status in_progress --json databaseId --jq '.[].databaseId' | xargs -I{} gh run cancel {}\`.`);
+    }
+    const requireShaHint = hasCodeItems
+        ? ` Include \`--require-sha $(git rev-parse HEAD)\` only when the commit-and-push step above ran.`
+        : "";
+    const dismissNote = changesRequestedReviews.length > 0
+        ? ` For \`--dismiss-review-ids\`: \`--message\` is required with one specific sentence describing the fix or the reason for not acting (no boilerplate like "address review comments"); omit \`--message\` when not dismissing. Review-summary IDs (\`PRR_…\` from \`## Review summaries\`) go into \`--minimize-comment-ids\`, never \`--dismiss-review-ids\`.`
+        : reviewSummaries.length > 0
+            ? ` Review-summary IDs (\`PRR_…\` from \`## Review summaries\`) go into \`--minimize-comment-ids\`.`
+            : "";
+    instructions.push(`Run \`npx pr-shepherd resolve ${prNumber} [--resolve-thread-ids <ids>] [--minimize-comment-ids <ids>] [--dismiss-review-ids <ids> --message "<reason>"]\` with only the non-empty flag subsets. Skip the command entirely if all three ID lists are empty.${requireShaHint}${dismissNote}`);
+    instructions.push(`Report: echo the CLI's mutation output, then one line per Acknowledged item: \`Acknowledged <id> (@<author>): <reason>\`. If any fetched item was neither resolved nor acknowledged, stop and escalate: "<N> item(s) fetched but not acted on or acknowledged — need human direction before closing".`);
+    return instructions;
+}

package/bin/commands/resolve.mjs

@@ -18,6 +18,8 @@ import { fetchPrBatch } from "../github/batch.mjs";
 import { getOutdatedThreads } from "../comments/outdated.mjs";
 import { autoResolveOutdated, applyResolveOptions } from "../comments/resolve.mjs";
 import { loadConfig } from "../config/load.mjs";
+import { parseSuggestion } from "../suggestions/parse.mjs";
+import { buildFetchInstructions } from "./resolve-instructions.mjs";
 /**
  * Fetch mode: auto-resolve outdated threads and return all active items for LLM triage.
  */
@@ -36,16 +38,45 @@ export async function runResolveFetch(opts) {
     if (outdated.length > 0) {
         const { errors } = await autoResolveOutdated(outdated.map((t) => t.id));
         if (errors.length > 0) {
-            throw new Error(`Failed to auto-resolve outdated threads: ${errors.join(", ")}`);
+            process.stderr.write(`pr-shepherd: auto-resolve outdated threads failed (continuing): ${errors.join(", ")}\n`);
         }
     }
     const activeThreads = unresolvedThreads.filter((t) => !t.isOutdated);
     const cfg = loadConfig();
-    return {
-        actionableThreads: activeThreads.map(({ isResolved: _r, isOutdated: _o, ...rest }) => rest),
+    const actionableThreads = activeThreads.map(({ isResolved: _r, isOutdated: _o, ...rest }) => {
+        const thread = rest;
+        const suggestion = extractSuggestion(rest);
+        if (suggestion)
+            thread.suggestion = suggestion;
+        return thread;
+    });
+    const result = {
+        prNumber,
+        actionableThreads,
         actionableComments: visibleComments,
         changesRequestedReviews: data.changesRequestedReviews,
         reviewSummaries: cfg.resolve.fetchReviewSummaries ? data.reviewSummaries : [],
+        commitSuggestionsEnabled: cfg.actions.commitSuggestions,
+    };
+    return { ...result, instructions: buildFetchInstructions(prNumber, result) };
+}
+/**
+ * Attach a parsed suggestion block to a thread if the comment body contains one
+ * and the thread has a resolvable line anchor. Threads without `path`/`line`
+ * (rare — usually file-level comments) can't accept a suggestion commit.
+ */
+function extractSuggestion(thread) {
+    if (!thread.path || thread.line === null)
+        return null;
+    const parsed = parseSuggestion(thread.body);
+    if (!parsed)
+        return null;
+    const startLine = thread.startLine ?? thread.line;
+    return {
+        startLine,
+        endLine: thread.line,
+        lines: parsed.lines,
+        author: thread.author,
     };
 }
 /**

package/bin/commands/status.mjs

@@ -31,8 +31,15 @@ async function fetchSummary(pr, owner, repo) {
     // If the response was truncated, fetch additional pages to get the full count.
     if (p.reviewThreads.totalCount > p.reviewThreads.nodes.length) {
         // Fetch additional pages backward until we have all threads.
+        const MAX_THREAD_PAGES = 10;
+        let pagesFetched = 0;
+        const totalCount = p.reviewThreads.totalCount;
         let cursor = p.reviewThreads.pageInfo?.startCursor ?? null;
         while (cursor !== null) {
+            if (++pagesFetched > MAX_THREAD_PAGES) {
+                process.stderr.write(`pr-shepherd: thread pagination cap reached for PR #${pr}: fetched ${allNodes.length} of ${totalCount} threads\n`);
+                break;
+            }
             // eslint-disable-next-line no-await-in-loop
             const extra = await graphql(MULTI_PR_STATUS_QUERY_WITH_CURSOR, {
                 owner,

package/bin/comments/resolve.mjs

@@ -37,7 +37,7 @@ export async function applyResolveOptions(pr, repo, opts) {
     };
     await runBatched(opts.resolveThreadIds ?? [], (id) => resolveThread(id), result.resolvedThreads, result.errors);
     await runBatched(opts.minimizeCommentIds ?? [], (id) => minimizeComment(id, "RESOLVED"), result.minimizedComments, result.errors);
-    await runBatched(opts.dismissReviewIds ?? [], (id) => dismissReview(id, opts.dismissMessage), result.dismissedReviews, result.errors);
+    await runBatched(opts.dismissReviewIds ?? [], (id) => dismissReview(id, opts.dismissMessage ?? ""), result.dismissedReviews, result.errors);
     return result;
 }
 /**

package/bin/config/load.mjs

@@ -36,128 +36,32 @@ function deepMerge(base, override) {
     }
     return result;
 }
-// ---------------------------------------------------------------------------
-// Compatibility shim — maps old RC keys to new ones and emits deprecation warnings
-// ---------------------------------------------------------------------------
-function applyCompat(raw) {
-    const out = { ...raw };
-    // Removed top-level sections — warn and strip.
-    if ("execution" in out) {
-        process.stderr.write(`pr-shepherd: config section "execution" (maxBufferMb, triageLogBufferMb) has been removed and has no effect.\n`);
-        delete out["execution"];
-    }
-    // Removed keys — warn and strip.
-    for (const gone of ["baseBranch", "minimizeBots", "cancelCiOnFailure", "autoMinimize"]) {
-        if (gone in out) {
-            process.stderr.write(`pr-shepherd: config key "${gone}" has been removed and has no effect.\n`);
-            delete out[gone];
-        }
-    }
-    // Renamed top-level section keys — iterate
-    const iterate = out["iterate"];
-    if (iterate && "maxFixAttempts" in iterate) {
-        process.stderr.write(`pr-shepherd: config key "iterate.maxFixAttempts" renamed to "iterate.fixAttemptsPerThread".\n`);
-        out["iterate"] = {
-            ...iterate,
-            fixAttemptsPerThread: iterate["fixAttemptsPerThread"] ?? iterate["maxFixAttempts"],
-        };
-        delete out["iterate"]["maxFixAttempts"];
-    }
-    // Renamed watch keys
-    const watch = out["watch"];
-    if (watch) {
-        const watchOut = { ...watch };
-        if ("intervalDefault" in watch) {
-            process.stderr.write(`pr-shepherd: config key "watch.intervalDefault" renamed to "watch.interval".\n`);
-            watchOut["interval"] = watchOut["interval"] ?? watch["intervalDefault"];
-            delete watchOut["intervalDefault"];
-        }
-        if ("readyDelayMinutesDefault" in watch) {
-            process.stderr.write(`pr-shepherd: config key "watch.readyDelayMinutesDefault" renamed to "watch.readyDelayMinutes".\n`);
-            watchOut["readyDelayMinutes"] =
-                watchOut["readyDelayMinutes"] ?? watch["readyDelayMinutesDefault"];
-            delete watchOut["readyDelayMinutesDefault"];
-        }
-        if ("expiresHoursDefault" in watch) {
-            process.stderr.write(`pr-shepherd: config key "watch.expiresHoursDefault" renamed to "watch.expiresHours".\n`);
-            watchOut["expiresHours"] = watchOut["expiresHours"] ?? watch["expiresHoursDefault"];
-            delete watchOut["expiresHoursDefault"];
-        }
-        out["watch"] = watchOut;
-    }
-    // Renamed resolve keys (shaPollIntervalMs / shaPollMaxAttempts → shaPoll object)
-    const resolve = out["resolve"];
-    if (resolve) {
-        const resolveOut = { ...resolve };
-        const shaPollOut = {};
-        let shaPollChanged = false;
-        if ("shaPollIntervalMs" in resolve) {
-            process.stderr.write(`pr-shepherd: config key "resolve.shaPollIntervalMs" moved to "resolve.shaPoll.intervalMs".\n`);
-            shaPollOut["intervalMs"] =
-                resolve["shaPoll"]?.["intervalMs"] ??
-                    resolve["shaPollIntervalMs"];
-            delete resolveOut["shaPollIntervalMs"];
-            shaPollChanged = true;
-        }
-        if ("shaPollMaxAttempts" in resolve) {
-            process.stderr.write(`pr-shepherd: config key "resolve.shaPollMaxAttempts" moved to "resolve.shaPoll.maxAttempts".\n`);
-            shaPollOut["maxAttempts"] =
-                resolve["shaPoll"]?.["maxAttempts"] ??
-                    resolve["shaPollMaxAttempts"];
-            delete resolveOut["shaPollMaxAttempts"];
-            shaPollChanged = true;
-        }
-        if (shaPollChanged) {
-            resolveOut["shaPoll"] = {
-                ...resolveOut["shaPoll"],
-                ...shaPollOut,
-            };
-        }
-        out["resolve"] = resolveOut;
-    }
-    // Renamed checks keys
-    const checks = out["checks"];
-    if (checks) {
-        const checksOut = { ...checks };
-        if ("relevantEvents" in checks) {
-            process.stderr.write(`pr-shepherd: config key "checks.relevantEvents" renamed to "checks.ciTriggerEvents".\n`);
-            checksOut["ciTriggerEvents"] = checksOut["ciTriggerEvents"] ?? checks["relevantEvents"];
-            delete checksOut["relevantEvents"];
-        }
-        if ("logLinesKept" in checks) {
-            process.stderr.write(`pr-shepherd: config key "checks.logLinesKept" renamed to "checks.logMaxLines".\n`);
-            checksOut["logMaxLines"] = checksOut["logMaxLines"] ?? checks["logLinesKept"];
-            delete checksOut["logLinesKept"];
-        }
-        if ("logExcerptMaxChars" in checks) {
-            process.stderr.write(`pr-shepherd: config key "checks.logExcerptMaxChars" renamed to "checks.logMaxChars".\n`);
-            checksOut["logMaxChars"] = checksOut["logMaxChars"] ?? checks["logExcerptMaxChars"];
-            delete checksOut["logExcerptMaxChars"];
-        }
-        out["checks"] = checksOut;
-    }
-    return out;
-}
 const defaults = builtins;
-let cached = null;
+const configCache = new Map();
 export function loadConfig() {
-    if (cached)
-        return cached;
-    const rcPath = findRcFile(process.cwd());
+    const cwd = process.cwd();
+    if (configCache.has(cwd))
+        return configCache.get(cwd);
+    const rcPath = findRcFile(cwd);
     if (!rcPath) {
-        cached = defaults;
-        return cached;
+        configCache.set(cwd, defaults);
+        return defaults;
     }
     try {
         const raw = readFileSync(rcPath, "utf8");
         const parsed = (parse(raw) ?? {});
-        const compat = applyCompat(parsed);
-        cached = deepMerge(defaults, compat);
-        return cached;
+        const config = deepMerge(defaults, parsed);
+        configCache.set(cwd, config);
+        return config;
     }
     catch (err) {
         process.stderr.write(`pr-shepherd: failed to parse ${rcPath}: ${err instanceof Error ? err.message : String(err)}\n`);
-        cached = { ...defaults };
-        return cached;
+        const fallback = { ...defaults };
+        configCache.set(cwd, fallback);
+        return fallback;
     }
 }
+/** Reset the config cache — for use in tests that change directories. */
+export function _resetConfigCache() {
+    configCache.clear();
+}

package/bin/config.json

@@ -1,10 +1,13 @@
 {
-  "cache": {
-    "ttlSeconds": 300
-  },
   "iterate": {
     "cooldownSeconds": 30,
-    "fixAttemptsPerThread": 3
+    "fixAttemptsPerThread": 3,
+    "stallTimeoutMinutes": 30,
+    "minimizeReviewSummaries": {
+      "bots": true,
+      "humans": true,
+      "approvals": false
+    }
   },
   "watch": {
     "interval": "4m",
@@ -21,29 +24,14 @@
     "fetchReviewSummaries": true
   },
   "checks": {
-    "ciTriggerEvents": ["pull_request", "pull_request_target"],
-    "timeoutPatterns": [
-      "cancel timeout",
-      "exceeded the maximum execution time",
-      "job was cancelled"
-    ],
-    "infraPatterns": [
-      "runner error",
-      "service unavailable",
-      "ETIMEOUT",
-      "ECONNRESET",
-      "lost communication with the server",
-      "the hosted runner lost connection"
-    ],
-    "logMaxLines": 50,
-    "logMaxChars": 3000
+    "ciTriggerEvents": ["pull_request", "pull_request_target"]
   },
   "mergeStatus": {
     "blockingReviewerLogins": ["copilot"]
   },
   "actions": {
     "autoResolveOutdated": true,
-    "autoRebase": true,
-    "autoMarkReady": true
+    "autoMarkReady": true,
+    "commitSuggestions": true
   }
 }

package/bin/github/batch-parsers.mjs

@@ -0,0 +1,140 @@
+export function parseRawPr(raw, rawThreadPages, rawCommentNodes, rawReviewNodes, rawReviewSummaryNodes, rawApprovedReviewNodes, rawCheckNodes) {
+    const reviewRequests = (raw.reviewRequests?.nodes ?? []).flatMap((n) => {
+        const login = n.requestedReviewer?.login ?? n.requestedReviewer?.name;
+        return login ? [{ login }] : [];
+    });
+    const latestReviews = (raw.latestReviews?.nodes ?? []).map((n) => ({
+        login: n.author?.login ?? "unknown",
+        state: n.state,
+    }));
+    const reviewThreads = rawThreadPages.map((t) => {
+        const comment = t.comments.nodes[0];
+        return {
+            id: t.id,
+            isResolved: t.isResolved,
+            isOutdated: t.isOutdated,
+            isMinimized: comment?.isMinimized ?? false,
+            path: comment?.path ?? null,
+            line: comment?.line ?? null,
+            startLine: comment?.startLine ?? null,
+            author: comment?.author?.login ?? "unknown",
+            body: comment?.body ?? "",
+            createdAtUnix: comment ? parseCreatedAt(comment.createdAt) : 0,
+        };
+    });
+    const comments = rawCommentNodes.map((c) => ({
+        id: c.id,
+        isMinimized: c.isMinimized,
+        author: c.author?.login ?? "unknown",
+        body: c.body,
+        createdAtUnix: parseCreatedAt(c.createdAt),
+    }));
+    const changesRequestedReviews = rawReviewNodes.map((r) => ({
+        id: r.id,
+        author: r.author?.login ?? "unknown",
+        body: r.body,
+    }));
+    const reviewSummaries = rawReviewSummaryNodes
+        .filter((r) => !r.isMinimized && r.body.trim() !== "")
+        .map((r) => ({
+        id: r.id,
+        author: r.author?.login ?? "unknown",
+        body: r.body,
+    }));
+    // APPROVED reviews often have empty bodies (clicking "Approve" without a comment), so
+    // we keep them — only the isMinimized filter applies. Monitor/iterate uses these IDs
+    // when the user opts in to minimizing approvals.
+    const approvedReviews = rawApprovedReviewNodes
+        .filter((r) => !r.isMinimized)
+        .map((r) => ({
+        id: r.id,
+        author: r.author?.login ?? "unknown",
+        body: r.body,
+    }));
+    const checks = rawCheckNodes.flatMap((node) => {
+        if (node.__typename === "CheckRun") {
+            const event = node.checkSuite?.workflowRun?.event ?? null;
+            const runId = extractRunId(node.detailsUrl);
+            const summary = extractCheckRunSummary(node.title, node.summary);
+            return [
+                {
+                    name: node.name,
+                    status: node.status,
+                    conclusion: node.conclusion,
+                    detailsUrl: node.detailsUrl ?? "",
+                    event,
+                    runId,
+                    ...(summary !== undefined && { summary }),
+                },
+            ];
+        }
+        if (node.__typename === "StatusContext") {
+            const { status, conclusion } = mapStatusContextState(node.state);
+            const summary = node.description?.trim() || undefined;
+            return [
+                {
+                    name: node.context,
+                    status,
+                    conclusion,
+                    detailsUrl: node.targetUrl ?? "",
+                    event: null,
+                    runId: null,
+                    ...(summary !== undefined && { summary }),
+                },
+            ];
+        }
+        return [];
+    });
+    return {
+        nodeId: raw.id,
+        number: raw.number,
+        state: raw.state,
+        isDraft: raw.isDraft,
+        mergeable: raw.mergeable,
+        mergeStateStatus: raw.mergeStateStatus,
+        reviewDecision: (raw.reviewDecision ?? null),
+        headRefOid: raw.headRefOid,
+        baseRefName: raw.baseRefName,
+        reviewRequests,
+        latestReviews,
+        reviewThreads,
+        comments,
+        changesRequestedReviews,
+        reviewSummaries,
+        approvedReviews,
+        checks,
+    };
+}
+function parseCreatedAt(iso) {
+    const ms = new Date(iso).getTime();
+    return Number.isFinite(ms) ? Math.floor(ms / 1000) : 0;
+}
+function extractRunId(url) {
+    if (!url)
+        return null;
+    const m = /\/runs\/(\d+)/.exec(url);
+    return m ? (m[1] ?? null) : null;
+}
+function extractCheckRunSummary(title, summary) {
+    const t = title?.trim();
+    if (t)
+        return t;
+    const firstLine = summary
+        ?.split("\n")
+        ?.find((l) => l.trim() !== "")
+        ?.trim();
+    return firstLine || undefined;
+}
+function mapStatusContextState(state) {
+    switch (state) {
+        case "SUCCESS":
+            return { status: "COMPLETED", conclusion: "SUCCESS" };
+        case "FAILURE":
+        case "ERROR":
+            return { status: "COMPLETED", conclusion: "FAILURE" };
+        case "PENDING":
+        case "EXPECTED":
+        default:
+            return { status: "IN_PROGRESS", conclusion: null };
+    }
+}

package/bin/github/batch-raw-types.mjs

@@ -0,0 +1,2 @@
+// Private raw GraphQL response types for the batch PR query.
+export {};