forge-workflow 0.1.0-beta.3 → 0.1.0-beta.5

package/lib/adapters/pr-state-adapter.js

@@ -7,8 +7,8 @@
  * reversible side-effects used by the PR shepherd:
  *   - `readState`           → `gh pr view --json ...`
  *   - `readRequiredChecks`  → `gh api repos/{o}/{r}/branches/{base}/protection/required_status_checks`
- *   - `readDivergence`      → `git rev-list --left-right --count {baseRef}...HEAD`
- *   - `detectConflicts`     → `git merge-tree --write-tree {baseRef} HEAD` (predict-only)
+ *   - `readDivergence`      → `git rev-list --left-right --count {baseRef}...{headRef}`
+ *   - `detectConflicts`     → `git merge-tree --write-tree {baseRef} {headRef}` (predict-only)
  *   - `rerunFailedChecks`   → `gh run rerun <id> --failed`
  *   - `replyToThread`       → shell-out to `.claude/scripts/review-resolve.sh reply` (reply ONLY,
  *                             never resolve — resolution stays with the semantic `/review` agent)
@@ -25,6 +25,49 @@
 
 const { execFileSync } = require('node:child_process');
 
+const GITHUB_ACTOR_TYPENAMES = new Set([
+  'Bot', 'EnterpriseUserAccount', 'Mannequin', 'Organization', 'User',
+]);
+const FULL_HEAD_SHA = /^[0-9a-f]{40}$/i;
+const POSITIVE_PR_NUMBER = /^[1-9][0-9]*$/;
+const CHECK_RUN_STATUSES = new Set(['QUEUED', 'IN_PROGRESS', 'COMPLETED', 'WAITING', 'PENDING', 'REQUESTED']);
+const CHECK_RUN_CONCLUSIONS = new Set([
+  '', 'SUCCESS', 'FAILURE', 'NEUTRAL', 'CANCELLED', 'SKIPPED', 'TIMED_OUT',
+  'ACTION_REQUIRED', 'STALE', 'STARTUP_FAILURE',
+]);
+const STATUS_CONTEXT_STATES = new Set(['ERROR', 'EXPECTED', 'FAILURE', 'PENDING', 'SUCCESS']);
+const MERGE_STATE_STATUSES = new Set([
+  'BEHIND', 'BLOCKED', 'CLEAN', 'DIRTY', 'DRAFT', 'HAS_HOOKS', 'UNKNOWN', 'UNSTABLE',
+]);
+const PULL_REQUEST_REVIEW_STATES = new Set([
+  'APPROVED', 'CHANGES_REQUESTED', 'COMMENTED', 'DISMISSED', 'PENDING',
+]);
+
+function canonicalPrNumber(value) {
+  const raw = typeof value === 'number' && Number.isSafeInteger(value) ? String(value) : value;
+  return typeof raw === 'string' && POSITIVE_PR_NUMBER.test(raw) ? Number(raw) : null;
+}
+
+function validRollupNode(check) {
+  if (!check || typeof check !== 'object' || Array.isArray(check)) return false;
+  if (check.__typename === 'CheckRun') {
+    const status = String(check.status || '').toUpperCase();
+    const conclusion = String(check.conclusion || '').toUpperCase();
+    return typeof check.name === 'string' && Boolean(check.name.trim())
+      && CHECK_RUN_STATUSES.has(status)
+      && Object.prototype.hasOwnProperty.call(check, 'conclusion')
+      && (check.conclusion === null || typeof check.conclusion === 'string')
+      && CHECK_RUN_CONCLUSIONS.has(conclusion)
+      && (status === 'COMPLETED' ? Boolean(conclusion) : !conclusion);
+  }
+  if (check.__typename === 'StatusContext') {
+    return typeof check.context === 'string' && Boolean(check.context.trim())
+      && typeof check.state === 'string'
+      && STATUS_CONTEXT_STATES.has(check.state.toUpperCase());
+  }
+  return false;
+}
+
 // NOTE: `reviewThreads` is NOT a valid `gh pr view --json` field — requesting it
 // makes `gh` exit non-zero ("Unknown JSON field"), which crashed readState on every
 // real PR. Review threads are read separately via GraphQL in readComments().
