agentic-orchestrator 0.1.27 → 0.2.0

package/apps/control-plane/src/application/services/git-reconciliation-service.ts

@@ -0,0 +1,1591 @@
+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, type ToolResponse } from '../../core/response.js';
+import type { RuntimeSessionsSnapshot } from '../../core/runtime-sessions.js';
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type AnyRecord = Record<string, any>;
+
+type MainlineConflictEntry = AnyRecord & {
+  type: 'mainline_divergence';
+  merge_base: string;
+  mainline_head: string;
+  worktree_head: string;
+  conflicting_files: string[];
+  resolution_status: 'pending' | 'in_progress' | 'resolved';
+};
+
+interface ReconciliationControlProvider {
+  sendMessage?(sessionId: string, message: string): Promise<void>;
+  getSessionInfo?(sessionId: string): Promise<{ active: boolean; provider: string }>;
+}
+
+function readFrontMatterVersion(frontMatter: AnyRecord): number {
+  const raw = frontMatter.version;
+  return typeof raw === 'number' && Number.isFinite(raw) ? raw : 0;
+}
+
+type MaterializedConflictResult =
+  | { kind: 'merged'; strategy: 'merge_commit' }
+  | { kind: 'conflict'; conflictingFiles: string[] }
+  | { kind: 'error'; response: ToolResponse<ReconciliationResult> };
+
+type ReconcilerLaneClaim = {
+  activeFeatureId: string | null;
+  sessionId: string | null;
+  queuePosition: number | null;
+  dispatchNow: boolean;
+};
+
+type ReconcilerLaneRelease = {
+  nextFeatureId: string | null;
+  sessionId: string | null;
+};
+
+type CollisionOverride = {
+  override_id: string;
+  feature_ids: [string, string];
+  rationale: string;
+  approved_paths: string[];
+  approved_collision_fingerprint: string;
+  status: 'active' | 'stale' | 'revoked' | 'applied';
+  source_collision_id: string;
+  applied_at?: string;
+};
+
+type CollisionRecord = {
+  collision_id: string;
+  detected_at: string;
+  [key: string]: unknown;
+};
+
+type ApprovedCollisionContext = {
+  override_id: string;
+  counterpart_feature_id: string;
+  rationale: string;
+  approved_paths: string[];
+  approved_collision_fingerprint: string;
+  source_collision_id: string;
+  detected_at: string;
+  applied_at?: string;
+  source_collision_record: CollisionRecord;
+};
+
+/**
+ * Result of a remote/local mainline divergence check.
+ */
+export type RemoteLocalDivergenceResult = {
+  diverged: boolean;
+  local_ahead: boolean;
+  local_head: string;
+  remote_head: string;
+};
+
+/**
+ * Result of a mainline reconciliation operation.
+ */
+export type ReconciliationResult = {
+  status: 'up_to_date' | 'merged' | 'conflict_detected';
+  divergence_detected: boolean;
+  files_changed_mainline: string[];
+  files_changed_worktree: string[];
+  conflicting_files: string[];
+  merge_base: string;
+  mainline_head: string;
+  worktree_head: string;
+  reconciler_active_feature_id?: string | null;
+  reconciler_queue_position?: number | null;
+  dispatched_to_reconciler?: boolean;
+  conflict_worktree_prepared?: boolean;
+};
+
+/**
+ * Port interface for the reconciliation service dependencies.
+ */
+export interface GitReconciliationServicePort {
+  getRepoRoot(): string;
+  worktreePath(featureId: string): string;
+  readState(featureId: string): Promise<{ frontMatter: AnyRecord; body: string }>;
+  writeState(featureId: string, frontMatter: AnyRecord, body?: string): Promise<void>;
+  withFeatureLock<T>(featureId: string, operation: () => Promise<T>): Promise<T>;
+  readIndex?(): Promise<AnyRecord>;
+  evidencePath(featureId: string): string;
+  logsPath(featureId: string): string;
+  withIndexLock<T>(operation: () => Promise<T>): Promise<T>;
+  readRunLease(): Promise<RuntimeSessionsSnapshot>;
+  writeRunLease(data: RuntimeSessionsSnapshot): Promise<void>;
+  normalizeRuntimeSessions(value: unknown, at?: string): RuntimeSessionsSnapshot;
+  getProvider(): ReconciliationControlProvider | null;
+  refreshReconcilerSession?(): Promise<string | null>;
+}
+
+function parseDiffNameOnly(stdout: string): string[] {
+  return stdout
+    .split('\n')
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0);
+}
+
+function parseStatusPaths(statusPorcelain: string): string[] {
+  const files: string[] = [];
+  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: string): boolean {
+  return (
+    filePath.startsWith('.aop/') ||
+    filePath.startsWith('.worktrees/') ||
+    filePath === 'agentic/orchestrator/tools.md'
+  );
+}
+
+function intersect(a: string[], b: string[]): string[] {
+  const setB = new Set(b);
+  return a.filter((f) => setB.has(f));
+}
+
+function asStringArray(value: unknown): string[] {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value.filter((item): item is string => typeof item === 'string' && item.length > 0);
+}
+
+function normalizeQueue(queue: string[]): string[] {
+  const seen = new Set<string>();
+  const normalized: string[] = [];
+  for (const featureId of queue) {
+    if (seen.has(featureId)) {
+      continue;
+    }
+    seen.add(featureId);
+    normalized.push(featureId);
+  }
+  return normalized;
+}
+
+function asCollisionOverrides(value: unknown): CollisionOverride[] {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value.filter(
+    (entry): entry is CollisionOverride => entry !== null && typeof entry === 'object',
+  );
+}
+
+function asCollisionRecords(value: unknown): CollisionRecord[] {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value.filter(
+    (entry): entry is CollisionRecord => entry !== null && typeof entry === 'object',
+  );
+}
+
+function defined<T>(value: T | null): value is T {
+  return value !== null;
+}
+
+function findLatestUnresolvedMainlineConflict(frontMatter: AnyRecord): {
+  index: number;
+  entry: MainlineConflictEntry | null;
+} {
+  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 as MainlineConflictEntry;
+    if (typed.resolution_status === 'resolved') {
+      continue;
+    }
+    return { index, entry: typed };
+  }
+  return { index: -1, entry: null };
+}
+
+function readConflictInfo(conflict: MainlineConflictEntry | null): {
+  mergeBase: string;
+  mainlineHead: string;
+  worktreeHead: string;
+  conflictingFiles: string[];
+} {
+  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: string | null,
+  queuePosition: number | null,
+): string {
+  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: unknown): string {
+  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 as Record<string, unknown>)
+        : 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: unknown): boolean {
+  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 as Record<string, unknown>)
+      : 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 {
+  private readonly port: GitReconciliationServicePort;
+
+  constructor(port: GitReconciliationServicePort) {
+    this.port = port;
+  }
+
+  async checkRemoteLocalDivergence(
+    baseRef: string,
+  ): Promise<ToolResponse<RemoteLocalDivergenceResult>> {
+    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<RemoteLocalDivergenceResult>({
+        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<RemoteLocalDivergenceResult>({
+        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<RemoteLocalDivergenceResult>({
+        diverged: false,
+        local_ahead: true,
+        local_head: localHead,
+        remote_head: remoteHead,
+      });
+    }
+
+    // True divergence — remote has commits local doesn't
+    return ok<RemoteLocalDivergenceResult>({
+      diverged: true,
+      local_ahead: false,
+      local_head: localHead,
+      remote_head: remoteHead,
+    });
+  }
+
+  async syncMainlineFromRemote(
+    baseRef: string,
+  ): Promise<ToolResponse<{ merged: boolean; sha: string }>> {
+    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: string,
+    baseRef: string,
+    checkpointCommitMessage: string | null = null,
+  ): Promise<ToolResponse<ReconciliationResult>> {
+    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 as ToolResponse<ReconciliationResult>;
+    }
+
+    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<ReconciliationResult>({
+        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<ReconciliationResult>({
+          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<ReconciliationResult>({
+        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 as ToolResponse<ReconciliationResult>;
+    }
+
+    await this.updateReconciliationState(featureId, mainlineHead);
+    await this.resolveMainlineConflictState(featureId, mainlineHead);
+    await this.releaseAndDispatchNext(featureId, baseRef);
+    await this.appendReconciliationLog(featureId, `merged: ${mainlineHead}`);
+
+    return ok<ReconciliationResult>({
+      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: string,
+    baseRef: string,
+  ): Promise<ToolResponse<ReconciliationResult>> {
+    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<ReconciliationResult>({
+        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<ReconciliationResult>({
+      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: string): Promise<boolean> {
+    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: RuntimeSessionsSnapshot;
+    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,
+    });
+  }
+
+  private async performAutoMerge(
+    featureId: string,
+    worktreePath: string,
+    baseRef: string,
+    mainlineHead: string,
+  ): Promise<ToolResponse> {
+    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,
+      },
+    );
+  }
+
+  private async checkpointFeatureWorktreeIfRequested(
+    featureId: string,
+    worktreePath: string,
+    commitMessage: string | null,
+  ): Promise<ToolResponse<{ committed: boolean; files: string[] }>> {
+    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 });
+  }
+
+  private async reuseExistingConflictIfPresent(
+    featureId: string,
+    worktreePath: string,
+    baseRef: string,
+  ): Promise<ToolResponse<ReconciliationResult> | null> {
+    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<ReconciliationResult>({
+      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,
+    });
+  }
+
+  private async materializeConflictWorktree(
+    featureId: string,
+    worktreePath: string,
+    baseRef: string,
+    mainlineHead: string,
+  ): Promise<MaterializedConflictResult> {
+    // 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,
+        },
+      ),
+    };
+  }
+
+  private async listUnmergedFiles(worktreePath: string): Promise<string[]> {
+    const status = await runGit(worktreePath, ['diff', '--name-only', '--diff-filter=U']);
+    if (status.code !== 0) {
+      return [];
+    }
+    return parseDiffNameOnly(status.stdout);
+  }
+
+  private async claimReconcilerLane(featureId: string): Promise<ReconcilerLaneClaim> {
+    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: RuntimeSessionsSnapshot = {
+        ...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,
+      };
+    });
+  }
+
+  private async releaseReconcilerLane(featureId: string): Promise<ReconcilerLaneRelease> {
+    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: RuntimeSessionsSnapshot = {
+        ...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,
+      };
+    });
+  }
+
+  private async releaseAndDispatchNext(featureId: string, baseRef: string): Promise<void> {
+    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);
+    }
+  }
+
+  private async activateQueuedFeature(
+    featureId: string,
+    baseRef: string,
+    sessionId: string | null,
+  ): Promise<boolean> {
+    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;
+  }
+
+  private async dispatchReconcilerTurn(
+    featureId: string,
+    baseRef: string,
+    sessionId: string | null,
+    info: {
+      mergeBase: string;
+      mainlineHead: string;
+      worktreeHead: string;
+      conflictingFiles: string[];
+    },
+  ): Promise<boolean> {
+    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;
+  }
+
+  private async waitForSessionToBecomeActive(
+    provider: ReconciliationControlProvider,
+    sessionId: string,
+  ): Promise<void> {
+    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<void>((resolve) => {
+        setTimeout(resolve, pollIntervalMs);
+      });
+    }
+  }
+
+  private async updateReconciliationState(featureId: string, mainlineHead: string): Promise<void> {
+    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
+    }
+  }
+
+  private async upsertMainlineConflictState(
+    featureId: string,
+    info: {
+      mergeBase: string;
+      mainlineHead: string;
+      worktreeHead: string;
+      conflictingFiles: string[];
+    },
+    options: {
+      baseRef: string;
+      resolutionStatus: 'pending' | 'in_progress';
+      queuePosition: number;
+      statusReason: string;
+    },
+  ): Promise<void> {
+    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: MainlineConflictEntry = {
+          ...(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' as const,
+              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
+    }
+  }
+
+  private async resolveMainlineConflictState(
+    featureId: string,
+    mainlineHead: string,
+  ): Promise<void> {
+    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: string | null = 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
+    }
+  }
+
+  private async appendReconciliationCompletionLog(featureId: string): Promise<void> {
+    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)}`,
+    );
+  }
+
+  private async writeEvidenceArtifacts(
+    featureId: string,
+    worktreePath: string,
+    mergeBase: string,
+    mainlineHead: string,
+    worktreeHead: string,
+    conflictingFiles: string[],
+  ): Promise<void> {
+    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
+    }
+  }
+
+  private async appendReconciliationLog(featureId: string, message: string): Promise<void> {
+    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
+    }
+  }
+
+  private async approvedCollisionContextsForFeature(
+    featureId: string,
+  ): Promise<ApprovedCollisionContext[]> {
+    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);
+  }
+}