agentic-orchestrator 0.1.28 → 0.2.0

package/apps/control-plane/test/git-reconciliation-service.spec.ts

@@ -0,0 +1,2307 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import type { FailResponse } from '../src/core/response.js';
+
+// ---------------------------------------------------------------------------
+// Hoisted mocks
+// ---------------------------------------------------------------------------
+const ensureDirMock = vi.hoisted(() => vi.fn(async () => {}));
+const nowIsoMock = vi.hoisted(() => vi.fn(() => '2026-01-01T00:00:00.000Z'));
+const runGitMock = vi.hoisted(() => vi.fn());
+const fsWriteFileMock = vi.hoisted(() => vi.fn(async () => {}));
+const fsAppendFileMock = vi.hoisted(() => vi.fn(async () => {}));
+
+vi.mock('../src/core/fs.js', () => ({
+  ensureDir: ensureDirMock,
+  nowIso: nowIsoMock,
+}));
+
+vi.mock('../src/core/git.js', () => ({
+  runGit: runGitMock,
+}));
+
+vi.mock('node:fs/promises', () => ({
+  default: {
+    writeFile: fsWriteFileMock,
+    appendFile: fsAppendFileMock,
+  },
+}));
+
+import {
+  GitReconciliationService,
+  type GitReconciliationServicePort,
+} from '../src/application/services/git-reconciliation-service.js';
+import type { RuntimeSessionsSnapshot } from '../src/core/runtime-sessions.js';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function cmdResult(
+  overrides: Partial<{
+    code: number;
+    signal: NodeJS.Signals | null;
+    stdout: string;
+    stderr: string;
+    timeout: boolean;
+  }> = {},
+) {
+  return { code: 0, signal: null, stdout: '', stderr: '', timeout: false, ...overrides };
+}
+
+function makePort(
+  overrides: Partial<GitReconciliationServicePort> = {},
+): GitReconciliationServicePort {
+  return {
+    getRepoRoot: vi.fn(() => '/repo'),
+    worktreePath: vi.fn((_id: string) => '/repo/.worktrees/feat1'),
+    readState: vi.fn(async (_id: string) => ({
+      frontMatter: { feature_id: 'feat1', version: 1, status: 'building' } as Record<
+        string,
+        unknown
+      >,
+      body: '# Feature\n',
+    })),
+    writeState: vi.fn(async () => {}),
+    withFeatureLock: (async <T>(_featureId: string, operation: () => Promise<T>) =>
+      await operation()) as GitReconciliationServicePort['withFeatureLock'],
+    readIndex: vi.fn(async () => ({
+      collision_overrides: [],
+      collision_records: [],
+    })),
+    evidencePath: vi.fn((_id: string) => '/repo/.aop/features/feat1/evidence'),
+    logsPath: vi.fn((_id: string) => '/repo/.aop/features/feat1/logs'),
+    withIndexLock: (async <T>(operation: () => Promise<T>) =>
+      await operation()) as GitReconciliationServicePort['withIndexLock'],
+    readRunLease: vi.fn(
+      async () =>
+        ({
+          run_id: 'run:test',
+          orchestrator_session_id: 'orchestrator:1',
+          reconciler_session_id: 'reconciler:1',
+          reconciler_active_feature_id: null,
+          reconciler_queue: [],
+          provider: 'codex',
+          model: 'codex-default',
+          provider_config_ref_hash: 'hash',
+          owner_instance_id: 'owner:test',
+          lease_id: 'lease:test',
+          started_at: '2026-01-01T00:00:00.000Z',
+          last_heartbeat_at: '2026-01-01T00:00:00.000Z',
+          lease_expires_at: '2026-01-01T00:05:00.000Z',
+          feature_sessions: {},
+        }) satisfies RuntimeSessionsSnapshot,
+    ),
+    writeRunLease: vi.fn(async () => {}),
+    normalizeRuntimeSessions: vi.fn((value: RuntimeSessionsSnapshot) => value),
+    getProvider: vi.fn(() => null),
+    ...overrides,
+  };
+}
+
+function makeSvc(portOverrides: Partial<GitReconciliationServicePort> = {}) {
+  return new GitReconciliationService(makePort(portOverrides));
+}
+
+// ---------------------------------------------------------------------------
+// reconcileWithMainline — up_to_date
+// ---------------------------------------------------------------------------
+
+describe('GitReconciliationService.reconcileWithMainline', () => {
+  beforeEach(() => {
+    vi.resetAllMocks();
+    nowIsoMock.mockReturnValue('2026-01-01T00:00:00.000Z');
+  });
+
+  it('GIVEN_worktree_up_to_date_WHEN_reconcile_THEN_returns_up_to_date', async () => {
+    const mergeBase = 'abc123';
+    runGitMock
+      .mockResolvedValueOnce(cmdResult({ code: 0 })) // fetch
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: `${mergeBase}\n` })) // merge-base main HEAD (local)
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: `${mergeBase}\n` })) // rev-parse main (repoRoot) → mainlineHead === mergeBase → up_to_date
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'origin123\n' })) // rev-parse origin/main (fallback, not used)
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'worktree456\n' })); // rev-parse HEAD
+
+    const svc = makeSvc();
+    const result = await svc.reconcileWithMainline('feat1', 'main');
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) {
+      return;
+    }
+    expect(result.data.status).toBe('up_to_date');
+    expect(result.data.divergence_detected).toBe(false);
+    expect(result.data.conflicting_files).toHaveLength(0);
+  });
+
+  it('GIVEN_fast_forward_possible_WHEN_reconcile_THEN_returns_merged_with_ff_strategy', async () => {
+    runGitMock
+      .mockResolvedValueOnce(cmdResult({ code: 0 })) // fetch
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'base001\n' })) // merge-base main HEAD (local)
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'main999\n' })) // rev-parse main (repoRoot) — mainlineHead
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'origin999\n' })) // rev-parse origin/main (fallback, not used)
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'feat111\n' })) // rev-parse HEAD (worktree)
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'fileA.ts\n' })) // mainline diff
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'fileB.ts\n' })) // worktree diff
+      .mockResolvedValueOnce(cmdResult({ code: 0 })) // write evidence — mainline diff
+      .mockResolvedValueOnce(cmdResult({ code: 0 })) // write evidence — worktree diff
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: '' })) // status --porcelain
+      .mockResolvedValueOnce(cmdResult({ code: 0 })) // ff merge succeeds
+      .mockResolvedValueOnce(cmdResult({ code: 0 })); // any remaining
+
+    const svc = makeSvc();
+    const result = await svc.reconcileWithMainline('feat1', 'main');
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) {
+      return;
+    }
+    expect(result.data.status).toBe('merged');
+    expect(result.data.divergence_detected).toBe(true);
+    expect(result.data.conflicting_files).toHaveLength(0);
+  });
+
+  it('GIVEN_ff_fails_but_rebase_succeeds_WHEN_reconcile_THEN_returns_merged', async () => {
+    runGitMock
+      .mockResolvedValueOnce(cmdResult({ code: 0 })) // fetch
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'base001\n' })) // merge-base main HEAD (local)
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'main999\n' })) // rev-parse main (repoRoot)
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'origin999\n' })) // rev-parse origin/main (fallback, not used)
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'feat111\n' })) // rev-parse HEAD (worktree)
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: '' })) // mainline diff — no files
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: '' })) // worktree diff — no files
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: '' })) // evidence: mainline patch diff
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: '' })) // evidence: worktree patch diff
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: '' })) // status --porcelain
+      .mockResolvedValueOnce(cmdResult({ code: 1, stderr: 'not-ff' })) // ff merge fails
+      .mockResolvedValueOnce(cmdResult({ code: 0 })); // rebase succeeds
+
+    const svc = makeSvc();
+    const result = await svc.reconcileWithMainline('feat1', 'main');
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) {
+      return;
+    }
+    expect(result.data.status).toBe('merged');
+  });
+
+  it('GIVEN_ff_and_rebase_both_fail_WHEN_reconcile_THEN_returns_reconciliation_failed', async () => {
+    runGitMock
+      .mockResolvedValueOnce(cmdResult({ code: 0 })) // fetch
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'base001\n' })) // merge-base main HEAD (local)
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'main999\n' })) // rev-parse main (repoRoot)
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'origin999\n' })) // rev-parse origin/main (fallback, not used)
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'feat111\n' })) // rev-parse HEAD (worktree)
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: '' })) // mainline diff
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: '' })) // worktree diff
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: '' })) // evidence: mainline patch diff
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: '' })) // evidence: worktree patch diff
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: '' })) // status --porcelain
+      .mockResolvedValueOnce(cmdResult({ code: 1, stderr: 'not-ff' })) // ff fails
+      .mockResolvedValueOnce(cmdResult({ code: 1, stderr: 'conflicts' })) // rebase fails
+      .mockResolvedValueOnce(cmdResult({ code: 0 })); // rebase --abort
+
+    const svc = makeSvc();
+    const result = await svc.reconcileWithMainline('feat1', 'main');
+
+    expect(result.ok).toBe(false);
+    if (result.ok) {
+      return;
+    }
+    expect((result as FailResponse).error.code).toBe('reconciliation_failed');
+  });
+
+  it('GIVEN_dirty_feature_worktree_WHEN_reconcile_requires_auto_merge_THEN_returns_uncommitted_changes', async () => {
+    runGitMock
+      .mockResolvedValueOnce(cmdResult({ code: 0 })) // fetch
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'base001\n' })) // merge-base main HEAD (local)
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'main999\n' })) // rev-parse main (repoRoot)
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'origin999\n' })) // rev-parse origin/main
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'feat111\n' })) // rev-parse HEAD (worktree)
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'fileA.ts\n' })) // mainline diff
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'fileB.ts\n' })) // worktree diff
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: '' })) // evidence: mainline patch diff
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: '' })) // evidence: worktree patch diff
+      .mockResolvedValueOnce(
+        cmdResult({
+          code: 0,
+          stdout:
+            ' M packages/web-dashboard/src/lib/planner-workspace.ts\n?? packages/web-dashboard/src/components/focus/plan/CriticalPathPanel.tsx\n',
+        }),
+      ); // status --porcelain
+
+    const svc = makeSvc();
+    const result = await svc.reconcileWithMainline('feat1', 'main');
+
+    expect(result.ok).toBe(false);
+    if (result.ok) {
+      return;
+    }
+    expect((result as FailResponse).error.code).toBe('uncommitted_changes');
+    expect((result as FailResponse).error.details).toMatchObject({
+      worktree_path: '/repo/.worktrees/feat1',
+      files: [
+        'packages/web-dashboard/src/components/focus/plan/CriticalPathPanel.tsx',
+        'packages/web-dashboard/src/lib/planner-workspace.ts',
+      ],
+    });
+  });
+
+  it('GIVEN_dirty_feature_worktree_and_checkpoint_message_WHEN_reconcile_called_THEN_commits_changes_before_auto_merge', async () => {
+    runGitMock
+      .mockResolvedValueOnce(cmdResult({ code: 0 })) // fetch
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'base001\n' })) // merge-base main HEAD (local)
+      .mockResolvedValueOnce(
+        cmdResult({
+          code: 0,
+          stdout:
+            ' M packages/web-dashboard/src/lib/planner-workspace.ts\n?? packages/web-dashboard/src/components/focus/plan/CriticalPathPanel.tsx\n',
+        }),
+      ) // status --porcelain (checkpoint)
+      .mockResolvedValueOnce(cmdResult({ code: 0 })) // add -A
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: '[feature 123] checkpoint\n' })) // commit
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'main999\n' })) // rev-parse main (repoRoot)
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'origin999\n' })) // rev-parse origin/main
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'feat222\n' })) // rev-parse HEAD (worktree)
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'fileA.ts\n' })) // mainline diff
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'fileB.ts\n' })) // worktree diff
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: '' })) // evidence: mainline patch diff
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: '' })) // evidence: worktree patch diff
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: '' })) // status --porcelain (auto-merge)
+      .mockResolvedValueOnce(cmdResult({ code: 0 })); // ff merge succeeds
+
+    const svc = makeSvc();
+    const result = await svc.reconcileWithMainline('feat1', 'main', 'Checkpoint before merge');
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) {
+      return;
+    }
+    expect(result.data.status).toBe('merged');
+    expect(runGitMock).toHaveBeenCalledWith('/repo/.worktrees/feat1', ['add', '-A']);
+    expect(runGitMock).toHaveBeenCalledWith('/repo/.worktrees/feat1', [
+      'commit',
+      '-m',
+      'Checkpoint before merge',
+    ]);
+  });
+
+  it('GIVEN_conflicting_files_WHEN_reconcile_THEN_returns_conflict_detected', async () => {
+    runGitMock
+      .mockResolvedValueOnce(cmdResult({ code: 0 })) // fetch
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'base001\n' })) // merge-base main HEAD (local)
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'main999\n' })) // rev-parse main (repoRoot)
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'origin999\n' })) // rev-parse origin/main (fallback, not used)
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'feat111\n' })) // rev-parse HEAD (worktree)
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'src/core/kernel.ts\nsrc/utils.ts\n' })) // mainline diff
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'src/core/kernel.ts\nsrc/feature.ts\n' })) // worktree diff
+      // evidence writes
+      .mockResolvedValueOnce(cmdResult({ code: 0 }))
+      .mockResolvedValueOnce(cmdResult({ code: 0 }))
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: '' })) // stale-merge check: diff --name-only --diff-filter=U (no stale merge)
+      .mockResolvedValueOnce(cmdResult({ code: 1, stderr: 'merge conflict' })) // merge --no-commit --no-ff
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'src/core/kernel.ts\n' })); // diff --name-only --diff-filter=U
+
+    const svc = makeSvc();
+    const result = await svc.reconcileWithMainline('feat1', 'main');
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) {
+      return;
+    }
+    expect(result.data.status).toBe('conflict_detected');
+    expect(result.data.divergence_detected).toBe(true);
+    expect(result.data.conflicting_files).toEqual(['src/core/kernel.ts']);
+    expect(result.data.files_changed_mainline).toContain('src/utils.ts');
+    expect(result.data.files_changed_worktree).toContain('src/feature.ts');
+  });
+
+  it('GIVEN_idle_reconciler_lane_WHEN_conflict_detected_THEN_dispatches_head_of_line_feature', async () => {
+    const sendMessageMock = vi.fn(async () => undefined);
+    const writeRunLeaseMock = vi.fn(async () => undefined);
+    runGitMock
+      .mockResolvedValueOnce(cmdResult({ code: 0 })) // fetch
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'base001\n' })) // merge-base
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'main999\n' })) // rev-parse main
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'origin999\n' })) // rev-parse origin/main
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'feat111\n' })) // rev-parse HEAD
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'shared.ts\n' })) // mainline diff
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'shared.ts\n' })) // worktree diff
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'diff content' })) // evidence mainline
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'diff content' })) // evidence worktree
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: '' })) // stale-merge check: diff --name-only --diff-filter=U (no stale merge)
+      .mockResolvedValueOnce(cmdResult({ code: 1, stderr: 'merge conflict' })) // merge --no-commit --no-ff
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'shared.ts\n' })); // diff --name-only --diff-filter=U
+
+    const svc = makeSvc({
+      writeRunLease: writeRunLeaseMock,
+      getProvider: vi.fn(() => ({
+        sendMessage: sendMessageMock,
+        getSessionInfo: vi.fn(async () => ({ active: true, provider: 'codex' })),
+      })),
+    });
+    const result = await svc.reconcileWithMainline('feat1', 'main');
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) {
+      return;
+    }
+    expect(result.data.status).toBe('conflict_detected');
+    expect(result.data.reconciler_active_feature_id).toBe('feat1');
+    expect(result.data.reconciler_queue_position).toBe(0);
+    expect(result.data.dispatched_to_reconciler).toBe(true);
+    expect(writeRunLeaseMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        reconciler_active_feature_id: 'feat1',
+        reconciler_queue: [],
+      }),
+    );
+    expect(sendMessageMock).toHaveBeenCalledWith(
+      'reconciler:1',
+      expect.stringContaining('feature_id=feat1'),
+    );
+  });
+
+  it('GIVEN_reconciler_send_failure_WHEN_conflict_detected_THEN_returns_conflict_without_bubbling_internal_error', async () => {
+    const sendMessageMock = vi.fn(async () => {
+      throw new Error('claude provider send failed');
+    });
+    runGitMock
+      .mockResolvedValueOnce(cmdResult({ code: 0 })) // fetch
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'base001\n' })) // merge-base
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'main999\n' })) // rev-parse main
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'origin999\n' })) // rev-parse origin/main
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'feat111\n' })) // rev-parse HEAD
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'shared.ts\n' })) // mainline diff
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'shared.ts\n' })) // worktree diff
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'diff content' })) // evidence mainline
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'diff content' })) // evidence worktree
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: '' })) // stale-merge check: diff --name-only --diff-filter=U (no stale merge)
+      .mockResolvedValueOnce(cmdResult({ code: 1, stderr: 'merge conflict' })) // merge --no-commit --no-ff
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'shared.ts\n' })); // diff --name-only --diff-filter=U
+
+    const svc = makeSvc({
+      getProvider: vi.fn(() => ({
+        sendMessage: sendMessageMock,
+        getSessionInfo: vi.fn(async () => ({ active: true, provider: 'claude' })),
+      })),
+    });
+    const result = await svc.reconcileWithMainline('feat1', 'main');
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) {
+      return;
+    }
+    expect(result.data.status).toBe('conflict_detected');
+    expect(result.data.dispatched_to_reconciler).toBe(false);
+    expect(fsAppendFileMock).toHaveBeenCalledWith(
+      expect.stringContaining('reconciliation.log'),
+      expect.stringContaining('dispatch_failed: claude provider send failed'),
+      'utf8',
+    );
+  });
+
+  it('GIVEN_approved_collision_context_WHEN_conflict_detected_THEN_includes_override_metadata_in_dispatch', async () => {
+    const sendMessageMock = vi.fn(async () => undefined);
+    runGitMock
+      .mockResolvedValueOnce(cmdResult({ code: 0 }))
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'base001\n' }))
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'main999\n' }))
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'origin999\n' }))
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'feat111\n' }))
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'shared.ts\n' }))
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'shared.ts\n' }))
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'diff content' }))
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'diff content' }))
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: '' })) // stale-merge check: no unmerged files
+      .mockResolvedValueOnce(cmdResult({ code: 1, stderr: 'merge conflict' })) // merge --no-commit --no-ff
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'shared.ts\n' })); // diff --name-only --diff-filter=U
+
+    const svc = makeSvc({
+      readIndex: vi.fn(async () => ({
+        collision_overrides: [
+          {
+            override_id: 'colovr_1',
+            feature_ids: ['feat1', 'feat2'],
+            rationale: 'preserve both dashboard behaviors',
+            approved_paths: ['shared.ts'],
+            approved_collision_fingerprint: 'fp_1',
+            status: 'applied',
+            source_collision_id: 'colrec_1',
+            applied_at: '2026-03-15T00:00:00.000Z',
+          },
+        ],
+        collision_records: [
+          {
+            collision_id: 'colrec_1',
+            detected_at: '2026-03-15T00:00:00.000Z',
+          },
+        ],
+      })),
+      getProvider: vi.fn(() => ({
+        sendMessage: sendMessageMock,
+        getSessionInfo: vi.fn(async () => ({ active: true, provider: 'codex' })),
+      })),
+    });
+
+    const result = await svc.reconcileWithMainline('feat1', 'main');
+
+    expect(result.ok).toBe(true);
+    expect(sendMessageMock).toHaveBeenCalledWith(
+      'reconciler:1',
+      expect.stringContaining('"override_id":"colovr_1"'),
+    );
+    expect(sendMessageMock).toHaveBeenCalledWith(
+      'reconciler:1',
+      expect.stringContaining('"counterpart_feature_id":"feat2"'),
+    );
+    expect(sendMessageMock).toHaveBeenCalledWith(
+      'reconciler:1',
+      expect.stringContaining('"source_collision_record":{"collision_id":"colrec_1"'),
+    );
+  });
+
+  it('GIVEN_busy_reconciler_lane_WHEN_conflict_detected_THEN_enqueues_feature_without_dispatch', async () => {
+    const writeRunLeaseMock = vi.fn(async () => undefined);
+    runGitMock
+      .mockResolvedValueOnce(cmdResult({ code: 0 })) // fetch
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'base001\n' })) // merge-base
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'main999\n' })) // rev-parse main
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'origin999\n' })) // rev-parse origin/main
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'feat111\n' })) // rev-parse HEAD
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'shared.ts\n' })) // mainline diff
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'shared.ts\n' })) // worktree diff
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'diff content' })) // evidence mainline
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'diff content' })) // evidence worktree
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: '' })) // stale-merge check: diff --name-only --diff-filter=U (no stale merge)
+      .mockResolvedValueOnce(cmdResult({ code: 1, stderr: 'merge conflict' })) // merge --no-commit --no-ff
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'shared.ts\n' })); // diff --name-only --diff-filter=U
+
+    const svc = makeSvc({
+      readRunLease: vi.fn(
+        async () =>
+          ({
+            run_id: 'run:test',
+            orchestrator_session_id: 'orchestrator:1',
+            reconciler_session_id: 'reconciler:1',
+            reconciler_active_feature_id: 'feature_busy',
+            reconciler_queue: ['feature_waiting'],
+            provider: 'codex',
+            model: 'codex-default',
+            provider_config_ref_hash: 'hash',
+            owner_instance_id: 'owner:test',
+            lease_id: 'lease:test',
+            started_at: '2026-01-01T00:00:00.000Z',
+            last_heartbeat_at: '2026-01-01T00:00:00.000Z',
+            lease_expires_at: '2026-01-01T00:05:00.000Z',
+            feature_sessions: {},
+          }) satisfies RuntimeSessionsSnapshot,
+      ),
+      writeRunLease: writeRunLeaseMock,
+    });
+    const result = await svc.reconcileWithMainline('feat1', 'main');
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) {
+      return;
+    }
+    expect(result.data.status).toBe('conflict_detected');
+    expect(result.data.reconciler_active_feature_id).toBe('feature_busy');
+    expect(result.data.reconciler_queue_position).toBe(2);
+    expect(result.data.dispatched_to_reconciler).toBe(false);
+    expect(writeRunLeaseMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        reconciler_active_feature_id: 'feature_busy',
+        reconciler_queue: ['feature_waiting', 'feat1'],
+      }),
+    );
+  });
+
+  it('GIVEN_merge_base_not_found_WHEN_reconcile_THEN_returns_merge_base_not_found_error', async () => {
+    runGitMock
+      .mockResolvedValueOnce(cmdResult({ code: 0 })) // fetch
+      .mockResolvedValueOnce(cmdResult({ code: 128, stderr: 'fatal: no merge base' })); // merge-base local fails
+
+    const svc = makeSvc();
+    const result = await svc.reconcileWithMainline('feat1', 'main');
+
+    expect(result.ok).toBe(false);
+    if (result.ok) {
+      return;
+    }
+    expect((result as FailResponse).error.code).toBe('merge_base_not_found');
+  });
+
+  it('GIVEN_empty_merge_base_sha_WHEN_reconcile_THEN_returns_merge_base_not_found_error', async () => {
+    runGitMock
+      .mockResolvedValueOnce(cmdResult({ code: 0 })) // fetch
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: '   \n' })); // local merge-base → whitespace → empty
+
+    const svc = makeSvc();
+    const result = await svc.reconcileWithMainline('feat1', 'main');
+
+    // Local fallback returns empty mergeBase → fail
+    expect(result.ok).toBe(false);
+    if (result.ok) {
+      return;
+    }
+    expect((result as FailResponse).error.code).toBe('merge_base_not_found');
+  });
+
+  it('GIVEN_state_read_throws_WHEN_reconcile_THEN_up_to_date_result_still_returned', async () => {
+    const mergeBase = 'sha_base';
+    runGitMock
+      .mockResolvedValueOnce(cmdResult({ code: 0 })) // fetch
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: `${mergeBase}\n` })) // merge-base main HEAD (local)
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: `${mergeBase}\n` })) // rev-parse main (repoRoot) → mainlineHead == mergeBase
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'origin_base\n' })) // rev-parse origin/main (fallback, not used)
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'feat999\n' })); // rev-parse HEAD
+
+    const port = makePort({
+      readState: vi.fn(async () => {
+        throw new Error('disk error');
+      }),
+    });
+    const svc = new GitReconciliationService(port);
+    const result = await svc.reconcileWithMainline('feat1', 'main');
+
+    // Non-fatal: state write failure should not break reconciliation
+    expect(result.ok).toBe(true);
+    if (!result.ok) {
+      return;
+    }
+    expect(result.data.status).toBe('up_to_date');
+  });
+
+  it('GIVEN_conflict_detected_WHEN_reconcile_THEN_state_is_updated_with_conflict_metadata', async () => {
+    const writeStateMock = vi.fn(async () => {});
+    runGitMock
+      .mockResolvedValueOnce(cmdResult({ code: 0 })) // fetch
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'base001\n' })) // merge-base main HEAD (local)
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'main999\n' })) // rev-parse main (repoRoot)
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'origin999\n' })) // rev-parse origin/main (fallback, not used)
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'feat111\n' })) // rev-parse HEAD (worktree)
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'conflict.ts\n' })) // mainline diff
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'conflict.ts\n' })) // worktree diff
+      .mockResolvedValueOnce(cmdResult({ code: 0 })) // evidence
+      .mockResolvedValueOnce(cmdResult({ code: 0 })) // evidence
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: '' })) // stale-merge check: diff --name-only --diff-filter=U (no stale merge)
+      .mockResolvedValueOnce(cmdResult({ code: 1, stderr: 'merge conflict' })) // merge --no-commit --no-ff
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'conflict.ts\n' })); // diff --name-only --diff-filter=U
+
+    const svc = makeSvc({ writeState: writeStateMock });
+    await svc.reconcileWithMainline('feat1', 'main');
+
+    expect(writeStateMock).toHaveBeenCalled();
+    const callArgs = writeStateMock.mock.calls[0] as unknown as [string, Record<string, unknown>];
+    const patchedFrontMatter = callArgs[1];
+    expect(Array.isArray(patchedFrontMatter.conflicts)).toBe(true);
+    const conflict = (patchedFrontMatter.conflicts as Record<string, unknown>[])[0];
+    expect(conflict.type).toBe('mainline_divergence');
+    expect(conflict.conflicting_files).toEqual(['conflict.ts']);
+    expect(conflict.resolution_status).toBe('in_progress');
+    expect(patchedFrontMatter.status).toBe('blocked');
+  });
+
+  it('GIVEN_fetch_fails_WHEN_reconcile_THEN_continues_with_local_refs', async () => {
+    const mergeBase = 'localbase';
+    runGitMock
+      .mockResolvedValueOnce(cmdResult({ code: 1, stderr: 'no remote' })) // fetch fails (non-fatal)
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: `${mergeBase}\n` })) // merge-base main HEAD (local)
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: `${mergeBase}\n` })) // rev-parse main (repoRoot) → mainlineHead == mergeBase
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'origin_base\n' })) // rev-parse origin/main (fallback, not used)
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'wt123\n' })); // rev-parse HEAD
+
+    const svc = makeSvc();
+    const result = await svc.reconcileWithMainline('feat1', 'main');
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) {
+      return;
+    }
+    expect(result.data.status).toBe('up_to_date');
+  });
+
+  it('GIVEN_local_mainline_ref_missing_WHEN_reconcile_THEN_falls_back_to_origin_and_treats_matching_head_as_up_to_date', async () => {
+    runGitMock
+      .mockResolvedValueOnce(cmdResult({ code: 0 })) // fetch
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'base001\n' })) // merge-base
+      .mockResolvedValueOnce(cmdResult({ code: 1, stderr: 'missing main' })) // rev-parse main
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'feat111\n' })) // rev-parse origin/main
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'feat111\n' })); // rev-parse HEAD
+
+    const svc = makeSvc();
+    const result = await svc.reconcileWithMainline('feat1', 'main');
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) {
+      return;
+    }
+    expect(result.data.status).toBe('up_to_date');
+    expect(result.data.mainline_head).toBe('feat111');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// detectDivergence
+// ---------------------------------------------------------------------------
+
+describe('GitReconciliationService.detectDivergence', () => {
+  beforeEach(() => {
+    vi.resetAllMocks();
+    nowIsoMock.mockReturnValue('2026-01-01T00:00:00.000Z');
+  });
+
+  it('GIVEN_no_divergence_WHEN_detect_THEN_returns_up_to_date', async () => {
+    const sha = 'samesha';
+    runGitMock
+      .mockResolvedValueOnce(cmdResult({ code: 0 })) // fetch
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: `${sha}\n` })) // merge-base main HEAD (local)
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: `${sha}\n` })) // rev-parse main (repoRoot) → mainlineHead == mergeBase
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'origin_sha\n' })) // rev-parse origin/main (fallback, not used)
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'feat555\n' })); // rev-parse HEAD
+
+    const svc = makeSvc();
+    const result = await svc.detectDivergence('feat1', 'main');
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) {
+      return;
+    }
+    expect(result.data.status).toBe('up_to_date');
+    expect(result.data.divergence_detected).toBe(false);
+  });
+
+  it('GIVEN_non_conflicting_divergence_WHEN_detect_THEN_returns_merged_status_without_mutating', async () => {
+    runGitMock
+      .mockResolvedValueOnce(cmdResult({ code: 0 })) // fetch
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'mergebase\n' })) // merge-base main HEAD (local)
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'mainhead\n' })) // rev-parse main (repoRoot)
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'origin_head\n' })) // rev-parse origin/main (fallback, not used)
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'worktreehead\n' })) // rev-parse HEAD
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'readme.md\n' })) // mainline diff files
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'src/feature.ts\n' })); // worktree diff files
+
+    const svc = makeSvc();
+    const result = await svc.detectDivergence('feat1', 'main');
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) {
+      return;
+    }
+    // detectDivergence returns 'merged' to indicate "would be mergeable"
+    expect(result.data.status).toBe('merged');
+    expect(result.data.conflicting_files).toHaveLength(0);
+    // Should NOT have called writeState (no mutation)
+  });
+
+  it('GIVEN_conflicting_divergence_WHEN_detect_THEN_returns_conflict_detected', async () => {
+    runGitMock
+      .mockResolvedValueOnce(cmdResult({ code: 0 })) // fetch
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'mergebase\n' })) // merge-base main HEAD (local)
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'mainhead\n' })) // rev-parse main (repoRoot)
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'origin_head\n' })) // rev-parse origin/main (fallback, not used)
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'worktreehead\n' })) // rev-parse HEAD
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'shared.ts\nonly_main.ts\n' })) // mainline diff
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'shared.ts\nonly_feat.ts\n' })); // worktree diff
+
+    const svc = makeSvc();
+    const result = await svc.detectDivergence('feat1', 'main');
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) {
+      return;
+    }
+    expect(result.data.status).toBe('conflict_detected');
+    expect(result.data.conflicting_files).toEqual(['shared.ts']);
+  });
+
+  it('GIVEN_merge_base_fails_for_both_remote_and_local_WHEN_detect_THEN_returns_error', async () => {
+    runGitMock
+      .mockResolvedValueOnce(cmdResult({ code: 0 })) // fetch
+      .mockResolvedValueOnce(cmdResult({ code: 128, stderr: 'fatal' })); // merge-base local fails
+
+    const svc = makeSvc();
+    const result = await svc.detectDivergence('feat1', 'main');
+
+    expect(result.ok).toBe(false);
+    if (result.ok) {
+      return;
+    }
+    expect((result as FailResponse).error.code).toBe('merge_base_not_found');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Evidence artifacts
+// ---------------------------------------------------------------------------
+
+describe('GitReconciliationService — evidence artifacts', () => {
+  beforeEach(() => {
+    vi.resetAllMocks();
+    nowIsoMock.mockReturnValue('2026-01-01T00:00:00.000Z');
+  });
+
+  it('GIVEN_conflict_detected_WHEN_reconcile_THEN_evidence_dir_is_created', async () => {
+    runGitMock
+      .mockResolvedValueOnce(cmdResult({ code: 0 })) // fetch
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'base\n' })) // merge-base main HEAD (local)
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'main\n' })) // rev-parse main (repoRoot)
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'origin\n' })) // rev-parse origin/main (fallback, not used)
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'feat\n' })) // rev-parse HEAD (worktree)
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'conflict.ts\n' })) // mainline diff
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'conflict.ts\n' })) // worktree diff
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'diff content' })) // mainline diff patch
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'diff content' })) // worktree diff patch
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: '' })) // stale-merge check: diff --name-only --diff-filter=U (no stale merge)
+      .mockResolvedValueOnce(cmdResult({ code: 1, stderr: 'merge conflict' })) // merge --no-commit --no-ff
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'conflict.ts\n' })); // diff --name-only --diff-filter=U
+
+    const svc = makeSvc();
+    await svc.reconcileWithMainline('feat1', 'main');
+
+    expect(ensureDirMock).toHaveBeenCalledWith(expect.stringContaining('reconciliation'));
+    expect(fsWriteFileMock).toHaveBeenCalledWith(
+      expect.stringContaining('mainline-diff.patch'),
+      expect.any(String),
+      'utf8',
+    );
+  });
+
+  it('GIVEN_merged_successfully_WHEN_reconcile_THEN_log_is_appended', async () => {
+    runGitMock
+      .mockResolvedValueOnce(cmdResult({ code: 0 })) // fetch
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'base\n' })) // merge-base main HEAD (local)
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'main\n' })) // rev-parse main (repoRoot)
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'origin\n' })) // rev-parse origin/main (fallback, not used)
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'feat\n' })) // rev-parse HEAD (worktree)
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: '' })) // mainline diff (no files)
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: '' })) // worktree diff (no files)
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: '' })) // evidence: mainline patch
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: '' })) // evidence: worktree patch
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: '' })) // status --porcelain
+      .mockResolvedValueOnce(cmdResult({ code: 0 })); // ff merge succeeds
+
+    const svc = makeSvc();
+    await svc.reconcileWithMainline('feat1', 'main');
+
+    expect(ensureDirMock).toHaveBeenCalledWith(expect.stringContaining('logs'));
+    expect(fsAppendFileMock).toHaveBeenCalledWith(
+      expect.stringContaining('reconciliation.log'),
+      expect.stringContaining('merged'),
+      'utf8',
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Additional branch coverage
+// ---------------------------------------------------------------------------
+
+describe('GitReconciliationService — additional branches', () => {
+  beforeEach(() => {
+    vi.resetAllMocks();
+    nowIsoMock.mockReturnValue('2026-01-01T00:00:00.000Z');
+  });
+
+  it('GIVEN_origin_rev_parse_fails_WHEN_reconcile_THEN_uses_local_ref_for_mainline_head', async () => {
+    const sha = 'localsha';
+    runGitMock
+      .mockResolvedValueOnce(cmdResult({ code: 0 })) // fetch
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: `${sha}\n` })) // merge-base main HEAD (local)
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: `${sha}\n` })) // rev-parse main (repoRoot) → mainlineHead == mergeBase
+      .mockResolvedValueOnce(cmdResult({ code: 128, stderr: 'no origin' })) // rev-parse origin/main FAILS (fallback not used since local succeeded)
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'wt333\n' })); // rev-parse HEAD
+
+    const svc = makeSvc();
+    const result = await svc.reconcileWithMainline('feat1', 'main');
+
+    // mainlineHead (localsha) === mergeBase (localsha) → up_to_date
+    expect(result.ok).toBe(true);
+    if (!result.ok) {
+      return;
+    }
+    expect(result.data.status).toBe('up_to_date');
+  });
+
+  it('GIVEN_origin_rev_parse_fails_in_detect_WHEN_detect_THEN_uses_local_ref', async () => {
+    const sha = 'localbase';
+    runGitMock
+      .mockResolvedValueOnce(cmdResult({ code: 0 })) // fetch
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: `${sha}\n` })) // merge-base main HEAD (local)
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: `${sha}\n` })) // rev-parse main (repoRoot) → mainlineHead == mergeBase
+      .mockResolvedValueOnce(cmdResult({ code: 128, stderr: 'no origin' })) // rev-parse origin/main FAILS (fallback not used)
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'wt_head\n' })); // rev-parse HEAD
+
+    const svc = makeSvc();
+    const result = await svc.detectDivergence('feat1', 'main');
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) {
+      return;
+    }
+    // mainlineHead (localbase) === mergeBase (localbase) → up_to_date
+    expect(result.data.status).toBe('up_to_date');
+  });
+
+  it('GIVEN_local_merge_base_fallback_in_detect_WHEN_local_also_fails_THEN_returns_error', async () => {
+    runGitMock
+      .mockResolvedValueOnce(cmdResult({ code: 0 })) // fetch
+      .mockResolvedValueOnce(cmdResult({ code: 1, stderr: 'no local' })); // merge-base local fails
+
+    const svc = makeSvc();
+    const result = await svc.detectDivergence('feat1', 'main');
+
+    expect(result.ok).toBe(false);
+    if (result.ok) {
+      return;
+    }
+    expect((result as FailResponse).error.code).toBe('merge_base_not_found');
+  });
+
+  it('GIVEN_local_merge_base_fallback_in_detect_WHEN_local_succeeds_THEN_continues_with_local_base', async () => {
+    const sha = 'localbase';
+    runGitMock
+      .mockResolvedValueOnce(cmdResult({ code: 0 })) // fetch
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: `${sha}\n` })) // merge-base local succeeds
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: `${sha}\n` })) // rev-parse main (repoRoot) → mainlineHead == mergeBase
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'origin_sha\n' })) // rev-parse origin/main (fallback, not used)
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'wt_h\n' })); // rev-parse HEAD
+
+    const svc = makeSvc();
+    const result = await svc.detectDivergence('feat1', 'main');
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) {
+      return;
+    }
+    expect(result.data.status).toBe('up_to_date');
+  });
+
+  it('GIVEN_local_mainline_ref_missing_WHEN_detect_THEN_falls_back_to_origin_ref', async () => {
+    runGitMock
+      .mockResolvedValueOnce(cmdResult({ code: 0 })) // fetch
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'mergebase\n' })) // merge-base
+      .mockResolvedValueOnce(cmdResult({ code: 1, stderr: 'missing main' })) // rev-parse main
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'origin-main\n' })) // rev-parse origin/main
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'worktreehead\n' })) // rev-parse HEAD
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'src/main.ts\n' })) // mainline diff
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'src/feature.ts\n' })); // worktree diff
+
+    const svc = makeSvc();
+    const result = await svc.detectDivergence('feat1', 'main');
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) {
+      return;
+    }
+    expect(result.data.status).toBe('merged');
+    expect(result.data.mainline_head).toBe('origin-main');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// checkRemoteLocalDivergence
+// ---------------------------------------------------------------------------
+describe('GitReconciliationService.checkRemoteLocalDivergence', () => {
+  beforeEach(() => {
+    runGitMock.mockReset();
+  });
+
+  it('GIVEN_local_and_remote_same_sha_WHEN_check_divergence_THEN_returns_not_diverged', async () => {
+    runGitMock
+      .mockResolvedValueOnce(cmdResult({ code: 0 })) // fetch
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'abc123\n' })) // rev-parse main (local)
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'abc123\n' })); // rev-parse origin/main
+
+    const svc = makeSvc();
+    const result = await svc.checkRemoteLocalDivergence('main');
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) {
+      return;
+    }
+    expect(result.data.diverged).toBe(false);
+    expect(result.data.local_ahead).toBe(false);
+    expect(result.data.local_head).toBe('abc123');
+    expect(result.data.remote_head).toBe('abc123');
+  });
+
+  it('GIVEN_local_and_remote_different_sha_WHEN_check_divergence_THEN_returns_diverged', async () => {
+    runGitMock
+      .mockResolvedValueOnce(cmdResult({ code: 0 })) // fetch
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'localsha\n' })) // rev-parse main (local)
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'remotesha\n' })) // rev-parse origin/main
+      .mockResolvedValueOnce(cmdResult({ code: 1 })); // merge-base --is-ancestor exits 1
+
+    const svc = makeSvc();
+    const result = await svc.checkRemoteLocalDivergence('main');
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) {
+      return;
+    }
+    expect(result.data.diverged).toBe(true);
+    expect(result.data.local_ahead).toBe(false);
+    expect(result.data.local_head).toBe('localsha');
+    expect(result.data.remote_head).toBe('remotesha');
+  });
+
+  it('GIVEN_no_remote_WHEN_check_divergence_THEN_returns_not_diverged_using_local_sha', async () => {
+    runGitMock
+      .mockResolvedValueOnce(cmdResult({ code: 0 })) // fetch (non-fatal)
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'localsha\n' })) // rev-parse main (local)
+      .mockResolvedValueOnce(cmdResult({ code: 1, stderr: 'unknown revision' })); // rev-parse origin/main fails
+
+    const svc = makeSvc();
+    const result = await svc.checkRemoteLocalDivergence('main');
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) {
+      return;
+    }
+    expect(result.data.diverged).toBe(false);
+    expect(result.data.local_ahead).toBe(false);
+    expect(result.data.local_head).toBe('localsha');
+    expect(result.data.remote_head).toBe('localsha');
+  });
+
+  it('GIVEN_identical_shas_WHEN_check_divergence_THEN_skips_merge_base_call', async () => {
+    runGitMock
+      .mockResolvedValueOnce(cmdResult({ code: 0 })) // fetch
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'abc123\n' })) // rev-parse main
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'abc123\n' })); // rev-parse origin/main
+
+    const svc = makeSvc();
+    const result = await svc.checkRemoteLocalDivergence('main');
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) {
+      return;
+    }
+    expect(result.data.diverged).toBe(false);
+    expect(result.data.local_ahead).toBe(false);
+    // Should NOT call merge-base when SHAs are identical
+    expect(runGitMock).toHaveBeenCalledTimes(3);
+  });
+
+  it('GIVEN_local_ahead_of_remote_WHEN_check_divergence_THEN_returns_not_diverged_and_local_ahead', async () => {
+    runGitMock
+      .mockResolvedValueOnce(cmdResult({ code: 0 })) // fetch
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'localsha\n' })) // rev-parse main
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'remotesha\n' })) // rev-parse origin/main
+      .mockResolvedValueOnce(cmdResult({ code: 0 })); // merge-base --is-ancestor exits 0
+
+    const svc = makeSvc();
+    const result = await svc.checkRemoteLocalDivergence('main');
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) {
+      return;
+    }
+    expect(result.data.diverged).toBe(false);
+    expect(result.data.local_ahead).toBe(true);
+    expect(runGitMock).toHaveBeenCalledWith(expect.any(String), [
+      'merge-base',
+      '--is-ancestor',
+      'origin/main',
+      'main',
+    ]);
+  });
+
+  it('GIVEN_true_divergence_WHEN_check_divergence_THEN_returns_diverged', async () => {
+    runGitMock
+      .mockResolvedValueOnce(cmdResult({ code: 0 })) // fetch
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'localsha\n' })) // rev-parse main
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'remotesha\n' })) // rev-parse origin/main
+      .mockResolvedValueOnce(cmdResult({ code: 1 })); // merge-base --is-ancestor exits 1
+
+    const svc = makeSvc();
+    const result = await svc.checkRemoteLocalDivergence('main');
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) {
+      return;
+    }
+    expect(result.data.diverged).toBe(true);
+    expect(result.data.local_ahead).toBe(false);
+  });
+
+  it('GIVEN_remote_ref_unresolvable_WHEN_check_divergence_THEN_returns_not_diverged', async () => {
+    runGitMock
+      .mockResolvedValueOnce(cmdResult({ code: 0 })) // fetch
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'localsha\n' })) // rev-parse main
+      .mockResolvedValueOnce(cmdResult({ code: 128, stderr: 'fatal: bad ref' })); // rev-parse origin/main fails
+
+    const svc = makeSvc();
+    const result = await svc.checkRemoteLocalDivergence('main');
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) {
+      return;
+    }
+    expect(result.data.diverged).toBe(false);
+    expect(result.data.local_ahead).toBe(false);
+    expect(result.data.remote_head).toBe('localsha');
+    // Should NOT call merge-base when remote ref fails
+    expect(runGitMock).toHaveBeenCalledTimes(3);
+  });
+
+  it('GIVEN_local_rev_parse_fails_WHEN_check_divergence_THEN_returns_git_failure', async () => {
+    runGitMock
+      .mockResolvedValueOnce(cmdResult({ code: 0 })) // fetch
+      .mockResolvedValueOnce(cmdResult({ code: 1, stderr: 'unknown revision main' })); // rev-parse main fails
+
+    const svc = makeSvc();
+    const result = await svc.checkRemoteLocalDivergence('main');
+
+    expect(result.ok).toBe(false);
+    if (result.ok) {
+      return;
+    }
+    expect((result as unknown as FailResponse).error.code).toBe('git_failure');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// syncMainlineFromRemote
+// ---------------------------------------------------------------------------
+describe('GitReconciliationService.syncMainlineFromRemote', () => {
+  beforeEach(() => {
+    runGitMock.mockReset();
+  });
+
+  it('GIVEN_no_conflicts_WHEN_sync_THEN_merges_and_returns_sha', async () => {
+    runGitMock
+      .mockResolvedValueOnce(cmdResult({ code: 0 })) // fetch
+      .mockResolvedValueOnce(cmdResult({ code: 0 })) // checkout main
+      .mockResolvedValueOnce(cmdResult({ code: 0 })) // merge -X ours origin/main
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'merged123\n' })); // rev-parse HEAD
+
+    const svc = makeSvc();
+    const result = await svc.syncMainlineFromRemote('main');
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) {
+      return;
+    }
+    expect(result.data.merged).toBe(true);
+    expect(result.data.sha).toBe('merged123');
+  });
+
+  it('GIVEN_fetch_fails_WHEN_sync_THEN_returns_git_failure', async () => {
+    runGitMock.mockResolvedValueOnce(cmdResult({ code: 1, stderr: 'network error' })); // fetch fails
+
+    const svc = makeSvc();
+    const result = await svc.syncMainlineFromRemote('main');
+
+    expect(result.ok).toBe(false);
+    if (result.ok) {
+      return;
+    }
+    expect((result as unknown as FailResponse).error.code).toBe('git_failure');
+  });
+
+  it('GIVEN_checkout_fails_WHEN_sync_THEN_returns_git_failure', async () => {
+    runGitMock
+      .mockResolvedValueOnce(cmdResult({ code: 0 })) // fetch
+      .mockResolvedValueOnce(cmdResult({ code: 1, stderr: 'checkout failed' })); // checkout main fails
+
+    const svc = makeSvc();
+    const result = await svc.syncMainlineFromRemote('main');
+
+    expect(result.ok).toBe(false);
+    if (result.ok) {
+      return;
+    }
+    expect((result as unknown as FailResponse).error.code).toBe('git_failure');
+  });
+
+  it('GIVEN_merge_fails_WHEN_sync_THEN_aborts_and_returns_reconciliation_failed', async () => {
+    runGitMock
+      .mockResolvedValueOnce(cmdResult({ code: 0 })) // fetch
+      .mockResolvedValueOnce(cmdResult({ code: 0 })) // checkout main
+      .mockResolvedValueOnce(cmdResult({ code: 1, stderr: 'merge conflict' })) // merge -X ours fails
+      .mockResolvedValueOnce(cmdResult({ code: 0 })); // merge --abort
+
+    const svc = makeSvc();
+    const result = await svc.syncMainlineFromRemote('main');
+
+    expect(result.ok).toBe(false);
+    if (result.ok) {
+      return;
+    }
+    expect((result as unknown as FailResponse).error.code).toBe('reconciliation_failed');
+    // Verify --abort was called
+    expect(runGitMock).toHaveBeenCalledWith('/repo', ['merge', '--abort']);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Internal branch coverage
+// ---------------------------------------------------------------------------
+describe('GitReconciliationService — internal queue and state branches', () => {
+  beforeEach(() => {
+    vi.resetAllMocks();
+    nowIsoMock.mockReturnValue('2026-01-01T00:00:00.000Z');
+  });
+
+  it('GIVEN_existing_conflict_without_unmerged_files_WHEN_reuse_checked_THEN_returns_null', async () => {
+    runGitMock.mockResolvedValueOnce(cmdResult({ code: 0, stdout: '' }));
+
+    const svc = makeSvc({
+      readState: vi.fn(async () => ({
+        frontMatter: {
+          feature_id: 'feat1',
+          version: 1,
+          status: 'blocked',
+          conflicts: [{ type: 'mainline_divergence', resolution_status: 'pending' }],
+        } as Record<string, unknown>,
+        body: '# Feature\n',
+      })),
+    }) as unknown as {
+      reuseExistingConflictIfPresent: (
+        featureId: string,
+        worktreePath: string,
+        baseRef: string,
+      ) => Promise<unknown>;
+    };
+
+    const result = await svc.reuseExistingConflictIfPresent(
+      'feat1',
+      '/repo/.worktrees/feat1',
+      'main',
+    );
+    expect(result).toBeNull();
+  });
+
+  it('GIVEN_no_unresolved_mainline_conflict_WHEN_reuse_checked_THEN_returns_null', async () => {
+    const svc = makeSvc({
+      readState: vi.fn(async () => ({
+        frontMatter: {
+          feature_id: 'feat1',
+          version: 1,
+          status: 'blocked',
+          conflicts: [{ type: 'mainline_divergence', resolution_status: 'resolved' }],
+        } as Record<string, unknown>,
+        body: '# Feature\n',
+      })),
+    }) as unknown as {
+      reuseExistingConflictIfPresent: (
+        featureId: string,
+        worktreePath: string,
+        baseRef: string,
+      ) => Promise<unknown>;
+    };
+
+    const result = await svc.reuseExistingConflictIfPresent(
+      'feat1',
+      '/repo/.worktrees/feat1',
+      'main',
+    );
+    expect(result).toBeNull();
+  });
+
+  it('GIVEN_existing_conflict_with_missing_metadata_WHEN_reuse_checked_THEN_defaults_to_unknown_values', async () => {
+    const writeStateMock = vi.fn(async () => {});
+    runGitMock.mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'src/shared.ts\n' }));
+
+    const svc = makeSvc({
+      readState: vi.fn(async () => ({
+        frontMatter: {
+          feature_id: 'feat1',
+          version: 1,
+          status: 'building',
+          conflicts: [{ type: 'mainline_divergence', resolution_status: 'pending' }],
+        } as Record<string, unknown>,
+        body: '# Feature\n',
+      })),
+      readRunLease: vi.fn(
+        async () =>
+          ({
+            run_id: 'run:test',
+            orchestrator_session_id: 'orchestrator:1',
+            reconciler_session_id: 'unassigned',
+            reconciler_active_feature_id: null,
+            reconciler_queue: [],
+            provider: 'codex',
+            model: 'codex-default',
+            provider_config_ref_hash: 'hash',
+            owner_instance_id: 'owner:test',
+            lease_id: 'lease:test',
+            started_at: '2026-01-01T00:00:00.000Z',
+            last_heartbeat_at: '2026-01-01T00:00:00.000Z',
+            lease_expires_at: '2026-01-01T00:05:00.000Z',
+            feature_sessions: {},
+          }) satisfies RuntimeSessionsSnapshot,
+      ),
+      writeState: writeStateMock,
+    }) as unknown as {
+      reuseExistingConflictIfPresent: (
+        featureId: string,
+        worktreePath: string,
+        baseRef: string,
+      ) => Promise<{ ok: true; data: Record<string, unknown> } | { ok: false } | null>;
+    };
+
+    const result = await svc.reuseExistingConflictIfPresent(
+      'feat1',
+      '/repo/.worktrees/feat1',
+      'main',
+    );
+    expect(result).not.toBeNull();
+    expect(result?.ok).toBe(true);
+    if (!result || !result.ok) {
+      return;
+    }
+    expect(result.data.merge_base).toBe('unknown');
+    expect(result.data.mainline_head).toBe('unknown');
+    expect(result.data.worktree_head).toBe('unknown');
+    expect(result.data.dispatched_to_reconciler).toBe(false);
+    expect(writeStateMock).toHaveBeenCalledWith(
+      'feat1',
+      expect.objectContaining({
+        status: 'blocked',
+        status_reason: 'Mainline divergence assigned to the shared reconciler lane',
+      }),
+      '# Feature\n',
+    );
+  });
+
+  it('GIVEN_materialized_merge_commit_succeeds_WHEN_materializing_conflict_worktree_THEN_returns_merged', async () => {
+    runGitMock
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: '' })) // stale-merge check: no unmerged files
+      .mockResolvedValueOnce(cmdResult({ code: 0 })) // merge --no-commit --no-ff succeeds
+      .mockResolvedValueOnce(cmdResult({ code: 0 })); // commit
+
+    const svc = makeSvc() as unknown as {
+      materializeConflictWorktree: (
+        featureId: string,
+        worktreePath: string,
+        baseRef: string,
+        mainlineHead: string,
+      ) => Promise<{ kind: string; strategy?: string }>;
+    };
+
+    const result = await svc.materializeConflictWorktree(
+      'feat1',
+      '/repo/.worktrees/feat1',
+      'main',
+      'main123',
+    );
+
+    expect(result).toEqual({ kind: 'merged', strategy: 'merge_commit' });
+    expect(fsAppendFileMock).toHaveBeenCalledWith(
+      expect.stringContaining('reconciliation.log'),
+      expect.stringContaining('materialized_merge_commit: main123'),
+      'utf8',
+    );
+  });
+
+  it('GIVEN_materialized_merge_commit_fails_WHEN_materializing_conflict_worktree_THEN_returns_error_and_aborts', async () => {
+    runGitMock
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: '' })) // stale-merge check: no unmerged files
+      .mockResolvedValueOnce(cmdResult({ code: 0 })) // merge --no-commit --no-ff succeeds
+      .mockResolvedValueOnce(cmdResult({ code: 1, stderr: 'commit failed' })) // commit fails
+      .mockResolvedValueOnce(cmdResult({ code: 0 })); // merge --abort
+
+    const svc = makeSvc() as unknown as {
+      materializeConflictWorktree: (
+        featureId: string,
+        worktreePath: string,
+        baseRef: string,
+        mainlineHead: string,
+      ) => Promise<{ kind: string; response?: FailResponse }>;
+    };
+
+    const result = await svc.materializeConflictWorktree(
+      'feat1',
+      '/repo/.worktrees/feat1',
+      'main',
+      'main123',
+    );
+
+    expect(result.kind).toBe('error');
+    expect(result.response?.error.code).toBe('reconciliation_failed');
+    expect(runGitMock).toHaveBeenCalledWith('/repo/.worktrees/feat1', ['merge', '--abort']);
+  });
+
+  it('GIVEN_merge_failure_without_unmerged_files_WHEN_materializing_conflict_worktree_THEN_returns_error', async () => {
+    runGitMock
+      .mockResolvedValueOnce(cmdResult({ code: 1, stderr: 'merge failed' }))
+      .mockResolvedValueOnce(cmdResult({ code: 1, stderr: 'diff failed' }))
+      .mockResolvedValueOnce(cmdResult({ code: 0 }));
+
+    const svc = makeSvc() as unknown as {
+      materializeConflictWorktree: (
+        featureId: string,
+        worktreePath: string,
+        baseRef: string,
+        mainlineHead: string,
+      ) => Promise<{ kind: string; response?: FailResponse }>;
+      listUnmergedFiles: (worktreePath: string) => Promise<string[]>;
+    };
+
+    const result = await svc.materializeConflictWorktree(
+      'feat1',
+      '/repo/.worktrees/feat1',
+      'main',
+      'main123',
+    );
+
+    expect(result.kind).toBe('error');
+    expect(result.response?.error.code).toBe('reconciliation_failed');
+    expect(runGitMock).toHaveBeenCalledWith('/repo/.worktrees/feat1', [
+      'diff',
+      '--name-only',
+      '--diff-filter=U',
+    ]);
+  });
+
+  it('GIVEN_blocked_feature_with_resume_status_WHEN_resolving_mainline_conflict_THEN_restores_prior_status', async () => {
+    const writeStateMock = vi.fn(async () => {});
+    const svc = makeSvc({
+      readState: vi.fn(async () => ({
+        frontMatter: {
+          feature_id: 'feat1',
+          version: 1,
+          status: 'blocked',
+          recovery: {
+            state: 'retrying',
+            cause: 'provider_output_invalid',
+            role: 'planner',
+          },
+          conflicts: [
+            {
+              type: 'mainline_divergence',
+              resolution_status: 'pending',
+              resume_status: 'ready_to_merge',
+            },
+          ],
+        } as Record<string, unknown>,
+        body: '# Feature\n',
+      })),
+      writeState: writeStateMock,
+    }) as unknown as {
+      resolveMainlineConflictState: (featureId: string, mainlineHead: string) => Promise<void>;
+    };
+
+    await svc.resolveMainlineConflictState('feat1', 'main456');
+
+    expect(writeStateMock).toHaveBeenCalledWith(
+      'feat1',
+      expect.objectContaining({
+        status: 'ready_to_merge',
+        status_reason: 'Reconciled against main456',
+        last_reconciliation_sha: 'main456',
+        recovery: null,
+      }),
+      '# Feature\n',
+    );
+    expect(fsAppendFileMock).toHaveBeenCalledWith(
+      expect.stringContaining('reconciliation.log'),
+      expect.stringContaining('"approved_collision_context_used":false'),
+      'utf8',
+    );
+  });
+
+  it('GIVEN_approved_collision_context_WHEN_resolving_mainline_conflict_THEN_appends_structured_completion_log', async () => {
+    const writeStateMock = vi.fn(async () => {});
+    const svc = makeSvc({
+      readState: vi.fn(async () => ({
+        frontMatter: {
+          feature_id: 'feat1',
+          version: 1,
+          status: 'blocked',
+          conflicts: [
+            {
+              type: 'mainline_divergence',
+              resolution_status: 'in_progress',
+              resume_status: 'building',
+            },
+          ],
+        } as Record<string, unknown>,
+        body: '# Feature\n',
+      })),
+      writeState: writeStateMock,
+      readIndex: vi.fn(async () => ({
+        collision_overrides: [
+          {
+            override_id: 'colovr_1',
+            feature_ids: ['feat1', 'feat2'],
+            rationale: 'preserve both dashboard behaviors',
+            approved_paths: ['shared.ts'],
+            approved_collision_fingerprint: 'fp_1',
+            status: 'applied',
+            source_collision_id: 'colrec_1',
+            applied_at: '2026-03-15T00:00:00.000Z',
+          },
+        ],
+        collision_records: [
+          {
+            collision_id: 'colrec_1',
+            detected_at: '2026-03-15T00:00:00.000Z',
+            collisions: {
+              files: [{ with_feature_id: 'feat2', paths: ['shared.ts'] }],
+              areas: [],
+              contracts: [],
+            },
+          },
+        ],
+      })),
+    }) as unknown as {
+      resolveMainlineConflictState: (featureId: string, mainlineHead: string) => Promise<void>;
+    };
+
+    await svc.resolveMainlineConflictState('feat1', 'main999');
+
+    expect(writeStateMock).toHaveBeenCalled();
+    expect(fsAppendFileMock).toHaveBeenCalledWith(
+      expect.stringContaining('reconciliation.log'),
+      expect.stringContaining('"approved_collision_context_used":true'),
+      'utf8',
+    );
+    expect(fsAppendFileMock).toHaveBeenCalledWith(
+      expect.stringContaining('reconciliation.log'),
+      expect.stringContaining('"override_ids":["colovr_1"]'),
+      'utf8',
+    );
+  });
+
+  it('GIVEN_resolved_and_unresolved_mainline_conflicts_WHEN_resolving_state_THEN_skips_resolved_entry_and_updates_latest_unresolved', async () => {
+    const writeStateMock = vi.fn(async () => {});
+    const svc = makeSvc({
+      readState: vi.fn(async () => ({
+        frontMatter: {
+          feature_id: 'feat1',
+          version: 1,
+          status: 'blocked',
+          conflicts: [
+            {
+              type: 'mainline_divergence',
+              resolution_status: 'resolved',
+              resume_status: 'building',
+            },
+            {
+              type: 'mainline_divergence',
+              resolution_status: 'pending',
+              resume_status: 'ready_to_merge',
+            },
+          ],
+        } as Record<string, unknown>,
+        body: '# Feature\n',
+      })),
+      writeState: writeStateMock,
+    }) as unknown as {
+      resolveMainlineConflictState: (featureId: string, mainlineHead: string) => Promise<void>;
+    };
+
+    await svc.resolveMainlineConflictState('feat1', 'main789');
+
+    const [, nextFrontMatter] = writeStateMock.mock.calls[0] as unknown as [
+      string,
+      Record<string, unknown>,
+      string,
+    ];
+    const conflicts = nextFrontMatter.conflicts as Array<Record<string, unknown>>;
+    expect(conflicts[0].resolution_status).toBe('resolved');
+    expect(conflicts[1].resolution_status).toBe('resolved');
+    expect(conflicts[1].resolved_mainline_head).toBe('main789');
+    expect(nextFrontMatter.status).toBe('ready_to_merge');
+  });
+
+  it('GIVEN_no_unresolved_mainline_conflict_WHEN_resolving_state_THEN_skips_write', async () => {
+    const writeStateMock = vi.fn(async () => {});
+    const svc = makeSvc({
+      readState: vi.fn(async () => ({
+        frontMatter: {
+          feature_id: 'feat1',
+          version: 1,
+          status: 'building',
+          conflicts: [{ type: 'qa_blocker', resolution_status: 'pending' }],
+        } as Record<string, unknown>,
+        body: '# Feature\n',
+      })),
+      writeState: writeStateMock,
+    }) as unknown as {
+      resolveMainlineConflictState: (featureId: string, mainlineHead: string) => Promise<void>;
+    };
+
+    await svc.resolveMainlineConflictState('feat1', 'main456');
+    expect(writeStateMock).not.toHaveBeenCalled();
+  });
+
+  it('GIVEN_existing_blocked_conflict_WHEN_upserting_mainline_conflict_THEN_reuses_entry_and_restores_building_resume_status', async () => {
+    const writeStateMock = vi.fn(async () => {});
+    const svc = makeSvc({
+      readState: vi.fn(async () => ({
+        frontMatter: {
+          feature_id: 'feat1',
+          version: 1,
+          status: 'blocked',
+          recovery: {
+            state: 'retrying',
+            cause: 'provider_output_invalid',
+            role: 'planner',
+          },
+          conflicts: [
+            {
+              type: 'mainline_divergence',
+              resolution_status: 'pending',
+              detected_at: '2025-12-31T00:00:00.000Z',
+            },
+          ],
+        } as Record<string, unknown>,
+        body: '# Feature\n',
+      })),
+      writeState: writeStateMock,
+    }) as unknown as {
+      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>;
+    };
+
+    await svc.upsertMainlineConflictState(
+      'feat1',
+      {
+        mergeBase: 'base123',
+        mainlineHead: 'main123',
+        worktreeHead: 'feat123',
+        conflictingFiles: ['src/shared.ts'],
+      },
+      {
+        baseRef: 'main',
+        resolutionStatus: 'pending',
+        queuePosition: 2,
+        statusReason: 'Queued for shared reconciler lane at position 3 behind feat0',
+      },
+    );
+
+    expect(writeStateMock).toHaveBeenCalledTimes(1);
+    const [, nextFrontMatter] = writeStateMock.mock.calls[0] as unknown as [
+      string,
+      Record<string, unknown>,
+      string,
+    ];
+    const nextConflict = (nextFrontMatter.conflicts as Array<Record<string, unknown>>)[0];
+    expect(nextConflict.detected_at).toBe('2025-12-31T00:00:00.000Z');
+    expect(nextConflict.resume_status).toBe('building');
+    expect(nextConflict.queue_position).toBe(2);
+    expect(nextConflict.queued_at).toBe('2026-01-01T00:00:00.000Z');
+    // When reconciler is assigned, recovery state is set to 'retrying'
+    expect(nextFrontMatter.recovery).toEqual(
+      expect.objectContaining({
+        state: 'retrying',
+        cause: 'mainline_divergence',
+        role: 'reconciler',
+        resume_phase: 'building',
+      }),
+    );
+  });
+
+  it('GIVEN_missing_session_or_provider_WHEN_dispatching_reconciler_turn_THEN_returns_false', async () => {
+    const svcNoSession = makeSvc() as unknown as {
+      dispatchReconcilerTurn: (
+        featureId: string,
+        baseRef: string,
+        sessionId: string | null,
+        info: {
+          mergeBase: string;
+          mainlineHead: string;
+          worktreeHead: string;
+          conflictingFiles: string[];
+        },
+      ) => Promise<boolean>;
+      waitForSessionToBecomeActive: (
+        provider: Record<string, unknown>,
+        sessionId: string,
+      ) => Promise<void>;
+    };
+
+    await expect(
+      svcNoSession.dispatchReconcilerTurn('feat1', 'main', 'unknown', {
+        mergeBase: 'base',
+        mainlineHead: 'main',
+        worktreeHead: 'feat',
+        conflictingFiles: ['src/shared.ts'],
+      }),
+    ).resolves.toBe(false);
+
+    await expect(
+      svcNoSession.waitForSessionToBecomeActive({}, 'reconciler:1'),
+    ).resolves.toBeUndefined();
+
+    const svcNoSender = makeSvc({
+      getProvider: vi.fn(() => ({
+        getSessionInfo: vi.fn(async () => ({ active: true, provider: 'codex' })),
+      })),
+    }) as unknown as {
+      dispatchReconcilerTurn: (
+        featureId: string,
+        baseRef: string,
+        sessionId: string | null,
+        info: {
+          mergeBase: string;
+          mainlineHead: string;
+          worktreeHead: string;
+          conflictingFiles: string[];
+        },
+      ) => Promise<boolean>;
+    };
+
+    await expect(
+      svcNoSender.dispatchReconcilerTurn('feat1', 'main', 'reconciler:1', {
+        mergeBase: 'base',
+        mainlineHead: 'main',
+        worktreeHead: 'feat',
+        conflictingFiles: ['src/shared.ts'],
+      }),
+    ).resolves.toBe(false);
+  });
+
+  it('GIVEN_send_message_throws_WHEN_dispatching_reconciler_turn_THEN_returns_false_and_logs_the_failure', async () => {
+    const sendMessageMock = vi.fn(async () => {
+      throw new Error('claude provider send failed');
+    });
+    const svc = makeSvc({
+      getProvider: vi.fn(() => ({
+        sendMessage: sendMessageMock,
+        getSessionInfo: vi.fn(async () => ({ active: true, provider: 'claude' })),
+      })),
+    }) as unknown as {
+      dispatchReconcilerTurn: (
+        featureId: string,
+        baseRef: string,
+        sessionId: string | null,
+        info: {
+          mergeBase: string;
+          mainlineHead: string;
+          worktreeHead: string;
+          conflictingFiles: string[];
+        },
+      ) => Promise<boolean>;
+    };
+
+    await expect(
+      svc.dispatchReconcilerTurn('feat1', 'main', 'reconciler:1', {
+        mergeBase: 'base',
+        mainlineHead: 'main',
+        worktreeHead: 'feat',
+        conflictingFiles: ['src/shared.ts'],
+      }),
+    ).resolves.toBe(false);
+    expect(fsAppendFileMock).toHaveBeenCalledWith(
+      expect.stringContaining('reconciliation.log'),
+      expect.stringContaining('dispatch_failed: claude provider send failed'),
+      'utf8',
+    );
+  });
+
+  it('GIVEN_missing_claude_reconciler_conversation_WHEN_dispatching_reconciler_turn_THEN_refreshes_the_session_and_retries_once', async () => {
+    const sendMessageMock = vi
+      .fn<(sessionId: string, _message: string) => Promise<void>>()
+      .mockRejectedValueOnce(
+        Object.assign(new Error('claude provider send failed'), {
+          details: { stderr: 'No conversation found with session ID: reconciler:1' },
+        }),
+      )
+      .mockResolvedValueOnce(undefined);
+    const refreshReconcilerSessionMock = vi.fn(async () => 'reconciler:2');
+    const svc = makeSvc({
+      refreshReconcilerSession: refreshReconcilerSessionMock,
+      getProvider: vi.fn(() => ({
+        sendMessage: sendMessageMock,
+        getSessionInfo: vi.fn(async () => ({ active: true, provider: 'claude' })),
+      })),
+    }) as unknown as {
+      dispatchReconcilerTurn: (
+        featureId: string,
+        baseRef: string,
+        sessionId: string | null,
+        info: {
+          mergeBase: string;
+          mainlineHead: string;
+          worktreeHead: string;
+          conflictingFiles: string[];
+        },
+      ) => Promise<boolean>;
+    };
+
+    await expect(
+      svc.dispatchReconcilerTurn('feat1', 'main', 'reconciler:1', {
+        mergeBase: 'base',
+        mainlineHead: 'main',
+        worktreeHead: 'feat',
+        conflictingFiles: ['src/shared.ts'],
+      }),
+    ).resolves.toBe(true);
+    expect(refreshReconcilerSessionMock).toHaveBeenCalledTimes(1);
+    expect(sendMessageMock).toHaveBeenNthCalledWith(
+      1,
+      'reconciler:1',
+      expect.stringContaining('feature_id=feat1'),
+    );
+    expect(sendMessageMock).toHaveBeenNthCalledWith(
+      2,
+      'reconciler:2',
+      expect.stringContaining('feature_id=feat1'),
+    );
+    expect(fsAppendFileMock).toHaveBeenCalledWith(
+      expect.stringContaining('reconciliation.log'),
+      expect.stringContaining(
+        'reconciler_session_refreshed old_session_id=reconciler:1 new_session_id=reconciler:2',
+      ),
+      'utf8',
+    );
+  });
+
+  it('GIVEN_missing_claude_reconciler_conversation_WHEN_refresh_does_not_change_the_session_THEN_logs_the_original_failure', async () => {
+    const sendMessageMock = vi
+      .fn<(sessionId: string, _message: string) => Promise<void>>()
+      .mockRejectedValueOnce(
+        Object.assign(new Error('claude provider send failed'), {
+          details: { stderr: 'No conversation found with session ID: reconciler:1' },
+        }),
+      );
+    const refreshReconcilerSessionMock = vi.fn(async () => 'reconciler:1');
+    const svc = makeSvc({
+      refreshReconcilerSession: refreshReconcilerSessionMock,
+      getProvider: vi.fn(() => ({
+        sendMessage: sendMessageMock,
+        getSessionInfo: vi.fn(async () => ({ active: true, provider: 'claude' })),
+      })),
+    }) as unknown as {
+      dispatchReconcilerTurn: (
+        featureId: string,
+        baseRef: string,
+        sessionId: string | null,
+        info: {
+          mergeBase: string;
+          mainlineHead: string;
+          worktreeHead: string;
+          conflictingFiles: string[];
+        },
+      ) => Promise<boolean>;
+    };
+
+    await expect(
+      svc.dispatchReconcilerTurn('feat1', 'main', 'reconciler:1', {
+        mergeBase: 'base',
+        mainlineHead: 'main',
+        worktreeHead: 'feat',
+        conflictingFiles: ['src/shared.ts'],
+      }),
+    ).resolves.toBe(false);
+
+    expect(refreshReconcilerSessionMock).toHaveBeenCalledTimes(1);
+    expect(sendMessageMock).toHaveBeenCalledTimes(1);
+    expect(fsAppendFileMock).toHaveBeenCalledWith(
+      expect.stringContaining('reconciliation.log'),
+      expect.stringContaining(
+        'dispatch_failed: claude provider send failed: No conversation found with session ID: reconciler:1 session_id=reconciler:1',
+      ),
+      'utf8',
+    );
+  });
+
+  it('GIVEN_missing_claude_reconciler_conversation_WHEN_retry_dispatch_fails_THEN_logs_the_retry_failure', async () => {
+    const sendMessageMock = vi
+      .fn<(sessionId: string, _message: string) => Promise<void>>()
+      .mockRejectedValueOnce(
+        Object.assign(new Error('claude provider send failed'), {
+          details: { stderr: 'No conversation found with session ID: reconciler:1' },
+        }),
+      )
+      .mockRejectedValueOnce(new Error('retry dispatch failed'));
+    const refreshReconcilerSessionMock = vi.fn(async () => 'reconciler:2');
+    const svc = makeSvc({
+      refreshReconcilerSession: refreshReconcilerSessionMock,
+      getProvider: vi.fn(() => ({
+        sendMessage: sendMessageMock,
+        getSessionInfo: vi.fn(async () => ({ active: true, provider: 'claude' })),
+      })),
+    }) as unknown as {
+      dispatchReconcilerTurn: (
+        featureId: string,
+        baseRef: string,
+        sessionId: string | null,
+        info: {
+          mergeBase: string;
+          mainlineHead: string;
+          worktreeHead: string;
+          conflictingFiles: string[];
+        },
+      ) => Promise<boolean>;
+    };
+
+    await expect(
+      svc.dispatchReconcilerTurn('feat1', 'main', 'reconciler:1', {
+        mergeBase: 'base',
+        mainlineHead: 'main',
+        worktreeHead: 'feat',
+        conflictingFiles: ['src/shared.ts'],
+      }),
+    ).resolves.toBe(false);
+
+    expect(refreshReconcilerSessionMock).toHaveBeenCalledTimes(1);
+    expect(sendMessageMock).toHaveBeenNthCalledWith(
+      2,
+      'reconciler:2',
+      expect.stringContaining('feature_id=feat1'),
+    );
+    expect(fsAppendFileMock).toHaveBeenCalledWith(
+      expect.stringContaining('reconciliation.log'),
+      expect.stringContaining('dispatch_failed: retry dispatch failed session_id=reconciler:2'),
+      'utf8',
+    );
+  });
+
+  it('GIVEN_active_prepared_conflict_WHEN_redriving_reconciler_assignment_THEN_dispatches_the_pending_turn', async () => {
+    runGitMock.mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'src/shared.ts\n' }));
+    const sendMessageMock = vi.fn(async () => undefined);
+    const writeStateMock = vi.fn(async () => {});
+    const svc = makeSvc({
+      readState: vi.fn(async () => ({
+        frontMatter: {
+          feature_id: 'feat1',
+          version: 1,
+          status: 'blocked',
+          conflicts: [
+            {
+              type: 'mainline_divergence',
+              base_ref: 'main',
+              merge_base: 'base123',
+              mainline_head: 'main456',
+              worktree_head: 'feat789',
+              conflicting_files: ['src/shared.ts'],
+              resolution_status: 'in_progress',
+              resume_status: 'ready_to_merge',
+            },
+          ],
+        },
+        body: '# Feature\n',
+      })),
+      writeState: writeStateMock,
+      readRunLease: vi.fn(
+        async () =>
+          ({
+            run_id: 'run:test',
+            orchestrator_session_id: 'orchestrator:1',
+            reconciler_session_id: 'reconciler:1',
+            reconciler_active_feature_id: 'feat1',
+            reconciler_queue: [],
+            provider: 'claude',
+            model: 'claude-sonnet-4-6',
+            provider_config_ref_hash: 'hash',
+            owner_instance_id: 'owner:test',
+            lease_id: 'lease:test',
+            started_at: '2026-01-01T00:00:00.000Z',
+            last_heartbeat_at: '2026-01-01T00:00:00.000Z',
+            lease_expires_at: '2026-01-01T00:05:00.000Z',
+            feature_sessions: {},
+          }) satisfies RuntimeSessionsSnapshot,
+      ),
+      getProvider: vi.fn(() => ({
+        sendMessage: sendMessageMock,
+        getSessionInfo: vi.fn(async () => ({ active: true, provider: 'claude' })),
+      })),
+    });
+
+    await expect(svc.redrivePreparedReconcilerConflict('feat1')).resolves.toBe(true);
+
+    expect(sendMessageMock).toHaveBeenCalledTimes(1);
+    expect(writeStateMock).toHaveBeenCalledWith(
+      'feat1',
+      expect.objectContaining({
+        status: 'blocked',
+        status_reason: 'Mainline divergence assigned to the shared reconciler lane',
+      }),
+      '# Feature\n',
+    );
+  });
+
+  it('GIVEN_session_never_becomes_active_WHEN_waiting_for_reconciler_session_THEN_times_out_cleanly', async () => {
+    vi.useFakeTimers();
+    const getSessionInfoMock = vi.fn(async () => ({ active: false, provider: 'codex' }));
+    const svc = makeSvc() as unknown as {
+      waitForSessionToBecomeActive: (
+        provider: {
+          getSessionInfo: (sessionId: string) => Promise<{ active: boolean; provider: string }>;
+        },
+        sessionId: string,
+      ) => Promise<void>;
+    };
+
+    const waitPromise = svc.waitForSessionToBecomeActive(
+      { getSessionInfo: getSessionInfoMock },
+      'reconciler:1',
+    );
+    await vi.advanceTimersByTimeAsync(6000);
+    await waitPromise;
+
+    expect(getSessionInfoMock).toHaveBeenCalled();
+    vi.useRealTimers();
+  });
+
+  it('GIVEN_released_lane_with_stale_first_queue_entry_WHEN_dispatching_next_THEN_promotes_next_dispatchable_feature', async () => {
+    let runtimeSessions: RuntimeSessionsSnapshot = {
+      run_id: 'run:test',
+      orchestrator_session_id: 'orchestrator:1',
+      reconciler_session_id: 'reconciler:1',
+      reconciler_active_feature_id: 'feat1',
+      reconciler_queue: ['feat2', 'feat3'],
+      provider: 'codex',
+      model: 'codex-default',
+      provider_config_ref_hash: 'hash',
+      owner_instance_id: 'owner:test',
+      lease_id: 'lease:test',
+      started_at: '2026-01-01T00:00:00.000Z',
+      last_heartbeat_at: '2026-01-01T00:00:00.000Z',
+      lease_expires_at: '2026-01-01T00:05:00.000Z',
+      feature_sessions: {},
+    };
+    const sendMessageMock = vi.fn(async () => undefined);
+
+    runGitMock
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: '' }))
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: '' }));
+
+    const svc = makeSvc({
+      readRunLease: vi.fn(async () => runtimeSessions),
+      writeRunLease: vi.fn(async (nextState: RuntimeSessionsSnapshot) => {
+        runtimeSessions = nextState;
+      }),
+      readState: vi.fn(async (featureId: string) => {
+        if (featureId === 'feat2') {
+          return {
+            frontMatter: {
+              feature_id: 'feat2',
+              version: 1,
+              status: 'blocked',
+              conflicts: [{ type: 'mainline_divergence', resolution_status: 'pending' }],
+            } as Record<string, unknown>,
+            body: '# Feature 2\n',
+          };
+        }
+        return {
+          frontMatter: {
+            feature_id: 'feat3',
+            version: 1,
+            status: 'blocked',
+            conflicts: [
+              {
+                type: 'mainline_divergence',
+                resolution_status: 'pending',
+                merge_base: 'base3',
+                mainline_head: 'main3',
+                worktree_head: 'feat3head',
+                conflicting_files: ['src/shared.ts'],
+              },
+            ],
+          } as Record<string, unknown>,
+          body: '# Feature 3\n',
+        };
+      }),
+      getProvider: vi.fn(() => ({
+        sendMessage: sendMessageMock,
+        getSessionInfo: vi.fn(async () => ({ active: true, provider: 'codex' })),
+      })),
+    }) as unknown as {
+      releaseAndDispatchNext: (featureId: string, baseRef: string) => Promise<void>;
+    };
+
+    await svc.releaseAndDispatchNext('feat1', 'main');
+
+    expect(runtimeSessions.reconciler_active_feature_id).toBe('feat3');
+    expect(runtimeSessions.reconciler_queue).toEqual([]);
+    expect(sendMessageMock).toHaveBeenCalledWith(
+      'reconciler:1',
+      expect.stringContaining('feature_id=feat3'),
+    );
+  });
+
+  it('GIVEN_idle_lane_with_feature_already_in_queue_WHEN_claiming_THEN_promotes_feature_and_removes_duplicate_queue_entry', async () => {
+    let runtimeSessions: RuntimeSessionsSnapshot = {
+      run_id: 'run:test',
+      orchestrator_session_id: 'orchestrator:1',
+      reconciler_session_id: 'reconciler:1',
+      reconciler_active_feature_id: null,
+      reconciler_queue: ['feat1', 'feat2'],
+      provider: 'codex',
+      model: 'codex-default',
+      provider_config_ref_hash: 'hash',
+      owner_instance_id: 'owner:test',
+      lease_id: 'lease:test',
+      started_at: '2026-01-01T00:00:00.000Z',
+      last_heartbeat_at: '2026-01-01T00:00:00.000Z',
+      lease_expires_at: '2026-01-01T00:05:00.000Z',
+      feature_sessions: {},
+    };
+
+    const svc = makeSvc({
+      readRunLease: vi.fn(async () => runtimeSessions),
+      writeRunLease: vi.fn(async (nextState: RuntimeSessionsSnapshot) => {
+        runtimeSessions = nextState;
+      }),
+    }) as unknown as {
+      claimReconcilerLane: (featureId: string) => Promise<{
+        activeFeatureId: string | null;
+        queuePosition: number | null;
+        dispatchNow: boolean;
+      }>;
+    };
+
+    const claim = await svc.claimReconcilerLane('feat1');
+
+    expect(claim.activeFeatureId).toBe('feat1');
+    expect(claim.dispatchNow).toBe(true);
+    expect(runtimeSessions.reconciler_queue).toEqual(['feat2']);
+  });
+
+  it('GIVEN_feature_already_owns_reconciler_lane_WHEN_claiming_THEN_deduplicates_queue_without_requeueing', async () => {
+    let runtimeSessions: RuntimeSessionsSnapshot = {
+      run_id: 'run:test',
+      orchestrator_session_id: 'orchestrator:1',
+      reconciler_session_id: 'reconciler:1',
+      reconciler_active_feature_id: 'feat1',
+      reconciler_queue: ['feat1', 'feat2', 'feat2', 'feat3'],
+      provider: 'codex',
+      model: 'codex-default',
+      provider_config_ref_hash: 'hash',
+      owner_instance_id: 'owner:test',
+      lease_id: 'lease:test',
+      started_at: '2026-01-01T00:00:00.000Z',
+      last_heartbeat_at: '2026-01-01T00:00:00.000Z',
+      lease_expires_at: '2026-01-01T00:05:00.000Z',
+      feature_sessions: {},
+    };
+
+    const svc = makeSvc({
+      readRunLease: vi.fn(async () => runtimeSessions),
+      writeRunLease: vi.fn(async (nextState: RuntimeSessionsSnapshot) => {
+        runtimeSessions = nextState;
+      }),
+    }) as unknown as {
+      claimReconcilerLane: (featureId: string) => Promise<{
+        activeFeatureId: string | null;
+        queuePosition: number | null;
+        dispatchNow: boolean;
+      }>;
+    };
+
+    const claim = await svc.claimReconcilerLane('feat1');
+
+    expect(claim.activeFeatureId).toBe('feat1');
+    expect(claim.queuePosition).toBe(0);
+    expect(claim.dispatchNow).toBe(false);
+    expect(runtimeSessions.reconciler_queue).toEqual(['feat2', 'feat3']);
+  });
+
+  it('GIVEN_releasing_non_active_queued_feature_WHEN_releasing_lane_THEN_removes_it_without_changing_active_owner', async () => {
+    let runtimeSessions: RuntimeSessionsSnapshot = {
+      run_id: 'run:test',
+      orchestrator_session_id: 'orchestrator:1',
+      reconciler_session_id: 'reconciler:1',
+      reconciler_active_feature_id: 'feat1',
+      reconciler_queue: ['feat2', 'feat3'],
+      provider: 'codex',
+      model: 'codex-default',
+      provider_config_ref_hash: 'hash',
+      owner_instance_id: 'owner:test',
+      lease_id: 'lease:test',
+      started_at: '2026-01-01T00:00:00.000Z',
+      last_heartbeat_at: '2026-01-01T00:00:00.000Z',
+      lease_expires_at: '2026-01-01T00:05:00.000Z',
+      feature_sessions: {},
+    };
+
+    const svc = makeSvc({
+      readRunLease: vi.fn(async () => runtimeSessions),
+      writeRunLease: vi.fn(async (nextState: RuntimeSessionsSnapshot) => {
+        runtimeSessions = nextState;
+      }),
+    }) as unknown as {
+      releaseReconcilerLane: (featureId: string) => Promise<{
+        nextFeatureId: string | null;
+        sessionId: string | null;
+      }>;
+    };
+
+    const release = await svc.releaseReconcilerLane('feat2');
+
+    expect(release.nextFeatureId).toBe('feat1');
+    expect(runtimeSessions.reconciler_active_feature_id).toBe('feat1');
+    expect(runtimeSessions.reconciler_queue).toEqual(['feat3']);
+  });
+
+  it('GIVEN_queued_feature_without_readable_state_WHEN_activating_THEN_returns_false', async () => {
+    const svc = makeSvc({
+      readState: vi.fn(async () => {
+        throw new Error('missing state');
+      }),
+    }) as unknown as {
+      activateQueuedFeature: (
+        featureId: string,
+        baseRef: string,
+        sessionId: string | null,
+      ) => Promise<boolean>;
+    };
+
+    await expect(svc.activateQueuedFeature('feat2', 'main', 'reconciler:1')).resolves.toBe(false);
+  });
+
+  it('GIVEN_queued_feature_without_unresolved_mainline_conflict_WHEN_activating_THEN_returns_false', async () => {
+    const svc = makeSvc({
+      readState: vi.fn(async () => ({
+        frontMatter: {
+          feature_id: 'feat2',
+          version: 1,
+          status: 'blocked',
+          conflicts: [{ type: 'qa_blocker', resolution_status: 'pending' }],
+        } as Record<string, unknown>,
+        body: '# Feature 2\n',
+      })),
+    }) as unknown as {
+      activateQueuedFeature: (
+        featureId: string,
+        baseRef: string,
+        sessionId: string | null,
+      ) => Promise<boolean>;
+    };
+
+    await expect(svc.activateQueuedFeature('feat2', 'main', 'reconciler:1')).resolves.toBe(false);
+  });
+
+  it('GIVEN_queued_feature_without_conflict_files_WHEN_activating_THEN_returns_false', async () => {
+    runGitMock.mockResolvedValueOnce(cmdResult({ code: 0, stdout: '' }));
+
+    const svc = makeSvc({
+      readState: vi.fn(async () => ({
+        frontMatter: {
+          feature_id: 'feat2',
+          version: 1,
+          status: 'blocked',
+          conflicts: [{ type: 'mainline_divergence', resolution_status: 'pending' }],
+        } as Record<string, unknown>,
+        body: '# Feature 2\n',
+      })),
+    }) as unknown as {
+      activateQueuedFeature: (
+        featureId: string,
+        baseRef: string,
+        sessionId: string | null,
+      ) => Promise<boolean>;
+    };
+
+    await expect(svc.activateQueuedFeature('feat2', 'main', 'reconciler:1')).resolves.toBe(false);
+  });
+
+  it('GIVEN_queued_feature_with_unmerged_files_WHEN_activating_THEN_dispatches_reconciler_turn', async () => {
+    const sendMessageMock = vi.fn(async () => undefined);
+    runGitMock.mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'src/shared.ts\n' }));
+
+    const svc = makeSvc({
+      readState: vi.fn(async () => ({
+        frontMatter: {
+          feature_id: 'feat2',
+          version: 1,
+          status: 'blocked',
+          conflicts: [
+            {
+              type: 'mainline_divergence',
+              resolution_status: 'pending',
+              merge_base: 'base2',
+              mainline_head: 'main2',
+              worktree_head: 'feat2head',
+            },
+          ],
+        } as Record<string, unknown>,
+        body: '# Feature 2\n',
+      })),
+      getProvider: vi.fn(() => ({
+        sendMessage: sendMessageMock,
+        getSessionInfo: vi.fn(async () => ({ active: true, provider: 'codex' })),
+      })),
+    }) as unknown as {
+      activateQueuedFeature: (
+        featureId: string,
+        baseRef: string,
+        sessionId: string | null,
+      ) => Promise<boolean>;
+    };
+
+    await expect(svc.activateQueuedFeature('feat2', 'main', 'reconciler:1')).resolves.toBe(true);
+    expect(sendMessageMock).toHaveBeenCalledWith(
+      'reconciler:1',
+      expect.stringContaining('feature_id=feat2'),
+    );
+  });
+
+  it('GIVEN_state_write_helpers_throw_WHEN_reconciliation_state_updates_run_THEN_errors_are_swallowed', async () => {
+    runGitMock
+      .mockResolvedValueOnce(cmdResult({ code: 0 })) // fetch
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'base001\n' })) // merge-base
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'base001\n' })) // rev-parse main
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'origin001\n' })) // rev-parse origin/main
+      .mockResolvedValueOnce(cmdResult({ code: 0, stdout: 'feat111\n' })); // rev-parse HEAD
+
+    const svc = makeSvc({
+      writeState: vi.fn(async () => {
+        throw new Error('write failed');
+      }),
+    });
+
+    const result = await svc.reconcileWithMainline('feat1', 'main');
+    expect(result.ok).toBe(true);
+
+    const privateSvc = svc as unknown as {
+      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>;
+      resolveMainlineConflictState: (featureId: string, mainlineHead: string) => Promise<void>;
+    };
+
+    await expect(
+      privateSvc.upsertMainlineConflictState(
+        'feat1',
+        {
+          mergeBase: 'base',
+          mainlineHead: 'main',
+          worktreeHead: 'feat',
+          conflictingFiles: ['src/shared.ts'],
+        },
+        {
+          baseRef: 'main',
+          resolutionStatus: 'pending',
+          queuePosition: 1,
+          statusReason: 'queued',
+        },
+      ),
+    ).resolves.toBeUndefined();
+    await expect(privateSvc.resolveMainlineConflictState('feat1', 'main')).resolves.toBeUndefined();
+  });
+});