xtrm-cli 0.5.0

package/src/core/sync-executor.ts

@@ -0,0 +1,427 @@
+import path from 'path';
+import fs from 'fs-extra';
+import kleur from 'kleur';
+import { safeMergeConfig } from '../utils/atomic-config.js';
+import { ConfigAdapter } from '../utils/config-adapter.js';
+import { syncMcpServersWithCli, loadCanonicalMcpConfig, detectAgent } from '../utils/sync-mcp-cli.js';
+import { hashDirectory } from '../utils/hash.js';
+import { createBackup, restoreBackup, cleanupBackup, type BackupInfo } from './rollback.js';
+import type { ChangeSet } from '../types/config.js';
+
+/**
+ * Sync MCP servers for a list of targets, once per unique agent type.
+ * Call this explicitly before per-target file sync loops.
+ */
+export async function syncMcpForTargets(
+    repoRoot: string,
+    targets: string[],
+    isDryRun: boolean = false,
+    selectedMcpServers?: string[],
+): Promise<number> {
+    const synced = new Set<string>();
+    let count = 0;
+
+    for (const target of targets) {
+        const agent = detectAgent(target);
+        if (!agent || synced.has(agent)) continue;
+
+        const coreConfig = loadCanonicalMcpConfig(repoRoot);
+        const mcpToSync: any = { mcpServers: { ...coreConfig.mcpServers } };
+
+        if (selectedMcpServers && selectedMcpServers.length > 0) {
+            const optionalConfig = loadCanonicalMcpConfig(repoRoot, true);
+            for (const name of selectedMcpServers) {
+                if (optionalConfig.mcpServers[name]) {
+                    mcpToSync.mcpServers[name] = optionalConfig.mcpServers[name];
+                }
+            }
+        }
+
+        if (!isDryRun) {
+            await syncMcpServersWithCli(agent, mcpToSync, isDryRun, false);
+        } else {
+            console.log(kleur.cyan(`  [DRY RUN] MCP sync for ${agent}`));
+        }
+        synced.add(agent);
+        count++;
+    }
+
+    return count;
+}
+
+/**
+ * Execute a sync plan based on changeset and mode
+ */
+
+function extractHookCommandPath(command: string): string | null {
+    const quoted = command.match(/"([^"]+)"/);
+    if (quoted?.[1]) return quoted[1];
+
+    const singleQuoted = command.match(/'([^']+)'/);
+    if (singleQuoted?.[1]) return singleQuoted[1];
+
+    const bare = command.trim().split(/\s+/).slice(1).join(' ').trim();
+    return bare || null;
+}
+
+async function filterHooksByInstalledScripts(hooksConfig: any): Promise<any> {
+    if (!hooksConfig || typeof hooksConfig !== 'object' || !hooksConfig.hooks) {
+        return hooksConfig;
+    }
+
+    for (const [event, wrappers] of Object.entries(hooksConfig.hooks)) {
+        if (!Array.isArray(wrappers)) continue;
+
+        const keptWrappers: any[] = [];
+        for (const wrapper of wrappers) {
+            if (!wrapper || !Array.isArray(wrapper.hooks)) continue;
+
+            const keptInner: any[] = [];
+            for (const inner of wrapper.hooks) {
+                const command = inner?.command;
+                if (typeof command !== 'string' || !command.trim()) continue;
+
+                const scriptPath = extractHookCommandPath(command);
+                if (!scriptPath) continue;
+
+                if (await fs.pathExists(scriptPath)) {
+                    keptInner.push(inner);
+                }
+            }
+
+            if (keptInner.length > 0) {
+                keptWrappers.push({ ...wrapper, hooks: keptInner });
+            }
+        }
+
+        hooksConfig.hooks[event] = keptWrappers;
+    }
+
+    return hooksConfig;
+}
+
+export async function executeSync(
+    repoRoot: string,
+    systemRoot: string,
+    changeSet: ChangeSet,
+    mode: 'copy' | 'symlink' | 'prune',
+    actionType: 'sync' | 'backport',
+    isDryRun: boolean = false,
+    options?: { force?: boolean },
+): Promise<number> {
+    const normalizedRoot = path.normalize(systemRoot).replace(/\\/g, '/');
+    const isAgentsSkills = normalizedRoot.includes('.agents/skills');
+    const isClaude = systemRoot.includes('.claude') || systemRoot.includes('Claude');
+
+    // ~/.agents/skills: skills-only, written directly into systemRoot (no subdirectory)
+    if (isAgentsSkills) {
+        return executeSyncAgentsSkills(repoRoot, systemRoot, changeSet, mode, actionType, isDryRun);
+    }
+
+    const categories: Array<keyof ChangeSet> = ['skills', 'hooks', 'config'];
+
+
+    let count = 0;
+    const adapter = new ConfigAdapter(systemRoot);
+    const backups: BackupInfo[] = [];
+    const newHashes: Record<string, string> = {};
+
+    try {
+        const agent = detectAgent(systemRoot);
+
+
+
+        for (const category of categories) {
+            const itemsToProcess: string[] = [];
+
+            if (actionType === 'sync') {
+                const cat = changeSet[category] as any;
+                itemsToProcess.push(...cat.missing);
+                itemsToProcess.push(...cat.outdated);
+
+                if (options?.force) {
+                    itemsToProcess.push(...cat.drifted);
+                }
+
+                if (mode === 'prune') {
+                    for (const itemToDelete of cat.drifted || []) {
+                        const dest = path.join(systemRoot, category, itemToDelete);
+                        console.log(kleur.red(`  [x] PRUNING ${category}/${itemToDelete}`));
+                        if (!isDryRun) {
+                            if (await fs.pathExists(dest)) {
+                                backups.push(await createBackup(dest));
+                                await fs.remove(dest);
+                            }
+                        }
+                        count++;
+                    }
+                }
+            } else if (actionType === 'backport') {
+                const cat = changeSet[category] as any;
+                itemsToProcess.push(...cat.drifted);
+            }
+
+            for (const item of itemsToProcess) {
+                let src: string, dest: string;
+
+                if (category === 'config' && item === 'settings.json' && actionType === 'sync') {
+                    src = path.join(repoRoot, 'config', 'settings.json');
+                    dest = path.join(systemRoot, 'settings.json');
+
+                    const agent = detectAgent(systemRoot);
+
+                    // Claude Code: settings.json managed by xtrm-tools plugin — skip wiring
+                    if (agent === 'claude') {
+                        if (!isDryRun) console.log(kleur.dim(`      (settings.json skipped — managed by xtrm-tools plugin)`));
+                        count++;
+                        continue;
+                    }
+
+                    console.log(kleur.gray(`  --> config/settings.json`));
+
+                    if (!isDryRun && await fs.pathExists(dest)) {
+                        backups.push(await createBackup(dest));
+                    }
+
+                    const repoConfig = await fs.readJson(src);
+                    let finalRepoConfig = resolveConfigPaths(repoConfig, systemRoot);
+
+                    // When agent CLI handles MCP servers, strip them from the config merge
+                    // but still merge hooks, permissions, plugins, skillSuggestions, etc.
+                    if (agent) {
+                        delete finalRepoConfig.mcpServers;
+                        if (!isDryRun) console.log(kleur.dim(`      (MCP servers managed by ${agent} CLI — merging non-MCP settings only)`));
+                    }
+
+                    const hooksSrc = path.join(repoRoot, 'config', 'hooks.json');
+                    if (await fs.pathExists(hooksSrc)) {
+                        const hooksRaw = await fs.readJson(hooksSrc);
+                        const hooksAdapted = await filterHooksByInstalledScripts(adapter.adaptHooksConfig(hooksRaw));
+                        if (hooksAdapted.hooks) {
+                            // hooks.json is the canonical source — replace template hooks entirely
+                            // hooks.json is canonical source — replace template hooks entirely
+                            finalRepoConfig.hooks = hooksAdapted.hooks;
+                            if (!isDryRun) console.log(kleur.dim(`      (Injected hooks)`));
+                        }
+                        if (hooksAdapted.statusLine) {
+                            finalRepoConfig.statusLine = hooksAdapted.statusLine;
+                        }
+                    }
+
+                    if (fs.existsSync(dest)) {
+                        const localConfig = await fs.readJson(dest);
+                        const resolvedLocalConfig = resolveConfigPaths(localConfig, systemRoot);
+
+                        if (mode === 'prune') {
+                            if (localConfig.mcpServers && finalRepoConfig.mcpServers) {
+                                const canonicalServers = new Set(Object.keys(finalRepoConfig.mcpServers));
+                                for (const serverName of Object.keys(localConfig.mcpServers)) {
+                                    if (!canonicalServers.has(serverName)) {
+                                        delete localConfig.mcpServers[serverName];
+                                        if (!isDryRun) console.log(kleur.red(`      (Pruned local MCP server: ${serverName})`));
+                                    }
+                                }
+                            }
+                        }
+
+                        if (mode === 'prune' && !isDryRun) {
+                            console.log(kleur.dim(`      (--prune: replacing canonical hook events wholesale)`));
+                        }
+
+                        const mergeResult = await safeMergeConfig(dest, finalRepoConfig, {
+                            backupOnSuccess: false,
+                            preserveComments: true,
+                            dryRun: isDryRun,
+                            resolvedLocalConfig: resolvedLocalConfig,
+                            pruneHooks: mode === 'prune',
+                        });
+
+                        if (mergeResult.updated) {
+                            console.log(kleur.blue(`      (Configuration safely merged)`));
+                        }
+                    } else {
+                        if (!isDryRun) {
+                            await fs.ensureDir(path.dirname(dest));
+                            await fs.writeJson(dest, finalRepoConfig, { spaces: 2 });
+                        }
+                        console.log(kleur.green(`      (Created new configuration)`));
+                    }
+                    count++;
+                    continue;
+                }
+
+                const repoPath = path.join(repoRoot, category);
+                const systemPath = path.join(systemRoot, category);
+
+                if (actionType === 'backport') {
+                    src = path.join(systemPath, item);
+                    dest = path.join(repoPath, item);
+                } else {
+                    src = path.join(repoPath, item);
+                    dest = path.join(systemPath, item);
+                }
+
+                console.log(kleur.gray(`  ${actionType === 'backport' ? '<--' : '-->'} ${category}/${item}`));
+
+                if (!isDryRun && actionType === 'sync' && await fs.pathExists(dest)) {
+                    backups.push(await createBackup(dest));
+                }
+
+                if (mode === 'symlink' && actionType === 'sync' && category !== 'config') {
+                    if (!isDryRun) {
+                        if (process.platform === 'win32') {
+                            console.log(kleur.yellow('  ⚠ Symlinks require Developer Mode on Windows — falling back to copy.'));
+                            await fs.remove(dest);
+                            await fs.copy(src, dest);
+                        } else {
+                            await fs.remove(dest);
+                            await fs.ensureSymlink(src, dest);
+                        }
+                    }
+                } else {
+                    if (!isDryRun) {
+                        await fs.remove(dest);
+                        await fs.copy(src, dest);
+                    }
+                }
+
+                // Record repo hash so future drift checks can distinguish
+                // "user modified" from "repo updated" without relying on mtime
+                if (!isDryRun && actionType === 'sync') {
+                    newHashes[`${category}/${item}`] = await hashDirectory(src);
+                }
+
+                count++;
+            }
+        }
+
+        if (!isDryRun && actionType === 'sync') {
+            const manifestPath = path.join(systemRoot, '.jaggers-sync-manifest.json');
+            const existing = await fs.pathExists(manifestPath)
+                ? await fs.readJson(manifestPath)
+                : {};
+            await fs.writeJson(manifestPath, {
+                ...existing,
+                lastSync: new Date().toISOString(),
+                repoRoot,
+                items: count,
+                fileHashes: { ...(existing.fileHashes ?? {}), ...newHashes },
+            }, { spaces: 2 });
+        }
+
+        for (const backup of backups) {
+            await cleanupBackup(backup);
+        }
+
+        return count;
+
+    } catch (error: any) {
+        console.error(kleur.red(`\nSync failed, rolling back ${backups.length} changes...`));
+        for (const backup of backups) {
+            try {
+                await restoreBackup(backup);
+            } finally {
+                await cleanupBackup(backup);
+            }
+        }
+        throw error;
+    }
+}
+
+/**
+ * Sync skills directly into ~/.agents/skills/<skill> (no subdirectory indirection).
+ * This target is skills-only — no hooks, config, MCP, or commands.
+ */
+async function executeSyncAgentsSkills(
+    repoRoot: string,
+    systemRoot: string,
+    changeSet: ChangeSet,
+    mode: 'copy' | 'symlink' | 'prune',
+    actionType: 'sync' | 'backport',
+    isDryRun: boolean,
+): Promise<number> {
+    let count = 0;
+    const backups: BackupInfo[] = [];
+
+    try {
+        const repoSkillsPath = path.join(repoRoot, 'skills');
+        const itemsToProcess: string[] = [];
+
+        if (actionType === 'sync') {
+            itemsToProcess.push(...changeSet.skills.missing, ...changeSet.skills.outdated);
+        } else if (actionType === 'backport') {
+            itemsToProcess.push(...changeSet.skills.drifted);
+        }
+
+        for (const item of itemsToProcess) {
+            const src = actionType === 'backport'
+                ? path.join(systemRoot, item)
+                : path.join(repoSkillsPath, item);
+            const dest = actionType === 'backport'
+                ? path.join(repoSkillsPath, item)
+                : path.join(systemRoot, item);
+
+            console.log(kleur.gray(`  ${actionType === 'backport' ? '<--' : '-->'} ${item}`));
+
+            if (!isDryRun) {
+                if (await fs.pathExists(dest)) backups.push(await createBackup(dest));
+                await fs.ensureDir(path.dirname(dest));
+
+                if (mode === 'symlink' && actionType === 'sync') {
+                    if (process.platform === 'win32') {
+                        console.log(kleur.yellow('  ⚠ Symlinks require Developer Mode on Windows — falling back to copy.'));
+                        await fs.remove(dest);
+                        await fs.copy(src, dest);
+                    } else {
+                        await fs.remove(dest);
+                        await fs.ensureSymlink(src, dest);
+                    }
+                } else {
+                    await fs.remove(dest);
+                    await fs.copy(src, dest);
+                }
+            }
+            count++;
+        }
+
+        for (const backup of backups) await cleanupBackup(backup);
+        return count;
+
+    } catch (error: any) {
+        console.error(kleur.red(`\nSync failed, rolling back ${backups.length} changes...`));
+        for (const backup of backups) {
+            try { await restoreBackup(backup); } finally { await cleanupBackup(backup); }
+        }
+        throw error;
+    }
+}
+
+function resolveConfigPaths(config: any, targetDir: string): any {
+    const newConfig = JSON.parse(JSON.stringify(config));
+    const home = process.env.HOME || process.env.USERPROFILE || '';
+
+    function recursiveReplace(obj: any) {
+        for (const key in obj) {
+            if (typeof obj[key] === 'string') {
+                let val = obj[key];
+                // Resolve $HOME and ~ to actual home directory for comparison
+                // but only match absolute paths, not env-var paths like "$HOME/..."
+                if (!val.startsWith('$') && !val.startsWith('~')) {
+                    if (val.match(/\/[^\s"']+\/hooks\//)) {
+                        const hooksDir = path.join(targetDir, 'hooks');
+                        let replacementDir = `${hooksDir}/`;
+                        if (process.platform === 'win32') {
+                            replacementDir = replacementDir.replace(/\\/g, '/');
+                        }
+                        obj[key] = val.replace(/(\/[^\s"']+\/hooks\/)/g, replacementDir);
+                    }
+                }
+            } else if (typeof obj[key] === 'object' && obj[key] !== null) {
+                recursiveReplace(obj[key]);
+            }
+        }
+    }
+
+    recursiveReplace(newConfig);
+    return newConfig;
+}

package/src/core/xtrm-finish.ts

@@ -0,0 +1,267 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import {
+  readSessionState,
+  updateSessionPhase,
+  type SessionState,
+} from './session-state.js';
+
+export interface FinishOptions {
+  cwd?: string;
+  pollIntervalMs?: number;
+  timeoutMs?: number;
+}
+
+export interface FinishResult {
+  ok: boolean;
+  message: string;
+}
+
+interface CmdResult {
+  code: number;
+  stdout: string;
+  stderr: string;
+}
+
+const DEFAULT_POLL_INTERVAL_MS = 5000;
+const DEFAULT_TIMEOUT_MS = 10 * 60 * 1000;
+
+function run(cmd: string, args: string[], cwd: string): CmdResult {
+  const r = spawnSync(cmd, args, {
+    cwd,
+    encoding: 'utf8',
+    stdio: ['pipe', 'pipe', 'pipe'],
+  });
+  return {
+    code: r.status ?? 1,
+    stdout: (r.stdout ?? '').trim(),
+    stderr: (r.stderr ?? '').trim(),
+  };
+}
+
+function getControlRepoRoot(cwd: string): string {
+  const commonDir = run('git', ['rev-parse', '--path-format=absolute', '--git-common-dir'], cwd);
+  if (commonDir.code === 0 && commonDir.stdout) {
+    return commonDir.stdout.replace(/\/.git$/, '');
+  }
+  return cwd;
+}
+
+function resolveExecutionCwd(controlCwd: string, state: SessionState): string {
+  if (state.worktreePath && existsSync(state.worktreePath)) {
+    return state.worktreePath;
+  }
+  return controlCwd;
+}
+
+function parsePrCreate(stdout: string): { prNumber: number | null; prUrl: string | null } {
+  const urlMatch = stdout.match(/https?:\/\/\S+\/pull\/(\d+)/);
+  if (urlMatch) {
+    return { prNumber: Number(urlMatch[1]), prUrl: urlMatch[0] };
+  }
+
+  const numberMatch = stdout.match(/#(\d+)/);
+  if (numberMatch) {
+    return { prNumber: Number(numberMatch[1]), prUrl: null };
+  }
+
+  return { prNumber: null, prUrl: null };
+}
+
+function getConflictFiles(cwd: string): string[] {
+  const out = run('git', ['diff', '--name-only', '--diff-filter=U'], cwd);
+  if (out.code !== 0 || !out.stdout) return [];
+  return out.stdout.split('\n').map((s) => s.trim()).filter(Boolean);
+}
+
+async function delay(ms: number): Promise<void> {
+  if (ms <= 0) return;
+  await new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function ensureCleanPhaseTransition(cwd: string, phase: SessionState['phase'], patch: Partial<SessionState> = {}) {
+  try {
+    updateSessionPhase(phase, cwd, patch);
+  } catch {
+    // non-fatal for re-entrant paths
+  }
+}
+
+function handleRebaseAndPush(cwd: string): { ok: boolean; conflicts?: string[]; error?: string } {
+  const fetch = run('git', ['fetch', 'origin'], cwd);
+  if (fetch.code !== 0) return { ok: false, error: fetch.stderr || fetch.stdout };
+
+  const rebase = run('git', ['rebase', 'origin/main'], cwd);
+  if (rebase.code !== 0) {
+    const conflicts = getConflictFiles(cwd);
+    return { ok: false, conflicts, error: rebase.stderr || rebase.stdout };
+  }
+
+  const push = run('git', ['push', '--force-with-lease'], cwd);
+  if (push.code !== 0) {
+    return { ok: false, error: push.stderr || push.stdout };
+  }
+
+  return { ok: true };
+}
+
+function cleanupPhase(controlCwd: string, state: SessionState): FinishResult {
+  if (existsSync(state.worktreePath)) {
+    const rm = run('git', ['worktree', 'remove', state.worktreePath, '--force'], controlCwd);
+    if (rm.code !== 0) {
+      return { ok: false, message: rm.stderr || rm.stdout || `Failed to remove worktree ${state.worktreePath}` };
+    }
+  }
+
+  run('git', ['fetch', '--prune'], controlCwd);
+  ensureCleanPhaseTransition(controlCwd, 'cleanup-done');
+
+  const prLabel = state.prNumber != null ? `#${state.prNumber}` : '(unknown PR)';
+  return { ok: true, message: `Done. PR ${prLabel} merged. Worktree removed.` };
+}
+
+async function pollUntilMerged(controlCwd: string, executionCwd: string, state: SessionState, opts: Required<FinishOptions>): Promise<FinishResult> {
+  if (state.prNumber == null) {
+    return { ok: false, message: 'Session state missing prNumber. Re-run phase 1 before polling.' };
+  }
+
+  const started = Date.now();
+  while ((Date.now() - started) < opts.timeoutMs) {
+    const view = run('gh', ['pr', 'view', String(state.prNumber), '--json', 'state,mergeStateStatus,mergeable'], executionCwd);
+
+    if (view.code !== 0) {
+      return { ok: false, message: view.stderr || view.stdout || `Failed to inspect PR #${state.prNumber}` };
+    }
+
+    let payload: any = null;
+    try {
+      payload = JSON.parse(view.stdout);
+    } catch {
+      return { ok: false, message: `Unable to parse gh pr view output for #${state.prNumber}` };
+    }
+
+    ensureCleanPhaseTransition(controlCwd, 'waiting-merge');
+
+    if (payload.state === 'MERGED') {
+      ensureCleanPhaseTransition(controlCwd, 'merged');
+      const latest = readSessionState(controlCwd) ?? state;
+      return cleanupPhase(controlCwd, latest);
+    }
+
+    if (payload.mergeStateStatus === 'BEHIND') {
+      run('git', ['fetch', 'origin'], executionCwd);
+      run('git', ['push'], executionCwd);
+      await delay(opts.pollIntervalMs);
+      continue;
+    }
+
+    if (payload.mergeable === 'CONFLICTING') {
+      const rebased = handleRebaseAndPush(executionCwd);
+      if (!rebased.ok) {
+        const conflictFiles = rebased.conflicts ?? getConflictFiles(executionCwd);
+        ensureCleanPhaseTransition(controlCwd, 'conflicting', { conflictFiles });
+        return {
+          ok: false,
+          message: `Conflicts in: ${conflictFiles.join(', ') || 'unknown files'}. Resolve, push, then re-run xtrm finish.`,
+        };
+      }
+
+      ensureCleanPhaseTransition(controlCwd, 'waiting-merge', { conflictFiles: [] });
+      await delay(opts.pollIntervalMs);
+      continue;
+    }
+
+    await delay(opts.pollIntervalMs);
+  }
+
+  ensureCleanPhaseTransition(controlCwd, 'pending-cleanup');
+  return {
+    ok: false,
+    message: `PR #${state.prNumber} not yet merged. Run xtrm finish when ready.`,
+  };
+}
+
+function isWorkingTreeDirty(cwd: string): boolean {
+  const st = run('git', ['status', '--porcelain'], cwd);
+  return st.code === 0 && st.stdout.length > 0;
+}
+
+function runPhase1(controlCwd: string, executionCwd: string, state: SessionState): FinishResult {
+  if (isWorkingTreeDirty(executionCwd)) {
+    const add = run('git', ['add', '-A'], executionCwd);
+    if (add.code !== 0) return { ok: false, message: add.stderr || add.stdout };
+
+    const msg = `feat(${state.issueId}): ${state.branch}`;
+    const commit = run('git', ['commit', '-m', msg], executionCwd);
+    if (commit.code !== 0) {
+      return { ok: false, message: commit.stderr || commit.stdout || 'git commit failed' };
+    }
+  }
+
+  const push = run('git', ['push', '-u', 'origin', state.branch], executionCwd);
+  if (push.code !== 0) return { ok: false, message: push.stderr || push.stdout || 'git push failed' };
+
+  const create = run('gh', ['pr', 'create', '--fill'], executionCwd);
+  if (create.code !== 0) return { ok: false, message: create.stderr || create.stdout || 'gh pr create failed' };
+  const parsed = parsePrCreate(create.stdout);
+
+  const merge = run('gh', ['pr', 'merge', '--squash', '--auto'], executionCwd);
+  if (merge.code !== 0) return { ok: false, message: merge.stderr || merge.stdout || 'gh pr merge failed' };
+
+  ensureCleanPhaseTransition(controlCwd, 'phase1-done', {
+    prNumber: parsed.prNumber,
+    prUrl: parsed.prUrl,
+  });
+  ensureCleanPhaseTransition(controlCwd, 'waiting-merge', {
+    prNumber: parsed.prNumber,
+    prUrl: parsed.prUrl,
+  });
+
+  return { ok: true, message: 'phase1 complete' };
+}
+
+export async function runXtrmFinish(options: FinishOptions = {}): Promise<FinishResult> {
+  const cwd = options.cwd ?? process.cwd();
+  const controlCwd = getControlRepoRoot(cwd);
+
+  const state = readSessionState(controlCwd);
+  if (!state) {
+    return { ok: false, message: 'No .xtrm-session-state.json found. Claim an issue first (bd update <id> --claim).' };
+  }
+
+  const executionCwd = resolveExecutionCwd(controlCwd, state);
+
+  const opts: Required<FinishOptions> = {
+    cwd: controlCwd,
+    pollIntervalMs: options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS,
+    timeoutMs: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+  };
+
+  if (state.phase === 'cleanup-done') {
+    return { ok: true, message: 'Session is already cleanup-done.' };
+  }
+
+  if (state.phase === 'conflicting') {
+    const resolved = handleRebaseAndPush(executionCwd);
+    if (!resolved.ok) {
+      const files = resolved.conflicts ?? getConflictFiles(executionCwd);
+      ensureCleanPhaseTransition(controlCwd, 'conflicting', { conflictFiles: files });
+      return { ok: false, message: `Conflicts in: ${files.join(', ') || 'unknown files'}. Resolve, push, then re-run xtrm finish.` };
+    }
+    ensureCleanPhaseTransition(controlCwd, 'waiting-merge', { conflictFiles: [] });
+    const refreshed = readSessionState(controlCwd) ?? state;
+    return pollUntilMerged(controlCwd, executionCwd, refreshed, opts);
+  }
+
+  if (state.phase === 'waiting-merge' || state.phase === 'pending-cleanup' || state.phase === 'merged') {
+    const refreshed = readSessionState(controlCwd) ?? state;
+    if (refreshed.phase === 'merged') return cleanupPhase(controlCwd, refreshed);
+    return pollUntilMerged(controlCwd, executionCwd, refreshed, opts);
+  }
+
+  const phase1 = runPhase1(controlCwd, executionCwd, state);
+  if (!phase1.ok) return phase1;
+
+  const refreshed = readSessionState(controlCwd) ?? state;
+  return pollUntilMerged(controlCwd, executionCwd, refreshed, opts);
+}