@telora/daemon 0.22.239 → 0.22.289

package/dist/completion/review-exit/review-exit-phase.js

@@ -0,0 +1,654 @@
+// PINNED-BY-BEGIN (generated by gen:pinned-by -- do not hand-edit; checked by lint:pinned-by)
+// Pinned by: 26 tests -- run: npm run gen:pinned-by -- --list packages/daemon/src/completion/review-exit/review-exit-phase.ts
+// PINNED-BY-END
+/**
+ * Review-exit phase of the team completion flow.
+ *
+ * Routes verify deliveries when a team exits while the focus has
+ * review_requested_at set: open work -> verify_failed, explicit report ->
+ * done, clean review session -> auto-approved done. Clears
+ * review_requested_at and emits review_completed when anything routed.
+ * Invoked by the phase sequencer in team-completion.ts and deterministically
+ * from completion/completion-event/event.ts on a review pass completion.
+ *
+ * History: docs/daemon/history-team-lifecycle.md (completion/review-exit/review-exit-phase.ts).
+ */
+import { filterWorkIssues, OPEN_ISSUE_STATUSES } from '../../types/issue-status.js';
+import { DELIVERY_STATUS } from '@telora/daemon-core';
+import { resolveReconciledWrite } from '../../delivery/delivery-reconciler-apply.js';
+import { resolveOperatorHold, writeOperatorHoldGateState, describeOperatorHold } from '../../delivery/operator-hold.js';
+import { resolveExternalHold, makeDeferredRequestClosureEvaluator, describeExternalHold } from '../../delivery/external-hold.js';
+import { surfaceStaleReferenceLessExternalHold } from '../../delivery/external-hold-surface.js';
+import { heldOnAwaitedModel } from '../../verify/outcome-routing/verification-model-unavailable-hold.js';
+import { resolveShortfallHold, writeShortfallGateState, describeShortfallHold, } from '../review-exit-holds/review-exit-shortfall.js';
+import { recordReviewCycleAndMaybeEndArm } from '../review-cycle-budget/review-cycle-cap.js';
+import { fileCoverageIncompleteEscalation, fileGapsWithoutIssueEscalation, fileMissingReportNotice, recordHandoffAndMaybeTerminate, } from './review-exit-escalations.js';
+import { forceFullPassReviewFocuses, recordBelowCoverageDrift, resetCoverageDriftState } from '../review-coverage/coverage-drift-state.js';
+import { resolveReviewCycleProgress, emitReviewCompleted, logLeftInVerifyWithoutSignal } from '../review-cycle-budget/review-exit-progress.js';
+import { closeFailedVerdictExit, holdForCommitVerdict, logCommitVerdictHeldExit, reviewReworkGateState } from '../review-exit-holds/review-exit-verdict-gate.js';
+import { refusesReworkOnShortfallPark, logShortfallParkedExit } from '../review-exit-holds/review-exit-shortfall-park.js';
+import { resolveGapsAttribution } from './review-exit-attribution.js';
+import { resolveOutsideWindowFindings, rehomeOutsideWindowFindings } from './review-exit-rehoming.js';
+import { scopeReviewEvidenceToOwnWork } from './review-exit-foreign-findings.js';
+import { gatherReviewExitEvidence } from './review-exit-evidence.js';
+import { recordReviewExitCensus } from './review-census-record.js';
+import { createLogger } from '../../log/daemon-log.js';
+const log = createLogger({ module: 'focus-executor' });
+/** Whether the focus's next review must be a full pass (drift-triggered). Consumes the flag. */
+export function consumeForceFullPassReview(focusId) {
+    if (forceFullPassReviewFocuses.has(focusId)) {
+        forceFullPassReviewFocuses.delete(focusId);
+        return true;
+    }
+    return false;
+}
+/**
+ * Auto-approve a delivery a clean review covered exactly (verify -> done), recording
+ * the commit the review covered FIRST: an auto-approval writes no focus_reviews row,
+ * so the record is the merge gate's only evidence for it
+ * (review-auto-approval-record.ts), and a delivery done without it could never merge.
+ * A record that is not written throws, leaving the delivery in verify for a later
+ * review; a record whose move then fails still names a commit a clean review covered
+ * in full.
+ */
+async function autoApproveCoveredDelivery(deps, params, deliveryId, doneStageId) {
+    const { organizationId, productId, focusId, sessionId, reviewSpawnTip } = params;
+    const approval = { productId, focusId, sha: reviewSpawnTip ?? '', sessionId, deliveryId, recordedAt: new Date().toISOString() };
+    if (!deps.recordReviewAutoApproval(approval)) {
+        throw new Error(`the covered commit '${approval.sha.slice(0, 12)}' could not be recorded as merge evidence; left in verify`);
+    }
+    await deps.markDeliveryAutoApproved(deliveryId, sessionId, doneStageId, { organizationId, fromStatus: DELIVERY_STATUS.VERIFY });
+}
+/**
+ * Handle a team exit when the focus has review_requested_at set.
+ *
+ * Routing is asymmetric in the downward direction (toward intent) -- open
+ * work on a verify delivery means the work isn't done, so it routes to
+ * verify_failed unconditionally. Closing a verify delivery to `done` is
+ * the other direction; it now happens via two paths: an explicit
+ * focus_reviews approval, OR a clean review session exit (auto-approve,
+ * reversible via the later unapprove affordance).
+ *
+ * Routing rules:
+ *   1. No review_requested_at -> nothing to do.
+ *   2. A spawn directive is pending -> defer to the incoming team.
+ *   3. For each verify delivery:
+ *        - open work issues  -> verify_failed (always, no evidence gate)
+ *        - no open work + reportExists -> done (explicit approval)
+ *        - no open work + no report + review session succeeded ->
+ *          done (auto-approve; tagged with auto_approved_at /
+ *          auto_approved_by_session for surfacing + unapprove)
+ *        - no open work + non-review session (or failed review) ->
+ *          leave in verify (next auto-review poll re-triggers)
+ *   4. If anything routed -> clear review_requested_at + emit
+ *      review_completed event so phase re-derives on the next poll.
+ *   5. If routed via issue evidence (no report present), file a soft
+ *      review_missing_report notice -- the loop continues regardless.
+ *   6. If nothing routed AND no evidence at all -> warn-and-leave. The
+ *      strict gate no longer escalates: an idle focus with no work and no
+ *      report is ambiguous, not failed; humans clear it via the MCP
+ *      clear-review-request path.
+ *
+ * The independent "evidence" signals (focus_reviews row + review-filed
+ * issues) still feed into the issue-evidence notice and the warn-and-leave
+ * messaging, but they no longer gate routing -- open work on a delivery
+ * is its own evidence that the work isn't done.
+ *
+ * The review-exit context is required: production passes the one the
+ * composition root built (composition/review-exit-context.ts).
+ */
+export async function runReviewExitHandler(params, deps) {
+    const { focusId, focusName, organizationId, productId, sessionId, sessionType, succeeded, reviewSpawnTip, currentBranchTip, reviewInspected, reviewPriorWatermark } = params;
+    // The SHA to stamp as coverage = what the review actually saw (spawn-tip);
+    // fall back to the exit tip only when the carry was lost (restart mid-review).
+    const coveredSha = reviewSpawnTip ?? currentBranchTip ?? null;
+    // Anchor shared by every escalation this exit can raise (review-exit-escalations.ts); coveredSha is the breaker's crossing head.
+    const escalationCtx = { organizationId, focusId, focusName, sessionId, coveredSha };
+    // Coverage is complete for auto-approve ONLY when the review saw the exact
+    // state being approved: spawn-tip and exit-tip are both known AND equal (no
+    // commits landed on the focus branch during the review pass). A lost carry
+    // (reviewSpawnTip null) can never be coverage-complete -- withhold auto-approve.
+    const coverageComplete = reviewSpawnTip != null && currentBranchTip != null && reviewSpawnTip === currentBranchTip;
+    // Open shortfall drift proposals for the focus. A shortfall means the tree
+    // claimed X and the work delivered less than X; until one is disposed, NO
+    // delivery on this focus may converge to done.
+    //
+    // Read ONCE per focus, before the delivery loop, exactly like coverageComplete
+    // -- the question is focus-scoped, not per-delivery. And deliberately OUTSIDE
+    // the reconciler: it is not an input the reconciler models, so it gates the
+    // write DOWNSTREAM of `target`, where coverageComplete also sits.
+    const shortfall = await resolveShortfallHold(deps, focusId, focusName);
+    const shortfallsClear = shortfall.clear;
+    let shortfallHold = false;
+    const focuses = await deps.getActiveFocuses(organizationId, productId);
+    const current = focuses.find(s => s.focus_id === focusId);
+    if (!current) {
+        // Focus not in the active set -- nothing to route.
+        return;
+    }
+    // The review window MAY already be closed by the time this handler runs (a
+    // prior exit cleared it, or state-cascade cleared it when no review owned it).
+    // Routing FINDINGS toward intent does not depend on the flag: a blocking
+    // review-filed gap that missed its window while its delivery was in verify
+    // must still re-open that delivery once it has advanced to done -- the
+    // verify/done asymmetry this delivery removes. So we do NOT bail on a null
+    // flag here; we gather the focus-wide review-filed evidence below and bail
+    // only when the window is closed AND there is no open review-filed gap to
+    // route. The toward-DONE branches (auto-approve, report->done) still require
+    // an open window and are gated on `windowOpen`.
+    const windowOpen = !!current.review_requested_at;
+    const reviewRequestedAt = current.review_requested_at ?? null;
+    // NOTE: a pending spawn directive no longer short-circuits the handler.
+    // Delivery finalization (auto-approve verify->done, done-via-report, and
+    // verify_failed on open work) plus clearing review_requested_at and emitting
+    // review_completed must run unconditionally on a session exit -- otherwise a
+    // transiently-pending spawn strands the verify delivery and feeds the
+    // per-poll re-fire spin. The pending-spawn signal is consulted ONLY in the
+    // non-routed branch below, where leaving the flag set for an incoming team is
+    // the legitimate behavior.
+    // ── Gather evidence ──────────────────────────────────────────────
+    // Read the review report + focus issues and derive every review-filed signal
+    // the routing decision tree consumes (review-exit-evidence.ts). Best-effort:
+    // a read failure degrades to no-evidence defaults, routing runs regardless.
+    const evidence = await gatherReviewExitEvidence(deps, { focusId, focusName, sessionId, reviewRequestedAt });
+    const { reportExists, reviewOutcome, reviewCreatedIssueIds, hasIssueEvidence, deferrableIssueIds } = evidence;
+    // The gaps-without-issue inconsistency (below) keys on hasBlockingIssueEvidence
+    // -- whether the review filed a blocking issue ANYWHERE in the focus (read
+    // focus-wide from the complete review-filed id set above), NOT a verify-scoped
+    // walk that made a sibling-delivery gap structurally invisible.
+    // Nothing-to-do bail: a CLOSED review window with no open review-filed gap has
+    // nothing to route -- the toward-intent evidence path is empty and the
+    // toward-done path requires an open window. An OPEN window always proceeds (its
+    // clean-session auto-approve / report routing still runs even with no gaps).
+    if (!windowOpen && evidence.reviewFiledTargetDeliveryIds.size === 0) {
+        return;
+    }
+    // ── Route verify deliveries ──────────────────────────────────────
+    // Runs unconditionally: open work routes to verify_failed even when no
+    // review evidence is present. This is the self-healing path -- a coding
+    // team that left pre-existing open work behind no longer needs the review
+    // agent to file fresh defects before the loop can correct itself.
+    const reviewDeliveries = await deps.getFocusDeliveries(focusId);
+    // Which verify deliveries this review saw at the commit it covered (review-census-record.ts): the standing-approval convergence reads it.
+    recordReviewExitCensus(deps.recordReviewCensus, { ...params, windowOpen, coveredSha, coverageComplete, reportExists, reviewOutcome, deliveries: reviewDeliveries });
+    // Judge only THIS focus's work: a blocking finding about another focus's commit (by Telora-Delivery
+    // trailer) is moved to its owner and leaves the target sets; an all-foreign gaps_found verdict resolves
+    // (not 'unresolvable'), so the in-verify delivery converges on merit (review-exit-foreign-findings.ts).
+    const { attributedDeliveryIds, reviewFiledTargetDeliveryIds, openBlockingFindings, hasBlockingIssueEvidence, attributionResolvable, foreignFindingIds, } = await scopeReviewEvidenceToOwnWork(deps, {
+        focusId, focusName, organizationId, sessionId, reviewSpawnTip, currentBranchTip, reviewPriorWatermark,
+        current, focuses, reviewDeliveries, evidence,
+    });
+    // Re-home a gaps_found review's blocking findings that were filed OUTSIDE the
+    // active verify window (on a done / sibling delivery) onto the delivery in
+    // verify, BEFORE per-delivery routing -- so that delivery re-enters coding
+    // CARRYING the finding instead of routing to verify_failed with "no blocking
+    // issue filed". Unambiguous single-in-verify case only (review-exit-rehoming.ts).
+    const verifyDeliveryIds = new Set(reviewDeliveries.filter(d => d.executionStatus === DELIVERY_STATUS.VERIFY).map(d => d.id));
+    if (windowOpen && reviewOutcome === 'gaps_found') {
+        await rehomeOutsideWindowFindings(deps, focusName, resolveOutsideWindowFindings(openBlockingFindings.filter(f => !foreignFindingIds.has(f.id)), verifyDeliveryIds), verifyDeliveryIds);
+    }
+    let routedAny = false;
+    // Whether any delivery CONVERGED to done this cycle -- feeds the review-cycle
+    // delta (a convergence is progress; a verify_failed re-route is not).
+    let convergedAny = false;
+    // Set when a clean review would have auto-approved a delivery but coverage is
+    // incomplete (spawn-tip != exit-tip -- the branch drifted mid-review). Drives
+    // the per-focus one-full-pass-respawn-then-escalate path after the loop.
+    let belowCoverageHold = false;
+    // Set when a delivery would have converged to done but is held by an open
+    // operator escalation (needs_operator / external_wait). Drives the post-loop
+    // "held; leave the review window open" branch.
+    let operatorHeldAny = false;
+    // Set when a delivery would have converged to done but is held by an
+    // irreducibly-external dependency carried as gate_state STATE (external-hold.ts,
+    // NOT an escalation row). Drives the same "leave the review window open" tail.
+    let externalHeldAny = false;
+    let modelHeldAny = false; // a done route held because the verify reconciliation could not RUN
+    // Set when a delivery's done / verify_failed route is held on the gate verdict for the
+    // commit it judges (review-exit-verdict-gate.ts). Keeps the review window open.
+    let verdictHeldAny = false;
+    let verdictFailed = null; // held on a verdict to come / on a FAILED one
+    // Set when a verify delivery's verify_failed route is refused by a shortfall park (review-exit-shortfall-park.ts).
+    let parkedAny = false;
+    // attributionResolvable (scoped above): whether the gaps_found verdict resolved
+    // to ANY delivery (or only to relocated foreign findings). When false, every
+    // delivery reads 'unresolvable' -- absence of attribution holds toward intent.
+    // Delivery ids that CONVERGED to a terminal (done) this cycle, and whether any
+    // delivery re-opened to verify_failed -- the two facts the post-loop
+    // convergence sweep reads to decide the focus actually converged.
+    const convergedDeliveryIds = new Set();
+    let anyReopenedToVerifyFailed = false;
+    for (const d of reviewDeliveries) {
+        const isVerify = d.executionStatus === DELIVERY_STATUS.VERIFY;
+        // A done delivery re-opens when EITHER the exiting session's gaps_found
+        // verdict targets it (the verdict path, preserved) OR it owns an open,
+        // blocking, review-filed gap in the focus-wide evidence set (the durability
+        // path -- a finding that missed its window while the delivery was in verify,
+        // routable by whichever session next reaches this handler). Either way the
+        // reconciled path re-opens THAT delivery rather than failing whichever
+        // sibling happens to be in verify.
+        const isReopenableDone = d.executionStatus === DELIVERY_STATUS.DONE &&
+            ((reviewOutcome === 'gaps_found' && attributedDeliveryIds.has(d.id)) ||
+                reviewFiledTargetDeliveryIds.has(d.id));
+        if (!isVerify && !isReopenableDone)
+            continue;
+        // A CLOSED review window has no authority to converge a delivery to done; it
+        // is processed ONLY to route open review-filed gaps toward intent. Skip any
+        // delivery that is not an evidence target so a closed window can never
+        // auto-approve or report->done a delivery (a verify delivery with no gap
+        // would otherwise reach the clean-session auto-approve branch).
+        if (!windowOpen && !reviewFiledTargetDeliveryIds.has(d.id))
+            continue;
+        // The loop body runs ONLY for a verify or a re-openable done delivery.
+        const fromStatus = isVerify ? DELIVERY_STATUS.VERIFY : DELIVERY_STATUS.DONE;
+        try {
+            const [issues, dWorkflow] = await Promise.all([
+                deps.getDeliveryIssues(d.id),
+                deps.fetchEffectiveWorkflow(d.id),
+            ]);
+            const workIssues = filterWorkIssues(issues);
+            const openWork = workIssues.filter(i => OPEN_ISSUE_STATUSES.has(i.status));
+            // BLOCKING open work excludes non-blocking review notes: a verify delivery
+            // whose only open work is a review finding isBlockingReviewFinding clears
+            // (a recorded concern, or -- none recorded -- P2/P3) converges rather than
+            // re-coding. Classified once from the focus-issue read (deferrableIssueIds).
+            const blockingOpenWork = openWork.filter(i => !deferrableIssueIds.has(i.id));
+            // Per-delivery attribution for a gaps_found verdict (see review-exit-attribution.ts).
+            const gapsAttribution = resolveGapsAttribution(d.id, reviewOutcome === 'gaps_found', attributedDeliveryIds, attributionResolvable);
+            // Route through the single-writer reconciler: the review-exit conditions are
+            // exactly its verify-state inputs. The route-specific WRITE mechanism is keyed
+            // off the resolved target + reportExists below. currentStatus is the
+            // delivery's ACTUAL status so a re-openable done delivery routes through the
+            // reconciler's done case (done -> verify_failed).
+            const decision = resolveReconciledWrite({
+                input: {
+                    currentStatus: fromStatus,
+                    // Tag deferrable review notes so the reconciler's verify case does not
+                    // treat them as blocking open work.
+                    issues: issues.map(i => ({
+                        status: i.status,
+                        issueType: i.issueType,
+                        deferrable: deferrableIssueIds.has(i.id),
+                    })),
+                    gitState: { worktreeCommitted: true },
+                    guardVerdict: null,
+                    reviewState: { reviewRequested: true, reportExists, sessionType, succeeded, outcome: reviewOutcome, inspected: reviewInspected, gapsAttribution, reviewFiledBlockingOnDone: reviewFiledTargetDeliveryIds.has(d.id) },
+                },
+            });
+            const target = decision.target;
+            // A re-openable done delivery's only action is re-open to verify_failed; if
+            // the reconciler leaves it done (gap already closed) there is nothing to
+            // write -- skip so the verify-only done branches below never fire for it.
+            if (!isVerify && target !== DELIVERY_STATUS.VERIFY_FAILED) {
+                continue;
+            }
+            // Operator-hold gate (FAIL-CLOSED): a delivery carrying an unresolved
+            // needs_operator / external_wait escalation anchored to it must not
+            // converge to done by ANY path -- including this auto-approve path, which
+            // is exactly what carried the observed failure (escalation 20f5c2fd: the
+            // delivery's own escalation said its host work was NEVER EXECUTED, yet a
+            // clean review auto-approved it to done). Checked per-delivery, downstream
+            // of the reconciler target like the shortfall hold, and BEFORE any of the
+            // done-writing branches below.
+            if (target === DELIVERY_STATUS.DONE) {
+                const hold = await resolveOperatorHold(deps, d.id, focusId);
+                if (hold.held) {
+                    operatorHeldAny = true;
+                    await writeOperatorHoldGateState(deps, d.id, hold, d.gateState);
+                    log.info(`[focus-executor] Delivery "${d.name}" NOT moved to done -- ${describeOperatorHold(hold)}. ` +
+                        `Left in verify pending operator resolution.`);
+                    continue;
+                }
+            }
+            // External-hold gate (sibling of the operator-hold gate): even a clean
+            // review that would auto-approve must not converge to done while an
+            // irreducibly-external dependency holds the delivery as gate_state STATE
+            // (not an escalation row). The hold clears by re-reading its condition,
+            // not by a human resolve. Same fail-closed shape as the operator-hold gate.
+            if (target === DELIVERY_STATUS.DONE) {
+                const externalHold = await resolveExternalHold({ updateDeliveryStatus: deps.updateDeliveryStatus }, d.id, d.gateState, makeDeferredRequestClosureEvaluator(productId), deps.now);
+                // Surface (or clear) a stale reference-less hold as operator-visible state
+                // (TEL-5, delivery 2): a reference-less hold cannot self-clear, so once it
+                // is age-bounded stale it must not be a silent permanent hold.
+                surfaceStaleReferenceLessExternalHold(d.id, d.name, externalHold.staleReferenceLess ?? false, externalHold.hold);
+                if (externalHold.held) {
+                    externalHeldAny = true;
+                    log.info(`[focus-executor] Delivery "${d.name}" NOT moved to done -- ${describeExternalHold(externalHold)}. ` +
+                        `Left in verify pending an external reality change.`);
+                    continue;
+                }
+            }
+            // Awaited judge (sibling of the two gates above): verify's reconciliation could not run.
+            if (target === DELIVERY_STATUS.DONE && heldOnAwaitedModel(d)) {
+                modelHeldAny = true;
+                continue;
+            }
+            if (isVerify && target === DELIVERY_STATUS.VERIFY_FAILED && refusesReworkOnShortfallPark(d)) {
+                parkedAny = true;
+                continue;
+            }
+            // Commit-verdict gate (review-exit-verdict-gate.ts): done where a done write follows; a verify delivery's verify_failed.
+            const verdictGatedRoute = target === DELIVERY_STATUS.DONE ? (shortfallsClear && (reportExists || coverageComplete) ? 'done' : null)
+                : isVerify && target === DELIVERY_STATUS.VERIFY_FAILED ? 'verify_failed' : null;
+            const verdictGate = verdictGatedRoute ? await holdForCommitVerdict(deps, params, current, d, verdictGatedRoute) : null;
+            if (verdictGate?.held) {
+                if (verdictGate.failed !== undefined)
+                    verdictFailed = verdictGate;
+                else
+                    verdictHeldAny = true;
+                continue;
+            }
+            if (target === DELIVERY_STATUS.VERIFY_FAILED) {
+                const awaitingVerifyStage = dWorkflow.stages.find(s => s.name === 'verify_failed');
+                // Verdict cleared (no hold banner survives into verify_failed); history carries forward, stamped with
+                // the commit the gate judged and its recorded verdict, so the resumed team reads it (review-exit-verdict-gate.ts).
+                await deps.updateDeliveryStatus(d.id, 'verify_failed', awaitingVerifyStage?.id ?? null, await reviewReworkGateState(deps, params, current, d, verdictGate?.judgedSha, deps.now), undefined, { organizationId, fromStatus });
+                const failReason = blockingOpenWork.length > 0
+                    ? `${blockingOpenWork.length} blocking open issue(s) (of ${openWork.length} open)`
+                    : reviewOutcome === 'gaps_found'
+                        ? 'review verdict gaps_found with no blocking issue filed (routing inconsistency)'
+                        : 'clean review exit with no inspection evidence (blind gate -- bounded re-work)';
+                log.info(`Delivery "${d.name}" moved from ${fromStatus} to verify_failed: ${failReason}`);
+                routedAny = true;
+                anyReopenedToVerifyFailed = true;
+            }
+            else if (target === DELIVERY_STATUS.DONE && reportExists) {
+                // Review stamped a verdict. product-api already refuses an `approved`
+                // stamp over an undisposed shortfall -- but a shortfall can be emitted
+                // by verify writeback AFTER the stamp and before this handler runs, and
+                // that race is invisible to the edge gate. Re-check here, at the single
+                // point where the delivery actually moves to done.
+                if (!shortfallsClear) {
+                    shortfallHold = true;
+                    await writeShortfallGateState(deps, d.id, shortfall.ids, d.gateState);
+                    log.info(`[focus-executor] Delivery "${d.name}" NOT moved to done despite a passing review -- ` +
+                        `${describeShortfallHold(shortfall)}. Left in verify.`);
+                }
+                else {
+                    const doneStage = dWorkflow.stages.find(s => s.name === 'done');
+                    // gateState null: clear any prior hold banner on the way to done.
+                    await deps.updateDeliveryStatus(d.id, 'done', doneStage?.id ?? null, null, undefined, { organizationId, fromStatus: 'verify' });
+                    log.info(`Delivery "${d.name}" moved from verify to done (review passed)`);
+                    routedAny = true;
+                    convergedAny = true;
+                    convergedDeliveryIds.add(d.id);
+                }
+            }
+            else if (target === DELIVERY_STATUS.DONE && !shortfallsClear) {
+                // Silent clean-exit auto-approve, but the focus carries an undisposed
+                // shortfall. Silence cannot approve over a contradiction nobody
+                // adjudicated: that is precisely the bar-lowering this gate exists to
+                // stop. Left in verify; the disposition pass is armed after the loop.
+                shortfallHold = true;
+                await writeShortfallGateState(deps, d.id, shortfall.ids, d.gateState);
+                log.info(`[focus-executor] Delivery "${d.name}" NOT auto-approved -- ` +
+                    `${describeShortfallHold(shortfall)}. Left in verify pending disposition.`);
+            }
+            else if (target === DELIVERY_STATUS.DONE) {
+                // Clean review session (no defects filed, no focus_reviews row). Silence
+                // approves ONLY with proven coverage: the review must have covered the
+                // EXACT state being approved. coverageComplete is true only when the
+                // spawn-tip (what the review saw) equals the exit-tip (current branch) --
+                // i.e. no commits landed on the focus branch during the review. On drift
+                // (coverageComplete false) we do NOT auto-approve: the delivery stays in
+                // verify and the focus is routed to a full-pass respawn, then escalated
+                // if drift persists (after the loop). This is what makes a one-turn
+                // rubber stamp of an unreviewed state structurally impossible.
+                if (coverageComplete) {
+                    await autoApproveCoveredDelivery(deps, params, d.id, dWorkflow.stages.find(s => s.name === 'done')?.id ?? null);
+                    log.info(`[focus-executor] Delivery "${d.name}" auto-approved verify -> done ` +
+                        `(clean review, full coverage @ ${(reviewSpawnTip ?? '').slice(0, 12)}, no defects filed)`);
+                    routedAny = true;
+                    convergedAny = true;
+                    convergedDeliveryIds.add(d.id);
+                }
+                else {
+                    belowCoverageHold = true;
+                    log.info(`[focus-executor] Delivery "${d.name}" NOT auto-approved -- below coverage: review covered ` +
+                        `${(reviewSpawnTip ?? '<unknown>').slice(0, 12)} but branch tip is ${(currentBranchTip ?? '<unknown>').slice(0, 12)} ` +
+                        `(drift during review). Left in verify; focus routed to a full-pass re-review.`);
+                }
+            }
+            else {
+                // No signal to auto-approve; the window stays set (review-exit-progress.ts logLeftInVerifyWithoutSignal).
+                logLeftInVerifyWithoutSignal(d.name, sessionType);
+            }
+        }
+        catch (err) {
+            log.warn(`Failed to route delivery "${d.name}" after review: ${err.message}`);
+        }
+    }
+    // The routing inconsistency this focus exists to catch: the review stamped a
+    // gaps_found VERDICT but filed no open, blocking issue anywhere in the focus
+    // (hasBlockingIssueEvidence, read focus-wide from the complete review-filed id
+    // set) -- the coding team has nothing concrete to close. gaps_found still routes
+    // the delivery to verify_failed (above, toward intent), and we ALSO file one
+    // needs_operator escalation below. Mutually exclusive with the
+    // review_missing_report notice by construction: gaps_found implies
+    // reportExists=true, and that notice requires !reportExists, so the two can
+    // never double-fire for one exit.
+    const gapsWithoutIssue = reviewOutcome === 'gaps_found' && !hasBlockingIssueEvidence;
+    if (verdictFailed)
+        await closeFailedVerdictExit(deps, params, verdictFailed, verdictHeldAny);
+    if (routedAny) {
+        // A delivery held on its gate verdict still owns this window: the release replay converges it.
+        if (!verdictHeldAny)
+            await deps.clearReviewRequestedAt(focusId);
+        log.info(`[focus-executor] Review complete for "${focusName}" -- review_requested_at ${verdictHeldAny ? 'left set (a delivery awaits its gate verdict)' : 'cleared'} ` +
+            `(reportExists=${reportExists}, issueEvidence=${hasIssueEvidence}, blockingEvidence=${hasBlockingIssueEvidence})`);
+        // Advance the review coverage watermark to what the review ACTUALLY covered
+        // (the carried spawn-tip, `coveredSha`) -- NOT the exit tip. A COMPLETED
+        // cycle with a routed outcome (approve / auto-approve / defects filed)
+        // advances it regardless of verdict; coverage is not approval. Stamping the
+        // spawn-tip (the SHA the review saw) is what makes the watermark truthful
+        // when the branch drifts mid-review. A subsequent review resumes from
+        // reviewed_through_sha..tip. Aborted cycles never reach this branch, so their
+        // successor inherits the full unreviewed range.
+        //
+        // Coverage records ONLY what an inspection actually covered. An uninspected
+        // exit (reviewInspected === false) routed to verify_failed above (the blind
+        // gate) but its session inspected nothing -- so it covered nothing. Leaving
+        // the watermark UNCHANGED keeps that range eligible for a real review; the
+        // exit event is not itself coverage. This is the compounding half of the
+        // fail-open: without this guard an uninspected range would be marked covered
+        // and no future pass would revisit it.
+        if (reviewInspected === false) {
+            log.info(`[focus-executor] Review coverage watermark for "${focusName}" left unchanged -- ` +
+                `exit had no inspection evidence (an uninspected pass covers nothing; range stays eligible).`);
+        }
+        else if (coveredSha) {
+            try {
+                await deps.setReviewedThroughSha(focusId, coveredSha);
+                log.info(`[focus-executor] Review coverage watermark for "${focusName}" advanced to ` +
+                    `${coveredSha.slice(0, 12)} (covered by this review pass).`);
+            }
+            catch (err) {
+                log.warn(`[focus-executor] setReviewedThroughSha failed for "${focusName}": ${err.message}`);
+            }
+        }
+        else {
+            log.warn(`[focus-executor] Review routed for "${focusName}" but no covered SHA was ` +
+                `resolved -- coverage watermark left unchanged (successor will re-cover the full range).`);
+        }
+        // A routed completion means the drift streak (if any) is broken: either
+        // coverage was complete (auto-approve) or defects routed the delivery. Clear
+        // the per-focus below-coverage counter so a future drift starts fresh (this
+        // also writes the cleared budget through durably).
+        resetCoverageDriftState(focusId);
+        // Gate the hand-off counter's reset on a real DELTA: a routed cycle that
+        // changed nothing is the empty loop the cap must bound, not progress that
+        // rearms it. See review-exit-progress.ts.
+        await resolveReviewCycleProgress(deps, escalationCtx, {
+            coveredSha,
+            // Measure the delta against the watermark the PRIOR review pass left,
+            // carried from spawn (reviewPriorWatermark) so review_complete's same-txn
+            // promotion of the current spawn-tip into reviewed_through_sha (migration
+            // 20260909203246) cannot erase the value we compare against. Fall back to
+            // the focus-row read ONLY when the carry was lost (undefined -- a restart
+            // mid-review); a lost carry is no proof of advance either way.
+            priorReviewedSha: reviewPriorWatermark !== undefined
+                ? reviewPriorWatermark
+                : (current.reviewed_through_sha ?? null),
+            deliveryConverged: convergedAny,
+            issuesFiled: reviewCreatedIssueIds.length > 0,
+            currentHandoffCount: current.review_handoff_count ?? 0,
+            // The hand-off breaker measures ONLY review-pass exits; a coding exit that
+            // routed a self-heal must not climb the review cap.
+            sessionType,
+            openBlockingFindings,
+        });
+        // Review-cycle BUDGET (review-cycle-cap.ts): a converged review cycle resets the count; an unconverged one
+        // climbs it, and at the budget the armed run ENDS -- the focus is un-armed with a recorded reason, so only a
+        // new arm grants further cycles. A coding exit touches none of it. Best-effort.
+        await recordReviewCycleAndMaybeEndArm(deps, escalationCtx, current.review_cycle_count ?? 0, { convergedAny, anyReopenedToVerifyFailed, verdictHeldAny, openBlockingFindings, sessionType });
+        emitReviewCompleted(deps, escalationCtx, {
+            gapsWithoutIssue, reportExists, hasBlockingIssueEvidence, sessionType, succeeded, reviewInspected,
+        });
+    }
+    else if (verdictHeldAny || parkedAny || verdictFailed) {
+        // Ahead of the hand-off bound: a gate run or a verify re-judgement, not an incoming team, owns this wait.
+        if (verdictHeldAny)
+            logCommitVerdictHeldExit(focusName);
+        else if (parkedAny)
+            logShortfallParkedExit(focusName);
+    }
+    else if (deps.hasPendingSpawnDirective(focusId)) {
+        // Nothing routed AND a spawn directive is pending: the team was torn down
+        // to make room for an incoming team (e.g., the directive executor spawning
+        // a review team). Leaving review_requested_at set hands the routing off to
+        // that incoming team -- but that is an UNVERIFIED promise: when there is no
+        // work left to route, the incoming team also routes nothing and re-makes the
+        // same empty hand-off, and the branch fires again on identical premises.
+        // Nothing bounded it, so the loop respawned a team every ~10 min forever.
+        //
+        // Bound it (the equivalent of the shortfallHold branch's bounded tail): a
+        // durable per-focus counter increments on each routes-nothing hand-off; under
+        // the cap it hands off as before, at the cap it closes the review window and
+        // escalates instead of re-asserting. Extracted to review-exit-escalations.ts
+        // (the sibling escalation seam) so this file stays under the size limit.
+        //
+        // The counter advances ONLY for a review-pass exit (sessionType): a coding
+        // exit that routed nothing was never a review routing candidate, so counting
+        // it exhausted the cap without a review having failed (2026-08-27). The
+        // exhausted escalation enumerates the open blocking review-filed findings so
+        // it states what it measured instead of asserting the focus is done.
+        await recordHandoffAndMaybeTerminate(deps, escalationCtx, current.review_handoff_count ?? 0, {
+            sessionType,
+            openBlockingFindings,
+        });
+    }
+    else if (shortfallHold) {
+        // Nothing routed because the focus carries undisposed shortfalls. This is a
+        // DEMAND for disposition, not a wait: review_requested_at is left SET so the
+        // focus stays in the review window where the disposition pass and the stall
+        // detector can both see it.
+        //
+        // The bounded-attempt tail (a scoped disposition pass, then a
+        // shortfall_undisposed escalation) is the sibling issues' scope; this branch
+        // records the hold and leaves the window open for them.
+        log.info(`[focus-executor] "${focusName}" review exit held: ` +
+            `${describeShortfallHold(shortfall)}. review_requested_at left set; awaiting disposition.`);
+    }
+    else if (operatorHeldAny) {
+        // A delivery would have converged to done but is held by an open operator
+        // escalation. Leave review_requested_at SET so the focus stays in the review
+        // window and the next auto-review re-evaluates the hold. When the operator
+        // resolves/dismisses the escalation, resolveOperatorHold returns not-held on
+        // the next pass and the delivery auto-approves -- the machine closes it, no
+        // human touches the delivery. The escalation itself is the human-residue
+        // signal, so no additional escalation is filed here.
+        log.info(`[focus-executor] "${focusName}" review exit held: an operator escalation blocks a verify ` +
+            `delivery from done. review_requested_at left set; the hold clears itself when the escalation resolves.`);
+    }
+    else if (externalHeldAny || modelHeldAny) {
+        // A delivery would have converged to done but is held by an irreducibly-external
+        // dependency as gate_state STATE (not an escalation), or awaits its verify judge.
+        // Leave review_requested_at SET so the next auto-review re-evaluates the
+        // hold's condition; when reality changes and the condition re-reads true the
+        // hold clears itself and the delivery auto-approves -- no human, no inbox.
+        log.info(`[focus-executor] "${focusName}" review exit held: an external dependency (gate_state hold) ` +
+            `blocks a verify delivery from done. review_requested_at left set; the hold clears when its condition re-reads true.`);
+    }
+    else if (belowCoverageHold) {
+        // Pure drift: a clean review under-covered (spawn-tip != exit-tip) and no
+        // delivery routed. Record the coverage that DID happen (the review saw
+        // coveredSha), then bound the tail: arm exactly ONE full-pass re-review, and
+        // on a second consecutive drift escalate for an operator (one open per focus).
+        // review_requested_at is left SET so the next auto-review re-spawns.
+        if (coveredSha) {
+            try {
+                await deps.setReviewedThroughSha(focusId, coveredSha);
+            }
+            catch (err) {
+                log.warn(`setReviewedThroughSha (drift) failed for "${focusName}": ${err.message}`);
+            }
+        }
+        const streak = recordBelowCoverageDrift(focusId);
+        if (streak >= 2) {
+            // Drift persisted after the full-pass respawn -- an operator must look.
+            await fileCoverageIncompleteEscalation(deps, escalationCtx, {
+                coveredSha,
+                currentBranchTip: currentBranchTip ?? null,
+                streak,
+            });
+        }
+        else {
+            // First drift: arm ONE full-pass re-review (prior incremental coverage
+            // cannot be trusted when the branch moved under the reviewer).
+            forceFullPassReviewFocuses.add(focusId);
+            log.info(`[focus-executor] "${focusName}" below coverage (drift streak 1) -- armed a full-pass re-review.`);
+        }
+    }
+    else if (!reportExists && !hasIssueEvidence) {
+        // Strict gate: no routing happened AND no evidence. Warn-and-leave --
+        // the focus may simply be idle (no verify deliveries to route, no
+        // review report) or awaiting human handling. We deliberately no longer
+        // escalate here: an idle focus with no report is not a missing report,
+        // it's an idle focus. Recovery is via MCP clear-review-request.
+        const reason = sessionType !== 'review'
+            ? `${sessionType} team exited (not a review team)`
+            : !succeeded
+                ? 'review team did not succeed'
+                : 'no verify deliveries to route (clean review sessions auto-approve verify deliveries; this focus had none)';
+        log.warn(`[focus-executor] "${focusName}" has review_requested_at set but ${reason}; ` +
+            `phase remains 'reviewing' until a review team runs, work is queued, ` +
+            `or review_requested_at is cleared via MCP.`);
+    }
+    // The routing-inconsistency escalation: the review stamped gaps_found but
+    // filed no blocking actionable issue. The verdict already routed the delivery
+    // to verify_failed (above) -- toward intent, never toward done -- but the
+    // coding team has no concrete gap to close, so a human must reconcile the
+    // contradiction. Deduped one-open-per-focus, like the other review
+    // escalations. Distinct from review_missing_report (which fires only WITH
+    // blocking issue evidence); the two are mutually exclusive by construction.
+    if (routedAny && gapsWithoutIssue) {
+        await fileGapsWithoutIssueEscalation(deps, escalationCtx);
+    }
+    // Surface that a REVIEW skipped review_complete though the loop healed (a coding
+    // exit stamps no report; its notice would crowd a cap-held focus's observation).
+    // Only on BLOCKING evidence: a deferrable-notes-only review converged cleanly,
+    // so raising the notice there would be operator noise.
+    if (sessionType === 'review' && routedAny && !reportExists && hasBlockingIssueEvidence) {
+        await fileMissingReportNotice(deps, escalationCtx);
+    }
+    // Convergence sweep: when THIS cycle converged the focus -- a delivery reached
+    // done, nothing re-opened to verify_failed, no hold stands, and every delivery
+    // is now terminal -- the review-family / team_failure escalations describe a
+    // focus that could NOT converge, and it just did. Retire them auto_swept so a
+    // converged focus carries no pending operator rows (the 2026-09-10 stranded
+    // review-family rows and the 2026-09-09 team_failure-after-last-delivery row).
+    if (convergedAny && !anyReopenedToVerifyFailed && !operatorHeldAny &&
+        !externalHeldAny && !modelHeldAny && !shortfallHold && !belowCoverageHold && !verdictHeldAny && !verdictFailed &&
+        reviewDeliveries.every(d => d.executionStatus === DELIVERY_STATUS.DONE ||
+            d.executionStatus === DELIVERY_STATUS.CANCELLED ||
+            convergedDeliveryIds.has(d.id))) {
+        try {
+            await deps.resolveConvergedFocusEscalations(focusId, `Focus "${focusName}" converged (verify deliveries reached done, review approved, ` +
+                `session ${sessionId}); convergence-terminated escalations auto-swept.`);
+        }
+        catch (err) {
+            log.warn(`[focus-executor] resolveConvergedFocusEscalations failed for "${focusName}": ${err.message}`);
+        }
+    }
+}
+//# sourceMappingURL=review-exit-phase.js.map