forge-workflow 0.1.0-beta.4 → 0.1.0-beta.6

package/lib/pr-monitor/render-summary.js

@@ -0,0 +1,293 @@
+'use strict';
+
+const { normalizeEvidenceText } = require('../review-adapter');
+
+/**
+ * PR-monitor Actions-summary renderer. It turns one read-only
+ * `gatherPrBundle` result (lib/pr-bundle.js) into deterministic Markdown for
+ * the workflow's `GITHUB_STEP_SUMMARY` surface.
+ *
+ * This is presentation only: it displays the canonical verdict supplied by
+ * `forge shepherd <pr> --pull --json`, lists unresolved review threads and CI
+ * state, and never merges or resolves anything. The `pr-verdict:*` label is a
+ * cheap visibility projection of that same verdict, not merge authority.
+ *
+ * @module pr-monitor/render-summary
+ */
+
+/**
+ * Presentation-only headline for each canonical merge verdict (lib/pr-pull.js).
+ * The verdict is computed once by pr-pull and passed in; this map only decides
+ * how it is displayed, so there is no second verdict ladder to drift.
+ */
+const VERDICT_HEADLINE = {
+  INCOMPLETE: '⚪ **Verdict: `INCOMPLETE`** — bounded review/check evidence is incomplete; merge readiness blocked (fail-closed).',
+  UNKNOWN: '⚪ **Verdict: `unknown`** — a signal was unreadable; state unconfirmed (fail-closed).',
+  'BLOCKED-CONFLICT': '🔀 **Verdict: `blocked-conflict`** — branch conflicts with base; rebase/merge and resolve.',
+  BEHIND: '⬇️ **Verdict: `behind`** — branch is behind base; update/rebase (protection requires up-to-date).',
+  'BLOCKED-CHECKS': '🔴 **Verdict: `blocked-checks`** — a required check is failing/missing; fix it.',
+  'BLOCKED-THREADS': '🟠 **Verdict: `blocked-threads`** — unresolved review threads need addressing.',
+  'REVIEW-PENDING': '🟡 **Verdict: `review-pending`** — awaiting review / settle window; not ready yet.',
+  'CLEAN-MERGEABLE': '🟢 **Verdict: `clean-mergeable`** — green + zero unresolved threads; ready for a human to merge.',
+};
+
+const MAX_SUMMARY_THREADS = 64;
+const MAX_SUMMARY_CHECKS = 20;
+const MAX_SUMMARY_AUTHORS = 12;
+const MAX_SUMMARY_TEXT_CHARS = 256;
+const MAX_SUMMARY_SIGNALS = 16;
+const MAX_SUMMARY_CHARS = 32768;
+
+/** Render the one-line headline for a canonical verdict, failing closed. */
+function verdictHeadline(verdict) {
+  return VERDICT_HEADLINE[String(verdict || '').toUpperCase()] || VERDICT_HEADLINE.UNKNOWN;
+}
+
+/**
+ * Render untrusted text as a Markdown code span without allowing its backticks
+ * or line breaks to change the surrounding summary structure.
+ *
+ * CommonMark permits a code span to use more than one backtick. Pick a fence
+ * longer than every run in the value, and flatten CR/LF so the summary stays
+ * one line per diagnostic.
+ */
+function mdCode(value) {
+  const text = normalizeEvidenceText(value, { maxChars: MAX_SUMMARY_TEXT_CHARS });
+  let longestRun = 0;
+  let currentRun = 0;
+  for (const character of text) {
+    if (character === '`') {
+      currentRun += 1;
+      longestRun = Math.max(longestRun, currentRun);
+    } else {
+      currentRun = 0;
+    }
+  }
+  const fence = '`'.repeat(longestRun + 1);
+  const content = text.startsWith('`') || text.endsWith('`') ? ` ${text} ` : text;
+  return `${fence}${content}${fence}`;
+}
+
+/** Cap threads listed per author so a noisy PR cannot produce an enormous summary. */
+const MAX_THREADS_PER_AUTHOR = 8;
+
+/** Group unresolved review-thread comments by author in deterministic order. */
+function groupByAuthor(comments) {
+  const byAuthor = new Map();
+  for (const comment of (Array.isArray(comments) ? comments : [])) {
+    const author = normalizeEvidenceText(comment.author || 'unknown', { maxChars: MAX_SUMMARY_TEXT_CHARS });
+    if (!byAuthor.has(author)) byAuthor.set(author, []);
+    byAuthor.get(author).push(comment);
+  }
+  return [...byAuthor.entries()].sort((a, b) => {
+    if (b[1].length !== a[1].length) return b[1].length - a[1].length;
+    if (a[0] < b[0]) return -1;
+    if (a[0] > b[0]) return 1;
+    return 0;
+  });
+}
+
+/** One-line locator for a thread: `path:line` when known, else its id. */
+function threadLocator(thread) {
+  if (thread.path) {
+    const path = normalizeEvidenceText(thread.path, { maxChars: MAX_SUMMARY_TEXT_CHARS });
+    return thread.line != null ? `${path}:${thread.line}` : path;
+  }
+  return normalizeEvidenceText(thread.threadId || '(thread)', { maxChars: MAX_SUMMARY_TEXT_CHARS });
+}
+
+function validThread(thread) {
+  if (!thread || typeof thread !== 'object' || Array.isArray(thread)
+    || typeof thread.author !== 'string' || !thread.author.trim()) return false;
+  const hasPath = typeof thread.path === 'string' && thread.path.trim();
+  const hasId = typeof thread.threadId === 'string' && thread.threadId.trim();
+  return Boolean(hasPath || hasId);
+}
+
+function validCheck(check) {
+  return Boolean(check && typeof check === 'object' && !Array.isArray(check)
+    && typeof check.name === 'string' && check.name.trim());
+}
+
+/** Render unresolved review threads, preserving fail-closed availability. */
+function renderThreads(bundle, lines) {
+  // Empty arrays are ambiguous when the adapter could not read comments. Only
+  // an explicit available:true read may report zero unresolved threads.
+  if (bundle.unresolvedCommentsAvailable !== true) {
+    const why = bundle.unresolvedCommentsError || 'thread read unavailable (capability absent)';
+    lines.push('### Review threads');
+    lines.push(`⚠️ Review threads were **unreadable** this pass (${mdCode(why)}) — not treated as zero. Re-run once the read recovers.`);
+    lines.push('');
+    return 'INCOMPLETE';
+  }
+
+  if (!Array.isArray(bundle.unresolvedComments)
+    || bundle.unresolvedComments.slice(0, MAX_SUMMARY_THREADS + 1).some((thread) => !validThread(thread))) {
+    lines.push(
+      '### Review threads',
+      '⚠️ Review thread evidence was **malformed** this pass — not treated as zero.',
+      ''
+    );
+    return 'INCOMPLETE';
+  }
+
+  const comments = bundle.unresolvedComments;
+  const incomplete = comments.length > MAX_SUMMARY_THREADS;
+  if (comments.length === 0) {
+    lines.push('### Review threads');
+    lines.push('✅ No unresolved review threads.');
+    lines.push('');
+    return 'ZERO';
+  }
+
+  const boundedComments = comments.slice(0, MAX_SUMMARY_THREADS);
+  const groups = groupByAuthor(boundedComments).slice(0, MAX_SUMMARY_AUTHORS);
+  lines.push(`### Unresolved review threads (${comments.length})`);
+  lines.push('');
+  for (const [author, threads] of groups) {
+    lines.push(`- **${mdCode(author)}** — ${threads.length}`);
+    for (const thread of threads.slice(0, MAX_THREADS_PER_AUTHOR)) {
+      lines.push(`  - ${mdCode(threadLocator(thread))}`);
+    }
+    if (threads.length > MAX_THREADS_PER_AUTHOR) {
+      lines.push(`  - …and ${threads.length - MAX_THREADS_PER_AUTHOR} more`);
+    }
+  }
+  if (comments.length > boundedComments.length) {
+    lines.push(`- …and ${comments.length - boundedComments.length} more thread(s) omitted by the bounded summary`);
+  }
+  const representedThreads = groups.reduce((total, [, threads]) => total + threads.length, 0);
+  if (representedThreads < boundedComments.length) {
+    lines.push(`- …and ${boundedComments.length - representedThreads} thread(s) from additional authors`);
+  }
+  lines.push('');
+  return incomplete ? 'INCOMPLETE' : 'OPEN';
+}
+
+/** Render failing and pending checks, preserving fail-closed availability. */
+function renderChecks(bundle, lines) {
+  // Only ciAvailable:true permits a clean-check claim. Missing or false means
+  // the read did not complete, so empty arrays must not look green.
+  if (bundle.ciAvailable !== true) {
+    lines.push('### Checks');
+    lines.push('⚠️ Checks were **unreadable** this pass — not treated as green. Re-run once the read recovers.');
+    lines.push('');
+    return false;
+  }
+
+  const ci = bundle.ci || {};
+  const checkArrays = [ci.checks, ci.failing, ci.pending];
+  if (checkArrays.some((checks) => !Array.isArray(checks))
+    || checkArrays.some((checks) => checks.slice(0, MAX_SUMMARY_CHECKS + 1)
+      .some((check) => !validCheck(check)))) {
+    lines.push(
+      '### Checks',
+      '⚠️ Check evidence was **malformed** this pass — not treated as green.',
+      ''
+    );
+    return false;
+  }
+  const failing = ci.failing;
+  const pending = ci.pending;
+  const incomplete = checkArrays.some((checks) => checks.length > MAX_SUMMARY_CHECKS);
+  lines.push('### Checks');
+  if (failing.length === 0 && pending.length === 0) {
+    lines.push('✅ No failing or pending checks.');
+  } else {
+    if (failing.length > 0) {
+      lines.push(`- ❌ **Failing (${failing.length}):** ${failing.slice(0, MAX_SUMMARY_CHECKS).map((check) => mdCode(check.name || '?')).join(', ')}`);
+      if (failing.length > MAX_SUMMARY_CHECKS) {
+        lines.push(`  - …and ${failing.length - MAX_SUMMARY_CHECKS} more failing check(s)`);
+      }
+    }
+    if (pending.length > 0) {
+      lines.push(`- ⏳ **Pending (${pending.length}):** ${pending.slice(0, MAX_SUMMARY_CHECKS).map((check) => mdCode(check.name || '?')).join(', ')}`);
+      if (pending.length > MAX_SUMMARY_CHECKS) {
+        lines.push(`  - …and ${pending.length - MAX_SUMMARY_CHECKS} more pending check(s)`);
+      }
+    }
+  }
+  lines.push('');
+  return !incomplete;
+}
+
+/**
+ * Render the PR monitor's Actions job summary.
+ *
+ * @param {object} bundle - a `gatherPrBundle` result (lib/pr-bundle.js)
+ * @param {object} [opts]
+ * @param {Date} [opts.now] - injected clock for deterministic output
+ * @param {string} [opts.verdict] - canonical `--pull` verdict
+ * @param {string[]} [opts.unreadable] - unreadable signal names from `--pull`
+ * @param {string|number} [opts.pr] - PR number for the CLI diagnostics hint
+ * @returns {{ body: string }}
+ */
+function renderSummary(bundle = {}, opts = {}) {
+  const now = opts.now instanceof Date ? opts.now : new Date();
+  const lines = ['## 🔭 Forge PR Monitor', ''];
+  const verdict = String(opts.verdict || '').toUpperCase();
+  const isUnknown = verdict === 'UNKNOWN' || !VERDICT_HEADLINE[verdict];
+  const unreadable = Array.isArray(opts.unreadable)
+    ? opts.unreadable.filter(Boolean).slice(0, MAX_SUMMARY_SIGNALS)
+    : [];
+
+  const headlineIndex = lines.length;
+  lines.push(verdictHeadline(opts.verdict));
+  if (isUnknown && unreadable.length > 0) {
+    lines.push('');
+    lines.push(`> Unreadable signal(s): ${unreadable.map((signal) => mdCode(signal)).join(', ')}.`);
+  }
+  lines.push('');
+  lines.push('_Surfaces open review + check state so async feedback never rots. This monitor **does not merge** and never resolves review threads — a human merges in the GitHub UI._');
+  lines.push('');
+
+  let threadState = renderThreads(bundle, lines);
+  const checksComplete = renderChecks(bundle, lines);
+
+  const branch = bundle.branch || {};
+  if ((branch.behind || 0) > 0) {
+    lines.push(`> Branch is **${branch.behind}** commit(s) behind base.`);
+    lines.push('');
+  }
+
+  const pr = opts.pr || bundle.pr || '<pr>';
+  const detailCommand = mdCode(`forge shepherd ${pr} --pull --json`);
+  lines.push(
+    '---',
+    `Detailed JSON: ${detailCommand}`,
+    `_Updated ${now.toISOString()} · summary-only monitor · labels state, never merges, never resolves threads._`
+  );
+
+  let evidenceStatus = threadState === 'INCOMPLETE' || !checksComplete ? 'INCOMPLETE' : 'COMPLETE';
+  if (evidenceStatus === 'INCOMPLETE') lines[headlineIndex] = verdictHeadline('INCOMPLETE');
+  let body = lines.join('\n');
+  if (body.length > MAX_SUMMARY_CHARS) {
+    threadState = 'INCOMPLETE';
+    evidenceStatus = 'INCOMPLETE';
+    body = [
+      '## 🔭 Forge PR Monitor',
+      '',
+      verdictHeadline('INCOMPLETE'),
+      '',
+      '⚠️ Summary evidence exceeded the bounded rendering limit; inspect the detailed JSON.',
+      '',
+      '_This monitor does not merge and never resolves review threads._',
+      '',
+      `Detailed JSON: ${detailCommand}`,
+      `_Updated ${now.toISOString()} · summary-only monitor · labels state, never merges, never resolves threads._`,
+    ].join('\n');
+  }
+
+  return { body, evidenceStatus, threadState };
+}
+
+module.exports = {
+  MAX_SUMMARY_CHARS,
+  MAX_SUMMARY_CHECKS,
+  MAX_SUMMARY_THREADS,
+  renderSummary,
+  verdictHeadline,
+  groupByAuthor,
+  threadLocator,
+  MAX_THREADS_PER_AUTHOR,
+};

