@revisium/orchestrator 0.1.0-alpha.8 → 0.1.0

package/dist/runners/integrator.js

@@ -18,7 +18,7 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
  * Exposes:
  *   - integrate(input, deps)     — REAL integrator (live only); git/gh side effects; resumable.
  *   - stubIntegrate(input)       — STUB (script only); ZERO external effects; pure + deterministic.
- *   - preflightLive(taskId, base, deps) — LIVE PREFLIGHT; clean check + base freshness; one-shot.
+ *   - preflightLive(taskId, base, deps) — LIVE PREFLIGHT; clean check + base availability; one-shot.
  *   - IntegratorService          — @Injectable wrapper with bound arrow properties.
  *
  * The pure primitives (resolveExecutable, branchName, parseOwnerRepo) and shared types live in
@@ -27,8 +27,9 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
  */
 import { Inject, Injectable } from '@nestjs/common';
 import { execFileSync } from 'node:child_process';
-import { collectPrReadiness } from '../poller/pr-readiness-core.js';
+import { collectPrReadiness, fetchRequiredCheckNames, } from '../poller/pr-readiness-core.js';
 import { RunService } from '../revisium/run.service.js';
+import { issueRefTag } from '../run/issue-ref.js';
 import { resolveGhAccount, resolvePinnedGh } from './gh-identity.js';
 import { gitAbsPath, branchExists, countAhead } from './integrator-git.js';
 import { resolveOwnerRepo } from './integrator-remote.js';
@@ -38,7 +39,23 @@ import { branchName } from './integrator-branch-naming.js';
 export { resolveExecutable } from './integrator-git.js';
 export { branchName };
 export { parseOwnerRepo } from './integrator-remote.js';
