@revisium/orchestrator 0.1.0-alpha.9 → 0.2.0-alpha.0

package/dist/runners/integrator.js

@@ -10,35 +10,35 @@ var __metadata = (this && this.__metadata) || function (k, v) {
 var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
-/**
- * integrator.ts — deterministic, replay-safe code integrator.
- *
- * DBOS-SEALED: zero @dbos-inc imports. Registration happens in PipelineService ctor.
- *
- * 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.
- *   - IntegratorService          — @Injectable wrapper with bound arrow properties.
- *
- * The pure primitives (resolveExecutable, branchName, parseOwnerRepo) and shared types live in
- * sibling modules (integrator-git / -branch-naming / -remote / -types) and are re-exported here so
- * the public import path ('./integrator.js') is unchanged.
- */
 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';
 import { branchName } from './integrator-branch-naming.js';
-// Public-API re-exports — the implementations now live in focused sibling modules, but callers
-// (worktree.service, git-worktree-manager, the test kit) keep importing from './integrator.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 +49,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 +65,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,13 +79,11 @@ function findOrCreatePr(ownerRepo, branch, base, title, execGh) {
         '--head',
         branch,
         '--title',
-        title,
+        issueBoundTitle(title, issueRef, ownerRepo),
         '--body',
         '',
     ]);
-    // gh pr create prints the PR url on stdout
     const createdUrl = createOut.trim();
-    // Fetch back number from the URL
     const viewRaw = execGh([
         'pr',
         'view',
@@ -105,8 +98,6 @@ function findOrCreatePr(ownerRepo, branch, base, title, execGh) {
         viewData = JSON.parse(viewRaw);
     }
     catch {
-        // gh pr view returned non-JSON after create — cannot determine real PR url/number.
-        // A live integrator must NEVER emit a stub:// url; surface as needsHuman for human review.
         return {
             needsHuman: true,
             lesson: `gh pr view returned non-JSON after create (url=${createdUrl || 'empty'}); ` +
@@ -115,23 +106,21 @@ function findOrCreatePr(ownerRepo, branch, base, title, execGh) {
     }
     return { prUrl: viewData.url, prNumber: viewData.number };
 }
-// ─── Preflight (B5+B7) ────────────────────────────────────────────────────────
-/**
- * preflightLive — clean check + base freshness, 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
- *
- * Returns { ok: true } when the repo is clean and based on fresh origin/<base>.
- * Returns IntegratorBlocked on ANY failure — no throw, so DBOS does NOT retry.
- */
+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');
+}
 export async function preflightLive(taskId, base, deps) {
     const { execGit, resolveTaskCwd } = deps;
     const cwd = await resolveTaskCwd(taskId);
-    // 1. Fetch (only mutation; idempotent; ignore errors — fetch failure handled as mismatch)
     try {
         execGit(['fetch', 'origin', base], cwd);
     }
@@ -141,7 +130,6 @@ export async function preflightLive(taskId, base, deps) {
             lesson: `live preflight: git fetch origin ${base} failed — base branch may not exist on remote: ${String(err)}`,
         };
     }
-    // 2. Clean check
     const porcelain = execGit(['status', '--porcelain'], cwd).trim();
     if (porcelain !== '') {
         const lineCount = porcelain.split('\n').length;
@@ -150,9 +138,6 @@ 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
     let headBranch;
     let headSha;
     let originSha;
@@ -164,150 +149,176 @@ 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) {
-        // The clean base branch isn't at origin/<base>. SELF-HEAL instead of dead-ending: a sibling run
-        // merging advances origin/<base>, and the old hard block forced a manual `git pull` + re-run for
-        // every other in-flight run (slice 142 / dogfood). The tree is already clean (step 2), so if the
-        // base is simply BEHIND (HEAD is an ancestor of origin/<base>) we fast-forward it — exactly what
-        // `git pull --ff-only` does, and harmless for worktree-isolated runs (they re-cut from origin anyway).
-        // Only a genuinely DIVERGED base (local commits absent from the remote) still blocks for a human.
         let behind = false;
         try {
             execGit(['merge-base', '--is-ancestor', 'HEAD', `origin/${base}`], cwd);
             behind = true;
         }
         catch {
-            behind = false; // not an ancestor → diverged (or unrelated)
+            behind = false;
         }
         if (!behind) {
             return {
                 needsHuman: true,
-                lesson: `target repo base branch ${base} has DIVERGED from origin/${base} ` +
+                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`,
             };
         }
-        try {
-            execGit(['merge', '--ff-only', `origin/${base}`], cwd); // clean + ancestor → cannot conflict
-        }
-        catch (err) {
-            return {
-                needsHuman: true,
-                lesson: `live preflight: fast-forward of ${base} to origin/${base} failed — ${String(err)}; pull ${base} manually and retry --live`,
-            };
-        }
-    }
-    if (headBranch !== base) {
-        try {
-            execGit(['merge-base', '--is-ancestor', `origin/${base}`, 'HEAD'], cwd);
-        }
-        catch {
-            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`,
-            };
-        }
     }
     return { ok: true };
 }
-// ─── STUB integrator (script only) ───────────────────────────────────────────
-/**
- * stubIntegrate — PURE, zero side effects; returns a placeholder result.
- * Used by `script` mode (default + --stub). Makes NO execGit/execGh calls.
- */
 export function stubIntegrate(input) {
     return {
         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 } : {}),
     };
 }
