mandrel 2.64.0 → 2.66.0

package/.agents/scripts/lib/orchestration/merge-poll.js

@@ -8,13 +8,29 @@ import { checkVerdict, classifyRollupEntry } from './check-state.js';
 
 /** Fixed poll interval; default for `delivery.mergeWatch.maxBudgetSeconds`. */
 export const DEFAULT_INTERVAL_SECONDS = 30;
+
+/** Checks green, PR unmerged: the merge is imminent, so observe it sooner. */
+const GREEN_INTERVAL_SECONDS = 10;
+
+/**
+ * @param {string|undefined} checksStatus
+ * @param {number} intervalSeconds The in-flight cadence.
+ * @returns {number} Milliseconds until the next poll.
+ */
+export function pollIntervalMs(checksStatus, intervalSeconds) {
+  const seconds =
+    checksStatus === 'success'
+      ? Math.min(GREEN_INTERVAL_SECONDS, intervalSeconds)
+      : intervalSeconds;
+  return seconds * 1000;
+}
 export const DEFAULT_MAX_BUDGET_SECONDS = 3600;
 
 /** Bounds every `gh` spawn so a hang degrades to the probe-error path. */
 export const MERGE_WAIT_GH_TIMEOUT_MS = 60_000;
 
 /**
- * Aggregate over EVERY check (the rollup has no `isRequired`): `failure`
+ * Aggregate over EVERY check (the view rollup has no `isRequired`): `failure`
  * means "something is red", not "blocked" — see {@link failingChecksBlockMerge}.
  */
 export function deriveChecksStatus(statusCheckRollup) {
@@ -47,7 +63,7 @@ export function isPrMerged(pr) {
  * @param {{ conclusion?: string, state?: string }} [check]
  * @returns {string|null}
  */
-function redConclusionOf(check) {
+export function redConclusionOf(check) {
   const conclusion = String(check?.conclusion ?? '').toUpperCase();
   if (conclusion === 'FAILURE' || conclusion === 'ERROR') return conclusion;
   const state = String(check?.state ?? '').toUpperCase();
@@ -61,17 +77,29 @@ function redConclusionOf(check) {
  * @param {{ name?: string, context?: string }} [check]
  * @returns {string|null}
  */
-function readRunName(check) {
+export function readRunName(check) {
   for (const value of [check?.name, check?.context]) {
     if (typeof value === 'string' && value) return value;
   }
   return null;
 }
 
+/**
+ * @param {{ status?: string, state?: string }} [check]
+ * @returns {boolean}
+ */
+export function isRunInFlight(check) {
+  const status = String(check?.status ?? '').toUpperCase();
+  // `status` is empty on a StatusContext, so it falls to the `state` branch.
+  if (status) return status !== 'COMPLETED';
+  const state = String(check?.state ?? '').toUpperCase();
+  return state === 'PENDING' || state === 'EXPECTED';
+}
+
 /**
  * Head-anchored evidence; `null` on an empty rollup (the caller falls back
- * to consecutive probes). Reads EVERY run despite the names — required-ness
- * is attributed via `BLOCKED` in {@link requiredCheckFailedBlocksMerge}.
+ * to consecutive probes). Reads EVERY run — the unscoped rule used when
+ * GitHub's required attribution is unavailable (see `required-checks.js`).
  *
  * @param {Array<{status?: string, conclusion?: string, state?: string}>} statusCheckRollup
  * @returns {{ requiredRunFailed: boolean, requiredRunInFlight: boolean } | null}
@@ -80,22 +108,12 @@ export function deriveRequiredRunEvidence(statusCheckRollup) {
   if (!Array.isArray(statusCheckRollup) || statusCheckRollup.length === 0) {
     return null;
   }
-  let requiredRunFailed = false;
-  let requiredRunInFlight = false;
-  for (const check of statusCheckRollup) {
-    const status = String(check?.status ?? '').toUpperCase();
-    const state = String(check?.state ?? '').toUpperCase();
-    // `status` is empty on a StatusContext, so it falls to the `state` branch.
-    if (status && status !== 'COMPLETED') {
-      requiredRunInFlight = true;
-    } else if (state === 'PENDING' || state === 'EXPECTED') {
-      requiredRunInFlight = true;
-    }
-    if (redConclusionOf(check)) {
-      requiredRunFailed = true;
-    }
-  }
-  return { requiredRunFailed, requiredRunInFlight };
+  return {
+    requiredRunFailed: statusCheckRollup.some(
+      (c) => redConclusionOf(c) !== null,
+    ),
+    requiredRunInFlight: statusCheckRollup.some(isRunInFlight),
+  };
 }
 
 /** The `mergeStateStatus` meaning GitHub itself gates the merge. */
@@ -139,7 +157,8 @@ export function formatChecksFailedReason(prProbe, evidencePath) {
 
 /**
  * A genuinely red REQUIRED check: gated, no review owns `BLOCKED`, a run is
- * red and none in flight. No evidence → false (consecutive-probe path).
+ * red and none in flight — with GitHub attribution, a required run is red and
+ * no re-run of it is in flight. No evidence → false (consecutive-probe path).
  *
  * @param {{ checksStatus?: string, mergeStateStatus?: string,
  *   reviewDecision?: string,

package/.agents/scripts/lib/orchestration/plan-metrics.js

@@ -231,75 +231,88 @@ function recordTimestamp(entry) {
  * }|null}
  */
 export function summarizePlanMetrics(ledger, opts = {}) {
-  const all = ledger?.entries ?? [];
-  const since = typeof opts.since === 'string' ? opts.since : null;
-  // ISO-8601 UTC strings compare correctly as strings.
-  const entries =
-    since === null
-      ? all
-      : all.filter((e) => {
-          const stamp = recordTimestamp(e);
-          return stamp !== null && stamp >= since;
-        });
+  const entries = scopeEntries(ledger?.entries ?? [], opts.since);
   if (entries.length === 0) return null;
-  const byCli = {};
-  const byMode = {};
-  const criticSkipsByCritic = {};
-  let criticSkips = 0;
-  let failures = 0;
-  let totalDurationMs = 0;
-  let firstStartedAt = null;
-  let lastEndedAt = null;
-  const invocationEntries = [];
-  for (const e of entries) {
-    if (e.kind === PLAN_METRICS_KIND_CRITIC_SKIP) {
-      criticSkips += 1;
-      if (typeof e.critic === 'string') {
-        criticSkipsByCritic[e.critic] =
-          (criticSkipsByCritic[e.critic] ?? 0) + 1;
-      }
-      continue;
-    }
-    if (typeof e.kind === 'string') {
-      // Other kinded records (e.g. `findings-yield`) are not invocations.
-      continue;
-    }
-    invocationEntries.push(e);
-    byCli[e.cli] = (byCli[e.cli] ?? 0) + 1;
-    if (typeof e.mode === 'string') byMode[e.mode] = (byMode[e.mode] ?? 0) + 1;
-    if (e.ok !== true) failures += 1;
-    if (typeof e.durationMs === 'number') totalDurationMs += e.durationMs;
-    if (typeof e.startedAt === 'string') {
-      if (firstStartedAt === null || e.startedAt < firstStartedAt) {
-        firstStartedAt = e.startedAt;
-      }
-    }
-    if (typeof e.endedAt === 'string') {
-      if (lastEndedAt === null || e.endedAt > lastEndedAt) {
-        lastEndedAt = e.endedAt;
-      }
-    }
-  }
-  let spanMs = null;
-  if (firstStartedAt !== null && lastEndedAt !== null) {
-    const span = Date.parse(lastEndedAt) - Date.parse(firstStartedAt);
-    if (Number.isFinite(span)) spanMs = Math.max(0, span);
-  }
+  const skips = tallyCriticSkips(entries);
+  const invocations = tallyInvocations(
+    entries.filter((e) => typeof e.kind !== 'string'),
+  );
   return {
-    invocations: invocationEntries.length,
-    failures,
-    byCli,
-    byMode,
-    criticSkips,
-    criticSkipsByCritic,
-    firstStartedAt,
-    lastEndedAt,
-    spanMs,
-    totalDurationMs,
+    invocations: invocations.count,
+    failures: invocations.failures,
+    byCli: invocations.byCli,
+    byMode: invocations.byMode,
+    criticSkips: skips.count,
+    criticSkipsByCritic: skips.byCritic,
+    firstStartedAt: invocations.firstStartedAt,
+    lastEndedAt: invocations.lastEndedAt,
+    spanMs: spanBetween(invocations.firstStartedAt, invocations.lastEndedAt),
+    totalDurationMs: invocations.totalDurationMs,
     malformedLines: ledger?.malformedLines ?? 0,
   };
 }
 
+function scopeEntries(all, since) {
+  if (typeof since !== 'string') return all;
+  // ISO-8601 UTC strings compare correctly as strings.
+  return all.filter((e) => {
+    const stamp = recordTimestamp(e);
+    return stamp !== null && stamp >= since;
+  });
+}
+
+function increment(counts, key) {
+  counts[key] = (counts[key] ?? 0) + 1;
+}
+
+function tallyCriticSkips(entries) {
+  const byCritic = {};
+  let count = 0;
+  for (const e of entries) {
+    if (e.kind !== PLAN_METRICS_KIND_CRITIC_SKIP) continue;
+    count += 1;
+    if (typeof e.critic === 'string') increment(byCritic, e.critic);
+  }
+  return { count, byCritic };
+}
+
+function earlierStamp(current, candidate) {
+  if (typeof candidate !== 'string') return current;
+  return current === null || candidate < current ? candidate : current;
+}
+
+function laterStamp(current, candidate) {
+  if (typeof candidate !== 'string') return current;
+  return current === null || candidate > current ? candidate : current;
+}
+
+function tallyInvocations(entries) {
+  const tally = {
+    count: entries.length,
+    failures: 0,
+    byCli: {},
+    byMode: {},
+    totalDurationMs: 0,
+    firstStartedAt: null,
+    lastEndedAt: null,
+  };
+  for (const e of entries) {
+    increment(tally.byCli, e.cli);
+    if (typeof e.mode === 'string') increment(tally.byMode, e.mode);
+    if (e.ok !== true) tally.failures += 1;
+    if (typeof e.durationMs === 'number') tally.totalDurationMs += e.durationMs;
+    tally.firstStartedAt = earlierStamp(tally.firstStartedAt, e.startedAt);
+    tally.lastEndedAt = laterStamp(tally.lastEndedAt, e.endedAt);
+  }
+  return tally;
+}
+
+function spanBetween(first, last) {
+  if (first === null || last === null) return null;
+  const span = Date.parse(last) - Date.parse(first);
+  return Number.isFinite(span) ? Math.max(0, span) : null;
+}
+
 /**
  * @param {ReturnType<typeof summarizePlanMetrics>} summary
  * @returns {string}

package/.agents/scripts/lib/orchestration/required-checks.js

@@ -0,0 +1,147 @@
+/**
+ * GitHub's per-PR required-check attribution (GraphQL `isRequired`), not
+ * `.agentrc` requiredChecks, which are local command names.
+ */
+
+import {
+  deriveRequiredRunEvidence,
+  failingChecksBlockMerge,
+  isRunInFlight,
+  MERGE_WAIT_GH_TIMEOUT_MS,
+  readRunName,
+  redConclusionOf,
+} from './merge-poll.js';
+
+/**
+ * A required run is red and no re-run of that same check is in flight.
+ *
+ * @param {Array<object>} statusCheckRollup non-empty
+ * @param {Set<string>} requiredNames
+ */
+function deriveAttributedEvidence(statusCheckRollup, requiredNames) {
+  const failedRequired = new Set();
+  for (const check of statusCheckRollup) {
+    const name = readRunName(check);
+    if (name && requiredNames.has(name) && redConclusionOf(check)) {
+      failedRequired.add(name);
+    }
+  }
+  let requiredRunInFlight = false;
+  let runInFlight = false;
+  for (const check of statusCheckRollup) {
+    if (!isRunInFlight(check)) continue;
+    runInFlight = true;
+    if (failedRequired.has(readRunName(check))) requiredRunInFlight = true;
+  }
+  return {
+    requiredRunFailed: failedRequired.size > 0,
+    requiredRunInFlight,
+    runInFlight,
+    attribution: 'github',
+  };
+}
+
+const REQUIRED_CHECKS_QUERY =
+  'query($id: ID!, $n: Int!) { node(id: $id) { ... on PullRequest { ' +
+  'commits(last: 1) { nodes { commit { statusCheckRollup { ' +
+  'contexts(first: 100) { nodes { __typename ' +
+  '... on CheckRun { name isRequired(pullRequestNumber: $n) } ' +
+  '... on StatusContext { context isRequired(pullRequestNumber: $n) } ' +
+  '} } } } } } } } }';
+
+/**
+ * @param {object|string} result `gh api graphql` output
+ * @returns {Set<string>}
+ */
+function parseRequiredNames(result) {
+  const text = typeof result === 'string' ? result : result?.stdout;
+  const parsed = JSON.parse(String(text ?? ''));
+  if (Array.isArray(parsed?.errors) && parsed.errors.length > 0) {
+    throw new Error('graphql errors reading required checks');
+  }
+  const nodes =
+    parsed?.data?.node?.commits?.nodes?.[0]?.commit?.statusCheckRollup?.contexts
+      ?.nodes;
+  if (!Array.isArray(nodes)) throw new Error('required-check contexts absent');
+  const names = new Set();
+  for (const node of nodes) {
+    const name = readRunName(node);
+    if (node?.isRequired === true && name) names.add(name);
+  }
+  return names;
+}
+
+/** Per-head cache: required attribution is read at most once per PR head. */
+const requiredNamesCache = new Map();
+
+/**
+ * Required check names, cached per PR head. `null` on any failure.
+ *
+ * @param {{ prNodeId?: string, prNumber: number|string, headSha?: string,
+ *   gh: { api: Function }, timeoutMs?: number }} args
+ * @returns {Promise<Set<string>|null>}
+ */
+async function readRequiredCheckNames({
+  prNodeId,
+  prNumber,
+  headSha,
+  gh,
+  timeoutMs = MERGE_WAIT_GH_TIMEOUT_MS,
+}) {
+  if (!prNodeId || !headSha) return null;
+  const key = `${prNodeId}@${headSha}`;
+  if (requiredNamesCache.has(key)) return requiredNamesCache.get(key);
+  try {
+    const names = parseRequiredNames(
+      await gh.api({
+        method: 'POST',
+        endpoint: 'graphql',
+        body: {
+          query: REQUIRED_CHECKS_QUERY,
+          variables: { id: prNodeId, n: Number(prNumber) },
+        },
+        execOpts: { timeoutMs },
+      }),
+    );
+    requiredNamesCache.set(key, names);
+    return names;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Scoped evidence when a red gates the merge and attribution reads; else
+ * the unscoped rule.
+ *
+ * @param {{ view?: object, checksStatus?: string, prNumber: number|string,
+ *   gh: object, ghTimeoutMs?: number, readFn?: Function }} args
+ * @returns {Promise<object|null>}
+ */
+export async function readProbeRunEvidence({
+  view,
+  checksStatus,
+  prNumber,
+  gh,
+  ghTimeoutMs,
+  readFn = readRequiredCheckNames,
+}) {
+  const rollup = view?.statusCheckRollup;
+  const gated = failingChecksBlockMerge({
+    checksStatus,
+    mergeStateStatus: view?.mergeStateStatus,
+  });
+  const names = gated
+    ? await readFn({
+        prNodeId: view?.id,
+        prNumber,
+        headSha: view?.headRefOid,
+        gh,
+        timeoutMs: ghTimeoutMs,
+      })
+    : null;
+  if (names instanceof Set && Array.isArray(rollup) && rollup.length > 0) {
+    return deriveAttributedEvidence(rollup, names);
+  }
+  return deriveRequiredRunEvidence(rollup);
+}

package/.agents/scripts/lib/orchestration/review-providers/code-review.js

@@ -0,0 +1,203 @@
+/**
+ * review-providers/code-review.js — a low-effort model bug review of the
+ * Story diff through `claude --print --effort low`. It asks only for
+ * merge-blocking problems, so every parsed finding is `critical` and halts
+ * close before auto-merge. The reviewer is handed the diff range, the Story
+ * id and the diff text — never `acceptance[]` or the self-eval verdict: this
+ * is a bug review, not a second acceptance scoring.
+ *
+ * A missing CLI throws at construction (the default chain entry is
+ * `optional: true`, so hosts without it skip). A review that cannot run or
+ * whose output does not parse degrades to one non-halting `suggestion`.
+ *
+ * @typedef {import('./types.js').Finding}        Finding
+ * @typedef {import('./types.js').ReviewInput}    ReviewInput
+ * @typedef {import('./types.js').ReviewProvider} ReviewProvider
+ */
+
+import { spawnCapture } from '../../child-exec.js';
+import { gitSpawn } from '../../git-utils.js';
+import { PROJECT_ROOT } from '../../project-root.js';
+import { parseProviderFindings } from './parse-findings.js';
+import { renderDepthDirective } from './review-depth.js';
+import { probeClaudeCli } from './security-review.js';
+
+const CLAUDE_ARGS = Object.freeze(['--print', '--effort', 'low']);
+const INVOKE_TIMEOUT_MS = 10 * 60 * 1000;
+/** Larger diffs are truncated; the reviewer is told so. */
+const MAX_DIFF_CHARS = 200_000;
+
+const PROMPT_HEAD =
+  'You are reviewing the diff `{baseRef}...{headRef}` for Story #{ticketId} ' +
+  'before it merges. {depthDirective}\n\n' +
+  'Report ONLY problems you would block this merge for: a bug that makes ' +
+  'the change behave incorrectly, crash, lose data, or break an existing ' +
+  'caller. Do not report style, naming, refactoring ideas, missing tests or ' +
+  'anything you would merge anyway. For each problem give the file, the ' +
+  'line in the new version, why it is wrong, and how to show it fails (an ' +
+  'input, command or test that exposes it).\n\n' +
+  'The diff below is authoritative — files on disk may not reflect it. ' +
+  'Emit ONLY a JSON array on stdout with this exact shape, no prose around ' +
+  'it:\n\n' +
+  '[{"title":"...","body":"Why it is wrong: ... How to show it fails: ...",' +
+  '"file":"...","line":1,"category":"bug"}]\n\n' +
+  'Emit [] if there is nothing you would block the merge for.\n\n';
+
+/**
+ * @param {ReviewInput} input
+ * @param {string} diff
+ * @returns {string}
+ */
+function buildPrompt(input, diff) {
+  const truncated = diff.length > MAX_DIFF_CHARS;
+  const body = truncated ? diff.slice(0, MAX_DIFF_CHARS) : diff;
+  const note = truncated
+    ? `\n[diff truncated at ${MAX_DIFF_CHARS} characters]\n`
+    : '';
+  const head = PROMPT_HEAD.replace('{baseRef}', input.baseRef)
+    .replace('{headRef}', input.headRef)
+    .replace('{ticketId}', String(input.ticketId))
+    .replace('{depthDirective}', renderDepthDirective(input.depth));
+  return `${head}<diff>\n${body}${note}\n</diff>\n`;
+}
+
+/**
+ * The prompt rides stdin so no shell ever quotes it.
+ *
+ * @param {string} prompt
+ * @param {Function} [run] - `spawnSync`-shaped seam for tests.
+ * @returns {{ status: number, stdout: string, stderr: string }}
+ */
+function invokeClaude(prompt, run) {
+  return spawnCapture('claude', [...CLAUDE_ARGS], {
+    cwd: PROJECT_ROOT,
+    input: prompt,
+    shell: process.platform === 'win32',
+    timeout: INVOKE_TIMEOUT_MS,
+    ...(run ? { run } : {}),
+  });
+}
+
+/** A model often fences its JSON; strip one surrounding fence. */
+function stripFence(text) {
+  const match = /^\s*```[a-z]*\s*\n([\s\S]*?)\n\s*```\s*$/i.exec(text ?? '');
+  return match ? match[1] : (text ?? '');
+}
+
+/**
+ * @param {string} title
+ * @param {string} detail
+ * @returns {Finding}
+ */
+function advisory(title, detail) {
+  return {
+    severity: 'suggestion',
+    title,
+    body:
+      `${detail} The model bug review did not produce a verdict — inspect ` +
+      'the diff manually before merging. Advisory only; the chain did not halt.',
+    category: 'bug',
+  };
+}
+
+/**
+ * @param {string} stdout
+ * @returns {Finding[]}
+ */
+function parseFindings(stdout) {
+  try {
+    return parseProviderFindings(stripFence(stdout), {
+      errorPrefix: '[code-review] Failed to parse reviewer stdout as JSON',
+      mapSeverity: () => 'critical',
+      defaultCategory: 'bug',
+    });
+  } catch (err) {
+    return [
+      advisory(
+        'Code review output not parseable as JSON',
+        `The reviewer returned text that did not parse as a JSON findings array (${err.message}).`,
+      ),
+    ];
+  }
+}
+
+/**
+ * @param {ReviewInput} input
+ */
+function assertInput(input) {
+  const { baseRef, headRef, ticketId } = input ?? {};
+  if (!baseRef || !headRef) {
+    throw new TypeError(
+      '[code-review] runReview requires baseRef and headRef.',
+    );
+  }
+  if (!Number.isInteger(ticketId) || ticketId <= 0) {
+    throw new TypeError(
+      '[code-review] runReview requires a positive integer ticketId.',
+    );
+  }
+}
+
+/**
+ * @param {{
+ *   probeFn?: () => boolean,
+ *   gitSpawnFn?: typeof gitSpawn,
+ *   spawnFn?: Function,
+ *   logger?: { info?: Function, warn?: Function },
+ * }} [deps] - `spawnFn` replaces `spawnSync` for the `claude` call.
+ * @returns {ReviewProvider}
+ */
+export function createCodeReviewProviderForRegistry(deps = {}) {
+  const probeFn = deps.probeFn ?? probeClaudeCli;
+  if (!probeFn()) {
+    throw new Error(
+      '[ReviewProviderFactory] codeReview provider "code-review" requires ' +
+        'the `claude` CLI on PATH but it was not detected. Install the ' +
+        'Claude Code CLI, or keep the entry `optional: true` so hosts ' +
+        'without it skip the model bug review.',
+    );
+  }
+  const gitSpawnFn = deps.gitSpawnFn ?? gitSpawn;
+  const { spawnFn, logger } = deps;
+
+  return {
+    async runReview(input) {
+      assertInput(input);
+      const { baseRef, headRef, ticketId } = input;
+      const diff = gitSpawnFn(
+        PROJECT_ROOT,
+        'diff',
+        '--no-color',
+        `${baseRef}...${headRef}`,
+      );
+      if (diff.status !== 0) {
+        return [
+          advisory(
+            'Code review could not read the diff',
+            `\`git diff ${baseRef}...${headRef}\` failed: ${diff.stderr || '<no output>'}.`,
+          ),
+        ];
+      }
+      if (diff.stdout.trim().length === 0) return [];
+
+      logger?.info?.(
+        `[code-review] Invoking claude --print --effort low for Story #${ticketId} (${baseRef}...${headRef})...`,
+      );
+      const result = invokeClaude(buildPrompt(input, diff.stdout), spawnFn);
+      if (result.status !== 0) {
+        logger?.warn?.(
+          `[code-review] claude exited ${result.status}; emitting advisory.`,
+        );
+        return [
+          advisory(
+            'Code review did not complete',
+            `\`claude --print\` exited with status ${result.status}: ${
+              result.stderr || result.stdout || '<no output>'
+            }.`,
+          ),
+        ];
+      }
+      return parseFindings(result.stdout);
+    },
+  };
+}