agentic-orchestrator 0.1.27 → 0.2.0

package/dist/apps/control-plane/application/services/git-reconciliation-service.js

@@ -0,0 +1,1097 @@
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { ensureDir, nowIso } from '../../core/fs.js';
+import { runGit } from '../../core/git.js';
+import { STATUS } from '../../core/constants.js';
+import { ERROR_CODES } from '../../core/error-codes.js';
+import { ok, fail } from '../../core/response.js';
+function readFrontMatterVersion(frontMatter) {
+    const raw = frontMatter.version;
+    return typeof raw === 'number' && Number.isFinite(raw) ? raw : 0;
+}
+function parseDiffNameOnly(stdout) {
+    return stdout
+        .split('\n')
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0);
+}
+function parseStatusPaths(statusPorcelain) {
+    const files = [];
+    const lines = statusPorcelain
+        .split('\n')
+        .map((line) => line.trimEnd())
+        .filter((line) => line.length >= 4);
+    for (const line of lines) {
+        const candidate = line.slice(3).trim();
+        if (!candidate) {
+            continue;
+        }
+        const renameMarker = candidate.indexOf(' -> ');
+        const pathValue = renameMarker >= 0 ? candidate.slice(renameMarker + 4) : candidate;
+        const normalized = pathValue.replaceAll('\\\\', '/').trim();
+        if (normalized.length > 0) {
+            files.push(normalized);
+        }
+    }
+    return [...new Set(files)].sort((a, b) => a.localeCompare(b));
+}
+function isIgnoredReconciliationStatusPath(filePath) {
+    return (filePath.startsWith('.aop/') ||
+        filePath.startsWith('.worktrees/') ||
+        filePath === 'agentic/orchestrator/tools.md');
+}
+function intersect(a, b) {
+    const setB = new Set(b);
+    return a.filter((f) => setB.has(f));
+}
+function asStringArray(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value.filter((item) => typeof item === 'string' && item.length > 0);
+}
+function normalizeQueue(queue) {
+    const seen = new Set();
+    const normalized = [];
+    for (const featureId of queue) {
+        if (seen.has(featureId)) {
+            continue;
+        }
+        seen.add(featureId);
+        normalized.push(featureId);
+    }
+    return normalized;
+}
+function asCollisionOverrides(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value.filter((entry) => entry !== null && typeof entry === 'object');
+}
+function asCollisionRecords(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value.filter((entry) => entry !== null && typeof entry === 'object');
+}
+function defined(value) {
+    return value !== null;
+}
+function findLatestUnresolvedMainlineConflict(frontMatter) {
+    const conflicts = Array.isArray(frontMatter.conflicts) ? frontMatter.conflicts : [];
+    for (let index = conflicts.length - 1; index >= 0; index -= 1) {
+        const entry = conflicts[index];
+        if (!entry || typeof entry !== 'object' || entry.type !== 'mainline_divergence') {
+            continue;
+        }
+        const typed = entry;
+        if (typed.resolution_status === 'resolved') {
+            continue;
+        }
+        return { index, entry: typed };
+    }
+    return { index: -1, entry: null };
+}
+function readConflictInfo(conflict) {
+    return {
+        mergeBase: typeof conflict?.merge_base === 'string' ? conflict.merge_base : 'unknown',
+        mainlineHead: typeof conflict?.mainline_head === 'string' ? conflict.mainline_head : 'unknown',
+        worktreeHead: typeof conflict?.worktree_head === 'string' ? conflict.worktree_head : 'unknown',
+        conflictingFiles: asStringArray(conflict?.conflicting_files),
+    };
+}
+function buildQueueStatusReason(activeFeatureId, queuePosition) {
+    if (queuePosition === null || queuePosition <= 0) {
+        return 'Mainline divergence assigned to the shared reconciler lane';
+    }
+    const ordinal = queuePosition + 1;
+    const active = activeFeatureId ? ` behind ${activeFeatureId}` : '';
+    return `Queued for shared reconciler lane at position ${ordinal}${active}`;
+}
+function errorMessage(error) {
+    if (error instanceof Error && typeof error.message === 'string' && error.message.length > 0) {
+        const details = 'details' in error && error.details && typeof error.details === 'object'
+            ? error.details
+            : null;
+        const stderr = details && typeof details.stderr === 'string' && details.stderr.trim().length > 0
+            ? details.stderr.trim()
+            : null;
+        if (stderr) {
+            return `${error.message}: ${stderr}`;
+        }
+        return error.message;
+    }
+    if (typeof error === 'string' && error.length > 0) {
+        return error;
+    }
+    return 'unknown reconciler dispatch failure';
+}
+function isMissingReconcilerConversation(error) {
+    if (error instanceof Error && error.message.includes('No conversation found with session ID')) {
+        return true;
+    }
+    if (typeof error === 'string') {
+        return error.includes('No conversation found with session ID');
+    }
+    const details = error &&
+        typeof error === 'object' &&
+        'details' in error &&
+        error.details &&
+        typeof error.details === 'object'
+        ? error.details
+        : null;
+    const stderr = details && typeof details.stderr === 'string' ? details.stderr : '';
+    return stderr.includes('No conversation found with session ID');
+}
+/**
+ * Service that reconciles feature worktrees with the mainline branch.
+ */
+export class GitReconciliationService {
+    port;
+    constructor(port) {
+        this.port = port;
+    }
+    async checkRemoteLocalDivergence(baseRef) {
+        const repoRoot = this.port.getRepoRoot();
+        await runGit(repoRoot, ['fetch', 'origin', baseRef]);
+        const localResult = await runGit(repoRoot, ['rev-parse', baseRef]);
+        const remoteResult = await runGit(repoRoot, ['rev-parse', `origin/${baseRef}`]);
+        if (localResult.code !== 0) {
+            return fail(ERROR_CODES.GIT_FAILURE, `Cannot resolve local ref ${baseRef}`, {
+                retryable: false,
+                requires_human: true,
+            });
+        }
+        const localHead = localResult.stdout.trim();
+        // Preserve fallback: if remote ref fails to resolve, treat as no divergence
+        if (remoteResult.code !== 0) {
+            return ok({
+                diverged: false,
+                local_ahead: false,
+                local_head: localHead,
+                remote_head: localHead,
+            });
+        }
+        const remoteHead = remoteResult.stdout.trim();
+        // Identical SHAs — short-circuit without merge-base call
+        if (localHead === remoteHead) {
+            return ok({
+                diverged: false,
+                local_ahead: false,
+                local_head: localHead,
+                remote_head: remoteHead,
+            });
+        }
+        // Check if remote is an ancestor of local (local is ahead)
+        const ancestorResult = await runGit(repoRoot, [
+            'merge-base',
+            '--is-ancestor',
+            `origin/${baseRef}`,
+            baseRef,
+        ]);
+        if (ancestorResult.code === 0) {
+            // Remote is ancestor of local — local is ahead, no real divergence
+            return ok({
+                diverged: false,
+                local_ahead: true,
+                local_head: localHead,
+                remote_head: remoteHead,
+            });
+        }
+        // True divergence — remote has commits local doesn't
+        return ok({
+            diverged: true,
+            local_ahead: false,
+            local_head: localHead,
+            remote_head: remoteHead,
+        });
+    }
+    async syncMainlineFromRemote(baseRef) {
+        const repoRoot = this.port.getRepoRoot();
+        const fetchResult = await runGit(repoRoot, ['fetch', 'origin', baseRef]);
+        if (fetchResult.code !== 0) {
+            return fail(ERROR_CODES.GIT_FAILURE, `Failed to fetch origin/${baseRef}`, {
+                stderr: fetchResult.stderr,
+                retryable: true,
+                requires_human: false,
+            });
+        }
+        const checkoutResult = await runGit(repoRoot, ['checkout', baseRef]);
+        if (checkoutResult.code !== 0) {
+            return fail(ERROR_CODES.GIT_FAILURE, `Failed to checkout ${baseRef} for remote sync`, {
+                stderr: checkoutResult.stderr,
+                retryable: false,
+                requires_human: true,
+            });
+        }
+        const mergeResult = await runGit(repoRoot, ['merge', '-X', 'ours', `origin/${baseRef}`]);
+        if (mergeResult.code !== 0) {
+            await runGit(repoRoot, ['merge', '--abort']);
+            return fail(ERROR_CODES.RECONCILIATION_FAILED, `Failed to sync origin/${baseRef} into local ${baseRef}`, {
+                stderr: mergeResult.stderr,
+                retryable: false,
+                requires_human: true,
+            });
+        }
+        const shaResult = await runGit(repoRoot, ['rev-parse', 'HEAD']);
+        return ok({ merged: true, sha: shaResult.stdout.trim() });
+    }
+    async reconcileWithMainline(featureId, baseRef, checkpointCommitMessage = null) {
+        const repoRoot = this.port.getRepoRoot();
+        const worktreePath = this.port.worktreePath(featureId);
+        const existingConflictResult = await this.reuseExistingConflictIfPresent(featureId, worktreePath, baseRef);
+        if (existingConflictResult) {
+            return existingConflictResult;
+        }
+        const fetchResult = await runGit(worktreePath, ['fetch', 'origin', baseRef]);
+        if (fetchResult.code !== 0) {
+            // Non-fatal: continue with local refs
+        }
+        const localMergeBase = await runGit(worktreePath, ['merge-base', baseRef, 'HEAD']);
+        if (localMergeBase.code !== 0) {
+            return fail(ERROR_CODES.MERGE_BASE_NOT_FOUND, `Cannot find merge base between ${baseRef} and HEAD`, { featureId, baseRef, retryable: false, requires_human: true });
+        }
+        const mergeBase = localMergeBase.stdout.trim();
+        if (!mergeBase) {
+            return fail(ERROR_CODES.MERGE_BASE_NOT_FOUND, `Empty merge base for ${baseRef}`, {
+                featureId,
+                baseRef,
+                retryable: false,
+                requires_human: true,
+            });
+        }
+        const checkpointResult = await this.checkpointFeatureWorktreeIfRequested(featureId, worktreePath, checkpointCommitMessage);
+        if (!checkpointResult.ok) {
+            return checkpointResult;
+        }
+        const localMainlineResult = await runGit(repoRoot, ['rev-parse', baseRef]);
+        const originMainlineResult = await runGit(worktreePath, ['rev-parse', `origin/${baseRef}`]);
+        const mainlineHead = localMainlineResult.code === 0
+            ? localMainlineResult.stdout.trim()
+            : originMainlineResult.stdout.trim();
+        const worktreeHeadResult = await runGit(worktreePath, ['rev-parse', 'HEAD']);
+        const worktreeHead = worktreeHeadResult.stdout.trim();
+        if (mainlineHead === mergeBase || mainlineHead === worktreeHead) {
+            await this.updateReconciliationState(featureId, mainlineHead);
+            await this.resolveMainlineConflictState(featureId, mainlineHead);
+            await this.releaseAndDispatchNext(featureId, baseRef);
+            return ok({
+                status: 'up_to_date',
+                divergence_detected: false,
+                files_changed_mainline: [],
+                files_changed_worktree: [],
+                conflicting_files: [],
+                merge_base: mergeBase,
+                mainline_head: mainlineHead,
+                worktree_head: worktreeHead,
+            });
+        }
+        const mainlineDiffResult = await runGit(worktreePath, [
+            'diff',
+            '--name-only',
+            mergeBase,
+            mainlineHead,
+        ]);
+        const filesChangedMainline = parseDiffNameOnly(mainlineDiffResult.stdout);
+        const worktreeDiffResult = await runGit(worktreePath, [
+            'diff',
+            '--name-only',
+            mergeBase,
+            worktreeHead,
+        ]);
+        const filesChangedWorktree = parseDiffNameOnly(worktreeDiffResult.stdout);
+        const overlappingFiles = intersect(filesChangedMainline, filesChangedWorktree);
+        await this.writeEvidenceArtifacts(featureId, worktreePath, mergeBase, mainlineHead, worktreeHead, overlappingFiles);
+        if (overlappingFiles.length > 0) {
+            const materialized = await this.materializeConflictWorktree(featureId, worktreePath, baseRef, mainlineHead);
+            if (materialized.kind === 'error') {
+                return materialized.response;
+            }
+            if (materialized.kind === 'conflict') {
+                const claim = await this.claimReconcilerLane(featureId);
+                const queuePosition = claim.activeFeatureId === featureId ? 0 : (claim.queuePosition ?? 1);
+                await this.upsertMainlineConflictState(featureId, {
+                    mergeBase,
+                    mainlineHead,
+                    worktreeHead,
+                    conflictingFiles: materialized.conflictingFiles,
+                }, {
+                    baseRef,
+                    resolutionStatus: claim.activeFeatureId === featureId ? 'in_progress' : 'pending',
+                    queuePosition,
+                    statusReason: buildQueueStatusReason(claim.activeFeatureId, queuePosition),
+                });
+                const dispatched = claim.activeFeatureId === featureId
+                    ? await this.dispatchReconcilerTurn(featureId, baseRef, claim.sessionId, {
+                        mergeBase,
+                        mainlineHead,
+                        worktreeHead,
+                        conflictingFiles: materialized.conflictingFiles,
+                    })
+                    : false;
+                await this.appendReconciliationLog(featureId, dispatched
+                    ? `queued_for_reconciler: active lane assigned to ${featureId}`
+                    : `queued_for_reconciler: waiting on ${claim.activeFeatureId ?? 'unknown'}`);
+                return ok({
+                    status: 'conflict_detected',
+                    divergence_detected: true,
+                    files_changed_mainline: filesChangedMainline,
+                    files_changed_worktree: filesChangedWorktree,
+                    conflicting_files: materialized.conflictingFiles,
+                    merge_base: mergeBase,
+                    mainline_head: mainlineHead,
+                    worktree_head: worktreeHead,
+                    reconciler_active_feature_id: claim.activeFeatureId,
+                    reconciler_queue_position: queuePosition,
+                    dispatched_to_reconciler: dispatched,
+                    conflict_worktree_prepared: true,
+                });
+            }
+            await this.updateReconciliationState(featureId, mainlineHead);
+            await this.resolveMainlineConflictState(featureId, mainlineHead);
+            await this.releaseAndDispatchNext(featureId, baseRef);
+            await this.appendReconciliationLog(featureId, `merged: ${mainlineHead} (materialized merge commit)`);
+            return ok({
+                status: 'merged',
+                divergence_detected: true,
+                files_changed_mainline: filesChangedMainline,
+                files_changed_worktree: filesChangedWorktree,
+                conflicting_files: [],
+                merge_base: mergeBase,
+                mainline_head: mainlineHead,
+                worktree_head: worktreeHead,
+            });
+        }
+        const mergeResult = await this.performAutoMerge(featureId, worktreePath, baseRef, mainlineHead);
+        if (!mergeResult.ok) {
+            return mergeResult;
+        }
+        await this.updateReconciliationState(featureId, mainlineHead);
+        await this.resolveMainlineConflictState(featureId, mainlineHead);
+        await this.releaseAndDispatchNext(featureId, baseRef);
+        await this.appendReconciliationLog(featureId, `merged: ${mainlineHead}`);
+        return ok({
+            status: 'merged',
+            divergence_detected: true,
+            files_changed_mainline: filesChangedMainline,
+            files_changed_worktree: filesChangedWorktree,
+            conflicting_files: [],
+            merge_base: mergeBase,
+            mainline_head: mainlineHead,
+            worktree_head: worktreeHead,
+        });
+    }
+    async detectDivergence(featureId, baseRef) {
+        const worktreePath = this.port.worktreePath(featureId);
+        await runGit(worktreePath, ['fetch', 'origin', baseRef]);
+        const localBase = await runGit(worktreePath, ['merge-base', baseRef, 'HEAD']);
+        if (localBase.code !== 0) {
+            return fail(ERROR_CODES.MERGE_BASE_NOT_FOUND, `Cannot find merge base between ${baseRef} and HEAD`, { featureId, baseRef, retryable: false, requires_human: true });
+        }
+        const mergeBase = localBase.stdout.trim();
+        const localMainlineResult = await runGit(this.port.getRepoRoot(), ['rev-parse', baseRef]);
+        const originMainlineResult = await runGit(worktreePath, ['rev-parse', `origin/${baseRef}`]);
+        const mainlineHead = localMainlineResult.code === 0
+            ? localMainlineResult.stdout.trim()
+            : originMainlineResult.stdout.trim();
+        const worktreeHead = (await runGit(worktreePath, ['rev-parse', 'HEAD'])).stdout.trim();
+        if (mainlineHead === mergeBase || mainlineHead === worktreeHead) {
+            return ok({
+                status: 'up_to_date',
+                divergence_detected: false,
+                files_changed_mainline: [],
+                files_changed_worktree: [],
+                conflicting_files: [],
+                merge_base: mergeBase,
+                mainline_head: mainlineHead,
+                worktree_head: worktreeHead,
+            });
+        }
+        const mainlineDiff = await runGit(worktreePath, [
+            'diff',
+            '--name-only',
+            mergeBase,
+            mainlineHead,
+        ]);
+        const worktreeDiff = await runGit(worktreePath, [
+            'diff',
+            '--name-only',
+            mergeBase,
+            worktreeHead,
+        ]);
+        const filesChangedMainline = parseDiffNameOnly(mainlineDiff.stdout);
+        const filesChangedWorktree = parseDiffNameOnly(worktreeDiff.stdout);
+        const conflictingFiles = intersect(filesChangedMainline, filesChangedWorktree);
+        const status = conflictingFiles.length > 0 ? 'conflict_detected' : 'merged';
+        return ok({
+            status,
+            divergence_detected: true,
+            files_changed_mainline: filesChangedMainline,
+            files_changed_worktree: filesChangedWorktree,
+            conflicting_files: conflictingFiles,
+            merge_base: mergeBase,
+            mainline_head: mainlineHead,
+            worktree_head: worktreeHead,
+        });
+    }
+    async redrivePreparedReconcilerConflict(featureId) {
+        const state = await this.port.readState(featureId).catch(() => null);
+        if (!state) {
+            return false;
+        }
+        const unresolved = findLatestUnresolvedMainlineConflict(state.frontMatter);
+        if (!unresolved.entry) {
+            return false;
+        }
+        const conflictInfo = readConflictInfo(unresolved.entry);
+        const conflictingFiles = await this.listUnmergedFiles(this.port.worktreePath(featureId));
+        const normalizedFiles = conflictingFiles.length > 0 ? conflictingFiles : conflictInfo.conflictingFiles;
+        if (normalizedFiles.length === 0) {
+            return false;
+        }
+        let runtimeSessions;
+        try {
+            runtimeSessions = this.port.normalizeRuntimeSessions(await this.port.readRunLease());
+        }
+        catch {
+            return false;
+        }
+        let sessionId = typeof runtimeSessions.reconciler_session_id === 'string' &&
+            runtimeSessions.reconciler_session_id.length > 0
+            ? runtimeSessions.reconciler_session_id
+            : null;
+        const activeFeatureId = typeof runtimeSessions.reconciler_active_feature_id === 'string' &&
+            runtimeSessions.reconciler_active_feature_id.length > 0
+            ? runtimeSessions.reconciler_active_feature_id
+            : null;
+        if (activeFeatureId !== featureId || sessionId === null) {
+            const claim = await this.claimReconcilerLane(featureId);
+            if (claim.activeFeatureId !== featureId) {
+                return false;
+            }
+            sessionId = claim.sessionId;
+        }
+        const baseRef = typeof unresolved.entry.base_ref === 'string' && unresolved.entry.base_ref.length > 0
+            ? unresolved.entry.base_ref
+            : 'main';
+        await this.upsertMainlineConflictState(featureId, {
+            mergeBase: conflictInfo.mergeBase,
+            mainlineHead: conflictInfo.mainlineHead,
+            worktreeHead: conflictInfo.worktreeHead,
+            conflictingFiles: normalizedFiles,
+        }, {
+            baseRef,
+            resolutionStatus: 'in_progress',
+            queuePosition: 0,
+            statusReason: buildQueueStatusReason(featureId, 0),
+        });
+        return await this.dispatchReconcilerTurn(featureId, baseRef, sessionId, {
+            mergeBase: conflictInfo.mergeBase,
+            mainlineHead: conflictInfo.mainlineHead,
+            worktreeHead: conflictInfo.worktreeHead,
+            conflictingFiles: normalizedFiles,
+        });
+    }
+    async performAutoMerge(featureId, worktreePath, baseRef, mainlineHead) {
+        const statusResult = await runGit(worktreePath, [
+            'status',
+            '--porcelain',
+            '--untracked-files=all',
+        ]);
+        if (statusResult.code !== 0) {
+            return fail(ERROR_CODES.GIT_FAILURE, 'Failed to inspect feature worktree status', {
+                featureId,
+                baseRef,
+                worktree_path: worktreePath,
+                stderr: statusResult.stderr,
+                retryable: false,
+                requires_human: true,
+            });
+        }
+        const dirtyFiles = parseStatusPaths(statusResult.stdout).filter((filePath) => !isIgnoredReconciliationStatusPath(filePath));
+        if (dirtyFiles.length > 0) {
+            return fail(ERROR_CODES.UNCOMMITTED_CHANGES, 'Feature worktree has uncommitted changes - commit or stash them before reconciliation', {
+                featureId,
+                baseRef,
+                worktree_path: worktreePath,
+                files: dirtyFiles,
+                retryable: false,
+                requires_human: true,
+            });
+        }
+        const ffResult = await runGit(worktreePath, ['merge', '--ff-only', `origin/${baseRef}`]);
+        if (ffResult.code === 0) {
+            return ok({ merged: true, strategy: 'fast_forward', mainline_head: mainlineHead });
+        }
+        const rebaseResult = await runGit(worktreePath, ['rebase', `origin/${baseRef}`]);
+        if (rebaseResult.code === 0) {
+            return ok({ merged: true, strategy: 'rebase', mainline_head: mainlineHead });
+        }
+        await runGit(worktreePath, ['rebase', '--abort']);
+        return fail(ERROR_CODES.RECONCILIATION_FAILED, 'Auto-merge failed: fast-forward and rebase both failed', {
+            retryable: false,
+            requires_human: true,
+            ff_stderr: ffResult.stderr,
+            rebase_stderr: rebaseResult.stderr,
+        });
+    }
+    async checkpointFeatureWorktreeIfRequested(featureId, worktreePath, commitMessage) {
+        const normalizedMessage = typeof commitMessage === 'string' ? commitMessage.trim() : '';
+        if (normalizedMessage.length === 0) {
+            return ok({ committed: false, files: [] });
+        }
+        const statusResult = await runGit(worktreePath, [
+            'status',
+            '--porcelain',
+            '--untracked-files=all',
+        ]);
+        if (statusResult.code !== 0) {
+            return fail(ERROR_CODES.GIT_FAILURE, 'Failed to inspect feature worktree before reconciliation', {
+                featureId,
+                worktree_path: worktreePath,
+                stderr: statusResult.stderr,
+                retryable: false,
+                requires_human: true,
+            });
+        }
+        const dirtyFiles = parseStatusPaths(statusResult.stdout).filter((filePath) => !isIgnoredReconciliationStatusPath(filePath));
+        if (dirtyFiles.length === 0) {
+            return ok({ committed: false, files: [] });
+        }
+        const stageResult = await runGit(worktreePath, ['add', '-A']);
+        if (stageResult.code !== 0) {
+            return fail(ERROR_CODES.GIT_FAILURE, 'Failed to stage dirty feature worktree before reconciliation', {
+                featureId,
+                worktree_path: worktreePath,
+                files: dirtyFiles,
+                stderr: stageResult.stderr,
+                retryable: false,
+                requires_human: true,
+            });
+        }
+        const commitResult = await runGit(worktreePath, ['commit', '-m', normalizedMessage]);
+        if (commitResult.code !== 0 &&
+            !commitResult.stderr.includes('nothing to commit') &&
+            !commitResult.stdout.includes('nothing to commit')) {
+            return fail(ERROR_CODES.GIT_FAILURE, 'Failed to checkpoint feature worktree before reconciliation', {
+                featureId,
+                worktree_path: worktreePath,
+                files: dirtyFiles,
+                stderr: commitResult.stderr || commitResult.stdout,
+                retryable: false,
+                requires_human: true,
+            });
+        }
+        return ok({ committed: true, files: dirtyFiles });
+    }
+    async reuseExistingConflictIfPresent(featureId, worktreePath, baseRef) {
+        const state = await this.port.readState(featureId).catch(() => null);
+        if (!state) {
+            return null;
+        }
+        const existing = findLatestUnresolvedMainlineConflict(state.frontMatter);
+        if (!existing.entry) {
+            return null;
+        }
+        const unresolvedFiles = await this.listUnmergedFiles(worktreePath);
+        if (unresolvedFiles.length === 0) {
+            return null;
+        }
+        // Verify the recorded conflict is still valid: if mainline has moved
+        // beyond the recorded head, the stale merge is no longer meaningful.
+        // Abort it so a fresh reconciliation attempt can proceed cleanly.
+        const recordedMainlineHead = readConflictInfo(existing.entry).mainlineHead;
+        if (recordedMainlineHead && recordedMainlineHead !== 'unknown') {
+            const repoRoot = this.port.getRepoRoot();
+            const currentMainlineResult = await runGit(repoRoot, ['rev-parse', baseRef]);
+            const currentMainlineHead = currentMainlineResult.code === 0 ? currentMainlineResult.stdout.trim() : null;
+            if (currentMainlineHead && currentMainlineHead !== recordedMainlineHead) {
+                await runGit(worktreePath, ['merge', '--abort']);
+                return null;
+            }
+        }
+        const conflictInfo = readConflictInfo(existing.entry);
+        const claim = await this.claimReconcilerLane(featureId);
+        const queuePosition = claim.activeFeatureId === featureId ? 0 : (claim.queuePosition ?? 1);
+        await this.upsertMainlineConflictState(featureId, {
+            mergeBase: conflictInfo.mergeBase,
+            mainlineHead: conflictInfo.mainlineHead,
+            worktreeHead: conflictInfo.worktreeHead,
+            conflictingFiles: unresolvedFiles,
+        }, {
+            baseRef,
+            resolutionStatus: claim.activeFeatureId === featureId ? 'in_progress' : 'pending',
+            queuePosition,
+            statusReason: buildQueueStatusReason(claim.activeFeatureId, queuePosition),
+        });
+        const dispatched = claim.activeFeatureId === featureId
+            ? await this.dispatchReconcilerTurn(featureId, baseRef, claim.sessionId, {
+                mergeBase: conflictInfo.mergeBase,
+                mainlineHead: conflictInfo.mainlineHead,
+                worktreeHead: conflictInfo.worktreeHead,
+                conflictingFiles: unresolvedFiles,
+            })
+            : false;
+        return ok({
+            status: 'conflict_detected',
+            divergence_detected: true,
+            files_changed_mainline: [],
+            files_changed_worktree: [],
+            conflicting_files: unresolvedFiles,
+            merge_base: conflictInfo.mergeBase,
+            mainline_head: conflictInfo.mainlineHead,
+            worktree_head: conflictInfo.worktreeHead,
+            reconciler_active_feature_id: claim.activeFeatureId,
+            reconciler_queue_position: queuePosition,
+            dispatched_to_reconciler: dispatched,
+            conflict_worktree_prepared: true,
+        });
+    }
+    async materializeConflictWorktree(featureId, worktreePath, baseRef, mainlineHead) {
+        // Abort any stale in-progress merge before attempting a fresh one.
+        // A leftover MERGE_HEAD from a previous failed reconciliation would cause
+        // the new merge to fail immediately without testing for real conflicts.
+        const staleUnmerged = await this.listUnmergedFiles(worktreePath);
+        if (staleUnmerged.length > 0) {
+            await runGit(worktreePath, ['merge', '--abort']);
+        }
+        const mergeResult = await runGit(worktreePath, ['merge', '--no-commit', '--no-ff', baseRef]);
+        if (mergeResult.code === 0) {
+            const commitMessage = `chore: reconcile ${baseRef} into ${featureId}`;
+            const commitResult = await runGit(worktreePath, ['commit', '-m', commitMessage]);
+            if (commitResult.code !== 0) {
+                await runGit(worktreePath, ['merge', '--abort']);
+                return {
+                    kind: 'error',
+                    response: fail(ERROR_CODES.RECONCILIATION_FAILED, 'Materialized merge succeeded but commit of reconciled worktree failed', {
+                        stderr: commitResult.stderr,
+                        retryable: false,
+                        requires_human: true,
+                    }),
+                };
+            }
+            await this.appendReconciliationLog(featureId, `materialized_merge_commit: ${mainlineHead}`);
+            return { kind: 'merged', strategy: 'merge_commit' };
+        }
+        const unmergedFiles = await this.listUnmergedFiles(worktreePath);
+        if (unmergedFiles.length > 0) {
+            return { kind: 'conflict', conflictingFiles: unmergedFiles };
+        }
+        await runGit(worktreePath, ['merge', '--abort']);
+        return {
+            kind: 'error',
+            response: fail(ERROR_CODES.RECONCILIATION_FAILED, 'Failed to materialize a merge-conflict worktree for reconciler handoff', {
+                stderr: mergeResult.stderr || mergeResult.stdout,
+                retryable: false,
+                requires_human: true,
+            }),
+        };
+    }
+    async listUnmergedFiles(worktreePath) {
+        const status = await runGit(worktreePath, ['diff', '--name-only', '--diff-filter=U']);
+        if (status.code !== 0) {
+            return [];
+        }
+        return parseDiffNameOnly(status.stdout);
+    }
+    async claimReconcilerLane(featureId) {
+        return await this.port.withIndexLock(async () => {
+            const runtimeSessions = this.port.normalizeRuntimeSessions(await this.port.readRunLease());
+            const activeFeatureId = typeof runtimeSessions.reconciler_active_feature_id === 'string' &&
+                runtimeSessions.reconciler_active_feature_id.length > 0
+                ? runtimeSessions.reconciler_active_feature_id
+                : null;
+            let queue = normalizeQueue(asStringArray(runtimeSessions.reconciler_queue)).filter((queuedFeatureId) => queuedFeatureId !== activeFeatureId);
+            let nextActiveFeatureId = activeFeatureId;
+            let dispatchNow = false;
+            if (!nextActiveFeatureId) {
+                nextActiveFeatureId = featureId;
+                queue = queue.filter((queuedFeatureId) => queuedFeatureId !== featureId);
+                dispatchNow = true;
+            }
+            else if (nextActiveFeatureId !== featureId && !queue.includes(featureId)) {
+                queue = [...queue, featureId];
+            }
+            const updated = {
+                ...runtimeSessions,
+                reconciler_active_feature_id: nextActiveFeatureId,
+                reconciler_queue: queue,
+            };
+            await this.port.writeRunLease(updated);
+            return {
+                activeFeatureId: nextActiveFeatureId,
+                sessionId: typeof updated.reconciler_session_id === 'string' &&
+                    updated.reconciler_session_id.length > 0
+                    ? updated.reconciler_session_id
+                    : null,
+                queuePosition: nextActiveFeatureId === featureId ? 0 : Math.max(1, queue.indexOf(featureId) + 1),
+                dispatchNow,
+            };
+        });
+    }
+    async releaseReconcilerLane(featureId) {
+        return await this.port.withIndexLock(async () => {
+            const runtimeSessions = this.port.normalizeRuntimeSessions(await this.port.readRunLease());
+            const queue = normalizeQueue(asStringArray(runtimeSessions.reconciler_queue)).filter((queuedFeatureId) => queuedFeatureId !== featureId);
+            const activeFeatureId = typeof runtimeSessions.reconciler_active_feature_id === 'string' &&
+                runtimeSessions.reconciler_active_feature_id.length > 0
+                ? runtimeSessions.reconciler_active_feature_id
+                : null;
+            let nextFeatureId = activeFeatureId;
+            let nextQueue = queue;
+            if (activeFeatureId === featureId) {
+                nextFeatureId = queue[0] ?? null;
+                nextQueue = nextFeatureId ? queue.slice(1) : [];
+            }
+            const updated = {
+                ...runtimeSessions,
+                reconciler_active_feature_id: nextFeatureId,
+                reconciler_queue: nextQueue,
+            };
+            await this.port.writeRunLease(updated);
+            return {
+                nextFeatureId,
+                sessionId: typeof updated.reconciler_session_id === 'string' &&
+                    updated.reconciler_session_id.length > 0
+                    ? updated.reconciler_session_id
+                    : null,
+            };
+        });
+    }
+    async releaseAndDispatchNext(featureId, baseRef) {
+        let release = await this.releaseReconcilerLane(featureId);
+        while (release.nextFeatureId) {
+            const activated = await this.activateQueuedFeature(release.nextFeatureId, baseRef, release.sessionId);
+            if (activated) {
+                return;
+            }
+            release = await this.releaseReconcilerLane(release.nextFeatureId);
+        }
+    }
+    async activateQueuedFeature(featureId, baseRef, sessionId) {
+        const state = await this.port.readState(featureId).catch(() => null);
+        if (!state) {
+            return false;
+        }
+        const unresolved = findLatestUnresolvedMainlineConflict(state.frontMatter);
+        if (!unresolved.entry) {
+            return false;
+        }
+        const conflictInfo = readConflictInfo(unresolved.entry);
+        const unmergedFiles = await this.listUnmergedFiles(this.port.worktreePath(featureId));
+        const conflictingFiles = unmergedFiles.length > 0 ? unmergedFiles : conflictInfo.conflictingFiles;
+        if (conflictingFiles.length === 0) {
+            return false;
+        }
+        await this.upsertMainlineConflictState(featureId, {
+            mergeBase: conflictInfo.mergeBase,
+            mainlineHead: conflictInfo.mainlineHead,
+            worktreeHead: conflictInfo.worktreeHead,
+            conflictingFiles,
+        }, {
+            baseRef,
+            resolutionStatus: 'in_progress',
+            queuePosition: 0,
+            statusReason: buildQueueStatusReason(featureId, 0),
+        });
+        await this.dispatchReconcilerTurn(featureId, baseRef, sessionId, {
+            mergeBase: conflictInfo.mergeBase,
+            mainlineHead: conflictInfo.mainlineHead,
+            worktreeHead: conflictInfo.worktreeHead,
+            conflictingFiles,
+        });
+        return true;
+    }
+    async dispatchReconcilerTurn(featureId, baseRef, sessionId, info) {
+        if (!sessionId || sessionId === 'unknown' || sessionId === 'unassigned') {
+            return false;
+        }
+        const provider = this.port.getProvider();
+        if (!provider?.sendMessage) {
+            return false;
+        }
+        await this.waitForSessionToBecomeActive(provider, sessionId);
+        const approvedCollisionContexts = await this.approvedCollisionContextsForFeature(featureId);
+        const message = [
+            `Reconciler lane assignment: feature_id=${featureId}`,
+            `base_ref=${baseRef}`,
+            `merge_base=${info.mergeBase}`,
+            `mainline_head=${info.mainlineHead}`,
+            `worktree_head=${info.worktreeHead}`,
+            'The feature worktree is already in a real conflicted merge state created by `git merge --no-commit --no-ff`.',
+            'Operate only on this feature until its mainline_divergence conflict is resolved.',
+            'Use feature-scoped tool calls with this exact feature_id.',
+            `Conflicting files: ${info.conflictingFiles.join(', ') || 'unknown'}`,
+            `approved_collision_context: ${JSON.stringify(approvedCollisionContexts)}`,
+        ].join('\n');
+        try {
+            await provider.sendMessage(sessionId, message);
+        }
+        catch (error) {
+            if (isMissingReconcilerConversation(error) && this.port.refreshReconcilerSession) {
+                const refreshedSessionId = await this.port.refreshReconcilerSession().catch(() => null);
+                if (refreshedSessionId &&
+                    refreshedSessionId !== 'unknown' &&
+                    refreshedSessionId !== 'unassigned' &&
+                    refreshedSessionId !== sessionId) {
+                    try {
+                        await this.waitForSessionToBecomeActive(provider, refreshedSessionId);
+                        await provider.sendMessage(refreshedSessionId, message);
+                        await this.appendReconciliationLog(featureId, `reconciler_session_refreshed old_session_id=${sessionId} new_session_id=${refreshedSessionId}`);
+                        return true;
+                    }
+                    catch (retryError) {
+                        await this.appendReconciliationLog(featureId, `dispatch_failed: ${errorMessage(retryError)} session_id=${refreshedSessionId}`);
+                        return false;
+                    }
+                }
+            }
+            await this.appendReconciliationLog(featureId, `dispatch_failed: ${errorMessage(error)} session_id=${sessionId}`);
+            return false;
+        }
+        await this.appendReconciliationLog(featureId, approvedCollisionContexts.length > 0
+            ? `dispatched_with_approved_collision_context override_ids=${approvedCollisionContexts
+                .map((entry) => entry.override_id)
+                .join(',')}`
+            : 'dispatched_without_approved_collision_context');
+        return true;
+    }
+    async waitForSessionToBecomeActive(provider, sessionId) {
+        if (!provider.getSessionInfo) {
+            return;
+        }
+        const timeoutMs = 5000;
+        const pollIntervalMs = 250;
+        const deadline = Date.now() + timeoutMs;
+        while (Date.now() <= deadline) {
+            const sessionInfo = await provider.getSessionInfo(sessionId).catch(() => null);
+            if (sessionInfo?.active) {
+                return;
+            }
+            await new Promise((resolve) => {
+                setTimeout(resolve, pollIntervalMs);
+            });
+        }
+    }
+    async updateReconciliationState(featureId, mainlineHead) {
+        try {
+            await this.port.withFeatureLock(featureId, async () => {
+                const { frontMatter, body } = await this.port.readState(featureId);
+                await this.port.writeState(featureId, {
+                    ...frontMatter,
+                    version: readFrontMatterVersion(frontMatter) + 1,
+                    last_updated: nowIso(),
+                    last_reconciliation_at: nowIso(),
+                    last_reconciliation_sha: mainlineHead,
+                }, body);
+            });
+        }
+        catch {
+            // Non-fatal
+        }
+    }
+    async upsertMainlineConflictState(featureId, info, options) {
+        try {
+            await this.port.withFeatureLock(featureId, async () => {
+                const { frontMatter, body } = await this.port.readState(featureId);
+                const conflicts = Array.isArray(frontMatter.conflicts) ? [...frontMatter.conflicts] : [];
+                const unresolved = findLatestUnresolvedMainlineConflict(frontMatter);
+                const detectedAt = typeof unresolved.entry?.detected_at === 'string'
+                    ? unresolved.entry.detected_at
+                    : nowIso();
+                const resumeStatus = typeof unresolved.entry?.resume_status === 'string'
+                    ? unresolved.entry.resume_status
+                    : frontMatter.status === STATUS.BLOCKED
+                        ? STATUS.BUILDING
+                        : frontMatter.status;
+                const queueMetadata = {
+                    queue_position: options.queuePosition,
+                    queued_at: typeof unresolved.entry?.queued_at === 'string' ? unresolved.entry.queued_at : nowIso(),
+                    status_reason: options.statusReason,
+                };
+                const nextConflict = {
+                    ...(unresolved.entry ?? {}),
+                    type: 'mainline_divergence',
+                    detected_at: detectedAt,
+                    base_ref: options.baseRef,
+                    merge_base: info.mergeBase,
+                    mainline_head: info.mainlineHead,
+                    worktree_head: info.worktreeHead,
+                    conflicting_files: info.conflictingFiles,
+                    resolution_status: options.resolutionStatus,
+                    resume_status: resumeStatus,
+                    ...queueMetadata,
+                    ...(options.resolutionStatus === 'in_progress' ? { dispatched_at: nowIso() } : {}),
+                };
+                if (unresolved.index >= 0) {
+                    conflicts[unresolved.index] = nextConflict;
+                }
+                else {
+                    conflicts.push(nextConflict);
+                }
+                // When the reconciler is assigned (in_progress or queued), set recovery.state
+                // so the dashboard distinguishes automated recovery from hard operator blocks.
+                const reconcilerAssigned = options.resolutionStatus === 'in_progress' || options.resolutionStatus === 'pending';
+                const recoveryState = reconcilerAssigned
+                    ? {
+                        state: 'retrying',
+                        cause: 'mainline_divergence',
+                        role: 'reconciler',
+                        resume_phase: resumeStatus,
+                        attempt: null,
+                        run_id: null,
+                        started_at: nowIso(),
+                        last_attempt_at: nowIso(),
+                    }
+                    : null;
+                await this.port.writeState(featureId, {
+                    ...frontMatter,
+                    version: readFrontMatterVersion(frontMatter) + 1,
+                    last_updated: nowIso(),
+                    status: STATUS.BLOCKED,
+                    status_reason: options.statusReason,
+                    last_reconciliation_at: nowIso(),
+                    recovery: recoveryState,
+                    conflicts,
+                }, body);
+            });
+        }
+        catch {
+            // Non-fatal
+        }
+    }
+    async resolveMainlineConflictState(featureId, mainlineHead) {
+        try {
+            await this.port.withFeatureLock(featureId, async () => {
+                const { frontMatter, body } = await this.port.readState(featureId);
+                const conflicts = Array.isArray(frontMatter.conflicts) ? [...frontMatter.conflicts] : [];
+                let resumeStatus = null;
+                let changed = false;
+                for (let index = 0; index < conflicts.length; index += 1) {
+                    const entry = conflicts[index];
+                    if (!entry || typeof entry !== 'object' || entry.type !== 'mainline_divergence') {
+                        continue;
+                    }
+                    if (entry.resolution_status === 'resolved') {
+                        continue;
+                    }
+                    if (typeof entry.resume_status === 'string' && entry.resume_status.length > 0) {
+                        resumeStatus = entry.resume_status;
+                    }
+                    conflicts[index] = {
+                        ...entry,
+                        resolution_status: 'resolved',
+                        resolved_at: nowIso(),
+                        resolved_mainline_head: mainlineHead,
+                    };
+                    changed = true;
+                }
+                if (!changed) {
+                    return;
+                }
+                await this.port.writeState(featureId, {
+                    ...frontMatter,
+                    version: readFrontMatterVersion(frontMatter) + 1,
+                    last_updated: nowIso(),
+                    status: frontMatter.status === STATUS.BLOCKED && resumeStatus
+                        ? resumeStatus
+                        : frontMatter.status,
+                    status_reason: `Reconciled against ${mainlineHead}`,
+                    last_reconciliation_at: nowIso(),
+                    last_reconciliation_sha: mainlineHead,
+                    recovery: null,
+                    conflicts,
+                }, body);
+                await this.appendReconciliationCompletionLog(featureId);
+            });
+        }
+        catch {
+            // Non-fatal
+        }
+    }
+    async appendReconciliationCompletionLog(featureId) {
+        const approvedCollisionContexts = await this.approvedCollisionContextsForFeature(featureId);
+        const usedApprovedCollisionContext = approvedCollisionContexts.length > 0;
+        const completionSummary = {
+            approved_collision_context_used: usedApprovedCollisionContext,
+            override_ids: approvedCollisionContexts.map((entry) => entry.override_id),
+            counterpart_feature_ids: approvedCollisionContexts.map((entry) => entry.counterpart_feature_id),
+            source_collision_ids: approvedCollisionContexts.map((entry) => entry.source_collision_id),
+            counterpart_behavior_preserved: usedApprovedCollisionContext
+                ? 'not_reported_by_reconciler'
+                : 'not_applicable',
+            residual_compromise_or_follow_up: usedApprovedCollisionContext
+                ? 'not_reported_by_reconciler'
+                : 'none',
+            summary_source: 'service_resolution',
+        };
+        await this.appendReconciliationLog(featureId, `reconciliation_completion_summary ${JSON.stringify(completionSummary)}`);
+    }
+    async writeEvidenceArtifacts(featureId, worktreePath, mergeBase, mainlineHead, worktreeHead, conflictingFiles) {
+        try {
+            const timestamp = nowIso().replaceAll(':', '-').replaceAll('.', '-');
+            const evidenceDir = path.join(this.port.evidencePath(featureId), 'reconciliation');
+            await ensureDir(evidenceDir);
+            const mainlineDiff = await runGit(worktreePath, ['diff', `${mergeBase}..${mainlineHead}`]);
+            if (mainlineDiff.code === 0 && mainlineDiff.stdout) {
+                await fs.writeFile(path.join(evidenceDir, `${timestamp}-mainline-diff.patch`), mainlineDiff.stdout, 'utf8');
+            }
+            const worktreeDiff = await runGit(worktreePath, ['diff', `${mergeBase}..${worktreeHead}`]);
+            if (worktreeDiff.code === 0 && worktreeDiff.stdout) {
+                await fs.writeFile(path.join(evidenceDir, `${timestamp}-worktree-diff.patch`), worktreeDiff.stdout, 'utf8');
+            }
+            if (conflictingFiles.length > 0) {
+                await fs.writeFile(path.join(evidenceDir, `${timestamp}-conflict-markers.txt`), conflictingFiles.join('\n'), 'utf8');
+            }
+        }
+        catch {
+            // Non-fatal
+        }
+    }
+    async appendReconciliationLog(featureId, message) {
+        try {
+            const logDir = this.port.logsPath(featureId);
+            await ensureDir(logDir);
+            const logFile = path.join(logDir, 'reconciliation.log');
+            const line = `${nowIso()} ${message}\n`;
+            await fs.appendFile(logFile, line, 'utf8');
+        }
+        catch {
+            // Non-fatal
+        }
+    }
+    async approvedCollisionContextsForFeature(featureId) {
+        if (!this.port.readIndex) {
+            return [];
+        }
+        const index = await this.port.readIndex().catch(() => null);
+        if (!index) {
+            return [];
+        }
+        const overrides = asCollisionOverrides(index.collision_overrides).filter((entry) => entry.feature_ids.includes(featureId) &&
+            (entry.status === 'active' || entry.status === 'applied'));
+        const records = asCollisionRecords(index.collision_records);
+        return overrides
+            .map((override) => {
+            const record = records.find((entry) => entry.collision_id === override.source_collision_id);
+            if (!record) {
+                return null;
+            }
+            return {
+                override_id: override.override_id,
+                counterpart_feature_id: override.feature_ids[0] === featureId
+                    ? override.feature_ids[1]
+                    : override.feature_ids[0],
+                rationale: override.rationale,
+                approved_paths: override.approved_paths,
+                approved_collision_fingerprint: override.approved_collision_fingerprint,
+                source_collision_id: override.source_collision_id,
+                detected_at: record.detected_at,
+                applied_at: override.applied_at,
+                source_collision_record: record,
+            };
+        })
+            .filter(defined);
+    }
+}
+//# sourceMappingURL=git-reconciliation-service.js.map