-// ─── REAL integrator (live only) ─────────────────────────────────────────────
-/**
- * integrate — REAL integrator (live only).
- * Replay-safe: branch create-if-absent (no clobber); commit only if staged diff;
- * push + find-or-create PR even if commit already happened (ahead guard).
- */
+function stagedDiffPresent(git, cwd) {
+    try {
+        git(['diff', '--cached', '--quiet'], cwd);
+        return false;
+    }
+    catch {
+        return true;
+    }
+}
 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);
-    // 1. Derive owner/repo
+    const branch = branchName(input.taskId, input.title, input.issueRef);
     const ownerRepoResult = resolveOwnerRepo(git, cwd);
     if ('needsHuman' in ownerRepoResult)
         return ownerRepoResult;
     const { ownerRepo } = ownerRepoResult;
-    // 2. Fetch base
     git(['fetch', 'origin', input.base], cwd);
-    // 3. Branch create-if-absent; never clobber a prior commit
     if (branchExists(git, cwd, branch)) {
         git(['switch', branch], cwd);
     }
     else {
         git(['switch', '-c', branch, `origin/${input.base}`], cwd);
     }
-    // 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) {
-        // Commit — NO Co-Authored-By, NO summary footer (MEMORY)
-        const commitMsg = `feat: ${input.title}`;
+    if (stagedDiffPresent(git, cwd)) {
+        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,
-            };
+            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 {
+            }
+            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
- * success terminal (so the worktree, released on `succeeded`, is cleaned only once the branch is in the
- * 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.
- *  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.
- *
- * Merge method is `--squash` by default; node-level parameterization (method/policy) is a deferred
- * follow-up (run-time node params).
- */
 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;
@@ -323,12 +334,10 @@ 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` };
     }
-    // Only auto-merge a CLEAN PR (CI green, no conflicts). Other states (BLOCKED/DIRTY/UNSTABLE/BEHIND…)
-    // require a human — block and keep the worktree for rework.
     if (pr.mergeStateStatus !== 'CLEAN') {
         return {
             needsHuman: true,
@@ -336,60 +345,80 @@ export async function confirmMerge(input, deps) {
                 `conflicts, or required reviews pending; merge it manually (or fix + re-run) then cleanup`,
         };
     }
-    // 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.
+    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`,
+        };
+    }
     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