-function findOrCreatePr(ownerRepo, branch, base, title, execGh) {
+function issueBoundTitle(title, issueRef, ownerRepo) {
+    const tag = issueRefTag(issueRef, ownerRepo);
+    return tag ? `${tag} ${title}` : title;
+}
+function commitMessage(title, issueRef, ownerRepo) {
+    const tag = issueRefTag(issueRef, ownerRepo);
+    return tag ? `feat: ${tag} ${title}` : `feat: ${title}`;
+}
+function parsePrList(raw) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`gh pr list returned non-JSON: ${raw.slice(0, 200)}`);
+    }
+}
+function matchingOpenPr(ownerRepo, branch, base, execGh, jsonFields) {
     const raw = execGh([
         'pr',
         'list',
@@ -49,21 +66,14 @@ function findOrCreatePr(ownerRepo, branch, base, title, execGh) {
         '--state',
         'open',
         '--json',
-        'number,url,baseRefName',
+        jsonFields,
     ]);
-    let entries;
-    try {
-        entries = JSON.parse(raw);
-    }
-    catch {
-        throw new Error(`gh pr list returned non-JSON: ${raw.slice(0, 200)}`);
-    }
-    const matching = entries.filter((p) => p.baseRefName === base);
+    const matching = parsePrList(raw).filter((p) => p.baseRefName === base);
     if (matching.length === 1) {
         const pr = matching[0];
         if (!pr)
             throw new Error('unexpected empty match');
-        return { prUrl: pr.url, prNumber: pr.number };
+        return { prUrl: pr.url, prNumber: pr.number, ...(pr.headRefOid ? { headSha: pr.headRefOid } : {}) };
     }
     if (matching.length > 1) {
         const candidates = matching.map((p) => `#${p.number}`).join(', ');
@@ -72,7 +82,9 @@ function findOrCreatePr(ownerRepo, branch, base, title, execGh) {
             lesson: `Ambiguous: ${matching.length} open PRs for branch "${branch}" targeting "${base}" in ${ownerRepo} — candidates ${candidates} — manual review needed`,
         };
     }
-    // 0 matches — create
+    return null;
+}
+function createPr(ownerRepo, branch, base, title, issueRef, execGh) {
     const createOut = execGh([
         'pr',
         'create',
@@ -84,7 +96,7 @@ function findOrCreatePr(ownerRepo, branch, base, title, execGh) {
         '--head',
         branch,
         '--title',
-        title,
+        issueBoundTitle(title, issueRef, ownerRepo),
         '--body',
         '',
     ]);
@@ -115,17 +127,29 @@ function findOrCreatePr(ownerRepo, branch, base, title, execGh) {
     }
     return { prUrl: viewData.url, prNumber: viewData.number };
 }
+function findOrCreatePr(ownerRepo, branch, base, title, issueRef, execGh) {
+    const existing = matchingOpenPr(ownerRepo, branch, base, execGh, 'number,url,baseRefName');
+    if (existing && !('needsHuman' in existing)) {
+        return { prUrl: existing.prUrl, prNumber: existing.prNumber };
+    }
+    if (existing)
+        return existing;
+    return createPr(ownerRepo, branch, base, title, issueRef, execGh);
+}
+function findExistingPrWithHead(ownerRepo, branch, base, execGh) {
+    return matchingOpenPr(ownerRepo, branch, base, execGh, 'number,url,baseRefName,headRefOid');
+}
 // ─── Preflight (B5+B7) ────────────────────────────────────────────────────────
 /**
- * preflightLive — clean check + base freshness, evaluated ONCE as a memoized DBOS step.
+ * preflightLive — clean check + base availability, evaluated ONCE as a memoized DBOS step.
  * Only called on live runs; script/stub runs skip this entirely.
  *
  * 1. git fetch origin <base>   (idempotent — the only mutation)
  * 2. git status --porcelain    → non-empty → block (repo not clean)
- * 3. Verify base branch runs are exactly on origin/<base>, while feature branch runs
- *    are based on origin/<base> → mismatch → block
+ * 3. Verify origin/<base> resolves. Non-base caller branches are allowed because the run worktree
+ *    is cut from origin/<base>; the caller checkout is never switched or rebased.
  *
- * Returns { ok: true } when the repo is clean and based on fresh origin/<base>.
+ * Returns { ok: true } when the caller repo is clean and origin/<base> is available.
  * Returns IntegratorBlocked on ANY failure — no throw, so DBOS does NOT retry.
  */
 export async function preflightLive(taskId, base, deps) {
@@ -150,9 +174,9 @@ export async function preflightLive(taskId, base, deps) {
             lesson: `target repo ${cwd} is not clean (${lineCount} uncommitted change${lineCount === 1 ? '' : 's'}); commit/stash and retry --live`,
         };
     }
-    // 3. Base freshness:
-    //    - base branch itself must exactly match origin/<base>
-    //    - feature branches are valid when origin/<base> is an ancestor of HEAD
+    // 3. Base availability. The isolated run worktree is created later from origin/<base>, so feature
+    // branches in the caller checkout do not need to be based on the fresh base. The only caller-branch
+    // policy we preserve here is fail-loud protection for local-only commits on the base branch itself.
     let headBranch;
     let headSha;
     let originSha;
@@ -164,27 +188,24 @@ export async function preflightLive(taskId, base, deps) {
     catch (err) {
         return {
             needsHuman: true,
-            lesson: `live preflight: cannot verify base freshness — ${String(err)}`,
+            lesson: `live preflight: cannot resolve origin/${base} after fetch — ${String(err)}`,
         };
     }
     if (headBranch === base && headSha !== originSha) {
-        return {
-            needsHuman: true,
-            lesson: `target repo base branch is not on fresh origin/${base} ` +
-                `(HEAD=${headBranch}@${headSha.slice(0, 8)}, expected ${base}@${originSha.slice(0, 8)}); ` +
-                `pull ${base}, then retry --live`,
-        };
-    }
-    if (headBranch !== base) {
+        let behind = false;
         try {
-            execGit(['merge-base', '--is-ancestor', `origin/${base}`, 'HEAD'], cwd);
+            execGit(['merge-base', '--is-ancestor', 'HEAD', `origin/${base}`], cwd);
+            behind = true;
         }
         catch {
+            behind = false; // not an ancestor → diverged (or unrelated)
+        }
+        if (!behind) {
             return {
                 needsHuman: true,
-                lesson: `target repo branch is not based on fresh origin/${base} ` +
-                    `(HEAD=${headBranch}@${headSha.slice(0, 8)}, expected origin/${base}@${originSha.slice(0, 8)} as ancestor); ` +
-                    `rebase or merge origin/${base}, then retry --live`,
+                lesson: `target repo base branch ${base} has local-only or diverged commits relative to origin/${base} ` +
+                    `(HEAD=${headSha.slice(0, 8)} has local commits absent from origin/${base}@${originSha.slice(0, 8)}); ` +
+                    `reconcile manually, then retry --live`,
             };
         }
     }
@@ -200,8 +221,43 @@ export function stubIntegrate(input) {
         prUrl: 'stub://pr/placeholder',
         branch: `feat/${input.taskId}-stub`,
         prNumber: 0,
+        ...(input.issueRef ? { issueRef: input.issueRef } : {}),
+    };
+}
+export async function captureProducedChange(input, deps) {
+    const { execGit: git, resolveRunCwd } = deps;
+    const cwd = await resolveRunCwd(input.runId, input.taskId);
+    const branch = branchName(input.taskId, input.title, input.issueRef);
+    const ownerRepoResult = resolveOwnerRepo(git, cwd);
+    const ownerRepo = 'needsHuman' in ownerRepoResult ? undefined : ownerRepoResult.ownerRepo;
+    if (branchExists(git, cwd, branch)) {
+        git(['switch', branch], cwd);
+    }
+    else {
+        git(['switch', '-c', branch], cwd);
+    }
+    git(['add', '-A'], cwd);
+    if (stagedDiffPresent(git, cwd)) {
+        git(['commit', '-m', commitMessage(input.title, input.issueRef, ownerRepo)], cwd);
+    }
+    const headSha = git(['rev-parse', 'HEAD'], cwd).trim();
+    return {
+        branch,
+        headSha,
+        ...(input.issueRef ? { issueRef: input.issueRef } : {}),
+        worktreePath: cwd,
+        ...(input.artifactRef ? { artifactRef: input.artifactRef } : {}),
     };
 }
+function stagedDiffPresent(git, cwd) {
+    try {
+        git(['diff', '--cached', '--quiet'], cwd);
+        return false;
+    }
+    catch {
+        return true;
+    }
+}
 // ─── REAL integrator (live only) ─────────────────────────────────────────────
 /**
  * integrate — REAL integrator (live only).
@@ -209,12 +265,14 @@ export function stubIntegrate(input) {
  * push + find-or-create PR even if commit already happened (ahead guard).
  */
 export async function integrate(input, deps) {
+    if (input.change)
+        return integrateProducedChange(input, deps, input.change);
     const { execGit: git, execGh: gh, resolveRunCwd } = deps;
     // Resolve the run's ISOLATED worktree (plan 0017) — it is already checked out on `branch`, so the
     // branchExists→switch path below is a no-op and the dirty-tree `switch -c origin/<base>` (which
     // failed when the base checkout carried prior-run changes) is never taken.
     const cwd = await resolveRunCwd(input.runId, input.taskId);
-    const branch = branchName(input.taskId, input.title);
+    const branch = branchName(input.taskId, input.title, input.issueRef);
     // 1. Derive owner/repo
     const ownerRepoResult = resolveOwnerRepo(git, cwd);
     if ('needsHuman' in ownerRepoResult)
@@ -232,38 +290,97 @@ export async function integrate(input, deps) {
     // 4. Stage all changes (safe: clean-repo precondition from preflight)
     git(['add', '-A'], cwd);
     // 5. Commit decision (B4 replay safety)
-    let hasStagedDiff;
-    try {
-        git(['diff', '--cached', '--quiet'], cwd);
-        hasStagedDiff = false; // exit 0 → nothing staged
-    }
-    catch {
-        hasStagedDiff = true; // exit 1 → staged diff present
-    }
-    if (hasStagedDiff) {
+    if (stagedDiffPresent(git, cwd)) {
         // Commit — NO Co-Authored-By, NO summary footer (MEMORY)
-        const commitMsg = `feat: ${input.title}`;
+        const commitMsg = commitMessage(input.title, input.issueRef, ownerRepo);
         git(['commit', '-m', commitMsg], cwd);
     }
     else {
         // No staged diff — check if branch is ahead of origin/<base>
         const ahead = countAhead(git, cwd, branch, input.base);
         if (ahead === 0) {
-            // Nothing to integrate — no commit, not ahead
-            return {
-                needsHuman: true,
-                lesson: 'nothing to integrate — no staged changes and branch is not ahead of origin/' + input.base,
-            };
+            // Probe the BASE checkout for uncommitted changes: if it is dirty the developer wrote OUTSIDE
+            // the run's worktree (the slice-143 / #130 symptom). Only changes the diagnostic lesson; no
+            // destructive action, so a rare mis-attribution is still a useful signal.
+            let lesson = 'nothing to integrate — no staged changes and branch is not ahead of origin/' + input.base;
+            try {
+                const baseCwd = await deps.resolveTaskCwd(input.taskId);
+                const basePorcelain = git(['status', '--porcelain'], baseCwd).trim();
+                if (basePorcelain !== '') {
+                    lesson =
+                        `developer produced changes but the run's worktree is empty — they appear to have been ` +
+                            `written OUTSIDE the worktree (the base checkout ${baseCwd} is dirty); see slice 143. ` +
+                            `Re-run; the agent must write under its cwd / $REVO_WORKTREE_PATH.`;
+                }
+            }
+            catch {
+                // git error on the base — keep the generic lesson
+            }
+            return { needsHuman: true, lesson };
         }
         // Ahead but no staged diff → commit happened on a prior attempt; fall through to push
     }
     // 6. Push (idempotent — no force)
     git(['push', '-u', 'origin', branch], cwd);
     // 7. Find-or-create PR
-    const prResult = findOrCreatePr(ownerRepo, branch, input.base, input.title, gh);
+    const prResult = findOrCreatePr(ownerRepo, branch, input.base, input.title, input.issueRef, gh);
     if ('needsHuman' in prResult)
         return prResult;
-    return { prUrl: prResult.prUrl, branch, prNumber: prResult.prNumber };
+    return { prUrl: prResult.prUrl, branch, prNumber: prResult.prNumber, ...(input.issueRef ? { issueRef: input.issueRef } : {}) };
+}
+async function integrateProducedChange(input, deps, change) {
+    const { execGit: git, execGh: gh } = deps;
+    const cwd = change.worktreePath ?? await deps.resolveRunCwd(input.runId, input.taskId);
+    const branch = change.branch;
+    const issueRef = change.issueRef ?? input.issueRef;
+    const ownerRepoResult = resolveOwnerRepo(git, cwd);
+    if ('needsHuman' in ownerRepoResult)
+        return ownerRepoResult;
+    const { ownerRepo } = ownerRepoResult;
+    git(['fetch', 'origin', input.base], cwd);
+    const existing = findExistingPrWithHead(ownerRepo, branch, input.base, gh);
+    if (existing && 'needsHuman' in existing)
+        return existing;
+    if (existing?.headSha === change.headSha) {
+        return {
+            prUrl: existing.prUrl,
+            branch,
+            prNumber: existing.prNumber,
+            ...(issueRef ? { issueRef } : {}),
+            headSha: change.headSha,
+            status: 'noop',
+            message: 'nothing to integrate — produced head already pushed and equals PR head',
+        };
+    }
+    if (!existing && countAhead(git, cwd, change.headSha, input.base) === 0) {
+        return {
+            needsHuman: true,
+            lesson: `nothing to integrate — produced head ${change.headSha.slice(0, 8)} is not ahead of ` +
+                `origin/${input.base} and no open PR exists`,
+        };
+    }
+    git(['push', 'origin', `${change.headSha}:refs/heads/${branch}`], cwd);
+    if (existing) {
+        return {
+            prUrl: existing.prUrl,
+            branch,
+            prNumber: existing.prNumber,
+            ...(issueRef ? { issueRef } : {}),
+            headSha: change.headSha,
+            status: 'pushed',
+        };
+    }
+    const created = createPr(ownerRepo, branch, input.base, input.title, issueRef, gh);
+    if ('needsHuman' in created)
+        return created;
+    return {
+        prUrl: created.prUrl,
+        branch,
+        prNumber: created.prNumber,
+        ...(issueRef ? { issueRef } : {}),
+        headSha: change.headSha,
+        status: 'pushed',
+    };
 }
 /**
  * confirmMerge — REAL (live only). Ensures the run's PR is actually merged before the run reaches its
@@ -271,8 +388,8 @@ export async function integrate(input, deps) {
  * base — truly disposable). Idempotent + replay-safe:
  *
  *  1. `gh pr view` the run's branch. Already `merged` (a human merged it) → succeed.
- *  2. Not merged + OPEN + `mergeStateStatus === CLEAN` (CI green, no conflicts) → `gh pr merge --squash
- *     --delete-branch`, then re-view to CONFIRM merged → succeed; otherwise block.
+ *  2. Not merged + OPEN + `mergeStateStatus === CLEAN` (CI green, no conflicts) + a fresh readiness head
+ *     → `gh pr merge --squash --delete-branch --match-head-commit <sha>`, then re-view to CONFIRM merged.
  *  3. Not mergeable (not OPEN, or not CLEAN — red CI / conflicts / blocked) → block (needsHuman), which
  *     routes to a `blocked` terminal and KEEPS the worktree for rework.
  *
@@ -282,7 +399,7 @@ export async function integrate(input, deps) {
 export async function confirmMerge(input, deps) {
     const { execGit: git, execGh: gh, resolveRunCwd } = deps;
     const cwd = await resolveRunCwd(input.runId, input.taskId);
-    const branch = branchName(input.taskId, input.title);
+    const branch = branchName(input.taskId, input.title, input.issueRef);
     const ownerRepoResult = resolveOwnerRepo(git, cwd);
     if ('needsHuman' in ownerRepoResult)
         return ownerRepoResult;
@@ -298,7 +415,7 @@ export async function confirmMerge(input, deps) {
     };
     const pr = view();
     if (pr.state === 'MERGED')
-        return { merged: true, prNumber: pr.number, prUrl: pr.url };
+        return { merged: true, prNumber: pr.number, prUrl: pr.url, ...(input.issueRef ? { issueRef: input.issueRef } : {}) };
     if (pr.state !== 'OPEN') {
         return { needsHuman: true, lesson: `PR #${pr.number} is ${pr.state} (not OPEN) and not merged — resolve manually` };
     }
@@ -311,16 +428,33 @@ export async function confirmMerge(input, deps) {
                 `conflicts, or required reviews pending; merge it manually (or fix + re-run) then cleanup`,
         };
     }
+    const expectedHeadSha = input.mergeReadiness?.headSha.trim();
+    if (!expectedHeadSha) {
+        return {
+            needsHuman: true,
+            lesson: `PR #${pr.number} merge requires a fresh merge readiness headSha guard — re-run readiness before approving merge`,
+        };
+    }
     // The integrator opens the PR as a DRAFT (human review at the merge gate); `gh pr merge` refuses a
     // draft, so mark it ready first (the approved merge gate IS that review). Idempotent: a no-op once ready.
     if (pr.isDraft) {
         gh(['pr', 'ready', branch, '--repo', ownerRepo]);
     }
     // Merge (squash) — idempotent: a replay re-views first (step 1) and short-circuits on state MERGED.
-    gh(['pr', 'merge', branch, '--repo', ownerRepo, '--squash', '--delete-branch']);
+    try {
+        gh(['pr', 'merge', branch, '--repo', ownerRepo, '--squash', '--delete-branch', '--match-head-commit', expectedHeadSha]);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            needsHuman: true,
+            lesson: `PR #${pr.number} merge was blocked by the GitHub head guard ` +
+                `(expected ${expectedHeadSha}): ${message || 'merge command failed'}`,
+        };
+    }
     const after = view();
     if (after.state === 'MERGED')
-        return { merged: true, prNumber: after.number, prUrl: after.url };
+        return { merged: true, prNumber: after.number, prUrl: after.url, ...(input.issueRef ? { issueRef: input.issueRef } : {}) };
     return { needsHuman: true, lesson: `PR #${after.number} merge did not take effect (state=${after.state}) — verify manually` };
 }
 /** Default polling bounds — pr-readiness parity (20 polls × 30s), overridable via env so the e2e suite
@@ -329,18 +463,39 @@ function envInt(name, fallback) {
     const n = Number.parseInt(process.env[name] ?? '', 10);
     return Number.isFinite(n) && n > 0 ? n : fallback;
 }
-function defaultCollect(repo, branch, base, execGh) {
+function defaultCollect(repo, branch, base, execGh, issueRef) {
     // pollPr classifies by CI checks + unresolved review THREADS only — it does not read the PR comment
     // feed, so suppress the `api repos/.../{reviews,comments}` calls (`includeComments: false`). Those
     // extra calls are pure overhead here and the review-thread query already carries the actionable
     // feedback the loop acts on.
-    return collectPrReadiness({ repo, headBranch: branch, baseBranch: base, includeReviewThreads: true, includeComments: false }, execGh).then((r) => ({
+    return collectPrReadiness({ repo, headBranch: branch, baseBranch: base, issueRef, includeReviewThreads: true, includeComments: false }, execGh).then((r) => ({
         pr: { number: r.pr.number, headSha: r.pr.headSha },
         checks: { pending: r.checks.pending, fail: r.checks.fail, list: r.checks.list },
         reviewThreads: { items: r.reviewThreads.items },
+        readinessVerdict: r.verdict,
+        nextAction: r.nextAction,
+        evidence: r.evidence,
     }));
 }
 const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+function ciFailuresFrom(readiness) {
+    return readiness.checks.list
+        .filter((c) => readiness.checks.fail.includes(c.name))
+        .map((c) => ({ name: c.name, conclusion: c.result }));
+}
+function readinessRequiresReview(readiness) {
+    return readiness.readinessVerdict === 'needs_human'
+        || readiness.readinessVerdict === 'needs_work'
+        || readiness.nextAction === 'human_decision'
+        || readiness.nextAction === 'reviewer_triage'
+        || readiness.nextAction === 'developer_fix';
+}
+function readinessEvidence(readiness) {
+    return [
+        readiness.readinessVerdict ? `readiness verdict=${readiness.readinessVerdict}` : undefined,
+        readiness.nextAction ? `readiness nextAction=${readiness.nextAction}` : undefined,
+    ].filter((item) => item !== undefined);
+}
 /**
  * pollPr — REAL (live only). Polls `collectPrReadiness` until CI is terminal (no pending checks) or a
  * timeout, then classifies the feedback by TYPE (plan 0018): unresolved review threads → review_changes;
@@ -351,19 +506,20 @@ export async function pollPr(input, deps) {
     const { execGit: git, execGh: gh, resolveRunCwd } = deps;
     const collect = deps.collect ?? defaultCollect;
     const sleep = deps.sleep ?? defaultSleep;
+    const requiredChecks = deps.requiredChecks ?? fetchRequiredCheckNames;
     // Read env at CALL time (not module load) so the e2e harness can shrink the poll budget regardless
     // of import order; prod default stays 20 × 30s.
     const maxPolls = deps.maxPolls ?? envInt('REVO_POLL_PR_MAX_POLLS', 20);
     const intervalMs = deps.pollIntervalMs ?? envInt('REVO_POLL_PR_INTERVAL_MS', 30_000);
     const cwd = await resolveRunCwd(input.runId, input.taskId);
-    const branch = branchName(input.taskId, input.title);
+    const branch = branchName(input.taskId, input.title, input.issueRef);
     const ownerRepoResult = resolveOwnerRepo(git, cwd);
     if ('needsHuman' in ownerRepoResult)
         return ownerRepoResult;
     const { ownerRepo } = ownerRepoResult;
     let readiness;
     for (let i = 0; i < maxPolls; i++) {
-        readiness = await collect(ownerRepo, branch, input.base, gh);
+        readiness = await collect(ownerRepo, branch, input.base, gh, input.issueRef);
         // Terminal once nothing is pending and at least one check has registered (matches pr-readiness).
         if (readiness.checks.pending.length === 0 && readiness.checks.list.length > 0)
             break;
@@ -377,21 +533,74 @@ export async function pollPr(input, deps) {
             lesson: `pollPr timed out after ${maxPolls} polls — CI checks still pending or none registered for ${branch}`,
         };
     }
-    const reviewThreads = readiness.reviewThreads.items.map((t) => ({
+    // `settled` is the CI-terminal readiness (defined past the guard); the review-grace loop may refresh it.
+    let settled = readiness;
+    const initialCiFailures = ciFailuresFrom(settled);
+    // CI green → flip the PR draft→ready so CodeRabbit / human reviewers actually engage. They SKIP
+    // draft PRs, which silently bypassed the entire review loop (the PR was readied only at confirmMerge,
+    // i.e. after the merge gate) — slice 142. Then wait a BOUNDED grace for review threads to surface
+    // before declaring clean, so we don't merge-gate a millisecond before CodeRabbit posts. We never
+    // BLOCK on a review arriving: the human merge gate is the backstop, so an absent / rate-limited
+    // reviewer falls through to it rather than deadlocking the run. CI-red stays draft (don't request
+    // review of broken code) and routes to ci_changes for a fix first.
+    if (initialCiFailures.length === 0) {
+        try {
+            gh(['pr', 'ready', branch, '--repo', ownerRepo]);
+        }
+        catch {
+            // already ready / nothing to ready — idempotent best-effort
+        }
+        const reviewGracePolls = deps.reviewGracePolls ?? envInt('REVO_POLL_PR_REVIEW_GRACE_POLLS', 4);
+        for (let i = 0; i < reviewGracePolls && settled.reviewThreads.items.length === 0; i++) {
+            await sleep(intervalMs);
+            settled = await collect(ownerRepo, branch, input.base, gh, input.issueRef);
+        }
+    }
+    if (settled.checks.pending.length > 0 || settled.checks.list.length === 0) {
+        const detail = settled.checks.pending.length > 0
+            ? `pending checks: ${settled.checks.pending.join(', ')}`
+            : 'no checks registered';
+        const evidence = settled.evidence.length > 0 ? ` Evidence: ${settled.evidence.join(' | ')}` : '';
+        return {
+            needsHuman: true,
+            lesson: `pollPr found unsettled readiness after readying ${branch} - ${detail}.${evidence}`,
+        };
+    }
+    const reviewThreads = settled.reviewThreads.items.map((t) => ({
         threadId: t.id,
         path: t.path,
         line: t.line,
         author: t.author,
         body: t.body,
     }));
-    const ciFailures = readiness.checks.list
-        .filter((c) => readiness.checks.fail.includes(c.name))
-        .map((c) => ({ name: c.name, conclusion: c.result }));
-    // Decision order (plan 0018): review threads first, then CI, else clean.
-    const verdict = reviewThreads.length > 0 ? 'review_changes' : ciFailures.length > 0 ? 'ci_changes' : 'clean';
+    const ciFailures = ciFailuresFrom(settled);
+    // Only REQUIRED-check failures drive the `ci_changes` verdict (PR #135 fix): on this repo only
+    // "Verify"/"E2E"/"Required checks" gate the merge — Sonar/CodeRabbit are advisory, and a failing
+    // advisory check used to wrongly trigger a pointless ciRework loop. `gh pr view` does not carry
+    // isRequired, so we ask GitHub directly. ciFailures keeps the FULL failing list for downstream
+    // context; the verdict keys off the required-only subset.
+    // FAIL-SAFE: if the required set can't be determined (gh error or empty), fall back to counting
+    // ALL failures (current behavior) — never silently treat an unknown required-set as clean.
+    let ciVerdictFailures = ciFailures;
+    if (ciFailures.length > 0 && settled.pr.number !== null) {
+        try {
+            const required = requiredChecks(ownerRepo, settled.pr.number, gh);
+            if (required.size > 0)
+                ciVerdictFailures = ciFailures.filter((f) => required.has(f.name));
+        }
+        catch {
+            // gh failed → keep the full failing list (fail-safe: unknown required-set ≠ clean).
+        }
+    }
+    // Decision order (plan 0018): review threads first, then CI (required-only), else clean.
+    const verdict = reviewThreads.length > 0 || readinessRequiresReview(settled)
+        ? 'review_changes'
+        : ciVerdictFailures.length > 0 ? 'ci_changes' : 'clean';
     return {
-        prNumber: readiness.pr.number ?? null,
-        headSha: readiness.pr.headSha,
+        prNumber: settled.pr.number ?? null,
+        headSha: settled.pr.headSha,
+        evidence: [...settled.evidence, ...readinessEvidence(settled), `PR headSha=${settled.pr.headSha}`, `pollPr verdict=${verdict}`],
+        ...(input.issueRef ? { issueRef: input.issueRef } : {}),
         verdict,
         ciFailures,
         reviewThreads,
@@ -507,6 +716,10 @@ let IntegratorService = class IntegratorService {
     runPreflight = (taskId, base) => {
         return preflightLive(taskId, base, this.deps);
     };
+    /** Capture a change-producing developer step as a git head artifact before reviewer/integrator handoff. */
+    runCaptureProducedChange = (input) => {
+        return captureProducedChange(input, this.deps);
+    };
     /**
      * Real pollPr — live path. Same fail-loud pinned-gh handling as runIntegrate (the review/CI poll reads
      * the PR via the pinned account, never the ambient one). Blocks if the pinned identity is unresolved.
@@ -521,7 +734,7 @@ let IntegratorService = class IntegratorService {
     };
     /** Stub pollPr — script path; zero external effects (reports a clean PR so the loop converges to merge). */
     runPollStub = (_input) => {
-        return { prNumber: null, headSha: 'stub', verdict: 'clean', ciFailures: [], reviewThreads: [] };
+        return { prNumber: null, headSha: 'stub', evidence: ['stub pollPr readiness: clean'], verdict: 'clean', ciFailures: [], reviewThreads: [] };
     };
     /**
      * Real respondThreads — live path. Same fail-loud pinned-gh handling: refuse the ambient account.