package/lib/pr-monitor/review-preflight.js

@@ -0,0 +1,269 @@
+'use strict';
+
+const { execFileSync } = require('node:child_process');
+
+const preflightCommand = require('../commands/preflight');
+
+const MAX_FINDINGS = 20;
+const MAX_FINDING_CHARS = 500;
+
+function boundedLines(value) {
+  return String(value || '')
+    .split(/\r?\n/)
+    .map(line => line.trim())
+    .filter(Boolean)
+    .slice(0, MAX_FINDINGS)
+    .map(line => line.slice(0, MAX_FINDING_CHARS));
+}
+
+async function defaultProbeCodeRabbit({ projectRoot }, exec = execFileSync) {
+  try {
+    exec('coderabbit', ['--version'], {
+      cwd: projectRoot,
+      encoding: 'utf8',
+      timeout: 10_000,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      windowsHide: true,
+    });
+    return { available: true };
+  } catch (error) {
+    const reason = error?.code === 'ENOENT' ? 'CLI not installed' : 'CLI unavailable or unauthenticated';
+    return { available: false, reason };
+  }
+}
+
+function parseCodeRabbitEvents(output) {
+  const rawLines = String(output || '').split(/\r?\n/).map(line => line.trim()).filter(Boolean);
+  const events = [];
+  let malformed = rawLines.length === 0;
+  for (const line of rawLines) {
+    try {
+      const event = JSON.parse(line);
+      if (!event || typeof event !== 'object' || Array.isArray(event)) malformed = true;
+      else events.push(event);
+    } catch {
+      malformed = true;
+    }
+  }
+  return { events, malformed };
+}
+
+async function defaultRunCodeRabbit({ projectRoot, base, baseCommit }, exec = execFileSync) {
+  try {
+    const output = exec('coderabbit', ['review', '--agent', '--base', baseCommit || base], {
+      cwd: projectRoot,
+      encoding: 'utf8',
+      timeout: 180_000,
+      maxBuffer: 1024 * 1024,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      windowsHide: true,
+    });
+    const { events, malformed } = parseCodeRabbitEvents(output);
+    const terminal = events.at(-1);
+    const terminalValid = terminal?.type === 'complete'
+      && ['review_completed', 'review_skipped'].includes(terminal.status)
+      && Number.isSafeInteger(terminal.findings) && terminal.findings >= 0;
+    const findingEvents = events.filter(event => event.type === 'finding');
+    const errorEvents = events.filter(event => event.type === 'error');
+    const clean = !malformed && terminalValid && terminal.findings === 0
+      && findingEvents.length === 0 && errorEvents.length === 0;
+    const findings = findingEvents.slice(0, MAX_FINDINGS).map(event => String(
+      event.codegenInstructions || event.message || 'CodeRabbit finding',
+    ).slice(0, MAX_FINDING_CHARS));
+    if (!clean && findings.length === 0) {
+      let detail = `CodeRabbit reported ${terminal?.findings || errorEvents.length} finding(s)`;
+      if (malformed || !terminalValid) {
+        detail = 'CodeRabbit agent output was malformed or incomplete';
+      }
+      findings.push(detail);
+    }
+    return {
+      ok: clean,
+      summary: clean ? 'local review completed with no findings' : `${findings.length} local review finding(s)`,
+      findings: clean ? [] : findings,
+    };
+  } catch (error) {
+    const output = `${error?.stdout || ''}\n${error?.stderr || ''}`;
+    const findings = boundedLines(output);
+    if (/unauthori[sz]ed|authentication|not authenticated|log in|login required/i.test(output)) {
+      return { ok: false, unavailable: true, summary: 'CLI authentication unavailable', findings: [] };
+    }
+    return {
+      ok: false,
+      summary: findings[0] || 'local review failed',
+      findings,
+    };
+  }
+}
+
+async function defaultRunDeterministic({ projectRoot, base, baseCommit, baseRef: resolvedBaseRef }, exec = execFileSync) {
+  const baseRef = baseCommit || resolvedBaseRef || (String(base || '').startsWith('origin/')
+    ? String(base)
+    : `origin/${String(base || '')}`);
+  return preflightCommand.handler([], {}, projectRoot, {
+    log: () => {},
+    resolveChangeSet: ({ runAll }) => preflightCommand.resolveChangeSet(exec, { runAll, baseRef }),
+  });
+}
+
+async function defaultResolveBaseCommit({ projectRoot, base, baseRef }, exec = execFileSync) {
+  const ref = baseRef || (String(base || '').startsWith('origin/')
+    ? String(base)
+    : `origin/${String(base || '')}`);
+  const resolved = String(exec('git', ['rev-parse', '--verify', '--quiet', `${ref}^{commit}`], {
+    cwd: projectRoot,
+    encoding: 'utf8',
+    timeout: 10_000,
+    stdio: ['ignore', 'pipe', 'pipe'],
+    windowsHide: true,
+  }) || '').trim().toLowerCase();
+  if (!/^[0-9a-f]{40}$/.test(resolved)) throw new Error(`PR base commit is unavailable for ${ref}`);
+  return resolved;
+}
+
+function providerResult(status, ok, summary, findings = []) {
+  return { status, ok, summary, findings: findings.slice(0, MAX_FINDINGS) };
+}
+
+function deterministicFindings(results) {
+  return (Array.isArray(results) ? results : [])
+    .filter(result => result?.ok === false && !result.skipped)
+    .slice(0, MAX_FINDINGS)
+    .map(result => ({
+      provider: String(result.name || 'deterministic-gate').slice(0, 80),
+      detail: String(result.summary || 'gate failed').slice(0, MAX_FINDING_CHARS),
+    }));
+}
+
+function notApplicableResult(context) {
+  const expectedHead = typeof context.expectedHead === 'string'
+    && /^[0-9a-f]{40}$/i.test(context.expectedHead) ? context.expectedHead.toLowerCase() : null;
+  const localHead = typeof context.localHead === 'string' ? context.localHead.toLowerCase() : null;
+  const exactHeadAvailable = expectedHead !== null;
+  const exactHeadCheckedOut = exactHeadAvailable && localHead === expectedHead;
+  if (exactHeadCheckedOut && context.cleanTree === true) return null;
+  const dirtyCheckout = exactHeadCheckedOut && context.cleanTree !== true;
+  const summary = dirtyCheckout
+    ? 'local checkout has uncommitted changes'
+    : (exactHeadAvailable ? 'local checkout is not the PR head' : 'PR head is unavailable');
+  return {
+    status: 'INCOMPLETE',
+    blocking: true,
+    providers: {
+      coderabbit: providerResult(
+        'NOT_APPLICABLE',
+        false,
+        summary,
+      ),
+      deterministic: { status: 'NOT_APPLICABLE', ok: false, results: [] },
+    },
+    findings: [{ provider: 'local-preflight', detail: summary }],
+  };
+}
+
+async function codeRabbitResult(context, probeCodeRabbit, runCodeRabbit) {
+  const probe = await probeCodeRabbit(context);
+  if (probe?.available !== true) {
+    return providerResult('UNAVAILABLE', false, probe?.reason || 'CLI unavailable');
+  }
+  const review = await runCodeRabbit(context);
+  if (review?.unavailable === true) {
+    return providerResult('UNAVAILABLE', false, review.summary || 'CLI unavailable');
+  }
+  return providerResult(
+    review?.ok === true ? 'PASS' : 'FAIL',
+    review?.ok === true,
+    review?.summary || 'local review completed',
+    Array.isArray(review?.findings) ? review.findings : [],
+  );
+}
+
+async function deterministicResult(context, runDeterministic) {
+  try {
+    return await runDeterministic(context);
+  } catch (error) {
+    return { success: false, results: [], reason: error?.message || String(error) };
+  }
+}
+
+async function runLocalReviewPreflight(context, deps = {}) {
+  const probeCodeRabbit = deps.probeCodeRabbit || defaultProbeCodeRabbit;
+  const runCodeRabbit = deps.runCodeRabbit || defaultRunCodeRabbit;
+  const runDeterministic = deps.runDeterministic || defaultRunDeterministic;
+
+  const notApplicable = notApplicableResult(context);
+  if (notApplicable) return notApplicable;
+
+  let reviewContext = context;
+  const suppliedBaseCommit = typeof context.baseCommit === 'string'
+    && /^[0-9a-f]{40}$/i.test(context.baseCommit);
+  const shouldResolveBase = deps.resolveBaseCommit !== false && !suppliedBaseCommit;
+  if (shouldResolveBase) {
+    const resolveBaseCommit = typeof deps.resolveBaseCommit === 'function'
+      ? deps.resolveBaseCommit
+      : defaultResolveBaseCommit;
+    try {
+      const baseCommit = String(await resolveBaseCommit(context) || '').trim().toLowerCase();
+      if (!/^[0-9a-f]{40}$/.test(baseCommit)) throw new Error('PR base commit resolver returned an invalid commit');
+      reviewContext = { ...context, baseCommit };
+    } catch (error) {
+      const detail = error?.message || String(error);
+      return {
+        status: 'INCOMPLETE',
+        blocking: true,
+        providers: {
+          coderabbit: providerResult('NOT_APPLICABLE', false, detail),
+          deterministic: { status: 'NOT_APPLICABLE', ok: false, results: [] },
+        },
+        findings: [{ provider: 'local-preflight', detail }],
+      };
+    }
+  } else if (suppliedBaseCommit) {
+    reviewContext = { ...context, baseCommit: context.baseCommit.toLowerCase() };
+  }
+
+  const coderabbit = await codeRabbitResult(reviewContext, probeCodeRabbit, runCodeRabbit);
+  const deterministic = await deterministicResult(reviewContext, runDeterministic);
+  const gateResults = Array.isArray(deterministic?.results) ? deterministic.results : [];
+  const deterministicOk = deterministic?.success === true;
+  const findings = [
+    ...coderabbit.findings.map(detail => ({ provider: 'coderabbit', detail })),
+    ...deterministicFindings(gateResults),
+  ].slice(0, MAX_FINDINGS);
+  if (!deterministicOk && findings.length === 0) {
+    findings.push({
+      provider: 'deterministic-gates',
+      detail: String(deterministic?.reason || 'preflight failed').slice(0, MAX_FINDING_CHARS),
+    });
+  }
+
+  const failed = !deterministicOk || coderabbit.status === 'FAIL';
+  const incomplete = coderabbit.status === 'UNAVAILABLE';
+  const blocking = failed || incomplete;
+  let status = 'PASS';
+  if (failed) status = 'FAIL';
+  else if (incomplete) status = 'INCOMPLETE';
+  return {
+    status,
+    blocking,
+    providers: {
+      coderabbit,
+      deterministic: {
+        status: deterministicOk ? 'PASS' : 'FAIL',
+        ok: deterministicOk,
+        results: gateResults,
+      },
+    },
+    findings,
+  };
+}
+
+module.exports = {
+  MAX_FINDINGS,
+  boundedLines,
+  defaultProbeCodeRabbit,
+  defaultResolveBaseCommit,
+  defaultRunCodeRabbit,
+  defaultRunDeterministic,
+  runLocalReviewPreflight,
+};

