@telora/daemon 0.17.36 → 0.17.42

package/dist/completion/team-completion.js

@@ -1,401 +1,44 @@
 /**
- * Focus team completion handling.
+ * Team completion -- explicit phase sequencer.
  *
- * Manages the post-execution lifecycle: advancing delivery statuses
- * based on issue completion, merging the focus branch, cleaning up
- * worktrees, and updating session records.
+ * "What happens when a team exits" reads from handleTeamCompletion below:
+ * an ordered sequence of named phases. The phase implementations live in
+ * focused modules, re-exported here so existing importers are unaffected:
+ *
+ *   - exit-classification.ts   classify exit (success / controlled stop / crash)
+ *   - merge-phase.ts           merge gate + focus->integration merge +
+ *                              merge-failure escalation + CI integration->main
+ *   - status-advance-phase.ts  delivery status advancement from issue completion
+ *   - review-exit-phase.ts     verify-delivery routing on review exit
+ *
+ * Phase order on team exit:
+ *   classify -> report git state -> read-only guard -> WIP preserve ->
+ *   status advance -> merge -> CI merge-to-main -> session finalize ->
+ *   review exit (escalate/handoff) -> terminate (cleanup + re-poll)
  */
-import { filterWorkIssues, filterContextGroups, ACTIVE_WORK_STATUSES, TERMINAL_ISSUE_STATUSES, planDeliveryCloseSweep } from '../constants.js';
-import { updateSession, reportGitState, getDeliveryIssues, getDeliverySessionCount, updateIssueStatus, fetchEffectiveWorkflow, updateDeliveryStatus, markDeliveryAutoApproved, getActiveFocuses, } from '../supabase.js';
-import { hasPendingSpawnDirective } from '../directive-executor.js';
-import { advanceDeliveryStage, ensureWorktreeCommittedBeforeAdvance } from '../delivery-lifecycle.js';
-import { withRetry, ESCALATION_REASONS, DELIVERY_STATUS } from '@telora/daemon-core';
-import { mergeFocusBranch, escalateMergeConflict } from '../focus-merge.js';
-import { mergeIntegrationToMain } from '../git-merge.js';
-import { resolveCiDecision } from '../pipeline-config.js';
-import { fileCdPushEscalation, shouldFileCdPushEscalation } from '../ci-escalation.js';
+import { updateSession, reportGitState } from '../supabase.js';
+import { withRetry, DELIVERY_STATUS } from '@telora/daemon-core';
 import { recordSessionCompleted } from '../agent-state.js';
 import { triggerCheck } from '../listener.js';
-import { emitLoopTrigger } from '../loop-event-bus.js';
 import { getActiveTeams } from '../focus-team-state.js';
 import { commitWipChanges, worktreeHasUncommittedChanges, branchHasUnmergedCommits, runGitSync } from '../git.js';
 import { computeGitDiffStats } from '../git-utils.js';
-import { getFocusDeliveries, getFocusIssues, clearReviewRequestedAt, getFocusReviewReportForSession, } from '../queries/focuses.js';
-import { createEscalation } from '../queries/issues.js';
-import { reviewFiledIssueExists } from '../review-defect-detector.js';
-// ── Stage classification (re-exported for consumers) ─────────────────
-import { isStatusAgentActionable } from '../stage-classifier.js';
+import { getFocusDeliveries } from '../queries/focuses.js';
+import { classifyTeamExit, deriveExitCategory } from './exit-classification.js';
+import { selectWorkedDeliveryIds, attemptFocusMerge, escalateFailedMergeDeliveries, runCiMergeToMain, } from './merge-phase.js';
+import { advanceDeliveryStatuses } from './status-advance-phase.js';
+import { runReviewExitHandler } from './review-exit-phase.js';
+// ── Re-exported public surface (callers unchanged) ───────────────────
 export { isStatusTerminal, isStatusAgentActionable } from '../stage-classifier.js';