@@ -78,13 +121,17 @@ class PrStateAdapter {
     this.id = options.id || 'pr-state-adapter';
     this.kind = 'pr-state';
     this.name = options.name || this.id;
+    // windowsHide keeps the shepherd's per-poll gh/git calls from flashing a
+    // console window on Windows when the watcher runs detached (issue 931e7924).
     const defaultRunner = (cmd, args, opts = {}) => execFileSync(cmd, args, {
       encoding: 'utf8',
       timeout: options.timeout || 30000,
+      windowsHide: true,
       ...(opts.cwd ? { cwd: opts.cwd } : {}),
     });
     this._gh = options.gh || defaultRunner;
     this._git = options.git || defaultRunner;
+    this.lastProtectionStatus = null;
   }
 
   /**
@@ -96,80 +143,220 @@ class PrStateAdapter {
   async readState(pr) {
     const raw = this._gh('gh', ['pr', 'view', String(pr), '--json', PR_VIEW_FIELDS]);
     const data = JSON.parse(raw || '{}');
-    const rollup = Array.isArray(data.statusCheckRollup) ? data.statusCheckRollup : [];
+    const lifecycleReadable = typeof data.state === 'string'
+      && ['OPEN', 'MERGED', 'CLOSED'].includes(data.state.toUpperCase())
+      && typeof data.isDraft === 'boolean';
+    const mergeStateStatus = typeof data.mergeStateStatus === 'string'
+      ? data.mergeStateStatus.toUpperCase()
+      : '';
+    const mergeStateReadable = MERGE_STATE_STATUSES.has(mergeStateStatus)
+      && mergeStateStatus !== 'UNKNOWN';
+    const rollupReadable = Array.isArray(data.statusCheckRollup)
+      && data.statusCheckRollup.every(validRollupNode);
+    const providerEvidenceReadable = lifecycleReadable && mergeStateReadable && rollupReadable
+      && typeof data.headRefOid === 'string' && FULL_HEAD_SHA.test(data.headRefOid);
+    const rollup = rollupReadable ? data.statusCheckRollup : [];
     return {
-      headSha: data.headRefOid || '',
-      state: String(data.state || 'OPEN').toUpperCase(),
+      headSha: typeof data.headRefOid === 'string' ? data.headRefOid : '',
+      state: lifecycleReadable ? data.state.toUpperCase() : 'UNKNOWN',
       mergeable: data.mergeable || 'UNKNOWN',
-      mergeStateStatus: data.mergeStateStatus || 'UNKNOWN',
-      // PR-level merge blockers (surfaced by the pull signal). `reviewDecision` is
-      // '' when no review is required; normalized to null so consumers can treat
-      // "not required" and "unknown" uniformly. `isDraft` blocks merge outright.
+      mergeStateStatus: mergeStateReadable ? mergeStateStatus : 'UNKNOWN',
       reviewDecision: data.reviewDecision || null,
-      isDraft: Boolean(data.isDraft),
-      // The rollup mixes two GraphQL types: a CheckRun (name/status/conclusion/
-      // detailsUrl) and a legacy commit StatusContext (context/state/targetUrl —
-      // Vercel/Netlify/other deploy+quality bots). Both are normalized into ONE
-      // shape here so the failing/pending classification treats them identically;
-      // `state` fills the conclusion slot for a StatusContext (SUCCESS/FAILURE/
-      // ERROR/PENDING) and `targetUrl` fills the details link.
-      checks: rollup.map((check) => ({
-        name: check.name || check.context || '',
-        status: check.status || check.state || '',
-        conclusion: check.conclusion || check.state || '',
-        databaseId: check.databaseId,
-        detailsUrl: check.detailsUrl || check.targetUrl,
-      })),
-      // gh pr view cannot return review threads; the shepherd reads them via
-      // readComments() (GraphQL). Kept for return-shape stability, always empty here.
+      isDraft: typeof data.isDraft === 'boolean' ? data.isDraft : null,
+      providerEvidenceReadable,
+      checks: rollup.map((check) => {
+        const statusContext = check.__typename === 'StatusContext';
+        const state = String(check.state || '').toUpperCase();
+        return {
+          name: check.name || check.context || '',
+          status: statusContext
+            ? (['SUCCESS', 'FAILURE', 'ERROR'].includes(state) ? 'COMPLETED' : 'IN_PROGRESS')
+            : String(check.status).toUpperCase(),
+          conclusion: statusContext ? state : String(check.conclusion || '').toUpperCase(),
+          databaseId: check.databaseId,
+          detailsUrl: check.detailsUrl || check.targetUrl,
+        };
+      }),
       threads: [],
     };
   }
 
   /**
-   * Read the branch-protection required-checks set.
+   * Read the required-checks set for a PR, with a two-source strategy so the
+   * verdict is not permanently UNKNOWN in CI.
    *
-   * Returns `null` when the protection endpoint is unreadable (e.g. 403
-   * insufficient scope, the branch is not protected, or the payload shape is
-   * unexpected) so the caller can escalate rather than guess. Re-throws non-auth
-   * errors.
+   * 1. **Branch protection** (`.../protection/required_status_checks`) — the
+   *    authoritative set, but this REST endpoint needs repo `Administration:read`,
+   *    which GitHub Actions' `GITHUB_TOKEN` can NEVER hold (administration is not a
+   *    grantable `permissions:` scope). So in CI this ALWAYS 403/404s and the set
+   *    was permanently null → verdict UNKNOWN on every PR.
+   * 2. **statusCheckRollup `isRequired`** (GraphQL, on the PR head commit) — the
+   *    fallback. It is readable with the plain PR-read scope the Actions token DOES
+   *    hold (it is what `gh pr checks --required` uses) and it covers BOTH classic
+   *    branch protection AND repository rulesets.
    *
-   * @param {{ owner: string, repo: string, base: string }} ctx
+   * Rollup `isRequired` data cannot prove the complete protected set because a
+   * required context that never ran is absent. `lastRequiredSource` is therefore
+   * `'protection'` only when an authoritative set is returned, and `null` when
+   * protection is unreadable.
+   * Re-throws non-auth protection errors (unchanged).
+   *
+   * @param {{ owner: string, repo: string, base: string, pr?: string|number }} ctx
    * @returns {Promise<string[] | null>}
    */