package/lib/pr-monitor/shepherd-lease.js

@@ -16,11 +16,12 @@
  * one lock. This module is the lease PRIMITIVE only: pure fs + I/O, no spawned
  * process and no reconcile loop (the daemon wires those up later).
  *
- * Payload JSON: `{ pid, token, startedAt, heartbeatAt, watchers: [prNumbers] }`.
+ * Payload JSON: `{ pid, token, startedAt, heartbeatAt }`.
+ * Per-PR watcher authority lives only in Kernel owner rows.
  *
  * ## Ownership is by TOKEN, not pid
  * Each successful `acquire` mints a unique `token`. Every mutating op
- * (`stamp`/`updateWatchers`/`release`) verifies that token against the on-disk
+ * (`stamp`/`release`) verifies that token against the on-disk
  * lock before writing. A pid can be reused after a crash/reboot, and a wedged
  * owner can revive after its lease was reclaimed — in both cases the token no
  * longer matches, so the superseded holder can never resurrect or mutate a lease
@@ -37,7 +38,9 @@ const crypto = require('node:crypto');
 const { resolveGitCommonDir } = require('../kernel/broker');
 
 /** A wedged owner whose heartbeat is older than this (ms) is reclaimable. */
-const STALE_MS = 30000;
+// Must exceed the longest synchronous daemon read (`gh pr list`, 30s) with
+// enough margin that a blocked event loop cannot be reclaimed mid-read.
+const STALE_MS = 90000;
 const LOCK_FILE_MODE = 0o600;
 
 /**
@@ -126,6 +129,9 @@ function tryExclusiveCreate(file, payload) {
  *   -> { ok:true, file, token, reclaimed }   stale lock (dead/wedged owner) reclaimed
  *   -> { ok:false, held }                    a LIVE, FRESH foreign owner holds it
  *   -> { ok:false, held }                    we lost the atomic takeover race
+ *   -> { ok:false, held:null, legacyMigrationPending:true, reason:'legacy-lease-unreadable' }
+ *                                            the lock exists but cannot be parsed —
+ *                                            never reclaimed, never deleted here
  *
  * `pid`/`isAlive`/`now`/`token` are injectable for testing. `onBeforeTakeover` is
  * a test seam invoked AFTER the stale lock is removed and BEFORE our exclusive
@@ -139,11 +145,12 @@ function acquire(projectRoot, {
   now = () => Date.now(),
   token = crypto.randomUUID(),
   onBeforeTakeover = null,
+  preserveLegacy = false,
 } = {}) {
   const file = lockFilePath(projectRoot, { gitCommonDir });
   fs.mkdirSync(path.dirname(file), { recursive: true });
   const iso = new Date(now()).toISOString();
-  const payload = { pid, token, startedAt: iso, heartbeatAt: iso, watchers: [] };
+  const payload = { pid, token, startedAt: iso, heartbeatAt: iso };
 
   // Fast path: atomic exclusive create. Only ONE caller can win O_EXCL.
   if (tryExclusiveCreate(file, payload)) {
@@ -156,15 +163,33 @@ function acquire(projectRoot, {
     return { ok: false, held };
   }
 
+  // NO caller may discard an unreadable lease: its bytes may be the only
+  // evidence of legacy watchers, and the daemon acquires HERE but migrates
+  // LATER — so an opt-in guard would still delete that evidence before
+  // migration could read it. This is unconditional at the shared acquisition
+  // boundary: fail closed, leave the bytes exactly as found, and surface a
+  // reason a caller can act on. Recovery belongs to migration, never to
+  // acquisition.
+  if (fs.existsSync(file) && !held) {
+    return {
+      ok: false, held: null, legacyMigrationPending: true, reason: 'legacy-lease-unreadable',
+    };
+  }
+
+  if (preserveLegacy && Array.isArray(held?.watchers)) {
+    return { ok: false, held, legacyMigrationPending: true };
+  }
+
   // Stale (dead/wedged owner, unreadable, or already ours). Take over ATOMICALLY:
   // remove the stale lock, then re-create it with O_EXCL. If a competitor
   // recreated it first, our exclusive create fails (EEXIST) and we back off — so
   // two racers reclaiming the same stale lock can NEVER both win. A wedged owner
   // that revives after we delete its lock is stopped by the per-lease `token`
-  // guard on stamp()/updateWatchers()/release(), never able to resurrect it here.
+  // guard on stamp()/release(), never able to resurrect it here.
   fs.rmSync(file, { force: true });
   if (typeof onBeforeTakeover === 'function') onBeforeTakeover();
-  if (!tryExclusiveCreate(file, payload)) {
+  const takeoverPayload = Array.isArray(held?.watchers) ? { ...payload, watchers: held.watchers } : payload;
+  if (!tryExclusiveCreate(file, takeoverPayload)) {
     return { ok: false, held: readLock(file) };
   }
   return { ok: true, file, token, reclaimed: true };
@@ -201,19 +226,6 @@ function stopHeartbeat(timer) {
   if (timer) clearInterval(timer);
 }
 
-/**
- * Rewrite the `watchers[]` array on OUR lock. Returns false when the lock is
- * missing or NOT ours by `token`.
- */
-function updateWatchers(projectRoot, prNumbers, { gitCommonDir, token, pid = process.pid } = {}) {
-  const file = lockFilePath(projectRoot, { gitCommonDir });
-  const held = readLock(file);
-  if (!held || !ownsLock(held, { token, pid })) return false;
-  held.watchers = Array.isArray(prNumbers) ? prNumbers : [];
-  writeLock(file, held);
-  return true;
-}
-
 /**
  * Release the lease — delete the lock ONLY when it is ours by `token`, so a
  * foreign or already-reclaimed lock is never removed out from under its owner
@@ -229,6 +241,12 @@ function release(projectRoot, { gitCommonDir, token, pid = process.pid } = {}) {
   }
 }
 
+/** True only while this exact pid+token still owns the shared lease. */
+function owns(projectRoot, { gitCommonDir, token, pid = process.pid } = {}) {
+  const held = readLock(lockFilePath(projectRoot, { gitCommonDir }));
+  return Boolean(held && ownsLock(held, { token, pid }));
+}
+
 module.exports = {
   STALE_MS,
   lockFilePath,
@@ -238,6 +256,6 @@ module.exports = {
   stamp,
   startHeartbeat,
   stopHeartbeat,
-  updateWatchers,
   release,
+  owns,
 };