-// ── Merge gate ───────────────────────────────────────────────────────
-/**
- * Decide whether to attempt mergeFocusBranch on team exit.
- *
- * The gate asks "does the branch have clean committed work?" rather than
- * "did the team session exit cleanly?" -- so a team that exits via review-
- * cycle SIGTERM, role-clear, daemon crash, or manual termination still gets
- * its committed work propagated to integration.
- *
- * Skip merge when:
- * - The team is still in its planning phase (cancellation mid-planning --
- *   nothing scoped, nothing to merge), OR
- * - The team is a read-only audit session (read-only violation; commits, if
- *   any, are surfaced separately by the existing readOnly guard), OR
- * - The branch has no committed work ahead of integration (clean exit with
- *   no commits, e.g. audit team or planning-only team).
- *
- * Exported for unit testing the gate logic in isolation.
- */
-export function shouldAttemptMerge(teamState, branchHasCommits) {
-    if (teamState.planningPhase)
-        return false;
-    if (teamState.readOnly)
-        return false;
-    return branchHasCommits;
-}
-/**
- * Statuses for deliveries whose git state should be reported on team
- * completion. Includes 'done' so a focus whose deliveries all reached done
- * before the branch was merged (review SIGTERM, role-clear, deferred merge,
- * etc.) still attempts the merge instead of being short-circuited as
- * "no worked deliveries". Excludes 'queued'/'planning'/'paused'/'cancelled'
- * — those represent work that never started or was abandoned.
- *
- * Exported for unit testing.
- */
-export const REPORTABLE_DELIVERY_STATUSES = new Set([
-    'coding',
-    'verify',
-    'done',
-]);
-/**
- * Filter delivery list to those whose git state should be reported on team
- * completion. Excludes already-merged deliveries so we don't re-report them.
- *
- * Exported for unit testing the filter logic without invoking handleTeamCompletion.
- */
-export function selectWorkedDeliveryIds(deliveries, alreadyMerged) {
-    return deliveries
-        .filter(d => REPORTABLE_DELIVERY_STATUSES.has(d.executionStatus ?? '') && !alreadyMerged.has(d.id))
-        .map(d => d.id);
-}
-/**
- * Decide whether to merge the focus branch and, if so, run the merge.
- *
- * This is the integration of three separate concerns that the merge gate
- * conflated before:
- *   1. Branch state: does the focus branch actually have committed work?
- *   2. Team gate: planningPhase + readOnly safety nets in shouldAttemptMerge.
- *   3. Per-delivery telemetry: workedDeliveryIds is passed through for
- *      git-state reporting inside mergeFocusBranch.
- *
- * Returns attempted=false when the gate skips the merge (clean exit with
- * nothing to merge, planning-phase, or read-only). Returns attempted=true
- * with the merge result otherwise.
- *
- * Exported so tests can verify the threading from done-only deliveries +
- * branch-with-commits to a real mergeFocusBranch invocation, without having
- * to mock all of handleTeamCompletion's other side effects.
- */
-export async function attemptFocusMerge(config, teamState, sessionId, workedDeliveryIds, deps = {
-    branchHasUnmergedCommits,
-    mergeFocusBranch,
-}) {
-    const branchHasCommits = deps.branchHasUnmergedCommits(teamState.branchName, config.integrationBranch, config.repoPath);
-    if (!shouldAttemptMerge(teamState, branchHasCommits)) {
-        return { attempted: false, mergeSucceeded: false, exitReason: null };
-    }
-    const mergeResult = await deps.mergeFocusBranch(config, teamState, sessionId, teamState.branchName, workedDeliveryIds);
-    return {
-        attempted: true,
-        mergeSucceeded: mergeResult.mergeSucceeded,
-        exitReason: mergeResult.exitReason ?? null,
-    };
-}
-const defaultReviewExitDeps = {
-    getActiveFocuses,
-    getFocusDeliveries,
-    getFocusIssues,
-    getDeliveryIssues,
-    fetchEffectiveWorkflow,
-    updateDeliveryStatus,
-    markDeliveryAutoApproved,
-    clearReviewRequestedAt,
-    hasPendingSpawnDirective,
-    emitLoopTrigger,
-    getFocusReviewReportForSession,
-    createEscalation,
-};
-/**
- * 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.
- *
- * Exported with injectable deps for unit testing.
- */
-export async function runReviewExitHandler(params, deps = defaultReviewExitDeps) {
-    const { focusId, focusName, organizationId, productId, sessionId, sessionType, succeeded } = params;
-    const focuses = await deps.getActiveFocuses(organizationId, productId);
-    const current = focuses.find(s => s.focus_id === focusId);
-    if (!current?.review_requested_at) {
-        // Nothing review-related to do.
-        return;
-    }
-    const reviewRequestedAt = current.review_requested_at;
-    // 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 ──────────────────────────────────────────────
-    let reportExists = false;
-    try {
-        const report = await deps.getFocusReviewReportForSession(focusId, sessionId);
-        reportExists = report.exists;
-    }
-    catch (err) {
-        console.warn(`[focus-executor] getFocusReviewReportForSession failed for "${focusName}" session ${sessionId}: ${err.message}`);
-        // Treat read failure the same as missing.
-    }
-    let hasIssueEvidence = false;
-    try {
-        const focusIssues = await deps.getFocusIssues(focusId);
-        hasIssueEvidence = reviewFiledIssueExists(focusIssues, reviewRequestedAt);
-    }
-    catch (err) {
-        console.warn(`[focus-executor] getFocusIssues failed for "${focusName}": ${err.message}`);
-        // Treat read failure as no evidence -- only affects the warn-and-leave
-        // message and the issue-evidence notice; routing runs regardless.
-    }
-    // ── 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);
-    let routedAny = false;
-    for (const d of reviewDeliveries) {
-        if (d.executionStatus !== DELIVERY_STATUS.VERIFY)
-            continue;
-        try {
-            const [issues, dWorkflow] = await Promise.all([
-                deps.getDeliveryIssues(d.id),
-                deps.fetchEffectiveWorkflow(d.id),
-            ]);
-            const workIssues = filterWorkIssues(issues);
-            const openWork = workIssues.filter(i => ACTIVE_WORK_STATUSES.has(i.status));
-            if (openWork.length > 0) {
-                const awaitingVerifyStage = dWorkflow.stages.find(s => s.name === 'verify_failed');
-                await deps.updateDeliveryStatus(d.id, 'verify_failed', awaitingVerifyStage?.id ?? null, undefined, undefined, { organizationId, fromStatus: 'verify' });
-                console.log(`[focus-executor] Delivery "${d.name}" moved from verify to verify_failed: ${openWork.length} open issue(s)`);
-                routedAny = true;
-            }
-            else if (reportExists) {
-                const doneStage = dWorkflow.stages.find(s => s.name === 'done');
-                await deps.updateDeliveryStatus(d.id, 'done', doneStage?.id ?? null, undefined, undefined, { organizationId, fromStatus: 'verify' });
-                console.log(`[focus-executor] Delivery "${d.name}" moved from verify to done (review passed)`);
-                routedAny = true;
-            }
-            else if (sessionType === 'review' && succeeded) {
-                // Clean review session: review agent exited without filing defects
-                // and without writing a focus_reviews row. Per the auto-approve-
-                // with-visibility direction (memory/feedback_auto_approve_with_visibility),
-                // promote verify -> done and tag the delivery with auto-approval
-                // metadata so the (later) dashboard/MCP unapprove path can surface
-                // it for human reversal. Reversible by construction.
-                const doneStage = dWorkflow.stages.find(s => s.name === 'done');
-                await deps.markDeliveryAutoApproved(d.id, sessionId, doneStage?.id ?? null);
-                console.log(`[focus-executor] Delivery "${d.name}" auto-approved verify -> done ` +
-                    `(clean review session ${sessionId.slice(0, 8)}, no defects filed)`);
-                routedAny = true;
-            }
-            else {
-                // Non-review session exit, or review session that didn't succeed --
-                // no signal to auto-approve. Leave in verify; the next state-cascade
-                // poll will re-trigger auto-review via checkAutoReview.
-                const reason = sessionType !== 'review'
-                    ? `${sessionType} session exited (not eligible for auto-approve)`
-                    : 'review session did not succeed';
-                console.log(`[focus-executor] Delivery "${d.name}" left in verify: ${reason} ` +
-                    `(verify-cycling; next auto-review poll will re-trigger).`);
-            }
-        }
-        catch (err) {
-            console.warn(`[focus-executor] Failed to route delivery "${d.name}" after review: ${err.message}`);
-        }
-    }
-    if (routedAny) {
-        await deps.clearReviewRequestedAt(focusId);
-        console.log(`[focus-executor] Review complete for "${focusName}" -- review_requested_at cleared ` +
-            `(reportExists=${reportExists}, issueEvidence=${hasIssueEvidence})`);
-        const routeVia = reportExists
-            ? 'report'
-            : hasIssueEvidence
-                ? 'issue-evidence'
-                : sessionType === 'review' && succeeded
-                    ? 'auto-approve'
-                    : 'open-work';
-        deps.emitLoopTrigger({
-            type: 'review_completed',
-            focusId,
-            detail: `review complete -- "${focusName}" routed via ${routeVia}`,
-        });
-    }
-    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). Leave review_requested_at set so the incoming team's exit
-        // performs the routing. This is the ONLY case the pending-spawn signal
-        // gates -- it never blocks the finalization above.
-        console.log(`[focus-executor] "${focusName}" review exit routed nothing and a spawn directive ` +
-            `is pending -- leaving review_requested_at set for the incoming team.`);
-    }
-    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)';
-        console.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.`);
-    }
-    // Surface that the agent skipped review_complete even though the loop healed.
-    // Only fire when we actually routed something via issue evidence; otherwise
-    // the notice misleads (it claims the loop continued when nothing moved).
-    if (routedAny && !reportExists && hasIssueEvidence) {
-        try {
-            await deps.createEscalation({
-                organizationId,
-                sessionId,
-                issueId: null,
-                reasonType: ESCALATION_REASONS.BLOCKED_BY_EXTERNAL,
-                description: 'Review session filed issues but did not call focus_review_complete. ' +
-                    'Deliveries routed via issue evidence; review_requested_at cleared. ' +
-                    'Tighten the review directive so the agent always stamps an outcome.',
-                escalationKind: 'review_missing_report',
-                metadata: { focus_id: focusId, session_id: sessionId, routed_via: 'issue_evidence' },
-            });
-        }
-        catch (err) {
-            console.warn(`[focus-executor] createEscalation (issue-evidence notice) failed for "${focusName}": ${err.message}`);
-        }
-    }
-}
-/**
- * Classify how a team lead process exited.
- *
- * Pure and side-effect free so the "lifecycle SIGTERM is not a review failure"
- * invariant is unit-testable in isolation. The crux: when the daemon proactively
- * terminates a team because its work is complete, it sets phase='shutting_down'
- * and shutdownReason='work_complete' BEFORE sending SIGTERM. We detect that
- * teardown and classify it as succeeded -- otherwise a clean review team
- * (which commits nothing of its own, then gets SIGTERMed once all deliveries
- * are terminal) would look like a failed exit and its verify delivery would be
- * stranded in `verify` instead of auto-approved to `done`.
- */
-export function classifyTeamExit(params) {
-    const exitCode = params.code ?? 1;
-    const wasSigterm = params.signal === 'SIGTERM' || exitCode === 143;
-    const proactivelyTerminated = params.teamPhase === 'shutting_down' &&
-        wasSigterm &&
-        params.shutdownReason === 'work_complete';
-    const succeeded = exitCode === 0 || proactivelyTerminated;
-    // A controlled stop is any SIGTERM the daemon sent while the team was already
-    // shutting down -- regardless of reason. It is the signal that distinguishes
-    // a deliberate daemon teardown from a crash, without touching `succeeded`.
-    const controlledStop = params.teamPhase === 'shutting_down' && wasSigterm;
-    const disposition = succeeded ? 'completed' : controlledStop ? 'stopped' : 'failed';
-    return { exitCode, wasSigterm, proactivelyTerminated, succeeded, controlledStop, disposition };
-}
-/**
- * Derive the `exit_category` to record alongside the session status, given the
- * classifier disposition and the team's shutdown reason.
- *
- * - 'completed' -> 'work_complete' when the daemon stopped the team because its
- *   work was done; otherwise null (a plain clean self-exit has no category).
- * - 'stopped'   -> the specific controlled-stop reason; any unknown/null reason
- *   falls back to 'handoff' (a benign daemon-initiated respawn).
- * - 'failed'    -> 'error' (genuine crash / unexpected exit).
- */
-export function deriveExitCategory(disposition, shutdownReason) {
-    switch (disposition) {
-        case 'completed':
-            return shutdownReason === 'work_complete' ? 'work_complete' : null;
-        case 'stopped':
-            switch (shutdownReason) {
-                case 'deactivated': return 'deactivated';
-                case 'user_stopped': return 'user_stopped';
-                case 'handoff': return 'handoff';
-                case 'teardown': return 'teardown';
-                default: return 'handoff';
-            }
-        case 'failed':
-            return 'error';
-    }
-}
-/**
- * Handle the team lead process exiting.
- *
- * Responsibilities:
- * - Report git state for all known deliveries
- * - Advance delivery statuses based on issue completion
- * - Merge focus branch to integration (if successful)
- * - Clean up worktree
- * - Update session record
- * - Record heartbeat counters
- * - Trigger re-poll for next work
- */
-export async function handleTeamCompletion(params) {
-    const { config, teamState, sessionId, code, signal } = params;
-    const { focusId, focusName, organizationId, branchName } = teamState;
-    const worktreePath = teamState.worktreePath;
-    // Classify the exit. A lifecycle teardown (shutdownReason='work_complete')
-    // SIGTERM is treated as a success, NOT a review failure -- see classifyTeamExit.
-    const { exitCode, proactivelyTerminated, succeeded, controlledStop, disposition } = classifyTeamExit({
-        code,
-        signal,
-        teamPhase: teamState.phase,
-        shutdownReason: teamState.shutdownReason,
-    });
-    let exitReason = exitCode === 0
+export { classifyTeamExit, deriveExitCategory, } from './exit-classification.js';
+export { shouldAttemptMerge, REPORTABLE_DELIVERY_STATUSES, selectWorkedDeliveryIds, attemptFocusMerge, escalateFailedMergeDeliveries, runCiMergeToMain, } from './merge-phase.js';
+export { advanceDeliveryStatuses, } from './status-advance-phase.js';
+export { runReviewExitHandler, } from './review-exit-phase.js';
+// ── Phase helpers ─────────────────────────────────────────────────────
+/** Build the initial exit reason from the exit classification. */
+function buildInitialExitReason(teamState, classification, signal) {
+    const { exitCode, proactivelyTerminated, succeeded, controlledStop } = classification;
+    return exitCode === 0
         ? 'Focus team completed.'
         : proactivelyTerminated
             ? teamState.mergedDeliveryIds.size > 0
@@ -408,16 +51,20 @@ export async function handleTeamCompletion(params) {
                 : signal
                     ? `Team lead terminated by signal: ${signal}`
                     : `Team lead exited with code: ${exitCode}`;
-    // Fetch fresh delivery list to include mid-flight additions
-    let allDeliveries;
+}
+/**
+ * Fetch the fresh delivery list (to include mid-flight additions), falling
+ * back to a synthesized list from knownDeliveryIds on read failure.
+ */
+async function fetchDeliveriesForCompletion(teamState) {
     try {
-        allDeliveries = await getFocusDeliveries(focusId);
+        return await getFocusDeliveries(teamState.focusId);
     }
     catch (err) {
         console.warn(`[focus-executor] Failed to fetch deliveries for gitState reporting, falling back to knownDeliveryIds:`, err.message);
         // Empty knownDeliveryIds (planning teams that exited without scoping) yields
         // an empty fallback array -- subsequent loops are intentional no-ops.
-        allDeliveries = [...teamState.knownDeliveryIds].map(id => ({
+        return [...teamState.knownDeliveryIds].map(id => ({
             id, name: '', description: null, priorityRank: 0,
             executionStatus: DELIVERY_STATUS.CODING, acceptanceCriteria: null,
             techContext: null, currentWorkflowStageId: null,
@@ -427,6 +74,85 @@ export async function handleTeamCompletion(params) {
             updatedAt: null,
         }));
     }
+}
+/**
+ * Read-only audit safety net: revert any uncommitted modifications, and if
+ * the agent somehow committed despite the pre-commit hook, mark the session
+ * failed and tear the team down WITHOUT merging.
+ *
+ * Returns true when the completion flow must abort (violation handled).
+ */
+async function runReadOnlyGuardPhase(config, teamState, sessionId) {
+    if (!teamState.readOnly)
+        return false;
+    const { focusId, focusName, branchName } = teamState;
+    const worktreePath = teamState.worktreePath;
+    // Revert any uncommitted changes
+    const hasChanges = worktreeHasUncommittedChanges(worktreePath);
+    if (hasChanges) {
+        console.warn(`[focus-executor] Read-only audit "${focusName}" left uncommitted changes. Reverting.`);
+        runGitSync(['checkout', '.'], worktreePath);
+        runGitSync(['clean', '-fd'], worktreePath);
+    }
+    // Check if the agent somehow committed (bypassed hook)
+    if (branchHasUnmergedCommits(branchName, config.integrationBranch, config.repoPath)) {
+        console.error(`[focus-executor] READ-ONLY VIOLATION: Audit "${focusName}" has commits on ${branchName}. ` +
+            `These will NOT be merged. Manual review required.`);
+        const exitReason = `Read-only audit violation: commits detected on ${branchName}. Merge skipped.`;
+        // Update session as failed due to read-only violation
+        try {
+            await withRetry(() => updateSession(sessionId, {
+                status: 'failed',
+                exit_reason: exitReason,
+                exit_category: 'error',
+                ended_at: new Date().toISOString(),
+            }), { maxAttempts: 3, baseDelayMs: 1000, label: 'session-update-readonly-violation' });
+        }
+        catch (err) {
+            console.warn(`[focus-executor] Failed to update session after retries:`, err.message);
+        }
+        // Record heartbeat and clean up
+        recordSessionCompleted(0, 0);
+        const activeTeams = getActiveTeams();
+        teamState.phase = 'terminated';
+        activeTeams.delete(focusId);
+        return true;
+    }
+    return false;
+}
+// ── The phase sequencer ───────────────────────────────────────────────
+/**
+ * Handle the team lead process exiting.
+ *
+ * Responsibilities (in phase order):
+ * - Classify the exit (lifecycle teardown vs crash -- see classifyTeamExit)
+ * - Report git state for all known deliveries
+ * - Read-only audit guard (revert / block merge on violation)
+ * - Preserve WIP commits on unclean exits
+ * - Advance delivery statuses based on issue completion
+ * - Merge focus branch to integration + escalate per-delivery merge failures
+ * - CI: merge integration -> main (CD optionally pushes)
+ * - Finalize the session record (status, exit reason, diff stats)
+ * - Review exit routing (escalate / handoff -- see runReviewExitHandler)
+ * - Terminate: heartbeat, team-state cleanup, re-poll trigger
+ */
+export async function handleTeamCompletion(params) {
+    const { config, teamState, sessionId, code, signal } = params;
+    const { focusId, focusName, branchName } = teamState;
+    const worktreePath = teamState.worktreePath;
+    // ── Phase: classify exit ────────────────────────────────────────────
+    // A lifecycle teardown (shutdownReason='work_complete') SIGTERM is treated
+    // as a success, NOT a review failure -- see classifyTeamExit.
+    const classification = classifyTeamExit({
+        code,
+        signal,
+        teamPhase: teamState.phase,
+        shutdownReason: teamState.shutdownReason,
+    });
+    const { succeeded, disposition } = classification;
+    let exitReason = buildInitialExitReason(teamState, classification, signal);
+    // ── Phase: report git state ─────────────────────────────────────────
+    const allDeliveries = await fetchDeliveriesForCompletion(teamState);
     // Report git state for deliveries the team plausibly worked on or finished.
     // See REPORTABLE_DELIVERY_STATUSES — including 'done' ensures focuses whose
     // deliveries all reached done before the team exit still attempt the merge.
@@ -435,42 +161,11 @@ export async function handleTeamCompletion(params) {
     for (const deliveryId of workedDeliveryIds) {
         reportGitState(deliveryId, 'worktree_complete').catch(err => console.warn(`[focus-executor] reportGitState worktree_complete failed for ${deliveryId}:`, err.message));
     }
-    // ── Read-only audit safety net ──────────────────────────────────
-    // If this was a read-only session, revert any file modifications and
-    // block merging if the agent somehow committed despite the pre-commit hook.
-    if (teamState.readOnly) {
-        // Revert any uncommitted changes
-        const hasChanges = worktreeHasUncommittedChanges(worktreePath);
-        if (hasChanges) {
-            console.warn(`[focus-executor] Read-only audit "${focusName}" left uncommitted changes. Reverting.`);
-            runGitSync(['checkout', '.'], worktreePath);
-            runGitSync(['clean', '-fd'], worktreePath);
-        }
-        // Check if the agent somehow committed (bypassed hook)
-        if (branchHasUnmergedCommits(branchName, config.integrationBranch, config.repoPath)) {
-            console.error(`[focus-executor] READ-ONLY VIOLATION: Audit "${focusName}" has commits on ${branchName}. ` +
-                `These will NOT be merged. Manual review required.`);
-            exitReason = `Read-only audit violation: commits detected on ${branchName}. Merge skipped.`;
-            // Update session as failed due to read-only violation
-            try {
-                await withRetry(() => updateSession(sessionId, {
-                    status: 'failed',
-                    exit_reason: exitReason,
-                    exit_category: 'error',
-                    ended_at: new Date().toISOString(),
-                }), { maxAttempts: 3, baseDelayMs: 1000, label: 'session-update-readonly-violation' });
-            }
-            catch (err) {
-                console.warn(`[focus-executor] Failed to update session after retries:`, err.message);
-            }
-            // Record heartbeat and clean up
-            recordSessionCompleted(0, 0);
-            const activeTeams = getActiveTeams();
-            teamState.phase = 'terminated';
-            activeTeams.delete(focusId);
-            return;
-        }
+    // ── Phase: read-only guard ──────────────────────────────────────────
+    if (await runReadOnlyGuardPhase(config, teamState, sessionId)) {
+        return;
     }
+    // ── Phase: WIP preserve ─────────────────────────────────────────────
     // Commit any uncommitted WIP changes left by the agent (crash, kill, timeout).
     // Only needed when the agent didn't exit cleanly — a clean exit means the
     // agent committed its own work.
@@ -482,10 +177,12 @@ export async function handleTeamCompletion(params) {
             console.warn(`[focus-executor] WIP commit failed for "${focusName}": ${err.message}`);
         }
     }
+    // ── Phase: status advance ───────────────────────────────────────────
     // Advance delivery statuses based on issue completion
     if (succeeded) {
         await advanceDeliveryStatuses(config, teamState, sessionId);
     }
+    // ── Phase: merge ────────────────────────────────────────────────────
     // Merge focus branch to integration if the branch has committed work.
     // Decoupled from team-exit success: a team that exits via review SIGTERM,
     // role-clear, daemon crash, or manual termination still gets its committed
@@ -509,93 +206,26 @@ export async function handleTeamCompletion(params) {
     }
     // Escalate merge failure for worked deliveries only
     if (mergeAttempt.attempted && !mergeSucceeded) {
-        for (const deliveryId of workedDeliveryIds) {
-            if (!teamState.mergedDeliveryIds.has(deliveryId)) {
-                escalateMergeConflict({
-                    organizationId,
-                    sessionId,
-                    deliveryId,
-                    deliveryName: focusName,
-                    branchName,
-                    integrationBranch: config.integrationBranch,
-                    mergeError: mergeAttempt.exitReason ?? 'unknown',
-                }).catch(err => console.warn(`[focus-executor] escalateMergeConflict failed for ${deliveryId}:`, err.message));
-            }
-        }
-    }
-    // ── CI: merge integration → main ──────────────────────────────
-    // When CI is enabled (default for legacy focuses without the field),
-    // always attempt the integration→main merge at team exit. This is the
-    // unconditional backstop: the eager path in focus-team-lifecycle fires
-    // when a focus drains mid-flight, but if it didn't (or fired and
-    // integration has since moved), the exit path closes the gap.
-    // Independent of mergeSucceeded — even when this focus had no new
-    // commits, past focuses may have left integration ahead of main.
-    // mergeIntegrationToMain no-ops cleanly when integration is already
-    // at main. CD additionally pushes.
-    const ciDecision = resolveCiDecision(teamState.pipelineConfig);
-    if (!ciDecision.shouldMerge) {
-        console.log(`[CI] Skipping integration→main merge for focus ${teamState.focusId} ("${focusName}"): ci.enabled=false`);
-        exitReason += ' CI skipped (ci.enabled=false).';
-    }
-    else {
-        const { pushToRemote, mergeStrategy } = ciDecision;
-        const ciLabel = pushToRemote ? 'CI+CD' : 'CI';
-        console.log(`[${ciLabel}] Merging integration to main for "${focusName}" (strategy=${mergeStrategy})${pushToRemote ? ' (will push to remote)' : ''}`);
-        try {
-            const ciResult = await mergeIntegrationToMain({
-                config,
-                focusId: teamState.focusId,
-                focusName,
-                pushToRemote,
-                mergeStrategy,
-            });
-            if (ciResult.success) {
-                if (ciResult.pushedTo) {
-                    console.log(`[${ciLabel}] Pushed main to ${ciResult.pushedTo.name} (${ciResult.pushedTo.url}) for focus ${teamState.focusId} ("${focusName}")`);
-                }
-                else {
-                    console.log(`[${ciLabel}] Successfully merged integration to main for focus ${teamState.focusId} ("${focusName}")`);
-                }
-                // Report merged_to_main / pushed_to_remote for every delivery on
-                // integration. That's mid-flight-merged deliveries plus, if this
-                // exit's focus→integration merge succeeded, the just-merged ones.
-                // Failed focus merges leave workedDeliveryIds off integration —
-                // exclude them so we don't lie about where they landed.
-                const onIntegration = new Set(teamState.mergedDeliveryIds);
-                if (mergeSucceeded) {
-                    for (const id of workedDeliveryIds)
-                        onIntegration.add(id);
-                }
-                const newState = ciResult.pushedTo ? 'pushed_to_remote' : 'merged_to_main';
-                for (const deliveryId of onIntegration) {
-                    reportGitState(deliveryId, newState).catch(err => console.warn(`[${ciLabel}] reportGitState ${newState} failed for ${deliveryId}:`, err.message));
-                }
-                exitReason += ` ${ciLabel}: merged to main${ciResult.pushedTo ? ' and pushed to remote' : ''}.`;
-            }
-            else {
-                console.error(`[${ciLabel}] Failed to merge integration to main for "${focusName}": ${ciResult.error}`);
-                exitReason += ` ${ciLabel} failed: ${ciResult.error}`;
-                if (shouldFileCdPushEscalation(pushToRemote, ciResult)) {
-                    await fileCdPushEscalation({
-                        organizationId: teamState.organizationId,
-                        sessionId,
-                        focusId: teamState.focusId,
-                        focusName,
-                        integrationBranch: config.integrationBranch,
-                        pushError: ciResult.error,
-                    });
-                }
-            }
-        }
-        catch (err) {
-            console.error(`[${ciLabel}] Error merging integration to main for "${focusName}":`, err.message);
-            exitReason += ` ${ciLabel} error: ${err.message}`;
-        }
+        escalateFailedMergeDeliveries({
+            config,
+            teamState,
+            sessionId,
+            workedDeliveryIds,
+            mergeExitReason: mergeAttempt.exitReason,
+        });
     }
+    // ── Phase: CI merge-to-main ─────────────────────────────────────────
+    exitReason += await runCiMergeToMain({
+        config,
+        teamState,
+        sessionId,
+        mergeSucceeded,
+        workedDeliveryIds,
+    });
     // Worktree is focus-owned — do NOT remove on team completion.
     // It persists for the next team session or QA use.
     // Removal only happens via coordinated teardown when focus is deactivated.
+    // ── Phase: session finalize ─────────────────────────────────────────
     // Compute git diff stats from all commits on this branch since integration
     let diffStats = { linesAdded: 0, linesRemoved: 0 };
     try {
@@ -622,12 +252,13 @@ export async function handleTeamCompletion(params) {
     catch (err) {
         console.warn(`[focus-executor] Failed to update session after retries:`, err.message);
     }
-    // Review exit handler: see runReviewExitHandler below for the rules.
+    // ── Phase: review exit (escalate / handoff) ─────────────────────────
+    // See runReviewExitHandler for the routing rules.
     try {
         await runReviewExitHandler({
             focusId,
             focusName,
-            organizationId,
+            organizationId: teamState.organizationId,
             productId: teamState.productId,
             sessionId,
             sessionType: teamState.sessionType,
@@ -637,6 +268,7 @@ export async function handleTeamCompletion(params) {
     catch (err) {
         console.warn(`[focus-executor] Review exit handler failed for "${focusName}":`, err.message);
     }
+    // ── Phase: terminate ────────────────────────────────────────────────
     // Record heartbeat
     recordSessionCompleted(0, 0);
     // Clean up team state
@@ -649,167 +281,4 @@ export async function handleTeamCompletion(params) {
     }
     console.log(`[focus-executor] Team for "${focusName}" cleaned up (merge: ${mergeSucceeded ? 'yes' : 'no'})`);
 }
-const defaultDeps = {
-    getFocusDeliveries,
-    getDeliveryIssues,
-    getDeliverySessionCount,
-    updateIssueStatus,
-    fetchEffectiveWorkflow,
-    updateDeliveryStatus,
-    advanceDeliveryStage,
-};
-/**
- * Advance delivery statuses after team completion.
- *
- * Re-queries all deliveries for the focus from the database rather
- * than relying on the spawn-time snapshot in teamState.knownDeliveryIds.
- * This ensures deliveries added mid-flight (after the team was spawned)
- * are discovered and advanced, and that stale deliveryStageIds don't
- * cause deliveries to be skipped.
- *
- * For each delivery in 'coding' status:
- * - All issues Done (or no issues): advance via workflow (coding -> verify -> done)
- * - Open issues remain: re-queue to 'queued' so the next team session picks it up
- */
-export async function advanceDeliveryStatuses(config, teamState, sessionId, deps = defaultDeps) {
-    // Re-query deliveries fresh from the DB to discover mid-flight additions
-    let deliveries;
-    try {
-        deliveries = await deps.getFocusDeliveries(teamState.focusId);
-    }
-    catch (err) {
-        console.warn(`[focus-executor] Failed to fetch deliveries for focus ${teamState.focusId}:`, err.message);
-        return;
-    }
-    for (const delivery of deliveries) {
-        // Skip deliveries that were already merged mid-flight
-        if (teamState.mergedDeliveryIds.has(delivery.id)) {
-            continue;
-        }
-        // Only advance deliveries in agent-actionable status.
-        if (!isStatusAgentActionable(delivery.executionStatus ?? '')) {
-            continue;
-        }
-        try {
-            const [issues, sessionCount, workflow] = await Promise.all([
-                deps.getDeliveryIssues(delivery.id),
-                deps.getDeliverySessionCount(delivery.id),
-                deps.fetchEffectiveWorkflow(delivery.id),
-            ]);
-            // Context Groups are reference material, not actionable work — exclude from open count
-            const workIssues = filterWorkIssues(issues);
-            const contextGroups = filterContextGroups(issues);
-            const openCount = workIssues.filter(i => !TERMINAL_ISSUE_STATUSES.has(i.status)).length;
-            const totalWork = workIssues.length;
-            // Use currentWorkflowStageId from the fresh query, falling back to
-            // the teamState cache for deliveries known at spawn time
-            const currentStageId = delivery.currentWorkflowStageId
-                ?? teamState.deliveryStageIds.get(delivery.id)
-                ?? null;
-            if (!currentStageId) {
-                console.warn(`[focus-executor] Delivery ${delivery.id}: no workflow stage ID, skipping advance`);
-                continue;
-            }
-            // Re-queue deliveries with open work issues so the next team picks them up
-            if (totalWork > 0 && openCount > 0) {
-                // Already queued — leave it there
-                if (delivery.executionStatus === DELIVERY_STATUS.QUEUED) {
-                    continue;
-                }
-                const queuedStage = workflow.stages.find(s => s.name === 'queued');
-                if (queuedStage) {
-                    console.log(`[focus-executor] Delivery ${delivery.id}: ${openCount}/${totalWork} work issues still open, re-queuing`);
-                    await deps.updateDeliveryStatus(delivery.id, 'queued', queuedStage.id, undefined, undefined, { organizationId: teamState.organizationId, fromStatus: delivery.executionStatus });
-                    teamState.deliveryStageIds.set(delivery.id, queuedStage.id);
-                }
-                else {
-                    console.warn(`[focus-executor] Delivery ${delivery.id}: ${openCount}/${totalWork} work issues still open, no queued stage in workflow — leaving in ${delivery.executionStatus}`);
-                }
-                continue;
-            }
-            // Auto-close Context Groups when all work issues are done
-            for (const cg of contextGroups) {
-                if (cg.status !== 'Done') {
-                    try {
-                        await deps.updateIssueStatus(cg.id, 'Done');
-                        console.log(`[focus-executor] Auto-closed Context Group "${cg.title}" (all work issues done)`);
-                    }
-                    catch (err) {
-                        console.warn(`[focus-executor] Failed to auto-close Context Group "${cg.title}":`, err.message);
-                    }
-                }
-            }
-            // Sweep Verified and In Review issues to Done before advancing.
-            // 'Verified': review agent confirmed the fix but used Verified instead of Done.
-            // 'In Review': dev signalled completion; no review agent ran before close.
-            // Both collapse to Done for a clean terminal record.
-            const sweepIds = planDeliveryCloseSweep(workIssues);
-            for (const issueId of sweepIds) {
-                try {
-                    await deps.updateIssueStatus(issueId, 'Done');
-                    console.log(`[focus-executor] Swept issue ${issueId} to Done before delivery advance`);
-                }
-                catch (err) {
-                    console.warn(`[focus-executor] Failed to sweep issue ${issueId} to Done:`, err.message);
-                }
-            }
-            // If delivery is queued or verify_failed, step through coding first
-            // (workflow doesn't allow queued/verify_failed -> verify directly).
-            // Update the stage ID for the subsequent advance call.
-            let effectiveStageId = currentStageId;
-            // from_status fed to the subsequent advanceDeliveryStage call: defaults to
-            // the delivery's current status, but becomes 'coding' once we step there.
-            let effectiveFromStatus = delivery.executionStatus ?? null;
-            if (delivery.executionStatus === DELIVERY_STATUS.QUEUED || delivery.executionStatus === DELIVERY_STATUS.VERIFY_FAILED) {
-                const codingStage = workflow.stages.find(s => s.name === 'coding');
-                if (codingStage) {
-                    console.log(`[focus-executor] Delivery ${delivery.id}: stepping ${delivery.executionStatus} -> coding before verify advance`);
-                    await deps.updateDeliveryStatus(delivery.id, 'coding', codingStage.id, undefined, undefined, { organizationId: teamState.organizationId, fromStatus: delivery.executionStatus });
-                    effectiveStageId = codingStage.id;
-                    effectiveFromStatus = 'coding';
-                }
-            }
-            console.log(`[focus-executor] Delivery ${delivery.id}: ${totalWork === 0 ? 'no issues' : `all ${totalWork} work issues done`}, advancing via workflow`);
-            const precheck = await ensureWorktreeCommittedBeforeAdvance({
-                deliveryId: delivery.id,
-                deliveryName: delivery.name,
-                focusId: teamState.focusId,
-                organizationId: teamState.organizationId,
-                sessionId,
-            });
-            if (!precheck.ok) {
-                console.log(`[focus-executor] Delivery ${delivery.id}: skip advance -- ${precheck.reason}`);
-                continue;
-            }
-            const result = await deps.advanceDeliveryStage({
-                deliveryId: delivery.id,
-                deliveryName: delivery.name,
-                organizationId: teamState.organizationId,
-                workflow,
-                currentStageId: effectiveStageId,
-                fromStatus: effectiveFromStatus,
-                exitCode: 0,
-                openIssueCount: openCount,
-                sessionCount,
-                policyFailureMode: config.policyFailureMode,
-                sessionId,
-                focusId: teamState.focusId,
-                config,
-            });
-            // Track the new stage ID for potential future advances
-            teamState.deliveryStageIds.set(delivery.id, result.deliveryStageId ?? null);
-            // Notify loop engine of delivery completion (verify or done)
-            if (result.advanced && (result.deliveryStatus === 'verify' || result.deliveryStatus === 'done')) {
-                emitLoopTrigger({
-                    type: 'delivery_completed',
-                    focusId: teamState.focusId,
-                    detail: `${delivery.name} -> ${result.deliveryStatus}`,
-                });
-            }
-        }
-        catch (err) {
-            console.warn(`[focus-executor] Failed to check/advance delivery ${delivery.id}:`, err.message);
-        }
-    }
-}
 //# sourceMappingURL=team-completion.js.map