ultra-builder-pro-cli 0.5.0

package/orchestrator/recovery.cjs

@@ -0,0 +1,70 @@
+'use strict';
+
+// Phase 5.1 — Recovery decision layer.
+//
+// Phase 4.5's reapOrphanSessions marks running sessions whose lease or
+// heartbeat has expired as `orphan`. Orphan is a safe waypoint — we don't yet
+// know whether the child is dead, deadlocked, or just slow.
+//
+// recoverOnBoot upgrades orphans whose pid is demonstrably dead to `crashed`,
+// records a task_failure event, and leaves orphans with live pids alone so
+// they can recover on their own heartbeat.
+//
+// The circuit breaker (Phase 5.2) consumes task_failure events to decide
+// whether the task should be tripped.
+
+const ops = require('../mcp-server/lib/state-ops.cjs');
+
+function isPidAlive(pid) {
+  if (!pid || pid <= 0) return false;
+  try {
+    // Signal 0 performs error checking without actually sending a signal.
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    // ESRCH = no such process; EPERM = process exists but owned by another user
+    // (still counts as alive for our purposes).
+    if (err && err.code === 'EPERM') return true;
+    return false;
+  }
+}
+
+function listOrphanSessions(db) {
+  return db.prepare("SELECT * FROM sessions WHERE status = 'orphan'").all();
+}
+
+function recoverOnBoot(db, { graceSeconds = 300 } = {}) {
+  if (!db) throw new Error('recoverOnBoot: db handle required');
+
+  // Step 1 — promote stale running sessions to orphan (Phase 4.5 logic).
+  ops.reapOrphanSessions(db, { graceSeconds });
+
+  // Step 2 — for every orphan, decide crashed vs. keep-watching.
+  const orphans = listOrphanSessions(db);
+  const recovered = [];
+  for (const s of orphans) {
+    const alive = isPidAlive(s.pid);
+    if (alive) continue;
+
+    ops.updateSession(db, s.sid, { status: 'crashed' });
+    ops.recordTaskFailure(db, s.task_id, {
+      reason: 'session_crashed_on_boot',
+      session_id: s.sid,
+    });
+    recovered.push({
+      sid: s.sid,
+      task_id: s.task_id,
+      pid: s.pid,
+      pid_alive: false,
+      reason: 'session_crashed_on_boot',
+    });
+  }
+
+  return { recovered, count: recovered.length };
+}
+
+module.exports = {
+  recoverOnBoot,
+  // exposed for tests
+  _internal: { isPidAlive, listOrphanSessions },
+};

package/orchestrator/session-runner.cjs

