@revisium/orchestrator 0.2.0-alpha.2 → 0.2.0-alpha.4

package/dist/runners/integrator.js

@@ -12,9 +12,9 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 };
 import { Inject, Injectable } from '@nestjs/common';
 import { execFileSync } from 'node:child_process';
-import { collectPrReadiness, fetchRequiredCheckNames, } from '../poller/pr-readiness-core.js';
+import { collectPrReadiness, fetchRequiredCheckNames, GITHUB_CHECK_ROLLUP_UNAVAILABLE, } from '../poller/pr-readiness-core.js';
 import { RunService } from '../revisium/run.service.js';
-import { issueRefTag } from '../run/issue-ref.js';
+import { hasClosingIssueReference, hasIssueRefToken, issueBodyWithClosingReference, 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';
@@ -22,14 +22,28 @@ import { branchName } from './integrator-branch-naming.js';
 export { resolveExecutable } from './integrator-git.js';
 export { branchName };
 export { parseOwnerRepo } from './integrator-remote.js';
-function issueBoundTitle(title, issueRef, ownerRepo) {
+function issueBoundTitle(title, issueRef, ownerRepo, issueAction = issueRef ? 'close' : 'none') {
+    if (!issueRef || issueAction === 'none')
+        return title;
+    if (hasIssueRefToken(title, issueRef, ownerRepo))
+        return title;
     const tag = issueRefTag(issueRef, ownerRepo);
     return tag ? `${tag} ${title}` : title;
 }
-function commitMessage(title, issueRef, ownerRepo) {
+function commitMessage(title, issueRef, ownerRepo, issueAction = issueRef ? 'close' : 'none') {
+    if (!issueRef || issueAction === 'none')
+        return `feat: ${title}`;
     const tag = issueRefTag(issueRef, ownerRepo);
     return tag ? `feat: ${tag} ${title}` : `feat: ${title}`;
 }
+function prBody(body, issueRef, ownerRepo, issueAction) {
+    if (issueAction !== 'close')
+        return body ?? '';
+    return issueBodyWithClosingReference(body, issueRef, ownerRepo);
+}
+function resolvedIssueAction(issueRef, issueAction) {
+    return issueAction ?? (issueRef ? 'close' : undefined);
+}
 function parsePrList(raw) {
     try {
         return JSON.parse(raw);
@@ -38,6 +52,22 @@ function parsePrList(raw) {
         throw new Error(`gh pr list returned non-JSON: ${raw.slice(0, 200)}`);
     }
 }
+function prAuthorLogin(author) {
+    if (typeof author === 'string' && author.trim().length > 0)
+        return author.trim();
+    if (author && typeof author === 'object' && typeof author.login === 'string' && author.login.trim().length > 0) {
+        return author.login.trim();
+    }
+    return undefined;
+}
+function asRecord(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    return value;
+}
+function nonBlank(value) {
+    return typeof value === 'string' && value.trim().length > 0 ? value.trim() : undefined;
+}
 function matchingOpenPr(ownerRepo, branch, base, execGh, jsonFields) {
     const raw = execGh([
         'pr',
@@ -56,7 +86,14 @@ function matchingOpenPr(ownerRepo, branch, base, execGh, jsonFields) {
         const pr = matching[0];
         if (!pr)
             throw new Error('unexpected empty match');
-        return { prUrl: pr.url, prNumber: pr.number, ...(pr.headRefOid ? { headSha: pr.headRefOid } : {}) };
+        return {
+            prUrl: pr.url,
+            prNumber: pr.number,
+            ...(pr.headRefOid ? { headSha: pr.headRefOid } : {}),
+            ...(pr.title !== undefined ? { title: pr.title } : {}),
+            ...(pr.body !== undefined ? { body: pr.body } : {}),
+            ...(prAuthorLogin(pr.author) ? { author: prAuthorLogin(pr.author) } : {}),
+        };
     }
     if (matching.length > 1) {
         const candidates = matching.map((p) => `#${p.number}`).join(', ');
@@ -67,7 +104,9 @@ function matchingOpenPr(ownerRepo, branch, base, execGh, jsonFields) {
     }
     return null;
 }
-function createPr(ownerRepo, branch, base, title, issueRef, execGh) {
+function createPr(ownerRepo, branch, base, title, issueRef, issueAction, execGh) {
+    const resolvedTitle = issueBoundTitle(title, issueRef, ownerRepo, issueAction);
+    const resolvedBody = prBody(undefined, issueRef, ownerRepo, issueAction);
     const createOut = execGh([
         'pr',
         'create',
@@ -79,9 +118,9 @@ function createPr(ownerRepo, branch, base, title, issueRef, execGh) {
         '--head',
         branch,
         '--title',
-        issueBoundTitle(title, issueRef, ownerRepo),
+        resolvedTitle,
         '--body',
-        '',
+        resolvedBody,
     ]);
     const createdUrl = createOut.trim();
     const viewRaw = execGh([
@@ -104,19 +143,66 @@ function createPr(ownerRepo, branch, base, title, issueRef, execGh) {
                 'check if the PR was created and update the run manually',
         };
     }
-    return { prUrl: viewData.url, prNumber: viewData.number };
+    return { prUrl: viewData.url, prNumber: viewData.number, title: resolvedTitle, body: resolvedBody };
 }
-function findOrCreatePr(ownerRepo, branch, base, title, issueRef, execGh) {
-    const existing = matchingOpenPr(ownerRepo, branch, base, execGh, 'number,url,baseRefName');
+function repairPr(ownerRepo, prNumber, issueRef, issueAction, title, body, desiredTitle, desiredBody, execGh) {
+    if (!issueRef && issueAction !== 'close')
+        return;
+    const args = ['pr', 'edit', String(prNumber), '--repo', ownerRepo];
+    if ((title ?? '') !== desiredTitle)
+        args.push('--title', desiredTitle);
+    if ((body ?? '') !== desiredBody)
+        args.push('--body', desiredBody);
+    if (args.length > 5)
+        execGh(args);
+}
+function findOrCreatePr(ownerRepo, branch, base, title, issueRef, issueAction, execGh) {
+    const existing = matchingOpenPr(ownerRepo, branch, base, execGh, 'number,url,baseRefName,title,body');
     if (existing && !('needsHuman' in existing)) {
+        repairPr(ownerRepo, existing.prNumber, issueRef, issueAction, existing.title, existing.body, issueBoundTitle(existing.title || title, issueRef, ownerRepo, issueAction), prBody(existing.body, issueRef, ownerRepo, issueAction), execGh);
         return { prUrl: existing.prUrl, prNumber: existing.prNumber };
     }
     if (existing)
         return existing;
-    return createPr(ownerRepo, branch, base, title, issueRef, execGh);
+    return createPr(ownerRepo, branch, base, title, issueRef, issueAction, execGh);
 }
 function findExistingPrWithHead(ownerRepo, branch, base, execGh) {
-    return matchingOpenPr(ownerRepo, branch, base, execGh, 'number,url,baseRefName,headRefOid');
+    return matchingOpenPr(ownerRepo, branch, base, execGh, 'number,url,baseRefName,headRefOid,title,body,author');
+}
+function foreignPrProvenance(author) {
+    const integratorAccount = resolveGhAccount();
+    if (!author || author.toLowerCase() === integratorAccount.toLowerCase())
+        return {};
+    return { foreignPr: true, prAuthor: author, integratorAccount };
+}
+function repairProducedChangePr(context, existing, provenance) {
+    if (provenance.foreignPr)
+        return;
+    repairPr(context.ownerRepo, existing.prNumber, context.issueRef, context.issueAction, existing.title, existing.body, issueBoundTitle(existing.title || context.title, context.issueRef, context.ownerRepo, context.issueAction), prBody(existing.body, context.issueRef, context.ownerRepo, context.issueAction), context.execGh);
+}
+function existingProducedChangeOutput(context, existing, provenance, status) {
+    return {
+        prUrl: existing.prUrl,
+        branch: context.branch,
+        prNumber: existing.prNumber,
+        ...(context.issueRef ? { issueRef: context.issueRef } : {}),
+        headSha: context.change.headSha,
+        status,
+        ...(status === 'noop' ? { message: 'nothing to integrate — produced head already pushed and equals PR head' } : {}),
+        ...provenance,
+    };
+}
+function reuseExistingProducedChangePr(context, existing) {
+    if (existing.headSha !== context.change.headSha)
+        return null;
+    const provenance = foreignPrProvenance(existing.author);
+    repairProducedChangePr(context, existing, provenance);
+    return existingProducedChangeOutput(context, existing, provenance, 'noop');
+}
+function updateExistingProducedChangePr(context, existing) {
+    const provenance = foreignPrProvenance(existing.author);
+    repairProducedChangePr(context, existing, provenance);
+    return existingProducedChangeOutput(context, existing, provenance, 'pushed');
 }
 export async function preflightLive(taskId, base, deps) {
     const { execGit, resolveTaskCwd } = deps;
@@ -186,6 +272,7 @@ export async function captureProducedChange(input, deps) {
     const branch = branchName(input.taskId, input.title, input.issueRef);
     const ownerRepoResult = resolveOwnerRepo(git, cwd);
     const ownerRepo = 'needsHuman' in ownerRepoResult ? undefined : ownerRepoResult.ownerRepo;
+    const issueAction = resolvedIssueAction(input.issueRef, input.issueAction);
     if (branchExists(git, cwd, branch)) {
         git(['switch', branch], cwd);
     }
@@ -194,13 +281,14 @@ export async function captureProducedChange(input, deps) {
     }
     git(['add', '-A'], cwd);
     if (stagedDiffPresent(git, cwd)) {
-        git(['commit', '-m', commitMessage(input.title, input.issueRef, ownerRepo)], cwd);
+        git(['commit', '-m', commitMessage(input.title, input.issueRef, ownerRepo, issueAction)], cwd);
     }
     const headSha = git(['rev-parse', 'HEAD'], cwd).trim();
     return {
         branch,
         headSha,
         ...(input.issueRef ? { issueRef: input.issueRef } : {}),
+        ...(issueAction ? { issueAction } : {}),
         worktreePath: cwd,
         ...(input.artifactRef ? { artifactRef: input.artifactRef } : {}),
     };
@@ -224,6 +312,7 @@ export async function integrate(input, deps) {
     if ('needsHuman' in ownerRepoResult)
         return ownerRepoResult;
     const { ownerRepo } = ownerRepoResult;
+    const issueAction = resolvedIssueAction(input.issueRef, input.issueAction);
     git(['fetch', 'origin', input.base], cwd);
     if (branchExists(git, cwd, branch)) {
         git(['switch', branch], cwd);
@@ -233,7 +322,7 @@ export async function integrate(input, deps) {
     }
     git(['add', '-A'], cwd);
     if (stagedDiffPresent(git, cwd)) {
-        const commitMsg = commitMessage(input.title, input.issueRef, ownerRepo);
+        const commitMsg = commitMessage(input.title, input.issueRef, ownerRepo, issueAction);
         git(['commit', '-m', commitMsg], cwd);
     }
     else {
@@ -256,7 +345,7 @@ export async function integrate(input, deps) {
         }
     }
     git(['push', '-u', 'origin', branch], cwd);
-    const prResult = findOrCreatePr(ownerRepo, branch, input.base, input.title, input.issueRef, gh);
+    const prResult = findOrCreatePr(ownerRepo, branch, input.base, input.title, input.issueRef, issueAction, gh);
     if ('needsHuman' in prResult)
         return prResult;
     return { prUrl: prResult.prUrl, branch, prNumber: prResult.prNumber, ...(input.issueRef ? { issueRef: input.issueRef } : {}) };
@@ -266,6 +355,7 @@ async function integrateProducedChange(input, deps, change) {
     const cwd = change.worktreePath ?? await deps.resolveRunCwd(input.runId, input.taskId);
     const branch = change.branch;
     const issueRef = change.issueRef ?? input.issueRef;
+    const issueAction = resolvedIssueAction(issueRef, change.issueAction ?? input.issueAction);
     const ownerRepoResult = resolveOwnerRepo(git, cwd);
     if ('needsHuman' in ownerRepoResult)
         return ownerRepoResult;
@@ -274,16 +364,11 @@ async function integrateProducedChange(input, deps, change) {
     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',
-        };
+    const prContext = { ownerRepo, branch, title: input.title, issueRef, issueAction, change, execGh: gh };
+    if (existing) {
+        const reused = reuseExistingProducedChangePr(prContext, existing);
+        if (reused)
+            return reused;
     }
     if (!existing && countAhead(git, cwd, change.headSha, input.base) === 0) {
         return {
@@ -294,16 +379,9 @@ async function integrateProducedChange(input, deps, change) {
     }
     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',
-        };
+        return updateExistingProducedChangePr(prContext, existing);
     }
-    const created = createPr(ownerRepo, branch, input.base, input.title, issueRef, gh);
+    const created = createPr(ownerRepo, branch, input.base, input.title, issueRef, issueAction, gh);
     if ('needsHuman' in created)
         return created;
     return {
@@ -315,6 +393,13 @@ async function integrateProducedChange(input, deps, change) {
         status: 'pushed',
     };
 }
+function mergeabilityForConfirmMerge(pr, overrideAccepted) {
+    if (!overrideAccepted) {
+        return pr.mergeStateStatus === 'CLEAN' ? 'clean' : 'blocked';
+    }
+    const mergeable = pr.mergeable ?? (pr.mergeStateStatus === 'CLEAN' ? 'MERGEABLE' : undefined);
+    return mergeSignal(pr.mergeStateStatus, mergeable);
+}
 export async function confirmMerge(input, deps) {
     const { execGit: git, execGh: gh, resolveRunCwd } = deps;
     const cwd = await resolveRunCwd(input.runId, input.taskId);
@@ -323,8 +408,9 @@ export async function confirmMerge(input, deps) {
     if ('needsHuman' in ownerRepoResult)
         return ownerRepoResult;
     const { ownerRepo } = ownerRepoResult;
+    const issueAction = resolvedIssueAction(input.issueRef, input.issueAction);
     const view = () => {
-        const raw = gh(['pr', 'view', branch, '--repo', ownerRepo, '--json', 'number,url,state,isDraft,mergeStateStatus']);
+        const raw = gh(['pr', 'view', branch, '--repo', ownerRepo, '--json', 'number,url,state,isDraft,mergeStateStatus,mergeable,closingIssuesReferences']);
         try {
             return JSON.parse(raw);
         }
@@ -338,7 +424,9 @@ export async function confirmMerge(input, deps) {
     if (pr.state !== 'OPEN') {
         return { needsHuman: true, lesson: `PR #${pr.number} is ${pr.state} (not OPEN) and not merged — resolve manually` };
     }
-    if (pr.mergeStateStatus !== 'CLEAN') {
+    const overrideAccepted = input.mergeReadiness?.override?.accepted === true;
+    const mergeability = mergeabilityForConfirmMerge(pr, overrideAccepted);
+    if (mergeability !== 'clean') {
         return {
             needsHuman: true,
             lesson: `PR #${pr.number} is not auto-mergeable (mergeStateStatus=${pr.mergeStateStatus}) — CI not green, ` +
@@ -352,6 +440,12 @@ export async function confirmMerge(input, deps) {
             lesson: `PR #${pr.number} merge requires a fresh merge readiness headSha guard — re-run readiness before approving merge`,
         };
     }
+    if (issueAction === 'close' && input.issueRef && !hasClosingIssueReference(pr.closingIssuesReferences, input.issueRef)) {
+        return {
+            needsHuman: true,
+            lesson: `PR #${pr.number} is expected to close ${issueRefTag(input.issueRef, ownerRepo)} but GitHub closingIssuesReferences does not include it`,
+        };
+    }
     if (pr.isDraft) {
         gh(['pr', 'ready', branch, '--repo', ownerRepo]);
     }
@@ -375,14 +469,22 @@ 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, issueRef) {
-    return collectPrReadiness({ repo, headBranch: branch, baseBranch: base, issueRef, includeReviewThreads: true, includeComments: false }, execGh).then((r) => ({
+function defaultCollect(repo, branch, base, execGh, issueRef, issueAction) {
+    return collectPrReadiness({ repo, headBranch: branch, baseBranch: base, issueRef, issueAction, 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 },
+        reviewThreads: {
+            items: r.reviewThreads.items,
+            unresolvedCount: r.reviewThreads.unresolvedCount,
+            ...(r.reviewThreads.truncated ? { truncated: true } : {}),
+        },
         readinessVerdict: r.verdict,
         nextAction: r.nextAction,
         evidence: r.evidence,
+        mergeStateStatus: r.pr.mergeState,
+        mergeable: r.ciSummary.mergeable,
+        draft: r.pr.draft,
+        feedback: r.feedback,
     }));
 }
 const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
@@ -428,8 +530,364 @@ function unsettledReadinessFeedback(input, readiness, reason) {
         verdict: 'recheck',
         ciFailures: ciFailuresFrom(readiness),
         reviewThreads,
+        ...(readiness.mergeStateStatus !== undefined ? { mergeStateStatus: readiness.mergeStateStatus } : {}),
+        ...(readiness.mergeable !== undefined ? { mergeable: readiness.mergeable } : {}),
+    };
+}
+// UNSTABLE/HAS_HOOKS: GitHub marks a PR mergeable even when non-required checks are unsettled.
+// Required-check gating is handled upstream; this quirk is intentional for advisory-only scenarios.
+export function mergeSignal(mergeStateStatus, mergeable) {
+    const ms = (mergeStateStatus ?? '').toUpperCase();
+    const mg = (mergeable ?? '').toUpperCase();
+    if (mg === 'CONFLICTING' || ms === 'DIRTY' || ms === 'BLOCKED' || ms === 'BEHIND')
+        return 'blocked';
+    if (mg === 'MERGEABLE' && (ms === 'CLEAN' || ms === 'UNSTABLE' || ms === 'HAS_HOOKS'))
+        return 'clean';
+    return 'unknown';
+}
+function mergeOverrideGate(input) {
+    const resolution = asRecord(input.gateResolution);
+    const audit = asRecord(resolution?.['mergeOverrideAudit']);
+    const note = nonBlank(resolution?.['note']);
+    if (!resolution || !note || !audit) {
+        return {
+            needsHuman: true,
+            lesson: 'override_merge requires a non-empty note and mergeOverrideAudit from the merge gate',
+        };
+    }
+    const actor = nonBlank(audit.actor) ?? nonBlank(resolution['resolvedBy']) ?? 'operator';
+    const trustedHeadSha = nonBlank(resolution['trustedGateHeadSha']);
+    return {
+        note,
+        audit,
+        actor,
+        ...(trustedHeadSha ? { trustedHeadSha } : {}),
+        source: { gate: 'mergeGate', inboxId: nonBlank(resolution['inboxId']) ?? '' },
+    };
+}
+function prReviewThreads(readiness) {
+    return readiness.reviewThreads.items.map((thread) => ({
+        threadId: thread.id,
+        path: thread.path,
+        line: thread.line,
+        author: thread.author,
+        body: thread.body,
+    }));
+}
+function checkFact(severity, kind, name, result) {
+    return { severity, kind, name, summary: `${name}: ${result}`, evidence: result };
+}
+function emptyFactBuckets() {
+    return { hard: [], advisory: [] };
+}
+function pushFact(buckets, fact) {
+    buckets[fact.severity].push(fact);
+}
+function reviewThreadFact(thread) {
+    return {
+        severity: 'advisory',
+        kind: 'review_thread',
+        threadId: thread.id,
+        summary: thread.body,
+        evidence: [thread.path, thread.line].filter((item) => item !== undefined).join(':') || thread.url || thread.id,
+    };
+}
+function feedbackEvidence(item) {
+    return item.evidence ?? item.location ?? item.author ?? item.summary;
+}
+function classifyFeedbackFacts(readiness) {
+    const facts = emptyFactBuckets();
+    const feedback = readiness.feedback;
+    if (!feedback)
+        return facts;
+    for (const fix of feedback.developerFixes) {
+        if (fix.source === 'ci' || fix.source === 'review_thread')
+            continue;
+        const fact = {
+            severity: 'advisory',
+            kind: fix.source,
+            summary: fix.summary,
+            evidence: feedbackEvidence(fix),
+        };
+        pushFact(facts, fix.source === 'human_review' ? { ...fact, severity: 'hard' } : fact);
+    }
+    for (const question of feedback.reviewerQuestions) {
+        pushFact(facts, {
+            severity: 'hard',
+            kind: 'reviewer_question',
+            summary: question.summary,
+            evidence: feedbackEvidence(question),
+        });
+    }
+    for (const decision of feedback.humanDecisions) {
+        pushFact(facts, {
+            severity: 'hard',
+            kind: decision.source,
+            summary: decision.summary,
+        });
+    }
+    for (const wait of feedback.providerWait) {
+        pushFact(facts, {
+            severity: 'advisory',
+            kind: `provider_wait:${wait.provider}`,
+            summary: wait.evidence,
+            evidence: wait.reason,
+        });
+    }
+    return facts;
+}
+function checkStatusFact(check, required, status) {
+    const severity = required ? 'hard' : 'advisory';
+    const kind = `${required ? 'required' : 'non_required'}_check_${status}`;
+    return checkFact(severity, kind, check.name, check.result);
+}
+function pushCheckStatusFact(facts, check, names, required, status) {
+    if (!names.includes(check.name))
+        return;
+    pushFact(facts, checkStatusFact(check, required, status));
+}
+function factsFromRequiredChecks(readiness, required) {
+    const facts = emptyFactBuckets();
+    for (const check of readiness.checks.list) {
+        const isRequired = required.has(check.name);
+        pushCheckStatusFact(facts, check, readiness.checks.fail, isRequired, 'failed');
+        pushCheckStatusFact(facts, check, readiness.checks.pending, isRequired, 'pending');
+    }
+    if (readiness.checks.list.length === 0) {
+        pushFact(facts, {
+            severity: 'advisory',
+            kind: 'checks_none_registered',
+            summary: 'No registered checks were reported for the PR.',
+            evidence: 'checks: none registered',
+        });
+    }
+    return facts;
+}
+function checkRollupUnavailableFact(readiness) {
+    const unavailable = readiness.checks.pending.includes(GITHUB_CHECK_ROLLUP_UNAVAILABLE)
+        || readiness.evidence.some((item) => item.includes(GITHUB_CHECK_ROLLUP_UNAVAILABLE));
+    if (!unavailable)
+        return undefined;
+    return {
+        severity: 'hard',
+        kind: 'check_rollup_unavailable',
+        summary: 'GitHub check rollup is unavailable; override cannot distinguish pending checks from no registered checks.',
+        evidence: GITHUB_CHECK_ROLLUP_UNAVAILABLE,
+    };
+}
+function reviewThreadsIncompleteFact(readiness) {
+    if (readiness.reviewThreads.truncated !== true)
+        return undefined;
+    return {
+        severity: 'hard',
+        kind: 'review_threads_incomplete',
+        summary: 'Review thread data is incomplete; override cannot safely resolve every unresolved thread.',
+        evidence: `unresolvedCount=${readiness.reviewThreads.unresolvedCount ?? readiness.reviewThreads.items.length}`,
     };
 }
+function mergeOverrideOutput(input) {
+    const readiness = input.readiness;
+    const evidence = [
+        ...(readiness?.evidence ?? []),
+        ...(readiness ? readinessEvidence(readiness) : []),
+        ...input.facts.map((fact) => `${fact.severity} ${fact.kind}: ${fact.summary}`),
+        input.reason,
+        `PR headSha=${readiness?.pr.headSha ?? input.fallbackHeadSha ?? input.gate.audit.headSha}`,
+        `overrideMerge verdict=${input.verdict}`,
+    ].filter((item) => typeof item === 'string' && item.length > 0);
+    return {
+        prNumber: readiness?.pr.number ?? null,
+        headSha: readiness?.pr.headSha ?? input.fallbackHeadSha ?? input.gate.audit.headSha,
+        evidence,
+        verdict: input.verdict,
+        ciFailures: readiness ? ciFailuresFrom(readiness) : [],
+        reviewThreads: readiness ? prReviewThreads(readiness) : [],
+        ...(readiness?.mergeStateStatus !== undefined ? { mergeStateStatus: readiness.mergeStateStatus } : {}),
+        ...(readiness?.mergeable !== undefined ? { mergeable: readiness.mergeable } : {}),
+        override: {
+            accepted: input.accepted,
+            actor: input.gate.actor,
+            note: input.gate.note,
+            audit: {
+                reason: input.gate.audit.reason,
+                risk: input.gate.audit.risk,
+                verificationResponsibility: input.gate.audit.verificationResponsibility,
+                headSha: input.gate.audit.headSha,
+            },
+            source: input.gate.source,
+            facts: input.facts,
+            replied: input.response?.replied ?? 0,
+            resolved: input.response?.resolved ?? 0,
+            ...(input.reason ? { reason: input.reason } : {}),
+        },
+    };
+}
+function hardMergeabilityFact(readiness) {
+    const signal = mergeSignal(readiness.mergeStateStatus, readiness.mergeable);
+    if (signal === 'clean')
+        return undefined;
+    return {
+        severity: 'hard',
+        kind: signal === 'blocked' ? 'mergeability_blocked' : 'mergeability_unknown',
+        summary: `mergeStateStatus=${readiness.mergeStateStatus ?? ''} mergeable=${readiness.mergeable ?? ''}`,
+        evidence: `mergeStateStatus=${readiness.mergeStateStatus ?? ''}; mergeable=${readiness.mergeable ?? ''}`,
+    };
+}
+function movedHeadFact(readiness, gate) {
+    const approvedHeadSha = gate.trustedHeadSha;
+    if (!approvedHeadSha) {
+        return {
+            severity: 'hard',
+            kind: 'trusted_gate_head_unavailable',
+            summary: 'Trusted merge gate head is unavailable.',
+            evidence: `audit=${gate.audit.headSha}; fresh=${readiness.pr.headSha}`,
+        };
+    }
+    if (readiness.pr.headSha === approvedHeadSha)
+        return undefined;
+    return {
+        severity: 'hard',
+        kind: 'head_moved',
+        summary: `approved head ${approvedHeadSha} no longer matches fresh head ${readiness.pr.headSha}`,
+        evidence: `approved=${approvedHeadSha}; audit=${gate.audit.headSha}; fresh=${readiness.pr.headSha}`,
+    };
+}
+function auditHeadMismatchFact(gate) {
+    if (!gate.trustedHeadSha)
+        return undefined;
+    if (gate.audit.headSha === gate.trustedHeadSha)
+        return undefined;
+    return {
+        severity: 'hard',
+        kind: 'audit_head_mismatch',
+        summary: `audit head ${gate.audit.headSha} does not match trusted merge gate head ${gate.trustedHeadSha}`,
+        evidence: `audit=${gate.audit.headSha}; approved=${gate.trustedHeadSha}`,
+    };
+}
+function initialMergeOverrideHardFacts(readiness, gate, unavailableRollup) {
+    return [
+        readiness.draft === true ? { severity: 'hard', kind: 'draft_pr', summary: 'PR is still draft.' } : undefined,
+        auditHeadMismatchFact(gate),
+        movedHeadFact(readiness, gate),
+        hardMergeabilityFact(readiness),
+        unavailableRollup,
+        reviewThreadsIncompleteFact(readiness),
+    ].filter((fact) => fact !== undefined);
+}
+function appendFeedbackFacts(buckets, readiness) {
+    for (const thread of readiness.reviewThreads.items) {
+        buckets.advisory.push(reviewThreadFact(thread));
+    }
+    const feedbackFacts = classifyFeedbackFacts(readiness);
+    buckets.hard.push(...feedbackFacts.hard);
+    buckets.advisory.push(...feedbackFacts.advisory);
+}
+function classifyAvailableCheckFacts(readiness, ownerRepo, execGh, requiredChecks) {
+    if (readiness.checks.fail.length === 0 && readiness.checks.pending.length === 0) {
+        return readiness.checks.list.length === 0 ? factsFromRequiredChecks(readiness, new Set()) : emptyFactBuckets();
+    }
+    if (readiness.pr.number === null) {
+        return {
+            hard: [{ severity: 'hard', kind: 'pr_number_unavailable', summary: 'Cannot classify required checks without a PR number.' }],
+            advisory: [],
+        };
+    }
+    try {
+        return factsFromRequiredChecks(readiness, requiredChecks(ownerRepo, readiness.pr.number, execGh));
+    }
+    catch (err) {
+        return {
+            hard: [{
+                    severity: 'hard',
+                    kind: 'required_check_names_unavailable',
+                    summary: 'Required check names are unavailable.',
+                    evidence: err instanceof Error ? err.message : String(err),
+                }],
+            advisory: [],
+        };
+    }
+}
+async function classifyMergeOverrideFacts(readiness, gate, ownerRepo, execGh, requiredChecks) {
+    const unavailableRollup = checkRollupUnavailableFact(readiness);
+    const facts = {
+        hard: initialMergeOverrideHardFacts(readiness, gate, unavailableRollup),
+        advisory: [],
+    };
+    if (!unavailableRollup) {
+        const checkFacts = classifyAvailableCheckFacts(readiness, ownerRepo, execGh, requiredChecks);
+        facts.hard.push(...checkFacts.hard);
+        facts.advisory.push(...checkFacts.advisory);
+    }
+    appendFeedbackFacts(facts, readiness);
+    return facts;
+}
+function overrideThreadTriage(readiness, note) {
+    return {
+        items: readiness.reviewThreads.items.map((thread) => ({
+            threadId: thread.id,
+            decision: 'wontfix',
+            replyText: `merged by operator override: ${note}`,
+        })),
+    };
+}
+export async function overrideMerge(input, deps) {
+    const gate = mergeOverrideGate(input);
+    if ('needsHuman' in gate)
+        return gate;
+    const { execGit: git, execGh: gh, resolveRunCwd } = deps;
+    const cwd = await resolveRunCwd(input.runId, input.taskId);
+    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;
+    try {
+        readiness = await (deps.collect ?? defaultCollect)(ownerRepo, branch, input.base, gh, input.issueRef, input.issueAction);
+    }
+    catch (err) {
+        const fact = {
+            severity: 'hard',
+            kind: 'readiness_transport_degraded',
+            summary: 'Fresh override reverify could not read PR readiness.',
+            evidence: err instanceof Error ? err.message : String(err),
+        };
+        return mergeOverrideOutput({
+            gate,
+            verdict: 'recheck',
+            facts: [fact],
+            accepted: false,
+            reason: fact.summary,
+        });
+    }
+    if (readiness.readinessVerdict === 'merged') {
+        return mergeOverrideOutput({ gate, readiness, verdict: 'merged', facts: [], accepted: false, reason: 'PR already merged externally.' });
+    }
+    if (readiness.readinessVerdict === 'closed') {
+        const fact = { severity: 'hard', kind: 'pr_closed_externally', summary: 'PR is closed without being merged.' };
+        return mergeOverrideOutput({ gate, readiness, verdict: 'closed', facts: [fact], accepted: false, reason: fact.summary });
+    }
+    const facts = await classifyMergeOverrideFacts(readiness, gate, ownerRepo, gh, deps.requiredChecks ?? fetchRequiredCheckNames);
+    if (facts.hard.length > 0) {
+        return mergeOverrideOutput({
+            gate,
+            readiness,
+            verdict: 'recheck',
+            facts: facts.hard,
+            accepted: false,
+            reason: 'override_merge refused because hard blockers remain',
+        });
+    }
+    const response = await respondThreads(overrideThreadTriage(readiness, gate.note), { execGh: gh });
+    return mergeOverrideOutput({
+        gate,
+        readiness,
+        verdict: 'clean',
+        facts: facts.advisory,
+        accepted: true,
+        response,
+    });
+}
 export async function pollPr(input, deps) {
     const { execGit: git, execGh: gh, resolveRunCwd } = deps;
     const collect = deps.collect ?? defaultCollect;
@@ -446,9 +904,9 @@ export async function pollPr(input, deps) {
     let readiness;
     let lastReadiness;
     for (let i = 0; i < maxPolls; i++) {
-        readiness = await collect(ownerRepo, branch, input.base, gh, input.issueRef);
+        readiness = await collect(ownerRepo, branch, input.base, gh, input.issueRef, input.issueAction);
         lastReadiness = readiness;
-        if (readiness.checks.pending.length === 0 && readiness.checks.list.length > 0)
+        if (readiness.checks.pending.length === 0)
             break;
         readiness = undefined;
         if (i < maxPolls - 1)
@@ -468,6 +926,51 @@ export async function pollPr(input, deps) {
         return { needsHuman: true, lesson: `pollPr timed out after ${maxPolls} polls before reading PR readiness for ${branch}` };
     }
     let settled = readiness;
+    const makeTerminalFeedback = (verdict) => ({
+        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: ciFailuresFrom(settled),
+        reviewThreads: [],
+        ...(settled.mergeStateStatus !== undefined ? { mergeStateStatus: settled.mergeStateStatus } : {}),
+        ...(settled.mergeable !== undefined ? { mergeable: settled.mergeable } : {}),
+    });
+    if (settled.readinessVerdict === 'merged')
+        return makeTerminalFeedback('merged');
+    if (settled.readinessVerdict === 'closed')
+        return makeTerminalFeedback('closed');
+    const standardCheckResults = new Set('ACTION_REQUIRED CANCELLED ERROR EXPECTED FAILURE IN_PROGRESS NEUTRAL PENDING QUEUED SKIPPED STALE STARTUP_FAILURE SUCCESS TIMED_OUT UNKNOWN'.split(' '));
+    const standardMergeStateStatuses = new Set('BEHIND BLOCKED CLEAN DIRTY DRAFT HAS_HOOKS UNKNOWN UNSTABLE'.split(' '));
+    const standardMergeableStates = new Set('CONFLICTING MERGEABLE UNKNOWN'.split(' '));
+    const addUnclassifiableState = (states, label, value, known) => {
+        const state = (value ?? '').trim().toUpperCase();
+        if (state !== '' && !known.has(state))
+            states.push(`${label} ${state}`);
+    };
+    const unclassifiablePollState = (snapshot) => {
+        const states = [];
+        for (const check of snapshot.checks.list) {
+            addUnclassifiableState(states, 'check result', check.result, standardCheckResults);
+        }
+        addUnclassifiableState(states, 'mergeStateStatus', snapshot.mergeStateStatus, standardMergeStateStatuses);
+        addUnclassifiableState(states, 'mergeable', snapshot.mergeable, standardMergeableStates);
+        return states;
+    };
+    const unclassifiableReadinessBlock = (snapshot, states) => ({
+        needsHuman: true,
+        lesson: [
+            ...snapshot.evidence,
+            ...readinessEvidence(snapshot),
+            `pollPr unclassifiable readiness state: ${states.join(', ')}`,
+            `PR headSha=${snapshot.pr.headSha}`,
+        ].join('; '),
+    });
+    const unclassifiable = unclassifiablePollState(settled);
+    if (unclassifiable.length > 0) {
+        return unclassifiableReadinessBlock(settled, unclassifiable);
+    }
     const initialCiFailures = ciFailuresFrom(settled);
     if (initialCiFailures.length === 0) {
         try {
@@ -478,14 +981,19 @@ export async function pollPr(input, deps) {
         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);
+            settled = await collect(ownerRepo, branch, input.base, gh, input.issueRef, input.issueAction);
         }
     }
-    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';
-        return unsettledReadinessFeedback(input, settled, `pollPr found unsettled readiness after readying ${branch}: ${detail}`);
+    if (settled.readinessVerdict === 'merged')
+        return makeTerminalFeedback('merged');
+    if (settled.readinessVerdict === 'closed')
+        return makeTerminalFeedback('closed');
+    const finalUnclassifiable = unclassifiablePollState(settled);
+    if (finalUnclassifiable.length > 0) {
+        return unclassifiableReadinessBlock(settled, finalUnclassifiable);
+    }
+    if (settled.checks.pending.length > 0) {
+        return unsettledReadinessFeedback(input, settled, `pollPr found unsettled readiness after readying ${branch}: pending checks: ${settled.checks.pending.join(', ')}`);
     }
     const reviewThreads = settled.reviewThreads.items.map((t) => ({
         threadId: t.id,
@@ -496,27 +1004,51 @@ export async function pollPr(input, deps) {
     }));
     const ciFailures = ciFailuresFrom(settled);
     let ciVerdictFailures = ciFailures;
+    let requiredCheckFetchFailure;
     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 {
+        catch (err) {
+            requiredCheckFetchFailure = err instanceof Error ? err.message : String(err);
         }
     }
-    const verdict = reviewThreads.length > 0 || readinessRequiresReview(settled)
-        ? 'review_changes'
-        : ciVerdictFailures.length > 0 ? 'ci_changes' : 'clean';
-    return {
+    const makeFeedback = (verdict, extraEvidence = []) => ({
         prNumber: settled.pr.number ?? null,
         headSha: settled.pr.headSha,
-        evidence: [...settled.evidence, ...readinessEvidence(settled), `PR headSha=${settled.pr.headSha}`, `pollPr verdict=${verdict}`],
+        evidence: [...settled.evidence, ...readinessEvidence(settled), ...extraEvidence, `PR headSha=${settled.pr.headSha}`, `pollPr verdict=${verdict}`],
         ...(input.issueRef ? { issueRef: input.issueRef } : {}),
         verdict,
         ciFailures,
         reviewThreads,
-    };
+        ...(settled.mergeStateStatus !== undefined ? { mergeStateStatus: settled.mergeStateStatus } : {}),
+        ...(settled.mergeable !== undefined ? { mergeable: settled.mergeable } : {}),
+    });
+    if (reviewThreads.length > 0 || readinessRequiresReview(settled))
+        return makeFeedback('review_changes');
+    if (requiredCheckFetchFailure) {
+        return makeFeedback('recheck', [`Required check names unavailable: ${requiredCheckFetchFailure}`]);
+    }
+    if (ciVerdictFailures.length > 0)
+        return makeFeedback('ci_changes');
+    const signal = mergeSignal(settled.mergeStateStatus, settled.mergeable);
+    if (signal === 'blocked') {
+        return {
+            needsHuman: true,
+            lesson: [
+                ...settled.evidence,
+                ...readinessEvidence(settled),
+                `pollPr merge readiness blocked (mergeStateStatus=${settled.mergeStateStatus ?? ''} mergeable=${settled.mergeable ?? ''})`,
+                `PR headSha=${settled.pr.headSha}`,
+            ].join('; '),
+        };
+    }
+    if (signal === 'unknown') {
+        return unsettledReadinessFeedback(input, settled, `pollPr merge readiness unknown (mergeable=${settled.mergeable ?? 'undefined'})`);
+    }
+    return makeFeedback('clean');
 }
 const TRIAGE_DECISIONS = new Set(['fix', 'wontfix', 'question']);
 export function asTriage(value) {
@@ -531,6 +1063,37 @@ export function asTriage(value) {
         : [];
     return { items };
 }
+function questionGateResolution(value) {
+    if (value === null || typeof value !== 'object')
+        return undefined;
+    const outcome = value.outcome;
+    if (outcome !== 'fix' && outcome !== 'wontfix')
+        return undefined;
+    const rawNote = value.note;
+    const note = typeof rawNote === 'string' ? rawNote.trim() : '';
+    return { decision: outcome, ...(note ? { note } : {}) };
+}
+function replyTextForQuestionResolution(decision, note) {
+    if (decision === 'fix')
+        return note ? `Addressed: ${note}` : 'Addressed.';
+    return note ? `Won't fix: ${note}` : "Won't fix.";
+}
+export function triageForRespondThreads(input) {
+    const triage = asTriage(input.triage);
+    const resolution = questionGateResolution(input.gateResolution);
+    if (!resolution)
+        return triage;
+    return {
+        ...triage,
+        items: triage.items.map((item) => item.decision === 'question'
+            ? {
+                ...item,
+                decision: resolution.decision,
+                replyText: replyTextForQuestionResolution(resolution.decision, resolution.note),
+            }
+            : item),
+    };
+}
 export async function respondThreads(triage, deps) {
     const { execGh: gh } = deps;
     let replied = 0;
@@ -609,13 +1172,51 @@ let IntegratorService = class IntegratorService {
     runPollStub = (_input) => {
         return { prNumber: null, headSha: 'stub', evidence: ['stub pollPr readiness: clean'], verdict: 'clean', ciFailures: [], reviewThreads: [] };
     };
+    runOverrideMerge = (input) => {
+        const pinned = resolvePinnedGh();
+        if ('needsHuman' in pinned) {
+            console.warn(`[override-merge] ${pinned.lesson}`);
+            return Promise.resolve(pinned);
+        }
+        return overrideMerge(input, { ...this.deps, execGh: pinned.execGh });
+    };
+    runOverrideStub = (input) => {
+        const gate = mergeOverrideGate(input);
+        if ('needsHuman' in gate) {
+            return {
+                prNumber: null,
+                headSha: 'stub',
+                evidence: [gate.lesson, 'overrideMerge verdict=recheck'],
+                verdict: 'recheck',
+                ciFailures: [],
+                reviewThreads: [],
+                override: {
+                    accepted: false,
+                    actor: 'stub',
+                    note: '',
+                    source: { gate: 'mergeGate', inboxId: '' },
+                    facts: [{ severity: 'hard', kind: 'override_input_missing', summary: gate.lesson }],
+                    replied: 0,
+                    resolved: 0,
+                    reason: gate.lesson,
+                },
+            };
+        }
+        return mergeOverrideOutput({
+            gate,
+            verdict: 'clean',
+            facts: [],
+            accepted: true,
+            fallbackHeadSha: gate.audit.headSha || 'stub',
+        });
+    };
     runRespondThreads = (input) => {
         const pinned = resolvePinnedGh();
         if ('needsHuman' in pinned) {
             console.warn(`[respond-threads] ${pinned.lesson}`);
             return Promise.resolve(pinned);
         }
-        return respondThreads(asTriage(input.triage), { execGh: pinned.execGh });
+        return respondThreads(triageForRespondThreads(input), { execGh: pinned.execGh });
     };
     runRespondStub = (_input) => {
         return { replied: 0, resolved: 0 };