- *  doesn't real-sleep; also injectable (deps.maxPolls/pollIntervalMs) so unit tests run instantly. */
 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) {
-    // 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) => ({
+function defaultCollect(repo, branch, base, execGh, issueRef) {
+    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));
-/**
- * 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;
- * else failing checks → ci_changes; else clean. A timeout with checks still pending → block (human).
- * Replay-safe at the DBOS-step boundary (memoized result), idempotent (read-only gh).
- */
+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.nextAction === 'human_decision'
+        || readiness.nextAction === 'reviewer_triage'
+        || (readiness.nextAction === 'developer_fix' && readiness.checks.fail.length === 0);
+}
+function readinessEvidence(readiness) {
+    return [
+        readiness.readinessVerdict ? `readiness verdict=${readiness.readinessVerdict}` : undefined,
+        readiness.nextAction ? `readiness nextAction=${readiness.nextAction}` : undefined,
+    ].filter((item) => item !== undefined);
+}
 export async function pollPr(input, deps) {
     const { execGit: git, execGh: gh, resolveRunCwd } = deps;
     const collect = deps.collect ?? defaultCollect;
     const sleep = deps.sleep ?? defaultSleep;
-    // 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 requiredChecks = deps.requiredChecks ?? fetchRequiredCheckNames;
     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);
-        // Terminal once nothing is pending and at least one check has registered (matches pr-readiness).
+        readiness = await collect(ownerRepo, branch, input.base, gh, input.issueRef);
         if (readiness.checks.pending.length === 0 && readiness.checks.list.length > 0)
             break;
         readiness = undefined;
@@ -402,32 +431,30 @@ export async function pollPr(input, deps) {
             lesson: `pollPr timed out after ${maxPolls} polls — CI checks still pending or none registered for ${branch}`,
         };
     }
-    // `settled` is the CI-terminal readiness (defined past the guard); the review-grace loop may refresh it.
     let settled = readiness;
-    // CI failures come from the CI-terminal snapshot (terminal → won't change under us).
-    const ciFailures = settled.checks.list
-        .filter((c) => settled.checks.fail.includes(c.name))
-        .map((c) => ({ name: c.name, conclusion: c.result }));
-    // 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 (ciFailures.length === 0) {
+    const initialCiFailures = ciFailuresFrom(settled);
+    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);
+            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,
@@ -435,19 +462,31 @@ export async function pollPr(input, deps) {
         author: t.author,
         body: t.body,
     }));
-    // 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);
+    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 {
+        }
+    }
+    const verdict = reviewThreads.length > 0 || readinessRequiresReview(settled)
+        ? 'review_changes'
+        : ciVerdictFailures.length > 0 ? 'ci_changes' : 'clean';
     return {
         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,
     };
 }
 const TRIAGE_DECISIONS = new Set(['fix', 'wontfix', 'question']);