@@ -0,0 +1,224 @@
+'use strict';
+
+// Phase 4.5.1 — Session 标准单元 runner.
+// Session = new process + independent git worktree + state.db sessions-table
+// lease/heartbeat (D20 + D32 — no .ultra/sessions/<sid>/lease.json file).
+//
+// This module is the execution layer. MCP session.* tools record state,
+// orchestrator runs the actual git worktree + child_process work.
+// Callers share a single open state-db connection (WAL supports multi-writer).
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawn, execFileSync } = require('node:child_process');
+const { randomUUID } = require('node:crypto');
+
+const ops = require('../mcp-server/lib/state-ops.cjs');
+const skillMiner = require('./skill-miner.cjs');
+
+class SessionRunnerError extends Error {
+  constructor(code, message, { cause } = {}) {
+    super(message);
+    this.name = 'SessionRunnerError';
+    this.code = code;
+    if (cause) this.cause = cause;
+  }
+}
+
+function gitWorktreeAdd(repoRoot, worktreePath, ref = 'HEAD') {
+  fs.mkdirSync(path.dirname(worktreePath), { recursive: true });
+  try {
+    execFileSync('git', ['worktree', 'add', '--detach', worktreePath, ref], {
+      cwd: repoRoot, stdio: 'pipe',
+    });
+  } catch (err) {
+    throw new SessionRunnerError('WORKTREE_FAILED', `git worktree add failed: ${err.stderr ? err.stderr.toString().trim() : err.message}`, { cause: err });
+  }
+}
+
+function gitWorktreeRemove(repoRoot, worktreePath) {
+  try {
+    execFileSync('git', ['worktree', 'remove', '--force', worktreePath], {
+      cwd: repoRoot, stdio: 'pipe',
+    });
+  } catch (_err) {
+    // worktree may already be detached; fall through to fs removal
+  }
+  if (fs.existsSync(worktreePath)) {
+    fs.rmSync(worktreePath, { recursive: true, force: true });
+  }
+}
+
+function mintSessionId() {
+  return `sess-${randomUUID().slice(0, 8)}`;
+}
+
+function spawnSession({
+  db,
+  repoRoot,
+  task_id,
+  runtime,
+  takeover = false,
+  command = null,
+  args = [],
+  env = {},
+  stdio = 'ignore',
+  worktreeRef = 'HEAD',
+  lease_seconds = 1800,
+}) {
+  if (!db) throw new SessionRunnerError('VALIDATION_ERROR', 'db handle required');
+  if (!repoRoot) throw new SessionRunnerError('VALIDATION_ERROR', 'repoRoot required');
+  if (!task_id) throw new SessionRunnerError('VALIDATION_ERROR', 'task_id required');
+  if (!runtime) throw new SessionRunnerError('VALIDATION_ERROR', 'runtime required');
+
+  // 1. Admission check
+  const verdict = ops.admissionCheck(db, task_id);
+  // Circuit breaker trumps takeover — tripped tasks require explicit reset.
+  if (verdict.recommended_action === 'blocked_by_breaker') {
+    const err = new SessionRunnerError(
+      'CIRCUIT_TRIPPED',
+      `task ${task_id} is tripped by circuit breaker; call resetCircuitBreaker before spawning`,
+    );
+    err.verdict = verdict;
+    throw err;
+  }
+  if (!verdict.can_spawn && !takeover) {
+    const err = new SessionRunnerError(
+      'ADMISSION_DENIED',
+      `active session exists for task ${task_id} (${verdict.conflict && verdict.conflict.sid}); recommended=${verdict.recommended_action}`,
+    );
+    err.verdict = verdict;
+    throw err;
+  }
+  if (!verdict.can_spawn && takeover && verdict.conflict) {
+    ops.updateSession(db, verdict.conflict.sid, { status: 'crashed' });
+  }
+
+  // 2. Mint sid + paths
+  const sid = mintSessionId();
+  const worktree_path = path.join(repoRoot, '.ultra', 'worktrees', sid);
+  const artifact_dir = path.join(repoRoot, '.ultra', 'sessions', sid);
+
+  // 3. Git worktree (throws WORKTREE_FAILED on failure)
+  gitWorktreeAdd(repoRoot, worktree_path, worktreeRef);
+  fs.mkdirSync(artifact_dir, { recursive: true });
+
+  // 4. Spawn child process (optional — caller may want a record-only session)
+  let proc = null;
+  if (command) {
+    proc = spawn(command, args, {
+      cwd: worktree_path,
+      env: {
+        ...process.env,
+        UBP_SESSION_ID: sid,
+        UBP_TASK_ID: task_id,
+        UBP_RUNTIME: runtime,
+        UBP_WORKTREE: worktree_path,
+        UBP_ARTIFACT_DIR: artifact_dir,
+        ...env,
+      },
+      stdio,
+      detached: false,
+    });
+  }
+
+  // 5. Write session record
+  let session;
+  try {
+    session = ops.createSession(db, {
+      sid,
+      task_id,
+      runtime,
+      pid: proc ? proc.pid : null,
+      worktree_path,
+      artifact_dir,
+      lease_seconds,
+    });
+  } catch (err) {
+    // state.db insert failed — roll back worktree + child
+    if (proc && !proc.killed) { try { proc.kill('SIGTERM'); } catch (_) { /* ignore */ } }
+    gitWorktreeRemove(repoRoot, worktree_path);
+    throw err;
+  }
+
+  return {
+    sid,
+    worktree_path,
+    artifact_dir,
+    lease_expires_at: session.lease_expires_at,
+    pid: proc ? proc.pid : null,
+    process: proc,
+  };
+}
+
+function closeSession({
+  db,
+  repoRoot,
+  sid,
+}, {
+  status = 'completed',
+  remove_worktree = true,
+  kill_signal = 'SIGTERM',
+  mineSkill = false,
+  skillsRoot = null,
+  autoMerge = false,
+  mergeBaseBranch = 'main',
+} = {}) {
+  if (!db || !sid) throw new SessionRunnerError('VALIDATION_ERROR', 'db + sid required');
+  const session = ops.readSession(db, sid);
+  if (!session) {
+    throw new SessionRunnerError('SESSION_NOT_FOUND', `session ${sid} not found`);
+  }
+  if (session.pid) {
+    try { process.kill(session.pid, kill_signal); }
+    catch (_) { /* already dead */ }
+  }
+  ops.updateSession(db, sid, { status });
+  // Phase 7.3 — opt-in skill mining (same lifecycle moment; runs after
+  // status flip so task_completed events are visible).
+  if (mineSkill && skillsRoot) {
+    try { skillMiner.mineSession(db, { sid, skillsRoot }); }
+    catch (err) { process.stderr.write(`skill-miner error: ${err.message}\n`); }
+  }
+  // Phase 8B.4 — opt-in auto-merge. Conflict preserves worktree for the
+  // human; clean/no-op merges fall through to normal removal below.
+  let mergeResult;
+  let effectiveRemove = remove_worktree;
+  if (autoMerge && status === 'completed' && repoRoot && session.worktree_path) {
+    const autoMergeMod = require('./auto-merge.cjs');
+    mergeResult = autoMergeMod.autoMerge({
+      repoRoot,
+      worktreePath: session.worktree_path,
+      baseBranch: mergeBaseBranch,
+      sid,
+      task_id: session.task_id,
+      db,
+    });
+    if (mergeResult.reason === 'conflict') effectiveRemove = false;
+  }
+  if (effectiveRemove && repoRoot && session.worktree_path) {
+    gitWorktreeRemove(repoRoot, session.worktree_path);
+  }
+  const out = { sid, status };
+  if (mergeResult) out.merge = mergeResult;
+  return out;
+}
+
+function attachHeartbeat(db, sid, { intervalMs = 30000 } = {}) {
+  if (!db || !sid) throw new SessionRunnerError('VALIDATION_ERROR', 'db + sid required');
+  const timer = setInterval(() => {
+    try { ops.heartbeatSession(db, sid); }
+    catch (_err) { clearInterval(timer); }
+  }, intervalMs);
+  if (typeof timer.unref === 'function') timer.unref();
+  return () => clearInterval(timer);
+}
+
+module.exports = {
+  SessionRunnerError,
+  spawnSession,
+  closeSession,
+  attachHeartbeat,
+  // exposed for tests
+  _internal: { gitWorktreeAdd, gitWorktreeRemove, mintSessionId },
+};

