@telora/daemon 0.21.26 → 0.21.82

package/dist/merge/merge-back-loop.js

@@ -0,0 +1,657 @@
+/**
+ * Continuous merge-back loop tick.
+ *
+ * Observes focus-branch state and merges to integration when safe.
+ * Adds a state-driven recovery path on top of the existing event-driven
+ * merge-back in focus-completion.handleTeamCompletion: any branch that
+ * ends up ahead of integration -- whether because the team-exit event
+ * was missed, the agent role was cleared mid-flight, the daemon
+ * restarted, or any other reason -- eventually gets merged here.
+ *
+ * Per product, per focus-branch ahead of integration:
+ *   - Skip if isWorktreeBeingWritten reports active.
+ *   - Skip if the worktree has uncommitted changes (covered by primitive,
+ *     but checked explicitly so the skip reason is logged at debug).
+ *   - Skip if a pending merge-conflict escalation exists for this branch.
+ *   - Otherwise: call mergeFocusBranch with a minimal synthetic teamState
+ *     and let the existing escalateMergeConflict path fire on failure.
+ *
+ * Stuck-branch escalation (Delivery 4) extends this tick with per-branch
+ * attempt tracking and creates 'stuck_focus_branch' escalations when a
+ * branch sits ahead of integration past a configurable threshold.
+ *
+ * @module merge-back-loop
+ */
+import { branchHasUnmergedCommits, worktreeHasUncommittedChanges } from '../worktree/index.js';
+import { runGitSync } from '../git/index.js';
+import { configForProduct } from '../shell/config.js';
+import { mergeFocusBranch as defaultMergeFocusBranch } from './focus-merge.js';
+import { getActiveFocuses } from '../queries/deliveries.js';
+import { getFocusDeliveries as defaultGetFocusDeliveries } from '../queries/focuses.js';
+import { listPendingEscalations as defaultListPendingEscalations, markEscalationResolved as defaultMarkEscalationResolved } from '../queries/issues.js';
+import { fileEscalationIdempotent as defaultFileEscalationIdempotent, } from '../queries/escalation-suppression.js';
+import { focusBlockageCauseKey } from '../queries/cause-key.js';
+import { classifyMergeFailure } from './merge-failure-classify.js';
+import { getAllFocusWorktrees } from '../focus/focus-worktree-state.js';
+import { isWorktreeBeingWritten as defaultIsWorktreeBeingWritten } from '../worktree/index.js';
+import { ESCALATION_REASONS, ESCALATION_DISPOSITIONS, loadEnvConfig } from '@telora/daemon-core';
+import { createLogger } from '../shell/log.js';
+const log = createLogger({ module: 'merge-back-loop' });
+// ── Stuck-branch escalation kind (Delivery 4) ─────────────────────────
+export const STUCK_FOCUS_BRANCH_KIND = 'stuck_focus_branch';
+const EMPTY_ATTEMPT_STATE = {
+    lastSuccessAt: null,
+    lastFailureAt: null,
+    lastFailureReason: null,
+    lastFailureClass: null,
+    firstRepeatAt: null,
+    repeatCount: 0,
+    throttledUntil: null,
+};
+const branchAttempts = new Map();
+/** Reset attempt tracking — tests use this to start from a clean slate. */
+export function __resetMergeBackAttemptsForTesting() {
+    branchAttempts.clear();
+}
+/** Read the attempt state for a branch (for tests / introspection). */
+export function getBranchAttemptState(branchName) {
+    return branchAttempts.get(branchName);
+}
+function recordSuccess(branchName, now) {
+    // A success clears the whole failure history including any throttle -- the
+    // branch merged, so the deterministic-failure run is over.
+    branchAttempts.set(branchName, { ...EMPTY_ATTEMPT_STATE, lastSuccessAt: now });
+}
+/**
+ * Record a merge failure and classify it. Tracks an IDENTICAL repeat (same
+ * classified condition as the previous failure) so a deterministic, unclearable
+ * failure can be signalled + throttled within minutes rather than waiting out the
+ * 24h stuck-branch threshold or re-running every tick. Returns the updated state
+ * and its classification so the caller can act on it.
+ */
+function recordFailure(branchName, now, reason) {
+    const existing = branchAttempts.get(branchName) ?? EMPTY_ATTEMPT_STATE;
+    const classification = classifyMergeFailure(reason);
+    const sameAsPrev = existing.lastFailureClass === classification.class;
+    const state = {
+        ...existing,
+        lastFailureAt: now,
+        lastFailureReason: reason,
+        lastFailureClass: classification.class,
+        firstRepeatAt: sameAsPrev ? existing.firstRepeatAt ?? existing.lastFailureAt ?? now : now,
+        repeatCount: sameAsPrev ? existing.repeatCount + 1 : 1,
+        throttledUntil: existing.throttledUntil,
+    };
+    branchAttempts.set(branchName, state);
+    return { state, failureClass: classification.class, isDeterministic: classification.isDeterministic };
+}
+/** Mark a branch throttled until `until` (a deterministic-failure backoff). */
+function setThrottle(branchName, until) {
+    const existing = branchAttempts.get(branchName) ?? EMPTY_ATTEMPT_STATE;
+    branchAttempts.set(branchName, { ...existing, throttledUntil: until });
+}
+/** Default minutes a deterministic merge failure may repeat before signal/throttle.
+ *  MIRRORS the canonical default declared in @telora/daemon-core env-config as
+ *  TELORA_MERGE_DETERMINISTIC_SIGNAL_MINUTES. */
+const DETERMINISTIC_SIGNAL_MINUTES_DEFAULT = 5;
+function readDeterministicSignalMs(env) {
+    // The canonical, zod-validated declaration lives in @telora/daemon-core
+    // env-config (TELORA_MERGE_DETERMINISTIC_SIGNAL_MINUTES, default 5). daemon-core
+    // is registry-installed, so a build predating that field returns undefined for
+    // it; read defensively and fall back to the mirrored default. Once daemon-core
+    // republishes with the field, loadEnvConfig parses + validates it and any
+    // operator override takes effect here automatically -- no further change.
+    const cfg = loadEnvConfig(env);
+    const minutes = cfg.TELORA_MERGE_DETERMINISTIC_SIGNAL_MINUTES;
+    const resolved = typeof minutes === 'number' && Number.isFinite(minutes) && minutes > 0
+        ? minutes
+        : DETERMINISTIC_SIGNAL_MINUTES_DEFAULT;
+    return resolved * 60_000;
+}
+function readStuckBranchThresholdMs(env) {
+    // Sourced from the typed env-config (validated at startup; default 24h).
+    return loadEnvConfig(env).TELORA_STUCK_BRANCH_THRESHOLD_HOURS * 3_600_000;
+}
+/**
+ * Read the unix-epoch milliseconds timestamp of the oldest commit on
+ * `branchName` not yet present on `targetBranch`. Returns null if there
+ * are no unmerged commits or the git invocation fails.
+ */
+export function getOldestUnmergedCommitMs(branchName, targetBranch, repoPath) {
+    const result = runGitSync(['log', '--format=%ct', `${targetBranch}..${branchName}`], repoPath);
+    if (!result.success)
+        return null;
+    const lines = result.output.trim().split('\n').filter(Boolean);
+    if (lines.length === 0)
+        return null;
+    // git log lists newest-first; the last line is the oldest commit.
+    const seconds = Number.parseInt(lines[lines.length - 1], 10);
+    if (!Number.isFinite(seconds) || Number.isNaN(seconds))
+        return null;
+    return seconds * 1000;
+}
+/**
+ * Enumerate focus branches with commits ahead of integration.
+ *
+ * Combines getActiveFocuses (for org/name/readOnly context) with the
+ * in-memory worktree state (for branchName + worktreePath). Returns one
+ * entry per focus whose branch has unmerged commits.
+ */
+export async function defaultEnumerateFocusBranchesAhead(config) {
+    const out = [];
+    const worktrees = getAllFocusWorktrees();
+    for (const product of config.products) {
+        const pc = configForProduct(config, product);
+        let focuses;
+        try {
+            focuses = await getActiveFocuses(pc.organizationId, product.id);
+        }
+        catch (err) {
+            log.warn(`[merge-back-loop] getActiveFocuses failed for product ${product.id}:`, err.message);
+            continue;
+        }
+        for (const focus of focuses) {
+            const wt = worktrees.get(focus.focus_id);
+            if (!wt)
+                continue;
+            const ahead = branchHasUnmergedCommits(wt.branchName, pc.integrationBranch, pc.repoPath);
+            if (!ahead)
+                continue;
+            out.push({
+                focusId: focus.focus_id,
+                focusName: focus.focus_name,
+                organizationId: pc.organizationId,
+                productId: product.id,
+                branchName: wt.branchName,
+                worktreePath: wt.worktreePath,
+                repoPath: pc.repoPath,
+                pipelineConfig: focus.pipeline_config ?? null,
+                readOnly: focus.read_only,
+            });
+        }
+    }
+    return out;
+}
+function defaultDeps() {
+    return {
+        enumerateFocusBranchesAhead: defaultEnumerateFocusBranchesAhead,
+        isWorktreeBeingWritten: defaultIsWorktreeBeingWritten,
+        worktreeHasUncommittedChanges,
+        listPendingEscalations: defaultListPendingEscalations,
+        markEscalationResolved: defaultMarkEscalationResolved,
+        fileEscalation: defaultFileEscalationIdempotent,
+        mergeFocusBranch: defaultMergeFocusBranch,
+        getFocusDeliveries: defaultGetFocusDeliveries,
+        getOldestUnmergedCommitMs,
+        now: () => Date.now(),
+    };
+}
+/**
+ * Find a pending escalation matching a kind and branch name.
+ * Uses the new metadata.branch_name field when present; falls back to
+ * scanning description strings for backward compatibility with rows
+ * created before the metadata column existed.
+ */
+function findPendingEscalationForBranch(pending, kind, branchName) {
+    for (const e of pending) {
+        const md = e.metadata ?? null;
+        const branchFromMd = md && typeof md === 'object' ? md.branch_name : undefined;
+        if (e.escalationKind === kind && branchFromMd === branchName) {
+            return { id: e.id };
+        }
+        // Fallback for legacy rows without escalationKind/metadata.
+        if (e.escalationKind == null &&
+            kind === STUCK_FOCUS_BRANCH_KIND &&
+            typeof e.description === 'string' &&
+            e.description.includes(`Branch: ${branchName}`)) {
+            return { id: e.id };
+        }
+    }
+    return null;
+}
+/**
+ * Find any pending merge-conflict escalation for this branch.
+ * Old-style rows do not carry escalationKind; they're detected via the
+ * description prefix used by escalateMergeConflict (focus-merge.ts:69).
+ */
+function findPendingConflictForBranch(pending, branchName) {
+    for (const e of pending) {
+        if (e.reasonType === ESCALATION_REASONS.ERROR_ENCOUNTERED &&
+            typeof e.description === 'string' &&
+            e.description.includes(`Source branch:** ${branchName}`)) {
+            return { id: e.id };
+        }
+    }
+    return null;
+}
+/**
+ * Build a minimal FocusTeamState shape that mergeFocusBranch can consume.
+ * Many fields are unused by mergeFocusBranch's read-path; they default to
+ * empty/null so the synthetic state stays observably distinct from real
+ * in-flight teams.
+ */
+function buildSyntheticTeamState(info, knownDeliveryIds) {
+    return {
+        focusId: info.focusId,
+        focusName: info.focusName,
+        roleId: '',
+        roleName: 'merge-back-loop',
+        organizationId: info.organizationId,
+        productId: info.productId,
+        executionConfig: { maxWorkers: 0, idlePollIntervalMs: 0, activePollIntervalMs: 0 },
+        pipelineConfig: info.pipelineConfig,
+        startedAt: new Date(),
+        phase: 'terminated',
+        knownDeliveryIds,
+        mergedDeliveryIds: new Set(),
+        planningPhase: false,
+        leadSessionId: null,
+        leadPid: null,
+        leadStdin: null,
+        branchName: info.branchName,
+        worktreePath: info.worktreePath,
+        integrationBaseSha: null,
+        reviewSpawnTip: null,
+        deliveryStageIds: new Map(),
+        resolvingMergeConflict: false,
+        shutdownReason: null,
+        readOnly: info.readOnly,
+        sessionType: 'coding',
+        lineage: 'coding',
+        completionDetector: null,
+        claudeSessionId: null,
+        lastProgressSnapshot: null,
+        noProgressCycles: 0,
+        commitNudgeAttempts: 0,
+        lastConsumedDirectiveHash: null,
+    };
+}
+/**
+ * Statuses that mark deliveries as worked-on (ready for git state REPORTING).
+ *
+ * 'done' is included so focuses whose deliveries all reached done before the
+ * branch was merged still get propagated. Without 'done' the merge-back loop
+ * skips the focus with "no worked deliveries" and the branch stays stranded.
+ *
+ * NOTE: this set is REPORTING-only (per-delivery git-state telemetry inside
+ * mergeFocusBranch). It is deliberately distinct from MERGE_ELIGIBLE_STATUSES:
+ * 'coding' is worked-on for reporting but NOT a merge trigger, so unreviewed
+ * coding-status code cannot reach integration ahead of the review gate.
+ */
+const WORKED_STATUSES = new Set(['coding', 'verify', 'done']);
+/**
+ * Statuses that make a focus branch ELIGIBLE to merge to integration.
+ *
+ * A delivery only becomes mergeable once it has passed the dev-complete bar:
+ * `verify` (awaiting the review gate) or `done` (already approved). `coding` is
+ * intentionally EXCLUDED so the merge-back loop never pushes unreviewed
+ * coding-status work to integration before the review gate runs against it.
+ * Separating this from WORKED_STATUSES keeps git-state reporting (which still
+ * marks coding deliveries worked-on) decoupled from the merge decision.
+ */
+const MERGE_ELIGIBLE_STATUSES = new Set(['verify', 'done']);
+/**
+ * Build a `whatWasTried` summary string for stuck-branch escalations.
+ */
+function summarizeAttempts(state) {
+    if (!state)
+        return 'No merge attempts recorded since daemon startup.';
+    const parts = [];
+    if (state.lastSuccessAt) {
+        parts.push(`last success at ${new Date(state.lastSuccessAt).toISOString()}`);
+    }
+    if (state.lastFailureAt) {
+        parts.push(`last failure at ${new Date(state.lastFailureAt).toISOString()}: ${state.lastFailureReason ?? 'unknown'}`);
+    }
+    if (state.lastFailureClass && state.repeatCount > 1) {
+        parts.push(`condition '${state.lastFailureClass}' repeated ${state.repeatCount}x identically`);
+    }
+    if (parts.length === 0)
+        return 'No merge attempts recorded since daemon startup.';
+    return parts.join('; ');
+}
+/**
+ * Decide whether to file a stuck-branch escalation for this branch.
+ *
+ * Conditions (all must hold):
+ *   - branch has at least one unmerged commit (already guaranteed by enumerate)
+ *   - oldest unmerged commit is older than threshold
+ *   - worktree is NOT being written
+ *   - no successful merge attempt has been recorded within the threshold window
+ *   - no open OR dismissed stuck_focus_branch escalation carries this branch's
+ *     cause key (idempotency + dismissal memory, enforced by the shared gate)
+ */
+async function maybeFileStuckBranchEscalation(info, oldestUnmergedMs, worktreeActive, thresholdMs, now, fileEscalation) {
+    if (worktreeActive)
+        return;
+    if (oldestUnmergedMs == null)
+        return;
+    if (now - oldestUnmergedMs <= thresholdMs)
+        return;
+    const state = branchAttempts.get(info.branchName);
+    if (state?.lastSuccessAt && now - state.lastSuccessAt <= thresholdMs)
+        return;
+    // Per-branch cause key: one open row per stuck branch, and a dismissed one keeps
+    // it silent until the branch merges (dedup + dismissal memory in one gate). The
+    // pending-list dedup this replaced saw only OPEN rows, so a dismissal re-filed
+    // every 30s tick until merge -- the incident pattern this closes.
+    const causeKey = focusBlockageCauseKey(STUCK_FOCUS_BRANCH_KIND, info.focusId, info.branchName);
+    const ageHours = Math.floor((now - oldestUnmergedMs) / 3_600_000);
+    const description = `Focus branch sat ahead of integration for ~${ageHours}h with no successful merge.\n\n` +
+        `**Focus:** ${info.focusName}\n` +
+        `**Branch:** ${info.branchName}\n` +
+        `**Oldest unmerged commit:** ${new Date(oldestUnmergedMs).toISOString()}\n` +
+        `**Recent attempts:** ${summarizeAttempts(state)}`;
+    try {
+        await fileEscalation({
+            causeKey,
+            organizationId: info.organizationId,
+            sessionId: '',
+            issueId: null,
+            reasonType: ESCALATION_REASONS.ERROR_ENCOUNTERED,
+            // Operator triage: rebase/merge manually, mark complete, or clear the branch.
+            disposition: ESCALATION_DISPOSITIONS.NEEDS_OPERATOR,
+            // Provenance via the anchor; focus_id no longer denormalized into metadata.
+            anchor: { focusId: info.focusId, branch: info.branchName },
+            description,
+            whatWasTried: summarizeAttempts(state),
+            helpNeeded: `Inspect the branch (${info.branchName}) and integration history. ` +
+                `Either rebase/merge manually, mark the focus complete, or clear the branch ` +
+                `if its commits are no longer wanted.`,
+            escalationKind: STUCK_FOCUS_BRANCH_KIND,
+            metadata: {
+                // branch_name is the dedup discriminator for this branch-scoped class
+                // (findPendingEscalationForBranch reads it); there is no branch column.
+                branch_name: info.branchName,
+                oldest_commit_ts: oldestUnmergedMs,
+                last_failure_reason: state?.lastFailureReason ?? null,
+            },
+        });
+        log.info(`Filed stuck_focus_branch escalation for ${info.branchName} (${ageHours}h old)`);
+    }
+    catch (err) {
+        log.warn(`[merge-back-loop] fileEscalation failed for ${info.branchName}:`, err.message);
+    }
+}
+/**
+ * Auto-resolve any open stuck-branch escalations for a branch we just merged.
+ */
+async function resolveStuckBranchEscalations(branchName, pending, markResolved) {
+    const match = findPendingEscalationForBranch(pending, STUCK_FOCUS_BRANCH_KIND, branchName);
+    if (!match)
+        return;
+    try {
+        await markResolved(match.id, 'Branch merged automatically by merge-back-loop');
+        log.info(`Auto-resolved stuck_focus_branch escalation ${match.id} for ${branchName}`);
+    }
+    catch (err) {
+        log.warn(`[merge-back-loop] markEscalationResolved failed for ${match.id}:`, err.message);
+    }
+}
+/** Human-readable one-liner for a deterministic merge-failure condition. */
+function describeDeterministicCondition(failureClass) {
+    switch (failureClass) {
+        case 'hook_rejected':
+            return 'a commit-msg hook rejected the merge commit (the daemon cannot satisfy it by retrying)';
+        case 'worktree_dirty':
+            return 'the merge worktree carried local changes the merge would overwrite, and the pre-merge recovery did not clear them';
+        default:
+            return 'a deterministic condition that re-fails identically on retry';
+    }
+}
+/** The operator remedy for a deterministic merge-failure condition. */
+function describeDeterministicRemedy(failureClass, branch) {
+    switch (failureClass) {
+        case 'hook_rejected':
+            return `Inspect the commit-msg hook installed for the merge worktree and the ${branch} branch. A merge commit should be exempt from the delivery-trailer guard; if the hook is rejecting merges, the hook install is wrong.`;
+        case 'worktree_dirty':
+            return `Inspect the merge worktree (.telora/merge-worktree) -- it is holding uncommitted changes the automatic recovery is not clearing. Clean it manually, then let merge-back retry.`;
+        default:
+            return `Inspect the ${branch} branch and the merge worktree; the same merge failure is repeating unchanged.`;
+    }
+}
+/**
+ * Signal a DETERMINISTIC merge failure that has repeated identically for at least
+ * the signal window. Unlike the aged-out stuck-branch escalation (24h threshold),
+ * this fires within minutes: the failure is self-inflicted and unclearable by
+ * retrying, so waiting a day serves nothing. Files through the SAME cause-keyed
+ * idempotent gate as the stuck-branch escalation (one open row per branch), so
+ * the two never double-file. Returns true when a signal was filed.
+ */
+async function maybeSignalDeterministicRepeat(info, state, failureClass, now, signalMs, fileEscalation) {
+    // Only after the SAME condition has repeated (>=2) AND persisted past the
+    // signal window -- a single transient failure is never signalled.
+    if (state.repeatCount < 2)
+        return false;
+    if (state.firstRepeatAt == null || now - state.firstRepeatAt < signalMs)
+        return false;
+    const causeKey = focusBlockageCauseKey(STUCK_FOCUS_BRANCH_KIND, info.focusId, info.branchName);
+    const minutes = Math.floor((now - state.firstRepeatAt) / 60_000);
+    const description = `Merge-back for focus "${info.focusName}" branch ${info.branchName} has FAILED IDENTICALLY ` +
+        `(${failureClass}) ${state.repeatCount} times over ~${minutes}m -- ` +
+        `${describeDeterministicCondition(failureClass)}. Retries are now throttled so it does not ` +
+        `re-run every poll tick.`;
+    try {
+        await fileEscalation({
+            causeKey,
+            organizationId: info.organizationId,
+            sessionId: '',
+            issueId: null,
+            reasonType: ESCALATION_REASONS.ERROR_ENCOUNTERED,
+            disposition: ESCALATION_DISPOSITIONS.NEEDS_OPERATOR,
+            anchor: { focusId: info.focusId, branch: info.branchName },
+            description,
+            whatWasTried: summarizeAttempts(state),
+            helpNeeded: describeDeterministicRemedy(failureClass, info.branchName),
+            escalationKind: STUCK_FOCUS_BRANCH_KIND,
+            metadata: {
+                branch_name: info.branchName,
+                failure_class: failureClass,
+                repeat_count: state.repeatCount,
+                first_repeat_ts: state.firstRepeatAt,
+                last_failure_reason: state.lastFailureReason ?? null,
+            },
+        });
+        log.warn(`[merge-back-loop] SIGNAL: ${info.branchName} deterministic ${failureClass} x${state.repeatCount} ` +
+            `(~${minutes}m); filed stuck_focus_branch and throttling.`);
+        return true;
+    }
+    catch (err) {
+        log.warn(`[merge-back-loop] deterministic-repeat signal fileEscalation failed for ${info.branchName}:`, err.message);
+        return false;
+    }
+}
+/**
+ * Act on a recorded merge failure. A DETERMINISTIC condition (hook rejection /
+ * dirty worktree) is throttled -- so it does not re-run at full poll rate -- and,
+ * once it has repeated past the signal window, signalled within minutes. Every
+ * failure logs which condition occurred and what the daemon did about it, so the
+ * state is readable from the log without reconstructing it from git.
+ */
+async function handleMergeFailure(info, rec, now, signalMs, fileEscalation) {
+    const { state, failureClass, isDeterministic } = rec;
+    if (isDeterministic) {
+        setThrottle(info.branchName, now + signalMs);
+        log.warn(`[merge-back-loop] ${info.branchName}: deterministic merge failure '${failureClass}' ` +
+            `(repeat ${state.repeatCount}) -- ${describeDeterministicCondition(failureClass)}. ` +
+            `Throttling retries for ~${Math.round(signalMs / 60_000)}m and evaluating a signal.`);
+        await maybeSignalDeterministicRepeat(info, state, failureClass, now, signalMs, fileEscalation);
+    }
+    else {
+        log.warn(`[merge-back-loop] ${info.branchName}: merge failure classified '${failureClass}' ` +
+            `(repeat ${state.repeatCount}); handled by the conflict / stuck-branch paths, not throttled.`);
+    }
+}
+/**
+ * Run one merge-back tick across all products in the daemon config.
+ *
+ * Idempotent: when no branches are ahead of integration, the tick is a
+ * no-op (no info-level log, debug only). When work happens, logs a
+ * single info-level summary line.
+ */
+export async function runMergeBackTick(config, depOverrides = {}) {
+    const deps = { ...defaultDeps(), ...depOverrides };
+    const counts = { scanned: 0, merged: 0, skipped: 0, conflicts: 0 };
+    const thresholdMs = readStuckBranchThresholdMs();
+    const signalMs = readDeterministicSignalMs();
+    let branches;
+    try {
+        branches = await deps.enumerateFocusBranchesAhead(config);
+    }
+    catch (err) {
+        log.warn('enumerate failed:', err.message);
+        return counts;
+    }
+    // Pull pending escalations once per tick — used for both conflict-skip and
+    // stuck-branch dedup checks. Empty list on error so the tick continues.
+    let pending;
+    try {
+        pending = await deps.listPendingEscalations();
+    }
+    catch (err) {
+        log.warn('listPendingEscalations failed:', err.message);
+        pending = [];
+    }
+    counts.scanned = branches.length;
+    if (branches.length === 0) {
+        log.debug('tick: 0 branches ahead of integration');
+        return counts;
+    }
+    for (const info of branches) {
+        const now = (deps.now ?? Date.now)();
+        // Gate 0: read-only audit focuses never merge to integration. The
+        // event-driven path enforces this via shouldAttemptMerge's readOnly
+        // check; mirror that here so a violating audit team (one that
+        // committed in violation of its constraint) can't bypass the guard
+        // through the state-driven loop.
+        if (info.readOnly) {
+            counts.skipped += 1;
+            log.debug(`skip ${info.branchName}: read-only focus`);
+            continue;
+        }
+        // Gate 0.5: throttle. A branch whose last failure was deterministic and
+        // unclearable is backed off so it does not re-attempt every 30s tick; it
+        // becomes eligible again once the throttle window elapses (state may have
+        // changed by then -- the hook fixed, the worktree cleaned).
+        const priorState = branchAttempts.get(info.branchName);
+        if (priorState?.throttledUntil && now < priorState.throttledUntil) {
+            counts.skipped += 1;
+            log.debug(`[merge-back-loop] skip ${info.branchName}: throttled after deterministic ` +
+                `'${priorState.lastFailureClass ?? 'failure'}' until ` +
+                `${new Date(priorState.throttledUntil).toISOString()}`);
+            continue;
+        }
+        // Gate 1: in-memory writer / active session / recent commit / dirty
+        let writeSignal;
+        try {
+            writeSignal = await deps.isWorktreeBeingWritten(info.focusId);
+        }
+        catch (err) {
+            log.warn(`[merge-back-loop] isWorktreeBeingWritten failed for ${info.focusId}:`, err.message);
+            counts.skipped += 1;
+            continue;
+        }
+        if (writeSignal.active) {
+            counts.skipped += 1;
+            log.debug(`[merge-back-loop] skip ${info.branchName}: ${writeSignal.reason?.code ?? 'unknown'} -- ${writeSignal.reason?.message ?? ''}`);
+            continue;
+        }
+        // Gate 2: explicit dirty-worktree skip (redundant w/ isWorktreeBeingWritten,
+        // but logged separately so the skip is easy to read in the log).
+        if (deps.worktreeHasUncommittedChanges(info.worktreePath)) {
+            counts.skipped += 1;
+            log.debug(`skip ${info.branchName}: dirty worktree`);
+            continue;
+        }
+        // Gate 3: existing pending merge-conflict escalation for this branch
+        if (findPendingConflictForBranch(pending, info.branchName)) {
+            counts.skipped += 1;
+            log.debug(`skip ${info.branchName}: pending merge-conflict escalation`);
+            // Even when we skip the merge, the stuck-branch escalation may still
+            // need to fire if the branch has aged out. Skip that here too —
+            // a stuck conflict already has an escalation surface.
+            continue;
+        }
+        // Gather worked deliveries (see WORKED_STATUSES).
+        let deliveries = [];
+        try {
+            deliveries = await deps.getFocusDeliveries(info.focusId);
+        }
+        catch (err) {
+            log.warn(`[merge-back-loop] getFocusDeliveries failed for ${info.focusId}:`, err.message);
+        }
+        const allDeliveryIds = deliveries.map((d) => d.id);
+        const workedDeliveryIds = deliveries
+            .filter((d) => WORKED_STATUSES.has(d.executionStatus ?? ''))
+            .map((d) => d.id);
+        if (allDeliveryIds.length === 0) {
+            // Degenerate case: branch is ahead but the focus has no deliveries
+            // (e.g., orphaned branch with no focus row). Skip and consider the
+            // stuck-branch surface — operators decide whether to keep or clean up.
+            counts.skipped += 1;
+            log.debug(`skip ${info.branchName}: focus has no deliveries`);
+            const oldestMs = deps.getOldestUnmergedCommitMs(info.branchName, config.integrationBranch, info.repoPath);
+            await maybeFileStuckBranchEscalation(info, oldestMs, writeSignal.active, thresholdMs, now, deps.fileEscalation);
+            continue;
+        }
+        // Gate 4: merge-eligibility. A focus whose deliveries are ALL still in
+        // `coding` is not yet past the dev-complete bar -- its branch carries
+        // unreviewed code. Skip the merge so the review gate runs first; the work
+        // becomes merge-eligible once a delivery reaches verify/done (the
+        // terminate-path reconciliation in completion/event.ts advances finished
+        // coding work to verify, so genuinely-complete work is not stranded here).
+        //
+        // Deliberately do NOT file a stuck_focus_branch escalation on this path: a
+        // coding-only focus is INTENTIONALLY held by the review gate, not stuck in
+        // the merge-back sense. A genuinely wedged coding focus (nothing committed,
+        // no progress) is surfaced by the completion-path team_failure / no-progress
+        // watchdogs, not by merge-back. So a held coding focus never spuriously
+        // ages into a stuck_focus_branch escalation before the threshold.
+        const mergeEligible = deliveries.some((d) => MERGE_ELIGIBLE_STATUSES.has(d.executionStatus ?? ''));
+        if (!mergeEligible) {
+            counts.skipped += 1;
+            log.debug(`[merge-back-loop] skip ${info.branchName}: no verify/done delivery ` +
+                `(deliveries still coding) -- waiting for the review gate`);
+            continue;
+        }
+        // Pass ALL delivery IDs as knownDeliveryIds so mergeFocusBranch's
+        // representative fallback can find a delivery even when workedDeliveryIds
+        // is empty (e.g., done-only focus). workedDeliveryIds still drives
+        // per-delivery git-state telemetry inside mergeFocusBranch.
+        const teamState = buildSyntheticTeamState(info, new Set(allDeliveryIds));
+        // Pass a product-scoped config so mergeFocusBranch's downstream git
+        // operations (mergeToIntegration, etc.) run against the correct repo.
+        const productConfig = { ...config, repoPath: info.repoPath, productId: info.productId };
+        let mergeResult;
+        try {
+            mergeResult = await deps.mergeFocusBranch(productConfig, teamState, 
+            /* sessionId */ '', info.branchName, workedDeliveryIds);
+        }
+        catch (err) {
+            counts.conflicts += 1;
+            const rec = recordFailure(info.branchName, now, err.message);
+            log.warn(`[merge-back-loop] mergeFocusBranch threw for ${info.branchName}:`, err.message);
+            await handleMergeFailure(info, rec, now, signalMs, deps.fileEscalation);
+            continue;
+        }
+        if (mergeResult.mergeSucceeded) {
+            counts.merged += 1;
+            recordSuccess(info.branchName, now);
+            await resolveStuckBranchEscalations(info.branchName, pending, deps.markEscalationResolved);
+        }
+        else {
+            counts.conflicts += 1;
+            const rec = recordFailure(info.branchName, now, mergeResult.exitReason);
+            // Deterministic conditions (hook rejection / dirty worktree) are throttled
+            // and signalled within minutes; every failure logs its condition + action.
+            await handleMergeFailure(info, rec, now, signalMs, deps.fileEscalation);
+            // Re-evaluate stuck-branch escalation: a persistent failure should
+            // surface as 'stuck' once the branch ages out (24h path, shared cause key).
+            const oldestMs = deps.getOldestUnmergedCommitMs(info.branchName, config.integrationBranch, info.repoPath);
+            await maybeFileStuckBranchEscalation(info, oldestMs, writeSignal.active, thresholdMs, now, deps.fileEscalation);
+        }
+    }
+    log.info(`[merge-back-loop] tick: ${counts.scanned} branches scanned, ${counts.merged} merged, ${counts.skipped} skipped, ${counts.conflicts} conflicts`);
+    return counts;
+}
+//# sourceMappingURL=merge-back-loop.js.map