-/** Coerce the analyst's (LLM-produced, untrusted-shape) triage output to a Triage, dropping malformed
- *  items so respondThreads never throws on a null/garbled entry (CodeRabbit). */
 export function asTriage(value) {
     if (value === null || typeof value !== 'object')
         return { items: [] };
@@ -460,20 +499,13 @@ export function asTriage(value) {
         : [];
     return { items };
 }
-/**
- * respondThreads — REAL (live only). For each triaged thread we acted on (decision fix OR wontfix —
- * plan 0018 decision #2), reply in the thread then resolve it, via the gh-pinned GraphQL API
- * (`addPullRequestReviewThreadReply` then `resolveReviewThread`). Question items are skipped (they go to
- * the question gate, not auto-resolved). Idempotent: resolving an already-resolved thread is a no-op for
- * the loop (a reopened/new comment is caught by the next pollPr).
- */
 export async function respondThreads(triage, deps) {
     const { execGh: gh } = deps;
     let replied = 0;
     let resolved = 0;
     for (const item of triage.items) {
         if (item.decision !== 'fix' && item.decision !== 'wontfix')
-            continue; // skip questions
+            continue;
         const body = item.replyText ?? (item.decision === 'wontfix' ? 'Acknowledged; not changing.' : 'Addressed.');
         gh([
             'api', 'graphql',
@@ -491,37 +523,20 @@ export async function respondThreads(triage, deps) {
     }
     return { replied, resolved };
 }
-// ─── IntegratorService ─────────────────────────────────────────────────────────
-/** Default execGit implementation wrapping execFileSync with a resolved absolute path. */
 function defaultExecGit(args, cwd) {
     return execFileSync(gitAbsPath(), args, { encoding: 'utf8', cwd, timeout: 60_000 });
 }
-/**
- * IntegratorService — @Injectable wrapper over integrate / stubIntegrate / preflightLive.
- * Exposes bound arrow properties so they survive being passed to registerStep unbound.
- * DBOS-SEALED: zero @dbos-inc imports; PipelineService registers these as steps.
- */
 let IntegratorService = class IntegratorService {
     runService;
     deps;
     constructor(runService) {
         this.runService = runService;
-        // execGh is resolved per-run inside runIntegrate (fail-loud on an unresolved pinned identity),
-        // so it is NOT built here — only the git + cwd deps are stable at construction.
         this.deps = {
             execGit: defaultExecGit,
             resolveTaskCwd: this.runService.makeResolveTaskCwd(),
             resolveRunCwd: this.runService.makeResolveRunCwd(),
         };
     }
-    /**
-     * Real integrator — live path. Arrow property: safe to pass unbound to registerStep.
-     *
-     * 0008 #1 (fail-loud, 2026-06-12 dogfood): resolve the PINNED gh identity first. If its token
-     * cannot be resolved we REFUSE to fall back to the ambient gh account (which would open the PR
-     * as the wrong user) and block as needsHuman instead. Only on success do we run the integrator
-     * with the pinned execGh.
-     */
     runIntegrate = (input) => {
         const pinned = resolvePinnedGh();
         if ('needsHuman' in pinned) {
@@ -531,14 +546,9 @@ let IntegratorService = class IntegratorService {
         console.log(`[integrator] gh pinned to account '${resolveGhAccount()}' (GH_TOKEN, not ambient)`);
         return integrate(input, { ...this.deps, execGh: pinned.execGh });
     };
-    /** Stub integrator — script path; zero external effects. */
     runStub = (input) => {
         return stubIntegrate(input);
     };
-    /**
-     * Real confirm-merge — live path. Same fail-loud pinned-gh handling as runIntegrate: refuse the
-     * ambient account, block if the pinned identity cannot be resolved.
-     */
     runConfirmMerge = (input) => {
         const pinned = resolvePinnedGh();
         if ('needsHuman' in pinned) {
@@ -547,18 +557,15 @@ let IntegratorService = class IntegratorService {
         }
         return confirmMerge(input, { ...this.deps, execGh: pinned.execGh });
     };
-    /** Stub confirm-merge — script path; zero external effects (treats the stub PR as merged). */
     runConfirmStub = (input) => {
         return { merged: true, prNumber: 0, prUrl: `stub://pr/${input.taskId}/merged` };
     };
-    /** Live preflight — clean check + base invariant. Arrow property for safe unbound registration. */
     runPreflight = (taskId, base) => {
         return preflightLive(taskId, base, 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.
-     */
+    runCaptureProducedChange = (input) => {
+        return captureProducedChange(input, this.deps);
+    };
     runPollPr = (input) => {
         const pinned = resolvePinnedGh();
         if ('needsHuman' in pinned) {
@@ -567,14 +574,9 @@ let IntegratorService = class IntegratorService {
         }
         return pollPr(input, { ...this.deps, execGh: pinned.execGh });
     };
-    /** 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.
-     * The consumed `triage` rides in IntegratorInput.triage (hydrated by the adapter from run_outputs).
-     */
     runRespondThreads = (input) => {
         const pinned = resolvePinnedGh();
         if ('needsHuman' in pinned) {
@@ -583,7 +585,6 @@ let IntegratorService = class IntegratorService {
         }
         return respondThreads(asTriage(input.triage), { execGh: pinned.execGh });
     };
-    /** Stub respondThreads — script path; zero external effects (no threads to reply/resolve). */
     runRespondStub = (_input) => {
         return { replied: 0, resolved: 0 };
     };