-  async readRequiredChecks({ owner, repo, base }) {
+  async readRequiredCheckPolicy({ owner, repo, base }) {
+    this.lastRequiredSource = null;
+    const fromProtection = this._readProtectionRequired({ owner, repo, base });
+    if (Array.isArray(fromProtection)) {
+      this.lastRequiredSource = 'protection';
+      return fromProtection;
+    }
+    return null;
+  }
+
+  async readRequiredChecks({ owner, repo, base, pr }) {
+    const fromProtection = await this.readRequiredCheckPolicy({ owner, repo, base });
+    if (Array.isArray(fromProtection)) return [...new Set(fromProtection.map((entry) => entry.context))];
+    if (this.lastProtectionStatus !== 'unavailable') return null;
+    // Rollup `isRequired` is retained only as diagnostic evidence. It is not the
+    // authoritative policy and therefore cannot authorize merge readiness.
+    this._readRollupRequired({ owner, repo, pr });
+    return null;
+  }
+
+  /**
+   * Branch-protection required set, or `null` when unreadable (auth/scope/
+   * not-protected/unexpected shape). Re-throws non-auth errors so a genuine
+   * outage is not silently masked. Split out so `readRequiredChecks` can fall
+   * back cleanly.
+   *
+   * @param {{ owner: string, repo: string, base: string }} ctx
+   * @returns {string[] | null}
+   */
+  _readProtectionRequired({ owner, repo, base }) {
+    this.lastProtectionStatus = 'malformed';
     const apiPath = `repos/${owner}/${repo}/branches/${encodeURIComponent(base)}/protection/required_status_checks`;
     try {
       const raw = this._gh('gh', ['api', apiPath]);
       const data = JSON.parse(raw || '{}');
-      if (Array.isArray(data.contexts)) return data.contexts;
-      if (Array.isArray(data.checks)) return data.checks.map((c) => c.context).filter(Boolean);
+      const hasContexts = Object.prototype.hasOwnProperty.call(data, 'contexts');
+      const hasChecks = Object.prototype.hasOwnProperty.call(data, 'checks');
+      if ((hasContexts && !Array.isArray(data.contexts))
+        || (hasChecks && !Array.isArray(data.checks))) return null;
+      const normalizeContexts = (items) => {
+        if (!Array.isArray(items)) return null;
+        if (items.some((item) => typeof item !== 'string' || item.trim().length === 0)) return null;
+        return [...new Set(items)];
+      };
+      const contexts = normalizeContexts(data.contexts);
+      let checks = null;
+      if (Array.isArray(data.checks)) {
+        if (data.checks.some((item) => !item || typeof item.context !== 'string'
+          || item.context.length === 0
+          || !Object.prototype.hasOwnProperty.call(item, 'app_id')
+          || (item.app_id !== null
+            && (!Number.isInteger(item.app_id) || item.app_id <= 0)))) return null;
+        const deduped = new Map();
+        const identityByContext = new Map();
+        for (const item of data.checks) {
+          const entry = { context: item.context, appId: item.app_id };
+          const identity = entry.appId === null ? '*' : String(entry.appId);
+          if (identityByContext.has(entry.context)
+            && identityByContext.get(entry.context) !== identity) return null;
+          identityByContext.set(entry.context, identity);
+          deduped.set(`${entry.context}\u0000${identity}`, entry);
+        }
+        checks = [...deduped.values()];
+      }
+      if (contexts && checks) {
+        const contextNames = [...contexts].sort((a, b) => a.localeCompare(b));
+        const checkNames = [...new Set(checks.map((entry) => entry.context))].sort((a, b) => a.localeCompare(b));
+        if (contextNames.length !== checkNames.length
+          || contextNames.some((value, index) => value !== checkNames[index])) return null;
+        this.lastProtectionStatus = 'authoritative';
+        return checks;
+      }
+      if (contexts) {
+        this.lastProtectionStatus = 'authoritative';
+        return contexts.map((context) => ({ context, appId: null }));
+      }
+      if (checks) {
+        this.lastProtectionStatus = 'authoritative';
+        return checks;
+      }
       // Unexpected/changed payload shape — treat as unreadable, not "no required
       // checks", so merge readiness is never computed from bad data.
       return null;
     } catch (error) {
       const auth = classifyAuthError(error);
       if (auth) {
-        // Unreadable protection (auth/scope/not-protected) — caller escalates.
+        this.lastProtectionStatus = 'unavailable';
         return null;
       }
       throw error;
     }
   }
 
+  /**
+   * Fallback required set from the PR head commit's `statusCheckRollup`, reading
+   * per-context `isRequired(pullRequestNumber:)` via GraphQL. Readable with plain
+   * PR-read scope (unlike branch protection). Returns the deduped names of every
+   * required CheckRun/StatusContext, `[]` when the rollup is readable but nothing
+   * is required, or `null` when the rollup itself is unreadable (fail-closed).
+   *
+   * @param {{ owner: string, repo: string, pr?: string|number }} ctx
+   * @returns {string[] | null}
+   */
+  _readRollupRequired({ owner, repo, pr }) {
+    const prNum = canonicalPrNumber(pr);
+    if (prNum === null) return null;
+    const query = [
+      'query($after:String){repository(owner:"', owner, '",name:"', repo, '"){',
+      'pullRequest(number:', prNum, '){headRef{target{... on Commit{statusCheckRollup{',
+      'contexts(first:100,after:$after){pageInfo{hasNextPage endCursor}nodes{__typename ',
+      '... on CheckRun{name isRequired(pullRequestNumber:', prNum, ')} ',
+      '... on StatusContext{context isRequired(pullRequestNumber:', prNum, ')}}}}}}}}}}',
+    ].join('');
+    try {
+      const projected = this._paginateConnection(
+        (after) => {
+          const args = ['api', 'graphql', '-f', `query=${query}`];
+          if (after) args.push('-f', `after=${after}`);
+          const data = this._parseGraphqlResponse(this._gh('gh', args));
+          return data?.data?.repository?.pullRequest?.headRef?.target
+            ?.statusCheckRollup?.contexts;
+        },
+        (node) => {
+          if (!['CheckRun', 'StatusContext'].includes(node.__typename)
+            || typeof node.isRequired !== 'boolean') {
+            throw new Error('Rollup required-check node is malformed');
+          }
+          const name = node.__typename === 'CheckRun' ? node.name : node.context;
+          if (typeof name !== 'string' || !name.trim()) {
+            throw new Error('Rollup required-check node has no context identity');
+          }
+          return node.isRequired ? name : null;
+        },
+      );
+      return [...new Set(projected.filter(Boolean))];
+    } catch {
+      return null;
+    }
+  }
+
   /**
    * Read ahead/behind divergence against the base ref.
    *
    * `cwd` is threaded through to the git runner so divergence is computed
    * against the target worktree/checkout, not the process directory.
    *
-   * @param {{ baseRef: string, cwd?: string }} ctx
+   * @param {{ baseRef: string, cwd?: string, headRef?: string }} ctx
    * @returns {Promise<{ behind: number, ahead: number }>}
    */
-  async readDivergence({ baseRef, cwd }) {
+  async readDivergence({ baseRef, cwd, headRef = 'HEAD' }) {
     const out = this._git(
       'git',
-      ['rev-list', '--left-right', '--count', `${baseRef}...HEAD`],
+      ['rev-list', '--left-right', '--count', `${baseRef}...${headRef}`],
       cwd ? { cwd } : undefined,
     );
     const [behindRaw = '0', aheadRaw = '0'] = String(out).trim().split(/\s+/);
@@ -191,7 +378,8 @@ class PrStateAdapter {
 
   /**
    * Fetch the base ref from its remote so a subsequent `readDivergence`/
-   * `detectConflicts` compares HEAD against the CURRENT `origin/<base>`, not a
+   * `detectConflicts` compares the selected PR head (or legacy `HEAD` default)
+   * against the CURRENT `origin/<base>`, not a
    * stale local remote-tracking ref (audit A6: a stale ref reports a false
    * `behind=0` / false "no conflict"). `baseRef` is `<remote>/<branch>` (e.g.
    * `origin/master`); the remote and branch are split back out for `git fetch`.
@@ -231,6 +419,8 @@ class PrStateAdapter {
    * @returns {Promise<object[]>}
    */
   async readComments({ owner, repo, pr }) {
+    const number = canonicalPrNumber(pr);
+    if (!number) throw new Error('PR selector must be one canonical positive decimal number');
     // `id`/`path`/`line` are surfaced so a consumer (e.g. the monitor bundle in
     // lib/pr-bundle.js) can hand an agent the thread id to resolve and the
     // file/line to act on — not just the body. Added fields are backward
@@ -239,22 +429,26 @@ class PrStateAdapter {
     // Both connections are FULLY paginated (cursors, not a first:100 cap): a
     // large PR must never silently drop a thread or a later reply, or the bundle
     // would declare "complete" on partial data and the monitor would skip work.
-    const threads = this._fetchAllReviewThreads({ owner, repo, pr });
+    const threads = this._fetchAllReviewThreads({ owner, repo, pr: number });
     return threads.map((t) => {
-      const allComments = (t.comments && t.comments.nodes) || [];
+      const allComments = t.comments.nodes;
       return {
-        threadId: t.id || '',
+        threadId: t.id,
         path: t.path || null,
         line: typeof t.line === 'number' ? t.line : null,
-        isResolved: !!t.isResolved,
-        isOutdated: !!t.isOutdated,
-        comments: allComments.map(c => ({
-          author: (c.author && c.author.login) || '',
-          body: c.body || '',
-          // REST comment id (needed to REPLY to the thread). `fullDatabaseId` is
-          // the string-encoded integer id; null when GitHub omits it.
-          commentId: c.fullDatabaseId ? String(c.fullDatabaseId) : null,
-        })),
+        isResolved: t.isResolved,
+        isOutdated: t.isOutdated,
+        comments: allComments.map((c) => {
+          const commentId = c.fullDatabaseId ? String(c.fullDatabaseId) : '';
+          const author = String(c.author?.login || '');
+          const authorType = String(c.author?.__typename || '');
+          if (!commentId) throw new Error(`Review thread ${t.id} comment is missing stable database id`);
+          if (!author || !GITHUB_ACTOR_TYPENAMES.has(authorType)) {
+            throw new Error(`Review thread ${t.id} comment ${commentId} is missing valid author identity`);
+          }
+          if (typeof c.body !== 'string') throw new Error(`Review thread ${t.id} comment ${commentId} has malformed body`);
+          return { author, authorType, body: c.body, commentId };
+        }),
       };
     });
   }
@@ -269,16 +463,20 @@ class PrStateAdapter {
    * @returns {object[]} raw thread nodes (comments.nodes carries the full chain)
    */
   _fetchAllReviewThreads({ owner, repo, pr }) {
-    const query = 'query($o:String!,$n:String!,$pr:Int!,$after:String){repository(owner:$o,name:$n){pullRequest(number:$pr){reviewThreads(first:100,after:$after){pageInfo{hasNextPage endCursor} nodes{id isResolved isOutdated path line comments(first:100){pageInfo{hasNextPage endCursor} nodes{fullDatabaseId author{login} body}}}}}}}';
+    const query = 'query($o:String!,$n:String!,$pr:Int!,$after:String){repository(owner:$o,name:$n){pullRequest(number:$pr){reviewThreads(first:100,after:$after){pageInfo{hasNextPage endCursor} nodes{id isResolved isOutdated path line comments(first:100){pageInfo{hasNextPage endCursor} nodes{fullDatabaseId author{__typename login} body}}}}}}}';
     return this._paginateConnection(
       (after) => this._ghGraphqlPage(query, { owner, repo, pr }, after)
         ?.data?.repository?.pullRequest?.reviewThreads,
       (t) => {
-        // A thread whose first comment page is truncated → fetch the rest.
-        if (t.comments?.pageInfo?.hasNextPage) {
-          t.comments = { nodes: this._fetchAllThreadComments(t.id, t.comments) };
+        if (typeof t.id !== 'string' || !t.id
+          || typeof t.isResolved !== 'boolean' || typeof t.isOutdated !== 'boolean') {
+          throw new Error('GraphQL review thread node is malformed');
         }
-        return t;
+        const comments = this._validateGraphqlConnection(t.comments, `Review thread ${t.id} comments`);
+        const nodes = comments.pageInfo.hasNextPage
+          ? this._fetchAllThreadComments(t.id, comments)
+          : comments.nodes;
+        return { ...t, comments: { nodes } };
       },
     );
   }
@@ -300,7 +498,31 @@ class PrStateAdapter {
       '-F', `o=${owner}`, '-F', `n=${repo}`, '-F', `pr=${pr}`,
     ];
     if (after) args.push('-f', `after=${after}`);
-    return JSON.parse(this._gh('gh', args) || '{}');
+    return this._parseGraphqlResponse(this._gh('gh', args));
+  }
+
+  _parseGraphqlResponse(raw) {
+    const parsed = JSON.parse(raw || '{}');
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      throw new Error('GraphQL response envelope is malformed');
+    }
+    if (Object.prototype.hasOwnProperty.call(parsed, 'errors')
+      && (!Array.isArray(parsed.errors) || parsed.errors.length > 0)) {
+      throw new Error('GraphQL response contains errors');
+    }
+    return parsed;
+  }
+
+  _validateGraphqlConnection(conn, label = 'GraphQL connection') {
+    if (!conn || typeof conn !== 'object' || Array.isArray(conn)
+      || !Array.isArray(conn.nodes) || conn.nodes.some((node) => !node || typeof node !== 'object' || Array.isArray(node))
+      || !conn.pageInfo || typeof conn.pageInfo !== 'object' || Array.isArray(conn.pageInfo)
+      || typeof conn.pageInfo.hasNextPage !== 'boolean'
+      || (conn.pageInfo.endCursor !== null && typeof conn.pageInfo.endCursor !== 'string')
+      || (conn.pageInfo.hasNextPage && !conn.pageInfo.endCursor)) {
+      throw new Error(`${label} is missing valid nodes/pageInfo`);
+    }
+    return conn;
   }
 
   /**
@@ -321,11 +543,18 @@ class PrStateAdapter {
     let guard = 0;
     const MAX_PAGES = 1000;
     do {
-      const conn = runPage(after);
-      for (const node of (conn?.nodes || [])) all.push(mapNode(node));
-      after = conn?.pageInfo?.hasNextPage ? conn.pageInfo.endCursor : null;
+      const previous = after;
+      const conn = this._validateGraphqlConnection(runPage(after));
+      for (const node of conn.nodes) all.push(mapNode(node));
+      after = conn.pageInfo.hasNextPage ? conn.pageInfo.endCursor : null;
+      if (after !== null && after === previous) {
+        throw new Error('GraphQL pagination cursor did not advance');
+      }
       guard += 1;
-    } while (after && guard < MAX_PAGES);
+      if (guard >= MAX_PAGES && after !== null) {
+        throw new Error('GraphQL pagination exceeded the page limit');
+      }
+    } while (after !== null);
     return all;
   }
 
@@ -338,21 +567,33 @@ class PrStateAdapter {
    * @returns {object[]} the full comment-node list (first page + all later pages)
    */
   _fetchAllThreadComments(threadId, initial) {
-    const query = 'query($id:ID!,$after:String){node(id:$id){... on PullRequestReviewThread{comments(first:100,after:$after){pageInfo{hasNextPage endCursor} nodes{fullDatabaseId author{login} body}}}}}';
-    const acc = [...((initial && initial.nodes) || [])];
-    let after = initial && initial.pageInfo && initial.pageInfo.hasNextPage ? initial.pageInfo.endCursor : null;
+    const query = 'query($id:ID!,$after:String){node(id:$id){... on PullRequestReviewThread{comments(first:100,after:$after){pageInfo{hasNextPage endCursor} nodes{fullDatabaseId author{__typename login} body}}}}}';
+    if (typeof threadId !== 'string' || !threadId) throw new Error('Review thread id is malformed');
+    let conn = this._validateGraphqlConnection(initial, `Review thread ${threadId} comments`);
+    const acc = [...conn.nodes];
+    let after = conn.pageInfo.hasNextPage ? conn.pageInfo.endCursor : null;
     let guard = 0;
     const MAX_PAGES = 1000;
-    while (after && guard < MAX_PAGES) {
+    while (after !== null) {
+      const previous = after;
       const raw = this._gh('gh', [
         'api', 'graphql', '-f', `query=${query}`,
         '-f', `id=${threadId}`, '-f', `after=${after}`,
       ]);
-      const data = JSON.parse(raw || '{}');
-      const conn = data.data && data.data.node && data.data.node.comments;
-      acc.push(...((conn && conn.nodes) || []));
-      after = conn && conn.pageInfo && conn.pageInfo.hasNextPage ? conn.pageInfo.endCursor : null;
+      const data = this._parseGraphqlResponse(raw);
+      conn = this._validateGraphqlConnection(
+        data?.data?.node?.comments,
+        `Review thread ${threadId} comments`,
+      );
+      acc.push(...conn.nodes);
+      after = conn.pageInfo.hasNextPage ? conn.pageInfo.endCursor : null;
+      if (after !== null && after === previous) {
+        throw new Error('GraphQL pagination cursor did not advance');
+      }
       guard += 1;
+      if (guard >= MAX_PAGES && after !== null) {
+        throw new Error('GraphQL pagination exceeded the page limit');
+      }
     }
     return acc;
   }
@@ -372,56 +613,112 @@ class PrStateAdapter {
     // `author{__typename login}` surfaces the GraphQL actor TYPE ('Bot' vs 'User')
     // so a non-human direct comment can be detected GENERICALLY — by mechanism,
     // not by a hardcoded bot-name list — which fails closed for unknown bots.
-    const query = 'query($o:String!,$n:String!,$pr:Int!,$after:String){repository(owner:$o,name:$n){pullRequest(number:$pr){comments(first:100,after:$after){pageInfo{hasNextPage endCursor} nodes{fullDatabaseId author{__typename login} body createdAt}}}}}';
+    const query = 'query($o:String!,$n:String!,$pr:Int!,$after:String){repository(owner:$o,name:$n){pullRequest(number:$pr){comments(first:100,after:$after){pageInfo{hasNextPage endCursor} nodes{fullDatabaseId author{__typename login} body createdAt updatedAt}}}}}';
     return this._paginateConnection(
       (after) => this._ghGraphqlPage(query, { owner, repo, pr }, after)
         ?.data?.repository?.pullRequest?.comments,
-      (c) => ({
-        // `id` is the stable REST comment id — the PR monitor keys `comment.posted`
-        // on it so a re-read never re-emits an already-seen comment. Falls back to
-        // author+createdAt when GitHub omits it.
-        id: c.fullDatabaseId ? String(c.fullDatabaseId) : `${c.author?.login || ''}:${c.createdAt || ''}`,
-        author: c.author?.login || '',
-        authorTypename: c.author?.__typename || '',
-        body: c.body || '',
-        createdAt: c.createdAt || '',
-      }),
+      (c) => {
+        const id = c.fullDatabaseId ? String(c.fullDatabaseId) : '';
+        if (!id) throw new Error('Issue comment is missing stable database id');
+        if (!c.author?.login) throw new Error(`Issue comment ${id} is missing author identity`);
+        if (!GITHUB_ACTOR_TYPENAMES.has(String(c.author?.__typename || ''))) {
+          throw new Error(`Issue comment ${id} has missing or malformed actor type`);
+        }
+        if (typeof c.body !== 'string' || typeof c.createdAt !== 'string' || !c.createdAt) {
+          throw new Error(`Issue comment ${id} has malformed body or timestamp`);
+        }
+        return {
+          id,
+          author: c.author.login,
+          authorTypename: c.author.__typename,
+          body: c.body,
+          createdAt: c.createdAt,
+          updatedAt: c.updatedAt || c.createdAt,
+        };
+      },
     );
   }
 
   /**
    * Read submitted PR REVIEWS (not inline threads) — the latest review per
    * author, each with the commit it was submitted against. This is the
-   * review-at-head signal that catches the #365 race: a CodeRabbit review from
-   * an earlier commit whose `commit.oid` no longer matches HEAD is STALE, so the
-   * post-push re-review is still pending. Uses GraphQL because `gh pr view`
+   * review-at-head signal that catches the #365 race: any reviewer submission
+   * from an earlier commit whose `commit.oid` no longer matches HEAD is STALE,
+   * so the post-push re-review is still pending. Uses GraphQL because `gh pr view`
    * cannot return a review's target commit oid. Fully paginated by cursor.
    *
    * @param {{ owner: string, repo: string, pr: string }} ctx
-   * @returns {Promise<Array<{ author: string, state: string, submittedAt: string|null, commitOid: string|null, body: string }>>}
+   * @returns {Promise<Array<{ author: string, state: string, createdAt: string, updatedAt: string, submittedAt: string, activityAt: string, commitOid: string, body: string }>>}
    */
   async readReviews({ owner, repo, pr }) {
-    const query = 'query($o:String!,$n:String!,$pr:Int!,$after:String){repository(owner:$o,name:$n){pullRequest(number:$pr){reviews(first:100,after:$after){pageInfo{hasNextPage endCursor} nodes{author{__typename login} state submittedAt commit{oid} body}}}}}';
+    const query = 'query($o:String!,$n:String!,$pr:Int!,$after:String){repository(owner:$o,name:$n){pullRequest(number:$pr){reviews(first:100,after:$after){pageInfo{hasNextPage endCursor} nodes{id author{__typename login} state createdAt updatedAt submittedAt commit{oid} body}}}}}';
     const all = this._paginateConnection(
       (after) => this._ghGraphqlPage(query, { owner, repo, pr }, after)
         ?.data?.repository?.pullRequest?.reviews,
-      (r) => ({
-        author: String(r.author?.login || '').toLowerCase(),
-        authorTypename: r.author?.__typename || '',
-        state: String(r.state || '').toUpperCase(),
-        submittedAt: r.submittedAt || null,
-        commitOid: r.commit?.oid || null,
-        body: r.body || '',
-      }),
+      (r) => {
+        if (typeof r.id !== 'string' || !r.id) {
+          throw new Error('Review is missing stable GraphQL id');
+        }
+        const id = r.id;
+        if (typeof r.author?.login !== 'string' || !r.author.login) {
+          throw new Error(`Review ${id} is missing author identity`);
+        }
+        const author = r.author.login.toLowerCase().replace(/\[bot\]$/, '');
+        if (!author) throw new Error(`Review ${id} has empty normalized author identity`);
+        if (typeof r.author?.__typename !== 'string'
+          || !GITHUB_ACTOR_TYPENAMES.has(r.author.__typename)) {
+          throw new Error(`Review ${id} has missing or malformed actor type`);
+        }
+        const state = typeof r.state === 'string' ? r.state.toUpperCase() : '';
+        if (!PULL_REQUEST_REVIEW_STATES.has(state)
+          || typeof r.createdAt !== 'string' || !r.createdAt
+          || typeof r.updatedAt !== 'string' || !r.updatedAt
+          || typeof r.submittedAt !== 'string' || !r.submittedAt
+          || typeof r.commit?.oid !== 'string' || !FULL_HEAD_SHA.test(r.commit.oid)
+          || typeof r.body !== 'string') {
+          throw new Error(`Review ${id} has malformed state, timestamp, commit, or body`);
+        }
+        return {
+          id,
+          author,
+          authorTypename: r.author.__typename,
+          state,
+          createdAt: r.createdAt,
+          updatedAt: r.updatedAt,
+          submittedAt: r.submittedAt,
+          commitOid: r.commit.oid,
+          body: r.body,
+        };
+      },
     );
     // Keep only the LATEST review per author (first:100 yields oldest→newest, so
     // a later entry supersedes an earlier one from the same login).
     const latest = new Map();
+    const latestSubmission = new Map();
+    const latestActivity = new Map();
     for (const r of all) {
-      if (!r.author) continue;
-      latest.set(r.author, r);
+      const submitted = Date.parse(r.submittedAt);
+      if (!Number.isFinite(submitted)) {
+        throw new Error(`Review ${r.id} has malformed submission timestamp`);
+      }
+      if (!latestSubmission.has(r.author) || submitted >= latestSubmission.get(r.author)) {
+        latest.set(r.author, r);
+        latestSubmission.set(r.author, submitted);
+      }
+      const activity = Math.max(
+        Date.parse(r.createdAt),
+        Date.parse(r.updatedAt),
+        Date.parse(r.submittedAt),
+      );
+      if (!Number.isFinite(activity)) {
+        throw new Error(`Review ${r.id} has malformed activity timestamps`);
+      }
+      latestActivity.set(r.author, Math.max(latestActivity.get(r.author) || 0, activity));
     }
-    return Array.from(latest.values());
+    return Array.from(latest.values()).map((review) => ({
+      ...review,
+      activityAt: new Date(latestActivity.get(review.author)).toISOString(),
+    }));
   }
 
   /**
@@ -441,23 +738,23 @@ class PrStateAdapter {
   }
 
   /**
-   * Predict files that would conflict when merging `baseRef` into HEAD WITHOUT
+   * Predict files that would conflict when merging `baseRef` into `headRef` WITHOUT
    * touching the working tree, via `git merge-tree --write-tree`. Returns
    * `{ supported: false, reason }` when conflict prediction is unavailable (git
    * < 2.38, an unreadable ref, or a non-conflict error) so the bundle degrades
    * gracefully rather than failing the whole gather.
    *
-   * @param {{ baseRef: string, cwd?: string }} ctx
+   * @param {{ baseRef: string, cwd?: string, headRef?: string }} ctx
    * @returns {Promise<{ supported: boolean, conflicted?: boolean, files?: string[], reason?: string }>}
    */
-  async detectConflicts({ baseRef, cwd }) {
+  async detectConflicts({ baseRef, cwd, headRef = 'HEAD' }) {
     const opts = cwd ? { cwd } : undefined;
     try {
       // Exit 0 = clean merge. `--name-only` reduces the conflict report to bare
       // paths; `--no-messages` suppresses the human-readable conflict prose.
       this._git(
         'git',
-        ['merge-tree', '--write-tree', '--name-only', '--no-messages', baseRef, 'HEAD'],
+        ['merge-tree', '--write-tree', '--name-only', '--no-messages', baseRef, headRef],
         opts,
       );
       return { supported: true, conflicted: false, files: [] };