package/orchestrator/skill-miner.cjs

@@ -0,0 +1,133 @@
+'use strict';
+
+// Phase 7.3 — Heuristic skill miner.
+//
+// Scans a completed session's event stream for "solved something
+// non-trivial" signals. Each signal produces a skills/learned/
+// <ts>_<sid>_unverified.md draft the operator can promote to a proper
+// skill by removing the _unverified suffix and filling in reuse notes.
+//
+// No LLM call. The heuristic is deliberately coarse so the feature ships
+// zero-API-cost; signal quality is explicitly marked "unverified" in the
+// frontmatter.
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const ops = require('../mcp-server/lib/state-ops.cjs');
+
+const LEARNED_DIR = 'learned';
+
+// Event type → draft kind + description template.
+const SIGNALS = Object.freeze({
+  task_completed: {
+    kind: 'task-completion',
+    describe: (task) => `Shipped task ${task.id} (${task.title}). Heuristic draft — fill reuse notes before removing _unverified.`,
+  },
+  task_circuit_broken: {
+    kind: 'debug-pattern',
+    describe: (task, e) => `Task ${task.id} (${task.title}) tripped the breaker after ${e.payload && e.payload.threshold} failures. Inspect the failure stream for a recurring debug pattern.`,
+  },
+  session_crashed: {
+    kind: 'recovery-pattern',
+    describe: (task) => `Session on task ${task.id} (${task.title}) crashed. Record the recovery path once investigated.`,
+  },
+});
+
+function sanitizeForFilename(s) {
+  return String(s).replace(/[^\w.-]/g, '_').slice(0, 80);
+}
+
+function renderDraft({ task, session, signalType, kind, description, events }) {
+  const ts = new Date().toISOString();
+  const evIds = events.map((e) => e.id).slice(0, 20);
+  const lines = [
+    '---',
+    `name: ${sanitizeForFilename(task.id + '_' + session.sid)}_unverified`,
+    `description: "Heuristic draft from session ${session.sid}, task ${task.id}"`,
+    `kind: ${kind}`,
+    `source_session: ${session.sid}`,
+    `source_task: ${task.id}`,
+    `signal: ${signalType}`,
+    `ts: ${ts}`,
+    'unverified: true',
+    '---',
+    '',
+    '## Problem',
+    '',
+    `${task.title}${task.trace_to ? ` (trace: ${task.trace_to})` : ''}`,
+    '',
+    '## Signal',
+    '',
+    description,
+    '',
+    '## Evidence',
+    '',
+    `- events: [${evIds.join(', ')}]`,
+    `- runtime: ${session.runtime}`,
+    `- final task status: ${task.status}`,
+    '',
+    '## Suggested reuse',
+    '',
+    '[human: fill in before removing the `_unverified` suffix]',
+    '',
+  ];
+  return lines.join('\n');
+}
+
+function existingDraftsForSession(learnedDir, sid) {
+  if (!fs.existsSync(learnedDir)) return [];
+  return fs.readdirSync(learnedDir).filter((f) => f.includes(sid) && f.endsWith('_unverified.md'));
+}
+
+function mineSession(db, { sid, skillsRoot } = {}) {
+  if (!sid || !skillsRoot) return { drafts: [] };
+  const session = ops.readSession(db, sid);
+  if (!session) return { drafts: [] };
+
+  const learnedDir = path.join(skillsRoot, LEARNED_DIR);
+  fs.mkdirSync(learnedDir, { recursive: true });
+
+  // Idempotency: skip if a draft already exists for this sid.
+  if (existingDraftsForSession(learnedDir, sid).length > 0) {
+    return { drafts: [] };
+  }
+
+  const task = ops.readTask(db, session.task_id);
+  if (!task) return { drafts: [] };
+
+  const { events } = ops.subscribeEventsSince(db, {
+    since_id: 0,
+    task_id: session.task_id,
+    limit: 500,
+  });
+  const sessionEvents = events.filter((e) => e.session_id === sid);
+
+  // Pick the first matching signal (most specific one per session — we don't
+  // want one session producing three drafts).
+  for (const e of sessionEvents) {
+    const sig = SIGNALS[e.type];
+    if (!sig) continue;
+    const content = renderDraft({
+      task,
+      session,
+      signalType: e.type,
+      kind: sig.kind,
+      description: sig.describe(task, e),
+      events: sessionEvents,
+    });
+    const filename = `${Date.now()}_${sanitizeForFilename(sid)}_unverified.md`;
+    const target = path.join(learnedDir, filename);
+    fs.writeFileSync(target, content);
+    return { drafts: [target] };
+  }
+
+  return { drafts: [] };
+}
+
+module.exports = {
+  mineSession,
+  SIGNALS,
+  // exposed for tests
+  _internal: { renderDraft, existingDraftsForSession, sanitizeForFilename },
+};

