mandrel 2.24.0 → 2.26.0

package/.agents/scripts/pr-watch-with-update.js

@@ -12,15 +12,16 @@
  * created; this is a direct, synchronous watch with a real exit code.
  *
  * Slow-vs-failed semantics (Story #4358):
- *   - GREEN — every required check terminal + green → exit 0.
+ *   - GREEN — every required check terminal + green → exit 0, unless the
+ *             no-rerun guard says otherwise (below).
  *   - RED   — one or more required checks genuinely failed → exit 1
  *             IMMEDIATELY, consuming no resume budget. On red the CLI
- *             writes `temp/story-<id>-ci-digest.{json,md}` (failing check
- *             name, run id, a `gh run view --log-failed` tail, and a
- *             coarse classification) and prints the red-green
- *             remediation handoff. The digest is scoped by filename, so
- *             it requires `--story` (Story #4539: the digest was
- *             Epic-scoped and therefore never written on the only
+ *             disarms native auto-merge and writes
+ *             `temp/story-<id>-ci-digest.{json,md}` (failing check name,
+ *             head SHA, run id + run link, a `gh run view --log-failed`
+ *             tail, and a coarse classification). The digest is scoped by
+ *             filename, so it requires `--story` (Story #4539: the digest
+ *             was Epic-scoped and therefore never written on the only
  *             delivery path v2 has).
  *   - STILL-RUNNING — the poll cap fired with checks still pending and
  *             none failed; the watcher re-armed up to
@@ -28,27 +29,104 @@
  *             `still-running` verdict → exit 2 (NEVER 1, NEVER
  *             `timed_out`). The CLI prints the `gh pr checks --watch`
  *             handoff so the host can keep polling on its own cadence.
+ *   - UNRESOLVED — every observed required check is green but the observed
+ *             set does not reconcile with the repository's own verdict
+ *             (Story #4873) → exit 2, same "keep watching" semantics as
+ *             still-running. Withholding is the point: this watcher has
+ *             reported green on a PR GitHub was reporting as BLOCKED.
+ *   - NOT-YET-STARTED — the attach window was spent and NO required context
+ *             ever attached, while the pull request itself kept reading back
+ *             fine (Story #4890) → exit 2, the same "keep watching"
+ *             semantics. This used to map onto the red exit code, which
+ *             misroutes the caller twice over: the module reserves exit 1 for
+ *             a required check that GENUINELY FAILED, and the red path writes
+ *             a CI digest naming the failing check — so a caller routed onto
+ *             it by a set that was merely empty found nothing to read. A
+ *             still-empty required set is a slow condition, and the module
+ *             already models slow as exit 2. A `gh` fault the PR probe cannot
+ *             see past is still exit 1.
+ *
+ * Two GitHub oracles are deliberately not trusted on a single reading
+ * (Story #4873). An EMPTY `gh pr checks --required` probe is re-resolved
+ * within {@link REQUIRED_CONTEXT_ATTACH_WINDOW_MS} before it is believed —
+ * a ruleset attaches its required contexts asynchronously, and a required
+ * context that is an aggregator job gated on every other tier is by
+ * construction the LAST to appear (#4890 measured 16m52s), so a watch launched
+ * right after `gh pr create` used to fail a delivery whose CI had not been
+ * asked to start yet. And a GREEN verdict is issued only after
+ * {@link reconcileGreenVerdict} confirms the repository agrees; an
+ * unreconcilable set reports unresolved instead of green.
+ *
+ * No-rerun enforcement (Story #4865). `rules/ci-remediation.md` § Verifier
+ * forbids re-running a failed job to reach green; this CLI is the point
+ * that enforces it. Enforcement acts on the **first red** — GitHub's native
+ * auto-merge fires server-side and races any post-green detection, so a
+ * green can already have merged by the time it is observed. On red the
+ * watcher disarms auto-merge and records the head SHA; on green it reads
+ * the digest and adjudicates: a green on the SAME head SHA is a forbidden
+ * re-run (exit 1, `agent::blocked`, `meta::framework-gap` required), while
+ * a green on a NEW head SHA is a fix at source — the digest is retired,
+ * auto-merge is re-armed, and the delivery proceeds. A delivery that never
+ * went red has no digest and is untouched. Mechanism:
+ * `lib/orchestration/ci-rerun-guard.js`.
  *
  * Config (Story #4356 namespace, read via `getCiDelivery`):
  *   - `delivery.ci.watch.pollIntervalMs`
  *   - `delivery.ci.watch.maxPolls`
  *   - `delivery.ci.watch.maxResumes`
+ *   - `delivery.ci.watch.attachWindowMs` (Story #4890)
  *   CLI flags override config; config overrides the framework fallback.
  *
  * Usage:
  *   node .agents/scripts/pr-watch-with-update.js --pr <n> --story <id>
  *     [--repo owner/repo] [--max-updates N] [--poll-interval-ms MS]
- *     [--max-polls N] [--max-resumes N]
+ *     [--max-polls N] [--max-resumes N] [--attach-window-ms MS]
  */
-import { spawnSync } from 'node:child_process';
-import { mkdirSync, writeFileSync } from 'node:fs';
-import path from 'node:path';
 import { parseArgs } from 'node:util';
 import { runAsCli } from './lib/cli-utils.js';
 import { getCiDelivery } from './lib/config/ci.js';
 import { resolveConfig } from './lib/config-resolver.js';
+import { gh as defaultGh } from './lib/gh-exec.js';
 import { Logger } from './lib/Logger.js';
+import {
+  blockStoryDelivery,
+  classifyFailure,
+  classifyGreenVerdict,
+  disarmAutoMerge,
+  formatRerunViolation,
+  readCiDigest,
+  resolveDigestScope,
+  resolvePrHeadSha,
+  retireCiDigest,
+  writeCiDigest,
+} from './lib/orchestration/ci-rerun-guard.js';
 import { watchPrToTerminal } from './lib/orchestration/lifecycle/listeners/watcher.js';
+import { enableAutoMergeWith } from './lib/orchestration/single-story-close/phases/auto-merge.js';
+import { sleep as defaultSleep } from './lib/util/poll-loop.js';
+
+/** Exit code reserved for the slow-but-not-red `still-running` verdict. */
+export const STILL_RUNNING_EXIT_CODE = 2;
+
+/**
+ * How long a probe that resolved NO required contexts keeps being retried
+ * before the watch stops waiting for one (Stories #4873, #4890).
+ *
+ * A repository ruleset attaches its required contexts to a pull request
+ * asynchronously, and the arrival latency is set by the SLOWEST context in the
+ * set. Story #4873 measured tens of seconds on a cold repo and calibrated the
+ * window at 90s; #4890 measured **16m52s** on this repository, because its
+ * required context is an aggregator job gated on every other tier and is
+ * therefore, by construction, the last check to appear. A 90s window still
+ * exhausted, so the watch still aborted on a PR whose CI was working exactly
+ * as designed.
+ *
+ * The default therefore covers a late aggregator with margin rather than a
+ * fast ruleset, and it is operator-tunable on the `delivery.ci.watch.*` ladder
+ * (`attachWindowMs`) for a repository whose contexts arrive on a different
+ * cadence. Spending the window costs nothing but wall-clock on a PR nobody
+ * could merge yet; exhausting it too early costs the whole delivery.
+ */
+export const REQUIRED_CONTEXT_ATTACH_WINDOW_MS = 1_200_000;
 
 /** Framework fallbacks when neither a CLI flag nor config supplies a value. */
 export const WATCH_DEFAULTS = Object.freeze({
@@ -56,10 +134,161 @@ export const WATCH_DEFAULTS = Object.freeze({
   maxPolls: 180,
   maxUpdates: 3,
   maxResumes: 3,
+  attachWindowMs: REQUIRED_CONTEXT_ATTACH_WINDOW_MS,
 });
 
-/** Exit code reserved for the slow-but-not-red `still-running` verdict. */
-export const STILL_RUNNING_EXIT_CODE = 2;
+/**
+ * Merge-state values that reconcile an observed all-green required set with
+ * the repository's own view of the pull request (Story #4873).
+ *
+ * `BLOCKED` is the measured false-green: the watcher's `gh pr checks
+ * --required` set came back SMALLER than branch protection's — a context
+ * attached after the first probe, so it was never in `requiredChecks` — every
+ * check the watcher knew about was green, and it reported green while GitHub
+ * still refused the merge. `UNKNOWN` / an unreadable probe is not a
+ * reconciliation either: it is the absence of the second opinion, and a green
+ * verdict is exactly the verdict that must not be issued on absent evidence.
+ */
+const RECONCILED_MERGE_STATES = Object.freeze(
+  new Set(['CLEAN', 'UNSTABLE', 'HAS_HOOKS', 'BEHIND', 'DRAFT']),
+);
+
+/**
+ * Does an observed-green required set reconcile with the repository's own
+ * verdict on the PR? Pure — exported so the rule is reviewable as code.
+ *
+ * @param {{ observedRequired?: string[], mergeStateStatus?: string|null }} args
+ * @returns {{ reconciled: boolean, mergeStateStatus: string|null, reason: string }}
+ */
+export function reconcileGreenVerdict({
+  observedRequired = [],
+  mergeStateStatus,
+} = {}) {
+  const state = String(mergeStateStatus ?? '')
+    .trim()
+    .toUpperCase();
+  const observed = observedRequired.length;
+  if (!state) {
+    return {
+      reconciled: false,
+      mergeStateStatus: null,
+      reason:
+        `observed ${observed} required check(s) green, but the repository's merge state ` +
+        'could not be read — the observed set cannot be reconciled, so the green verdict is withheld',
+    };
+  }
+  if (RECONCILED_MERGE_STATES.has(state)) {
+    return {
+      reconciled: true,
+      mergeStateStatus: state,
+      reason: `observed ${observed} required check(s) green and the repository reports mergeStateStatus=${state}`,
+    };
+  }
+  return {
+    reconciled: false,
+    mergeStateStatus: state,
+    reason:
+      `observed ${observed} required check(s) green, but the repository reports ` +
+      `mergeStateStatus=${state} — branch protection is enforcing a context this watch did not observe`,
+  };
+}
+
+/** Default merge-state probe: one `gh pr view --json mergeStateStatus`. */
+async function defaultMergeStateProbe({ prRef }) {
+  try {
+    const view = await defaultGh.pr.view(prRef, ['mergeStateStatus']);
+    return typeof view?.mergeStateStatus === 'string'
+      ? view.mergeStateStatus
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Adapt the watch loop's own `ghPrViewFn` port — which already spawns
+ * `gh pr view --json mergeStateStatus` for BEHIND recovery — into the
+ * reconciliation probe, so a caller that injected one port does not have to
+ * inject a second for the same `gh` call.
+ */
+function mergeStateProbeFromView(ghPrViewFn) {
+  return async ({ prUrl, repo, cwd }) => {
+    try {
+      const view = await ghPrViewFn({ prUrl, repo, cwd });
+      if (view?.status !== 0) return null;
+      const parsed = JSON.parse(String(view.stdout ?? '').trim());
+      return typeof parsed?.mergeStateStatus === 'string'
+        ? parsed.mergeStateStatus
+        : null;
+    } catch {
+      return null;
+    }
+  };
+}
+
+/**
+ * Run the watch, re-resolving a required-check set that came back EMPTY until
+ * the attach window is spent (Stories #4873 AC-3, #4890 AC-1). Every other
+ * terminal — green, red, still-running — returns on the first arm exactly as
+ * before.
+ *
+ * Re-arming the whole call is what makes convergence possible: the required
+ * check NAMES are resolved once per `watchPrToTerminal` call, so a context that
+ * attaches minutes later is only ever seen by a fresh call.
+ *
+ * `probePrResolvable` is the **structural** classifier, re-read every round: a
+ * required set that is empty while the pull request itself reads back fine is
+ * CI that has not started, so the window is worth spending; a pull request that
+ * does not read back at all is a `gh` fault, so the window is not spent on it
+ * and the caller reports the failure immediately. `gh` overloads its exit code
+ * across both conditions, and this deliberately does not fall back to matching
+ * its stderr prose — a human-readable string is not a classification contract.
+ *
+ * @returns {Promise<object>} the watch result plus `attachRetries`, and
+ *   `prResolvable` whenever the required set stayed empty.
+ */
+async function watchWithAttachWindow({
+  watchArgs,
+  attachWindowMs,
+  retryIntervalMs,
+  sleepFn,
+  nowMsFn,
+  probePrResolvable,
+  logger,
+}) {
+  const deadline = nowMsFn() + attachWindowMs;
+  // The window is wall-clock, but the retry count is also capped: a caller
+  // running with a zero poll interval (every unit test, and a config that
+  // sets one) would otherwise spin the window out as a tight loop. Flooring
+  // the assumed cadence at 5s bounds the attempts without changing the
+  // wall-clock bound that governs a real watch.
+  const maxRetries = Math.ceil(
+    attachWindowMs / Math.max(retryIntervalMs, 5000),
+  );
+  let result = await watchPrToTerminal(watchArgs);
+  let retries = 0;
+  let prResolvable;
+  while (result.requiredChecksEmpty) {
+    prResolvable = await probePrResolvable();
+    if (!prResolvable) break;
+    if (retries >= maxRetries || nowMsFn() >= deadline) break;
+    retries += 1;
+    logger?.warn?.(
+      `[pr-watch] no required context has attached yet (${result.error}) — the pull request reads ` +
+        'back fine, so this is CI that has not started; re-resolving the required set within the ' +
+        `${Math.round(attachWindowMs / 1000)}s attach window (attempt ${retries}).`,
+    );
+    await sleepFn(retryIntervalMs);
+    result = await watchPrToTerminal(watchArgs);
+  }
+  return {
+    ...result,
+    attachRetries: retries,
+    ...(result.requiredChecksEmpty
+      ? { prResolvable: Boolean(prResolvable) }
+      : {}),
+  };
+}
 
 function parsePositiveInt(raw, fallback) {
   if (raw == null) return fallback;
@@ -76,8 +305,8 @@ function parsePositiveInt(raw, fallback) {
  *
  * @param {object} opts
  * @param {object|null} [opts.config]  resolved config (or a bare bag).
- * @param {object} [opts.flags]        `{ pollIntervalMs, maxPolls, maxResumes, maxUpdates }`.
- * @returns {{ pollIntervalMs: number, maxPolls: number, maxResumes: number, maxUpdates: number }}
+ * @param {object} [opts.flags]        `{ pollIntervalMs, maxPolls, maxResumes, maxUpdates, attachWindowMs }`.
+ * @returns {{ pollIntervalMs: number, maxPolls: number, maxResumes: number, maxUpdates: number, attachWindowMs: number }}
  */
 export function resolveWatchKnobs({ config, flags = {} } = {}) {
   const watch = getCiDelivery(config).watch ?? {};
@@ -96,165 +325,164 @@ export function resolveWatchKnobs({ config, flags = {} } = {}) {
       WATCH_DEFAULTS.maxResumes,
     ),
     maxUpdates: pick(flags.maxUpdates, undefined, WATCH_DEFAULTS.maxUpdates),
+    attachWindowMs: pick(
+      flags.attachWindowMs,
+      watch.attachWindowMs,
+      WATCH_DEFAULTS.attachWindowMs,
+    ),
   };
 }
 
-/**
- * Coarse failure classification from a failing-check name. Pure —
- * exported for tests. Deliberately shallow: it steers the operator's
- * next move (which `/loop` unit to reach for), not a root-cause verdict.
- *
- * @param {string} name  failing required-check name.
- * @returns {'test'|'lint'|'baseline'|'build'|'unknown'}
- */
-export function classifyFailure(name) {
-  const n = String(name ?? '').toLowerCase();
-  if (/lint|format|biome|markdownlint/.test(n)) return 'lint';
-  if (/baseline|coverage|crap|maintainab|duplicat/.test(n)) return 'baseline';
-  if (/build|compile|typecheck|bundle/.test(n)) return 'build';
-  if (/test|spec|validate|ci|check/.test(n)) return 'test';
-  return 'unknown';
-}
-
-/**
- * Default `gh run view --log-failed` spawn — pulls the tail of the failed
- * job log so the digest carries an actionable excerpt. Best-effort:
- * returns an empty tail when the run id is unknown or `gh` errors.
- * Exported indirectly via `writeCiDigest` injection so tests can stub
- * without shelling out.
- */
-function ghRunLogTail({ runId, cwd, spawnFn = spawnSync, maxLines = 40 }) {
-  if (!runId) return '';
-  const result = spawnFn('gh', ['run', 'view', String(runId), '--log-failed'], {
-    cwd,
-    encoding: 'utf-8',
-    shell: false,
-    maxBuffer: 10 * 1024 * 1024,
-  });
-  const out = (result.stdout ?? '').trim();
-  if (out.length === 0) return '';
-  const lines = out.split('\n');
-  return lines.slice(-maxLines).join('\n');
+/** Default re-arm: the sanctioned auto-merge enablement path. */
+function defaultReArm({ cwd, prNumber }) {
+  return enableAutoMergeWith({ cwd, prNumber });
 }
 
 /**
- * Resolve the GitHub Actions run id for a failing check. Best-effort via
- * `gh pr checks --json name,link` — the `link` field carries the run URL
- * whose trailing path segment is the run id. Returns `null` when
- * unresolvable.
+ * Red path (Story #4865). Disarm native auto-merge FIRST — that is the
+ * race-free moment, before any green can exist — then record the digest so
+ * the green path can adjudicate against the head SHA the red happened on.
+ *
+ * A disarm failure is a **blocker**, not a warning: an armed PR whose
+ * required check went red can still be merged by GitHub the instant a
+ * re-run turns it green, which is precisely what this guard exists to stop.
+ *
+ * @returns {Promise<{ headSha: string|null, disarm: object, digestPaths: object|null, blocked: boolean }>}
  */
-function resolveRunId({ prRef, checkName, cwd, spawnFn = spawnSync }) {
-  const result = spawnFn('gh', ['pr', 'checks', prRef, '--json', 'name,link'], {
-    cwd,
-    encoding: 'utf-8',
-    shell: false,
-  });
+async function handleRedWatch({
+  storyId,
+  prNumber,
+  prRef,
+  failures,
+  tempRoot,
+  cwd,
+  writeDigestFn,
+  headShaFn,
+  disarmFn,
+  blockFn,
+  logger,
+}) {
+  const disarm = disarmFn({ prRef, cwd });
+  const scope = resolveDigestScope({ storyId });
+  const headSha = scope ? headShaFn({ prRef, cwd }) : null;
+  let digestPaths = null;
   try {
-    const parsed = JSON.parse((result.stdout ?? '').trim() || '[]');
-    const entry = Array.isArray(parsed)
-      ? parsed.find((e) => e?.name === checkName)
-      : null;
-    const link = entry?.link ?? '';
-    const m = /\/runs\/(\d+)/.exec(String(link));
-    return m ? m[1] : null;
-  } catch {
-    return null;
+    digestPaths = writeDigestFn({
+      storyId,
+      prNumber,
+      headSha,
+      failures,
+      tempRoot,
+      cwd,
+      prRef,
+    });
+  } catch (err) {
+    logger.warn?.(
+      `[pr-watch] failed to write CI digest (non-fatal): ${err?.message ?? err}`,
+    );
   }
+  let blocked = false;
+  if (!disarm.disarmed) {
+    logger.error?.(
+      `[pr-watch] BLOCKER: auto-merge could NOT be disarmed on PR #${prNumber} (${disarm.detail}). ` +
+        'An armed PR can merge the moment a re-run turns it green — the no-rerun rule cannot be enforced.',
+    );
+    const outcome = await blockFn({
+      storyId,
+      body: [
+        '### Auto-merge could not be disarmed after a red check — delivery blocked',
+        '',
+        `A required check went red on PR #${prNumber}, but disarming native auto-merge failed:`,
+        '',
+        `> ${disarm.detail}`,
+        '',
+        'While the PR stays armed, GitHub can merge it server-side the instant the',
+        'checks read green — including a green reached by re-running the failed job,',
+        'which `.agents/rules/ci-remediation.md` § Verifier forbids. Disarm the PR by',
+        'hand (or fix the `gh` fault), then resume the delivery.',
+      ].join('\n'),
+    });
+    blocked = Boolean(outcome?.blocked);
+  } else {
+    logger.error?.(
+      `[pr-watch] native auto-merge ${disarm.alreadyUnarmed ? 'was already un-armed' : 'DISARMED'} on PR #${prNumber} — ` +
+        'it is re-armed only by a green on a NEW head SHA.',
+    );
+  }
+  if (digestPaths) {
+    logger.error?.(`[pr-watch] CI failure digest → ${digestPaths.jsonPath}`);
+  }
+  return { headSha, disarm, digestPaths, blocked };
 }
 
 /**
- * Resolve which ticket the digest is keyed to. Story #4539: the digest used
- * to be Epic-scoped by filename and returned `null` without an epic id — so
- * on the v2 Story path (which has no Epic and invokes the watch with `--pr`
- * alone) a red check wrote no digest at all, despite the module header
- * advertising one. v2.0.0 removed the Epic tier; Story scope is the only
- * scope.
+ * Green path (Story #4865). Adjudicate the green against any digest the
+ * scope recorded, and return the exit code with the report the caller
+ * prints.
  *
- * @param {{ storyId?: number|string|null }} opts
- * @returns {{ kind: 'story', id: number } | null}
+ * @returns {Promise<{ verdict: string, reason: string, exitCode: number, headSha: string|null, reArmed?: boolean, blocked?: boolean }>}
  */
-export function resolveDigestScope({ storyId = null } = {}) {
-  if (storyId == null || String(storyId).length === 0) return null;
-  const parsed = Number.parseInt(String(storyId), 10);
-  return Number.isInteger(parsed) && parsed > 0
-    ? { kind: 'story', id: parsed }
-    : null;
-}
-
-/**
- * Write the CI failure digest (`.json` + `.md`) for a red watch. Returns
- * the two paths written, or `null` when no story id was supplied (the
- * digest is scoped by filename and has nothing to key on). Exported for
- * tests.
- *
- * @param {object} opts
- * @param {number|string|null} [opts.storyId] The v2 delivery scope.
- * @param {number} opts.prNumber
- * @param {Array<{name:string, outcome:string}>} opts.failures
- * @param {string} opts.tempRoot
- * @param {string} opts.cwd
- * @param {string} opts.prRef
- * @param {Function} [opts.runIdFn]
- * @param {Function} [opts.logTailFn]
- * @returns {{ jsonPath: string, mdPath: string } | null}
- */
-export function writeCiDigest({
-  storyId = null,
+async function evaluateGreenWatch({
+  storyId,
   prNumber,
-  failures,
+  prRef,
   tempRoot,
   cwd,
-  prRef,
-  runIdFn = resolveRunId,
-  logTailFn = ghRunLogTail,
+  readDigestFn,
+  retireDigestFn,
+  headShaFn,
+  reArmFn,
+  blockFn,
+  logger,
 }) {
   const scope = resolveDigestScope({ storyId });
-  if (!scope) return null;
-  const primary = failures[0] ?? { name: 'unknown', outcome: 'failure' };
-  const runId = runIdFn({ prRef, checkName: primary.name, cwd });
-  const logTail = logTailFn({ runId, cwd });
-  const classification = classifyFailure(primary.name);
-  const digest = {
-    storyId: scope.id,
-    prNumber,
-    failingCheck: primary.name,
-    failingOutcome: primary.outcome,
-    runId,
-    classification,
-    allFailures: failures,
-    logTail,
-    generatedAt: new Date().toISOString(),
+  if (!scope) {
+    return {
+      verdict: 'clean',
+      reason: 'no --story scope: no digest can be keyed, guard inert',
+      exitCode: 0,
+      headSha: null,
+    };
+  }
+  const digest = readDigestFn({ storyId, tempRoot, cwd });
+  if (!digest) {
+    return {
+      verdict: 'clean',
+      reason: 'no digest for this scope: this delivery never went red',
+      exitCode: 0,
+      headSha: null,
+    };
+  }
+  const headSha = headShaFn({ prRef, cwd });
+  const { verdict, reason } = classifyGreenVerdict({ digest, headSha });
+  if (verdict === 'fix-at-source') {
+    retireDigestFn({ storyId, tempRoot, cwd });
+    const reArm = await reArmFn({ cwd, prNumber });
+    const reArmed = Boolean(reArm?.enabled);
+    logger.info?.(
+      `[pr-watch] green on a NEW head SHA (${reason}) — fix at source; digest retired, ` +
+        `auto-merge ${reArmed ? 're-armed' : `NOT re-armed (${reArm?.reason ?? 'unknown'})`}.`,
+    );
+    return { verdict, reason, exitCode: 0, headSha, reArmed };
+  }
+  const body = formatRerunViolation({ digest, headSha, prNumber, reason });
+  logger.error?.(
+    `[pr-watch] FORBIDDEN CI RE-RUN: ${reason}. Required check \`${digest.failingCheck}\` was red on this exact commit.`,
+  );
+  logger.error?.(
+    `[pr-watch] run link: ${digest.runUrl ?? `run id ${digest.runId ?? 'unresolved'}`} — classification: ${digest.classification ?? 'unknown'}`,
+  );
+  logger.error?.(
+    '[pr-watch] fix the root cause and push a new commit, or file a `meta::framework-gap` issue carrying the run link and failure signature.',
+  );
+  const outcome = await blockFn({ storyId, body });
+  return {
+    verdict,
+    reason,
+    exitCode: 1,
+    headSha,
+    blocked: Boolean(outcome?.blocked),
   };
-  const dir = path.isAbsolute(tempRoot) ? tempRoot : path.join(cwd, tempRoot);
-  mkdirSync(dir, { recursive: true });
-  const base = `${scope.kind}-${scope.id}-ci-digest`;
-  const jsonPath = path.join(dir, `${base}.json`);
-  const mdPath = path.join(dir, `${base}.md`);
-  writeFileSync(jsonPath, `${JSON.stringify(digest, null, 2)}\n`);
-  const md = [
-    `# CI failure digest — Story #${scope.id} (PR #${prNumber})`,
-    '',
-    `- **Failing check:** \`${digest.failingCheck}\` (${digest.failingOutcome})`,
-    `- **Run id:** ${runId ?? 'unresolved'}`,
-    `- **Classification:** ${classification}`,
-    `- **Generated:** ${digest.generatedAt}`,
-    '',
-    failures.length > 1
-      ? `Other non-green checks: ${failures
-          .slice(1)
-          .map((f) => `\`${f.name}\`=${f.outcome}`)
-          .join(', ')}`
-      : '',
-    '',
-    '## `gh run view --log-failed` tail',
-    '',
-    '```text',
-    logTail || '(no failed-log output available)',
-    '```',
-    '',
-  ].join('\n');
-  writeFileSync(mdPath, md);
-  return { jsonPath, mdPath };
 }
 
 /**
@@ -262,17 +490,24 @@ export function writeCiDigest({
  * the green / red / still-running / BEHIND paths can be exercised with
  * injected `gh` spawns and no `process.exit`.
  *
- *   0 → all required checks green.
- *   1 → a required check genuinely failed (red).
- *   2 → still-running (slow CI): cap + resume budget exhausted, none red.
+ *   0 → all required checks green (and the no-rerun guard cleared them).
+ *   1 → a required check genuinely failed (red), OR the green was reached
+ *       by a forbidden re-run of the same commit, OR the pull request itself
+ *       could not be read (a `gh` / access fault).
+ *   2 → slow-but-not-red: still-running (cap + resume budget exhausted, none
+ *       red), an unreconcilable green, or no required context attached within
+ *       the attach window while the PR kept reading back fine (#4890).
  *
  * @param {object} opts
  * @param {number} opts.prNumber
- * @param {string|null} [opts.repo]
+ * @param {string|null} [opts.repo]           `owner/repo`; passed to `gh` as `--repo`.
  * @param {number|string} [opts.maxUpdates]
  * @param {number|string} [opts.pollIntervalMs]
  * @param {number|string} [opts.maxPolls]
  * @param {number|string} [opts.maxResumes]
+ * @param {number|string} [opts.attachWindowMs] override the required-context
+ *   attach window for one run (flag → `delivery.ci.watch.attachWindowMs` →
+ *   {@link REQUIRED_CONTEXT_ATTACH_WINDOW_MS}).
  * @param {object|null} [opts.config]         resolved config (defaults to resolveConfig()).
  * @param {string} [opts.tempRoot]            digest output dir (default `temp`).
  * @param {Function} [opts.ghPrChecksFn]      inject for tests
@@ -280,6 +515,12 @@ export function writeCiDigest({
  * @param {Function} [opts.ghPrUpdateBranchFn] inject for tests
  * @param {Function} [opts.sleepFn]           inject for tests
  * @param {Function} [opts.writeDigestFn]     inject for tests (default writeCiDigest)
+ * @param {Function} [opts.readDigestFn]      inject for tests (default readCiDigest)
+ * @param {Function} [opts.retireDigestFn]    inject for tests (default retireCiDigest)
+ * @param {Function} [opts.headShaFn]         inject for tests (default resolvePrHeadSha)
+ * @param {Function} [opts.disarmAutoMergeFn] inject for tests (default disarmAutoMerge)
+ * @param {Function} [opts.reArmAutoMergeFn]  inject for tests (default enableAutoMergeWith)
+ * @param {Function} [opts.blockDeliveryFn]   inject for tests (default blockStoryDelivery)
  * @param {object} [opts.logger]
  * @param {(line: string) => void} [opts.print] stdout sink (default process.stdout)
  * @returns {Promise<number>} process exit code.
@@ -299,6 +540,15 @@ export async function runPrWatch({
   ghPrUpdateBranchFn,
   sleepFn,
   writeDigestFn = writeCiDigest,
+  readDigestFn = readCiDigest,
+  retireDigestFn = retireCiDigest,
+  headShaFn = resolvePrHeadSha,
+  disarmAutoMergeFn = disarmAutoMerge,
+  reArmAutoMergeFn = defaultReArm,
+  blockDeliveryFn = blockStoryDelivery,
+  mergeStateProbeFn,
+  attachWindowMs,
+  nowMsFn = Date.now,
   logger = Logger,
   print = (line) => process.stdout.write(`${line}\n`),
 } = {}) {
@@ -309,63 +559,156 @@ export async function runPrWatch({
     config !== undefined ? config : safeResolveConfig(logger);
   const knobs = resolveWatchKnobs({
     config: resolvedConfig,
-    flags: { pollIntervalMs, maxPolls, maxResumes, maxUpdates },
+    flags: {
+      pollIntervalMs,
+      maxPolls,
+      maxResumes,
+      maxUpdates,
+      attachWindowMs,
+    },
   });
   const effectiveTempRoot =
     tempRoot ?? resolvedConfig?.project?.paths?.tempRoot ?? 'temp';
+  const cwd = process.cwd();
+
+  // `gh` has NO `<owner/repo>#<number>` argument form — it parses that string
+  // as a BRANCH NAME, which is why every `--repo` invocation used to fail at
+  // the first probe with a misleading `gh-checks-failed:status=1` (#4890). The
+  // repository therefore travels two sanctioned ways, never as a composed ref:
+  //   - a real `--repo` flag on the watch ports, which build their own argv;
+  //   - a canonical PR URL for the no-rerun-guard helpers, which take a bare
+  //     ref and no repository of their own.
+  // With `--repo` omitted, `gh` infers the repository from the cwd's remote.
+  const prRef = String(prNumber);
+  const guardPrRef = repo
+    ? `https://github.com/${repo}/pull/${prNumber}`
+    : prRef;
 
-  // `gh` accepts a bare PR number or a URL; passing `<repo>#<n>` lets
-  // `gh` resolve the right repository without a URL. When `--repo` is
-  // omitted, `gh` infers the repo from the cwd's remote.
-  const prRef = repo ? `${repo}#${prNumber}` : String(prNumber);
+  // One merge-state probe, resolved once and used for both readings that need
+  // the repository's own view of the PR: the empty-required-set classification
+  // below, and the green-verdict reconciliation further down.
+  const probeMergeState =
+    mergeStateProbeFn ??
+    (ghPrViewFn ? mergeStateProbeFromView(ghPrViewFn) : defaultMergeStateProbe);
+  const readMergeState = () =>
+    probeMergeState({ prRef: guardPrRef, prUrl: prRef, repo, cwd, prNumber });
 
-  const result = await watchPrToTerminal({
-    prUrl: prRef,
-    cwd: process.cwd(),
-    maxPolls: knobs.maxPolls,
-    maxUpdates: knobs.maxUpdates,
-    maxResumes: knobs.maxResumes,
-    pollIntervalMs: knobs.pollIntervalMs,
-    ...(ghPrChecksFn ? { ghPrChecksFn } : {}),
-    ...(ghPrViewFn ? { ghPrViewFn } : {}),
-    ...(ghPrUpdateBranchFn ? { ghPrUpdateBranchFn } : {}),
-    ...(sleepFn ? { sleepFn } : {}),
+  const result = await watchWithAttachWindow({
+    watchArgs: {
+      prUrl: prRef,
+      repo,
+      cwd,
+      maxPolls: knobs.maxPolls,
+      maxUpdates: knobs.maxUpdates,
+      maxResumes: knobs.maxResumes,
+      pollIntervalMs: knobs.pollIntervalMs,
+      ...(ghPrChecksFn ? { ghPrChecksFn } : {}),
+      ...(ghPrViewFn ? { ghPrViewFn } : {}),
+      ...(ghPrUpdateBranchFn ? { ghPrUpdateBranchFn } : {}),
+      ...(sleepFn ? { sleepFn } : {}),
+      logger,
+    },
+    attachWindowMs: knobs.attachWindowMs,
+    retryIntervalMs: knobs.pollIntervalMs,
+    sleepFn: sleepFn ?? defaultSleep,
+    nowMsFn,
+    // Structural, not prose: the PR reads back ⇒ `gh` works and the empty
+    // required set is CI that has not started yet.
+    probePrResolvable: async () => (await readMergeState()) !== null,
     logger,
   });
 
   // Always print the final outcomes map so the operator (and the
   // workflow log) can see exactly which check blocked.
-  print(
-    JSON.stringify({
-      prNumber,
-      checkOutcomes: result.outcomes,
-      requiredChecks: result.requiredChecks,
-      polls: result.polls,
-      updatesApplied: result.updatesApplied,
-      resumesApplied: result.resumesApplied,
-      terminal: result.terminal,
-      green: result.green,
-      stillRunning: result.stillRunning,
-      ...(result.error ? { error: result.error } : {}),
-    }),
-  );
+  const envelope = {
+    prNumber,
+    checkOutcomes: result.outcomes,
+    requiredChecks: result.requiredChecks,
+    polls: result.polls,
+    updatesApplied: result.updatesApplied,
+    resumesApplied: result.resumesApplied,
+    terminal: result.terminal,
+    green: result.green,
+    stillRunning: result.stillRunning,
+    ...(result.attachRetries ? { attachRetries: result.attachRetries } : {}),
+    ...(result.error ? { error: result.error } : {}),
+  };
 
-  if (result.error) {
+  if (result.requiredChecksEmpty || result.error) {
+    // The attach window is spent and the required set is still empty. Classify
+    // it structurally — never against `gh`'s stderr prose (Story #4890).
+    const notYetStarted = Boolean(
+      result.requiredChecksEmpty && result.prResolvable,
+    );
+    print(
+      JSON.stringify({
+        ...envelope,
+        requiredChecksEmpty: Boolean(result.requiredChecksEmpty),
+        notYetStarted,
+      }),
+    );
+    if (notYetStarted) {
+      logger.warn?.(
+        `[pr-watch] no required check has attached to PR #${prNumber} within the ` +
+          `${Math.round(knobs.attachWindowMs / 1000)}s attach window (${result.attachRetries} re-resolutions), ` +
+          'and the pull request still reads back fine — this is CI that has not started, NOT a red check. ' +
+          'Keep polling natively:',
+      );
+      logger.warn?.('[pr-watch]   gh pr checks <pr> --watch');
+      return STILL_RUNNING_EXIT_CODE;
+    }
     logger.error?.(
-      `[pr-watch] could not resolve required checks: ${result.error}`,
+      `[pr-watch] could not resolve required checks: ${result.error} — the pull request itself could ` +
+        'not be read, so this is a `gh` / access fault rather than CI that has not started.',
     );
     return 1;
   }
 
   if (result.green) {
-    logger.info?.('[pr-watch] all required checks green.');
-    return 0;
+    // Never green on an undercount (Story #4873). The observed required set is
+    // whatever `gh pr checks --required` returned on the FIRST probe; when a
+    // ruleset attached a context after that, every check we knew about can be
+    // green while GitHub still refuses the merge. Reconcile against the
+    // repository's own verdict before any green is issued — an unreconcilable
+    // set reports unresolved (exit 2, keep watching) rather than a false green
+    // or a false red.
+    const reconciliation = reconcileGreenVerdict({
+      observedRequired: result.requiredChecks,
+      mergeStateStatus: await readMergeState(),
+    });
+    if (!reconciliation.reconciled) {
+      print(JSON.stringify({ ...envelope, reconciliation }));
+      logger.warn?.(
+        `[pr-watch] withholding the green verdict: ${reconciliation.reason}. ` +
+          'Re-run the watch once the repository settles, or inspect branch protection for a context this watch never saw.',
+      );
+      return STILL_RUNNING_EXIT_CODE;
+    }
+    const guard = await evaluateGreenWatch({
+      storyId,
+      prNumber,
+      prRef: guardPrRef,
+      tempRoot: effectiveTempRoot,
+      cwd,
+      readDigestFn,
+      retireDigestFn,
+      headShaFn,
+      reArmFn: reArmAutoMergeFn,
+      blockFn: blockDeliveryFn,
+      logger,
+    });
+    print(JSON.stringify({ ...envelope, reconciliation, rerunGuard: guard }));
+    if (guard.exitCode === 0) {
+      logger.info?.('[pr-watch] all required checks green.');
+    }
+    return guard.exitCode;
   }
 
   // Slow-but-not-red: the cap AND resume budget are exhausted with checks
   // still pending and none failed. Never exit 1, never `timed_out` — hand
   // off to the host's interval loop and exit 2.
   if (result.stillRunning) {
+    print(JSON.stringify(envelope));
     const stillPending = Object.entries(result.outcomes)
       .filter(([, v]) => v === 'still-running')
       .map(([k]) => k)
@@ -377,8 +720,8 @@ export async function runPrWatch({
     return STILL_RUNNING_EXIT_CODE;
   }
 
-  // Genuine red check — exit 1 immediately, write the digest, and surface
-  // the fix-loop handoff.
+  // Genuine red check — exit 1 immediately, disarm auto-merge, write the
+  // digest, and surface the fix-loop handoff.
   // Exclude 'still-running' as well as the non-failing states: when the cap
   // fires with a mixed failed+pending map, promotePendingToStillRunning has
   // rewritten the pending entries, and a still-running check is slow, not
@@ -395,26 +738,36 @@ export async function runPrWatch({
     .map(([name, outcome]) => ({ name, outcome }));
   const red = failures.map((f) => `${f.name}=${f.outcome}`).join(', ');
   logger.error?.(`[pr-watch] required check(s) not green: ${red}`);
-  let digestPaths = null;
-  try {
-    digestPaths = writeDigestFn({
-      storyId,
-      prNumber,
-      failures,
-      tempRoot: effectiveTempRoot,
-      cwd: process.cwd(),
-      prRef,
-    });
-  } catch (err) {
-    logger.warn?.(
-      `[pr-watch] failed to write CI digest (non-fatal): ${err?.message ?? err}`,
-    );
-  }
-  if (digestPaths) {
-    logger.error?.(`[pr-watch] CI failure digest → ${digestPaths.jsonPath}`);
-  }
+  const redOutcome = await handleRedWatch({
+    storyId,
+    prNumber,
+    prRef: guardPrRef,
+    failures,
+    tempRoot: effectiveTempRoot,
+    cwd,
+    writeDigestFn,
+    headShaFn,
+    disarmFn: disarmAutoMergeFn,
+    blockFn: blockDeliveryFn,
+    logger,
+  });
+  print(
+    JSON.stringify({
+      ...envelope,
+      classification: classifyFailure(failures[0]?.name),
+      rerunGuard: {
+        verdict: 'red',
+        headSha: redOutcome.headSha,
+        autoMergeDisarmed: redOutcome.disarm.disarmed,
+        disarmDetail: redOutcome.disarm.detail,
+        digestPath: redOutcome.digestPaths?.jsonPath ?? null,
+        blocked: redOutcome.blocked,
+      },
+    }),
+  );
   logger.error?.(
-    '[pr-watch] a required check failed. Read the digest, apply the smallest fix, and re-run the suite until green.',
+    '[pr-watch] a required check failed. Read the digest, reproduce the failure, and apply the smallest fix at source, ' +
+      'then push a new commit — re-running the failed job is forbidden (`.agents/rules/ci-remediation.md` § Verifier).',
   );
   return 1;
 }
@@ -441,6 +794,7 @@ async function main() {
       'poll-interval-ms': { type: 'string' },
       'max-polls': { type: 'string' },
       'max-resumes': { type: 'string' },
+      'attach-window-ms': { type: 'string' },
     },
     strict: false,
   });
@@ -452,6 +806,7 @@ async function main() {
     pollIntervalMs: values['poll-interval-ms'],
     maxPolls: values['max-polls'],
     maxResumes: values['max-resumes'],
+    attachWindowMs: values['attach-window-ms'],
   });
 }