package/orchestrator/tests/auto-merge.test.cjs

@@ -0,0 +1,216 @@
+'use strict';
+
+// Phase 8B.4 — Auto-merge back.
+//
+// autoMerge({ repoRoot, worktreePath, baseBranch, sid, task_id, db }):
+//   • no changes (session_sha === base_sha)        → { merged:false, reason:'no_changes' }
+//   • clean merge                                   → { merged:true }  + merged_back event
+//   • conflict                                      → { merged:false, reason:'conflict', conflict_paths[] }
+//                                                     + merge_conflict event + merge --abort
+// closeSession({ autoMerge:true }) integration:
+//   • autoMerge=true + conflict → worktree kept on disk (for human to resolve)
+//   • autoMerge=false (default) → behavior unchanged (Phase 4.5 / 5 / 7 tests)
+
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+
+const { initStateDb, closeStateDb } = require('../../mcp-server/lib/state-db.cjs');
+const ops = require('../../mcp-server/lib/state-ops.cjs');
+const wtmgr = require('../worktree-manager.cjs');
+const autoMerge = require('../auto-merge.cjs');
+const runner = require('../session-runner.cjs');
+
+function mkRepo() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'ubp-automerge-'));
+  execFileSync('git', ['init', '-q', '-b', 'main'], { cwd: dir });
+  execFileSync('git', ['config', 'user.email', 'test@ubp.dev'], { cwd: dir });
+  execFileSync('git', ['config', 'user.name', 'ubp-test'], { cwd: dir });
+  fs.writeFileSync(path.join(dir, 'seed.md'), '# seed\n');
+  // The DB and worktree dirs live under .ultra/ — keep them out of git so
+  // `git status` in conflict tests isn't polluted by untracked test artifacts.
+  fs.writeFileSync(path.join(dir, '.gitignore'), '.ultra/\n');
+  execFileSync('git', ['add', '-A'], { cwd: dir });
+  execFileSync('git', ['commit', '-q', '-m', 'seed'], { cwd: dir });
+  return dir;
+}
+
+function mkDb(repoRoot) {
+  const dbPath = path.join(repoRoot, '.ultra', 'state.db');
+  fs.mkdirSync(path.dirname(dbPath), { recursive: true });
+  const { db } = initStateDb(dbPath);
+  return db;
+}
+
+function commitInWorktree(wtPath, filename, content, msg = 'session change') {
+  fs.writeFileSync(path.join(wtPath, filename), content);
+  execFileSync('git', ['add', '-A'], { cwd: wtPath });
+  execFileSync('git', ['-c', 'user.email=s@ubp.dev', '-c', 'user.name=s-ubp',
+    'commit', '-q', '-m', msg], { cwd: wtPath });
+  return execFileSync('git', ['rev-parse', 'HEAD'], { cwd: wtPath, stdio: ['ignore', 'pipe', 'pipe'] })
+    .toString().trim();
+}
+
+function cleanup(repoRoot, db) {
+  try { if (db) closeStateDb(db); } catch (_) { /* best-effort */ }
+  try { fs.rmSync(repoRoot, { recursive: true, force: true }); } catch (_) { /* best-effort */ }
+}
+
+// ─── autoMerge pure function ──────────────────────────────────────────────
+
+test('autoMerge: no session commits → merged:false reason:no_changes', () => {
+  const repo = mkRepo();
+  try {
+    const { worktree_path } = wtmgr.allocate({ repoRoot: repo, sid: 's-noop' });
+    const r = autoMerge.autoMerge({
+      repoRoot: repo, worktreePath: worktree_path,
+      baseBranch: 'main', sid: 's-noop',
+    });
+    assert.equal(r.merged, false);
+    assert.equal(r.reason, 'no_changes');
+  } finally { cleanup(repo); }
+});
+
+test('autoMerge: 3 slices with independent files → all merged back to main', () => {
+  const repo = mkRepo();
+  const db = mkDb(repo);
+  try {
+    for (const sid of ['s1', 's2', 's3']) {
+      ops.createTask(db, { id: sid, title: sid, type: 'feature', priority: 'P2' });
+    }
+    const shas = {};
+    for (const [sid, file] of [['s1', 'a.txt'], ['s2', 'b.txt'], ['s3', 'c.txt']]) {
+      const { worktree_path } = wtmgr.allocate({ repoRoot: repo, sid });
+      shas[sid] = commitInWorktree(worktree_path, file, `${file}\n`);
+      const r = autoMerge.autoMerge({
+        repoRoot: repo, worktreePath: worktree_path,
+        baseBranch: 'main', sid, task_id: sid, db,
+      });
+      assert.equal(r.merged, true, `${sid} should merge`);
+      assert.equal(r.session_sha, shas[sid]);
+    }
+    assert.ok(fs.existsSync(path.join(repo, 'a.txt')));
+    assert.ok(fs.existsSync(path.join(repo, 'b.txt')));
+    assert.ok(fs.existsSync(path.join(repo, 'c.txt')));
+    const { events } = ops.subscribeEventsSince(db, 0);
+    const merged = events.filter((e) => e.type === 'merged_back');
+    assert.equal(merged.length, 3);
+  } finally { cleanup(repo, db); }
+});
+
+test('autoMerge: 2 slices on same file → first merges, second conflict + event', () => {
+  const repo = mkRepo();
+  const db = mkDb(repo);
+  try {
+    ops.createTask(db, { id: 'cf1', title: 'cf1', type: 'feature', priority: 'P2' });
+    ops.createTask(db, { id: 'cf2', title: 'cf2', type: 'feature', priority: 'P2' });
+    const { worktree_path: w1 } = wtmgr.allocate({ repoRoot: repo, sid: 'cf1' });
+    const { worktree_path: w2 } = wtmgr.allocate({ repoRoot: repo, sid: 'cf2' });
+    commitInWorktree(w1, 'conflict.txt', 'version-A\n');
+    commitInWorktree(w2, 'conflict.txt', 'version-B\n');
+
+    const r1 = autoMerge.autoMerge({
+      repoRoot: repo, worktreePath: w1, baseBranch: 'main', sid: 'cf1', task_id: 'cf1', db,
+    });
+    assert.equal(r1.merged, true);
+    const r2 = autoMerge.autoMerge({
+      repoRoot: repo, worktreePath: w2, baseBranch: 'main', sid: 'cf2', task_id: 'cf2', db,
+    });
+    assert.equal(r2.merged, false);
+    assert.equal(r2.reason, 'conflict');
+    assert.ok(Array.isArray(r2.conflict_paths));
+    assert.ok(r2.conflict_paths.includes('conflict.txt'));
+
+    // main HEAD rolled back to r1's merge commit, not mid-conflict
+    const status = execFileSync('git', ['status', '--porcelain'], {
+      cwd: repo, stdio: ['ignore', 'pipe', 'pipe'],
+    }).toString();
+    assert.equal(status.trim(), '', 'working tree must be clean after abort');
+
+    const { events } = ops.subscribeEventsSince(db, 0);
+    const conflict = events.find((e) => e.type === 'merge_conflict');
+    assert.ok(conflict, 'merge_conflict event expected');
+    assert.deepEqual(conflict.payload.conflict_paths, ['conflict.txt']);
+  } finally { cleanup(repo, db); }
+});
+
+// ─── closeSession integration ─────────────────────────────────────────────
+
+test('closeSession autoMerge=true + clean merge → worktree removed', () => {
+  const repo = mkRepo();
+  const db = mkDb(repo);
+  try {
+    ops.createTask(db, { id: 'cs-clean', title: 'x', type: 'feature', priority: 'P2' });
+    const handle = runner.spawnSession({
+      db, repoRoot: repo,
+      task_id: 'cs-clean', runtime: 'claude',
+      command: process.execPath, args: ['-e', 'process.exit(0)'],
+    });
+    // Simulate agent commit inside worktree
+    commitInWorktree(handle.worktree_path, 'new.txt', 'hi\n');
+    // Wait for child to exit so closeSession can kill cleanly (it already did)
+    if (handle.process) { try { handle.process.kill('SIGTERM'); } catch (_) { /* noop */ } }
+
+    const result = runner.closeSession(
+      { db, repoRoot: repo, sid: handle.sid },
+      { autoMerge: true, mergeBaseBranch: 'main' },
+    );
+    assert.equal(result.merge && result.merge.merged, true);
+    assert.equal(fs.existsSync(handle.worktree_path), false, 'clean merge → worktree removed');
+  } finally { cleanup(repo, db); }
+});
+
+test('closeSession autoMerge=true + conflict → worktree kept', () => {
+  const repo = mkRepo();
+  const db = mkDb(repo);
+  try {
+    ops.createTask(db, { id: 'cs-cflict', title: 'x', type: 'feature', priority: 'P2' });
+
+    // Spawn FIRST so the worktree forks at seed commit (before main diverges).
+    const handle = runner.spawnSession({
+      db, repoRoot: repo,
+      task_id: 'cs-cflict', runtime: 'claude',
+      command: process.execPath, args: ['-e', 'process.exit(0)'],
+    });
+    // Advance main with a conflicting version of shared.txt.
+    fs.writeFileSync(path.join(repo, 'shared.txt'), 'main-version\n');
+    execFileSync('git', ['add', '-A'], { cwd: repo });
+    execFileSync('git', ['commit', '-q', '-m', 'main change'], { cwd: repo });
+    // Session worktree forks off seed and writes its own version of the same file.
+    commitInWorktree(handle.worktree_path, 'shared.txt', 'session-version\n');
+
+    const result = runner.closeSession(
+      { db, repoRoot: repo, sid: handle.sid },
+      { autoMerge: true, mergeBaseBranch: 'main' },
+    );
+    assert.equal(result.merge && result.merge.merged, false);
+    assert.equal(result.merge.reason, 'conflict');
+    assert.ok(fs.existsSync(handle.worktree_path), 'conflict → worktree preserved for resolution');
+  } finally { cleanup(repo, db); }
+});
+
+test('closeSession autoMerge=false (default) → no merge, legacy behavior', () => {
+  const repo = mkRepo();
+  const db = mkDb(repo);
+  try {
+    ops.createTask(db, { id: 'cs-off', title: 'x', type: 'feature', priority: 'P2' });
+    const handle = runner.spawnSession({
+      db, repoRoot: repo,
+      task_id: 'cs-off', runtime: 'claude',
+      command: process.execPath, args: ['-e', 'process.exit(0)'],
+    });
+    commitInWorktree(handle.worktree_path, 'n.txt', 'x\n');
+
+    const result = runner.closeSession(
+      { db, repoRoot: repo, sid: handle.sid },
+      {}, // autoMerge not set
+    );
+    assert.equal(result.merge, undefined, 'no merge when opt-in disabled');
+    assert.equal(fs.existsSync(handle.worktree_path), false, 'worktree removed normally');
+    // main must still be at seed (no merge happened)
+    assert.equal(fs.existsSync(path.join(repo, 'n.txt')), false);
+  } finally { cleanup(repo, db); }
+});