ultra-builder-pro-cli 0.5.0

package/orchestrator/tests/session-runner.test.cjs

@@ -0,0 +1,314 @@
+'use strict';
+
+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 runner = require('../session-runner.cjs');
+
+// Short-lived child: keep the process alive until killed.
+const LONG_SLEEP_CMD = process.execPath;
+const LONG_SLEEP_ARGS = ['-e', 'setInterval(() => {}, 60000);'];
+
+function mkRepo() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'ubp-runner-repo-'));
+  execFileSync('git', ['init', '-q'], { 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, 'README.md'), '# test\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');
+  const { db } = initStateDb(dbPath);
+  return { db, dbPath };
+}
+
+function seedTask(db, id = 't-1') {
+  ops.createTask(db, { id, title: 'runner target', type: 'feature', priority: 'P1' });
+  return id;
+}
+
+function cleanup(repoRoot, db) {
+  try { closeStateDb(db); } catch (_) { /* ignore */ }
+  try { fs.rmSync(repoRoot, { recursive: true, force: true }); } catch (_) { /* ignore */ }
+}
+
+function isProcessAlive(pid) {
+  try { process.kill(pid, 0); return true; }
+  catch (_) { return false; }
+}
+
+test('spawnSession creates worktree, child process, and sessions row', () => {
+  const repoRoot = mkRepo();
+  const { db } = mkDb(repoRoot);
+  let handle;
+  try {
+    seedTask(db, 'r-1');
+    handle = runner.spawnSession({
+      db, repoRoot,
+      task_id: 'r-1', runtime: 'claude',
+      command: LONG_SLEEP_CMD, args: LONG_SLEEP_ARGS,
+    });
+    assert.match(handle.sid, /^sess-/);
+    assert.ok(fs.existsSync(handle.worktree_path));
+    assert.ok(fs.existsSync(handle.artifact_dir));
+    assert.ok(handle.pid);
+    assert.ok(isProcessAlive(handle.pid));
+
+    const row = ops.readSession(db, handle.sid);
+    assert.equal(row.task_id, 'r-1');
+    assert.equal(row.status, 'running');
+    assert.equal(row.pid, handle.pid);
+  } finally {
+    if (handle && handle.pid) { try { process.kill(handle.pid, 'SIGKILL'); } catch (_) { /* ignore */ } }
+    cleanup(repoRoot, db);
+  }
+});
+
+test('closeSession kills child, marks completed, removes worktree', async () => {
+  const repoRoot = mkRepo();
+  const { db } = mkDb(repoRoot);
+  let handle;
+  try {
+    seedTask(db, 'r-close');
+    handle = runner.spawnSession({
+      db, repoRoot,
+      task_id: 'r-close', runtime: 'claude',
+      command: LONG_SLEEP_CMD, args: LONG_SLEEP_ARGS,
+    });
+    const wt = handle.worktree_path;
+    runner.closeSession(
+      { db, repoRoot, sid: handle.sid },
+      { status: 'completed', kill_signal: 'SIGKILL' },
+    );
+
+    const row = ops.readSession(db, handle.sid);
+    assert.equal(row.status, 'completed');
+    // give the kernel a tick to reap the SIGKILL
+    await new Promise((r) => setTimeout(r, 50));
+    assert.ok(!isProcessAlive(handle.pid), `pid ${handle.pid} should be dead`);
+    assert.ok(!fs.existsSync(wt));
+  } finally {
+    cleanup(repoRoot, db);
+  }
+});
+
+test('spawnSession refuses second session without takeover (ADMISSION_DENIED)', () => {
+  const repoRoot = mkRepo();
+  const { db } = mkDb(repoRoot);
+  let first;
+  try {
+    seedTask(db, 'r-adm');
+    first = runner.spawnSession({
+      db, repoRoot,
+      task_id: 'r-adm', runtime: 'claude',
+      command: LONG_SLEEP_CMD, args: LONG_SLEEP_ARGS,
+    });
+    assert.throws(
+      () => runner.spawnSession({
+        db, repoRoot,
+        task_id: 'r-adm', runtime: 'codex',
+        command: LONG_SLEEP_CMD, args: LONG_SLEEP_ARGS,
+      }),
+      (err) => err instanceof runner.SessionRunnerError && err.code === 'ADMISSION_DENIED',
+    );
+  } finally {
+    if (first && first.pid) { try { process.kill(first.pid, 'SIGKILL'); } catch (_) { /* ignore */ } }
+    cleanup(repoRoot, db);
+  }
+});
+
+test('takeover=true crashes old session and spawns new one', () => {
+  const repoRoot = mkRepo();
+  const { db } = mkDb(repoRoot);
+  let first, second;
+  try {
+    seedTask(db, 'r-take');
+    first = runner.spawnSession({
+      db, repoRoot,
+      task_id: 'r-take', runtime: 'claude',
+      command: LONG_SLEEP_CMD, args: LONG_SLEEP_ARGS,
+    });
+    second = runner.spawnSession({
+      db, repoRoot,
+      task_id: 'r-take', runtime: 'codex',
+      command: LONG_SLEEP_CMD, args: LONG_SLEEP_ARGS,
+      takeover: true,
+    });
+    assert.notEqual(second.sid, first.sid);
+
+    const firstRow = ops.readSession(db, first.sid);
+    assert.equal(firstRow.status, 'crashed');
+    const secondRow = ops.readSession(db, second.sid);
+    assert.equal(secondRow.status, 'running');
+    assert.equal(secondRow.runtime, 'codex');
+  } finally {
+    for (const h of [first, second]) {
+      if (h && h.pid) { try { process.kill(h.pid, 'SIGKILL'); } catch (_) { /* ignore */ } }
+    }
+    cleanup(repoRoot, db);
+  }
+});
+
+test('attachHeartbeat updates heartbeat_at while running', async () => {
+  const repoRoot = mkRepo();
+  const { db } = mkDb(repoRoot);
+  let handle;
+  try {
+    seedTask(db, 'r-hb');
+    handle = runner.spawnSession({
+      db, repoRoot,
+      task_id: 'r-hb', runtime: 'claude',
+      command: LONG_SLEEP_CMD, args: LONG_SLEEP_ARGS,
+    });
+    const stop = runner.attachHeartbeat(db, handle.sid, { intervalMs: 20 });
+    await new Promise((r) => setTimeout(r, 80));
+    stop();
+
+    const row = ops.readSession(db, handle.sid);
+    assert.ok(row.heartbeat_at, 'heartbeat_at should be populated');
+    // lease extended beyond initial default of started_at + 1800s? compare against start
+    assert.ok(Date.parse(row.heartbeat_at) > 0);
+  } finally {
+    if (handle && handle.pid) { try { process.kill(handle.pid, 'SIGKILL'); } catch (_) { /* ignore */ } }
+    cleanup(repoRoot, db);
+  }
+});
+
+test('kill -9 child: reapOrphanSessions marks orphan after heartbeat grace expires', async () => {
+  const repoRoot = mkRepo();
+  const { db } = mkDb(repoRoot);
+  let handle;
+  try {
+    seedTask(db, 'r-orphan');
+    handle = runner.spawnSession({
+      db, repoRoot,
+      task_id: 'r-orphan', runtime: 'claude',
+      command: LONG_SLEEP_CMD, args: LONG_SLEEP_ARGS,
+    });
+    // force lease + heartbeat into the past so reaper has something to grab
+    ops.updateSession(db, handle.sid, {
+      lease_expires_at: new Date(Date.now() - 60 * 1000).toISOString(),
+      heartbeat_at: new Date(Date.now() - 60 * 1000).toISOString(),
+    });
+    process.kill(handle.pid, 'SIGKILL');
+
+    const reaped = ops.reapOrphanSessions(db, { graceSeconds: 30 });
+    assert.ok(reaped.reaped.includes(handle.sid));
+    const row = ops.readSession(db, handle.sid);
+    assert.equal(row.status, 'orphan');
+  } finally {
+    cleanup(repoRoot, db);
+  }
+});
+
+test('concurrent spawns on same task: only one succeeds (admission serialization)', async () => {
+  const repoRoot = mkRepo();
+  const { db } = mkDb(repoRoot);
+  let winner;
+  try {
+    seedTask(db, 'r-race');
+
+    const attempts = [0, 1, 2].map((i) =>
+      Promise.resolve().then(() => {
+        try {
+          return runner.spawnSession({
+            db, repoRoot,
+            task_id: 'r-race', runtime: ['claude', 'opencode', 'codex'][i],
+            command: LONG_SLEEP_CMD, args: LONG_SLEEP_ARGS,
+          });
+        } catch (err) {
+          return { error: err.code };
+        }
+      }),
+    );
+    const results = await Promise.all(attempts);
+    const winners = results.filter((r) => r && r.sid);
+    const denied = results.filter((r) => r && r.error === 'ADMISSION_DENIED');
+    assert.equal(winners.length, 1, `expected 1 winner, got ${winners.length}`);
+    assert.equal(denied.length, 2, `expected 2 denied, got ${denied.length}`);
+    winner = winners[0];
+  } finally {
+    if (winner && winner.pid) { try { process.kill(winner.pid, 'SIGKILL'); } catch (_) { /* ignore */ } }
+    cleanup(repoRoot, db);
+  }
+});
+
+test('spawnSession refuses tripped task (CIRCUIT_TRIPPED, takeover cannot override)', () => {
+  const repoRoot = mkRepo();
+  const { db } = mkDb(repoRoot);
+  try {
+    seedTask(db, 'r-cb');
+    for (let i = 0; i < 3; i += 1) ops.recordTaskFailure(db, 'r-cb', { reason: 'test' });
+    assert.equal(ops.isCircuitTripped(db, 'r-cb'), true);
+
+    const attempt = (takeover) => runner.spawnSession({
+      db, repoRoot,
+      task_id: 'r-cb', runtime: 'claude',
+      command: LONG_SLEEP_CMD, args: LONG_SLEEP_ARGS,
+      takeover,
+    });
+    assert.throws(() => attempt(false), (err) => err.code === 'CIRCUIT_TRIPPED');
+    assert.throws(() => attempt(true), (err) => err.code === 'CIRCUIT_TRIPPED');
+  } finally {
+    cleanup(repoRoot, db);
+  }
+});
+
+test('spawnSession works again after resetCircuitBreaker', () => {
+  const repoRoot = mkRepo();
+  const { db } = mkDb(repoRoot);
+  let handle;
+  try {
+    seedTask(db, 'r-cb-reset');
+    for (let i = 0; i < 3; i += 1) ops.recordTaskFailure(db, 'r-cb-reset', { reason: 'test' });
+    ops.resetCircuitBreaker(db, 'r-cb-reset');
+    handle = runner.spawnSession({
+      db, repoRoot,
+      task_id: 'r-cb-reset', runtime: 'claude',
+      command: LONG_SLEEP_CMD, args: LONG_SLEEP_ARGS,
+    });
+    assert.ok(handle.sid);
+  } finally {
+    if (handle && handle.pid) { try { process.kill(handle.pid, 'SIGKILL'); } catch (_) { /* ignore */ } }
+    cleanup(repoRoot, db);
+  }
+});
+
+test('two sessions on different tasks get independent worktrees', () => {
+  const repoRoot = mkRepo();
+  const { db } = mkDb(repoRoot);
+  let a, b;
+  try {
+    seedTask(db, 'r-multi-a');
+    seedTask(db, 'r-multi-b');
+    a = runner.spawnSession({
+      db, repoRoot,
+      task_id: 'r-multi-a', runtime: 'claude',
+      command: LONG_SLEEP_CMD, args: LONG_SLEEP_ARGS,
+    });
+    b = runner.spawnSession({
+      db, repoRoot,
+      task_id: 'r-multi-b', runtime: 'codex',
+      command: LONG_SLEEP_CMD, args: LONG_SLEEP_ARGS,
+    });
+    assert.notEqual(a.sid, b.sid);
+    assert.notEqual(a.worktree_path, b.worktree_path);
+    assert.notEqual(a.pid, b.pid);
+    assert.ok(isProcessAlive(a.pid) && isProcessAlive(b.pid));
+  } finally {
+    for (const h of [a, b]) {
+      if (h && h.pid) { try { process.kill(h.pid, 'SIGKILL'); } catch (_) { /* ignore */ } }
+    }
+    cleanup(repoRoot, db);
+  }
+});

package/orchestrator/tests/skill-miner.test.cjs

@@ -0,0 +1,147 @@
+'use strict';
+
+// Phase 7.3 — Skill miner (heuristic, no LLM):
+//   • mineSession scans a session's events + task state for "solved
+//     something non-trivial" signals and writes skills/learned/
+//     <ts>_<sid>_unverified.md drafts.
+//   • Idempotent: same sid twice → only one draft per signal.
+
+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 { initStateDb, closeStateDb } = require('../../mcp-server/lib/state-db.cjs');
+const ops = require('../../mcp-server/lib/state-ops.cjs');
+const skillMiner = require('../skill-miner.cjs');
+
+function mkFixture() {
+  const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'ubp-skill-'));
+  const dbPath = path.join(repoRoot, '.ultra', 'state.db');
+  const { db } = initStateDb(dbPath);
+  const skillsRoot = path.join(repoRoot, 'skills');
+  fs.mkdirSync(skillsRoot, { recursive: true });
+  return { repoRoot, db, skillsRoot };
+}
+
+function teardown(repoRoot, db) {
+  try { closeStateDb(db); } catch (_) { /* ignore */ }
+  try { fs.rmSync(repoRoot, { recursive: true, force: true }); } catch (_) { /* ignore */ }
+}
+
+function seed(db, { sid, task_id, title = 'demo', tag = null }) {
+  ops.createTask(db, { id: task_id, title, type: 'feature', priority: 'P1', tag });
+  ops.createSession(db, {
+    sid, task_id, runtime: 'claude',
+    worktree_path: `/tmp/${sid}/wt`, artifact_dir: `/tmp/${sid}/art`,
+  });
+}
+
+test('mineSession: task_completed signal → generates draft', () => {
+  const { repoRoot, db, skillsRoot } = mkFixture();
+  try {
+    seed(db, { sid: 's-done', task_id: 't-done', title: 'ship auth flow' });
+    ops.patchTask(db, 't-done', { status: 'in_progress' });
+    ops.appendEvent(db, { type: 'task_completed', task_id: 't-done', session_id: 's-done', payload: { to: 'completed' } });
+    ops.patchTask(db, 't-done', { status: 'completed' });
+
+    const out = skillMiner.mineSession(db, { sid: 's-done', skillsRoot });
+    assert.equal(out.drafts.length, 1);
+    assert.match(out.drafts[0], /_unverified\.md$/);
+    const draft = fs.readFileSync(out.drafts[0], 'utf8');
+    assert.match(draft, /kind: task-completion/);
+    assert.match(draft, /unverified: true/);
+    assert.match(draft, /ship auth flow/);
+  } finally { teardown(repoRoot, db); }
+});
+
+test('mineSession: task_circuit_broken signal → debug-pattern draft', () => {
+  const { repoRoot, db, skillsRoot } = mkFixture();
+  try {
+    seed(db, { sid: 's-cb', task_id: 't-cb', title: 'flaky integration' });
+    ops.appendEvent(db, { type: 'task_circuit_broken', task_id: 't-cb', session_id: 's-cb', payload: { threshold: 3 } });
+    const out = skillMiner.mineSession(db, { sid: 's-cb', skillsRoot });
+    assert.equal(out.drafts.length, 1);
+    const draft = fs.readFileSync(out.drafts[0], 'utf8');
+    assert.match(draft, /kind: debug-pattern/);
+  } finally { teardown(repoRoot, db); }
+});
+
+test('mineSession: session_crashed signal → recovery-pattern draft', () => {
+  const { repoRoot, db, skillsRoot } = mkFixture();
+  try {
+    seed(db, { sid: 's-crash', task_id: 't-crash', title: 'crashing task' });
+    ops.appendEvent(db, { type: 'session_crashed', task_id: 't-crash', session_id: 's-crash', payload: { to: 'crashed' } });
+    const out = skillMiner.mineSession(db, { sid: 's-crash', skillsRoot });
+    assert.equal(out.drafts.length, 1);
+    const draft = fs.readFileSync(out.drafts[0], 'utf8');
+    assert.match(draft, /kind: recovery-pattern/);
+  } finally { teardown(repoRoot, db); }
+});
+
+test('mineSession: no trigger signals → no draft', () => {
+  const { repoRoot, db, skillsRoot } = mkFixture();
+  try {
+    seed(db, { sid: 's-quiet', task_id: 't-quiet', title: 'nothing happened' });
+    const out = skillMiner.mineSession(db, { sid: 's-quiet', skillsRoot });
+    assert.equal(out.drafts.length, 0);
+  } finally { teardown(repoRoot, db); }
+});
+
+test('mineSession: idempotent — running twice on same sid yields no new drafts', () => {
+  const { repoRoot, db, skillsRoot } = mkFixture();
+  try {
+    seed(db, { sid: 's-idem', task_id: 't-idem', title: 'shipped' });
+    ops.patchTask(db, 't-idem', { status: 'in_progress' });
+    ops.appendEvent(db, { type: 'task_completed', task_id: 't-idem', session_id: 's-idem', payload: { to: 'completed' } });
+    ops.patchTask(db, 't-idem', { status: 'completed' });
+
+    const first = skillMiner.mineSession(db, { sid: 's-idem', skillsRoot });
+    const second = skillMiner.mineSession(db, { sid: 's-idem', skillsRoot });
+    assert.equal(first.drafts.length, 1);
+    assert.equal(second.drafts.length, 0, 'second mining should see existing draft and skip');
+    const learned = fs.readdirSync(path.join(skillsRoot, 'learned'));
+    assert.equal(learned.length, 1);
+  } finally { teardown(repoRoot, db); }
+});
+
+test('mineSession: missing session → empty drafts array', () => {
+  const { repoRoot, db, skillsRoot } = mkFixture();
+  try {
+    const out = skillMiner.mineSession(db, { sid: 's-nope', skillsRoot });
+    assert.deepEqual(out.drafts, []);
+  } finally { teardown(repoRoot, db); }
+});
+
+test('AC flow: 5 mock sessions (3 with signal, 2 empty) → ≥3 drafts', () => {
+  const { repoRoot, db, skillsRoot } = mkFixture();
+  try {
+    // 3 with a trigger signal
+    for (const [i, kind] of [['ac1', 'completed'], ['ac2', 'crashed'], ['ac3', 'broken']]) {
+      seed(db, { sid: `s-${i}`, task_id: `t-${i}`, title: `task ${i}` });
+      if (kind === 'completed') {
+        ops.patchTask(db, `t-${i}`, { status: 'in_progress' });
+        ops.appendEvent(db, { type: 'task_completed', task_id: `t-${i}`, session_id: `s-${i}`, payload: {} });
+        ops.patchTask(db, `t-${i}`, { status: 'completed' });
+      } else if (kind === 'crashed') {
+        ops.appendEvent(db, { type: 'session_crashed', task_id: `t-${i}`, session_id: `s-${i}`, payload: {} });
+      } else if (kind === 'broken') {
+        ops.appendEvent(db, { type: 'task_circuit_broken', task_id: `t-${i}`, session_id: `s-${i}`, payload: { threshold: 3 } });
+      }
+    }
+    // 2 empty
+    for (const i of ['ac4', 'ac5']) {
+      seed(db, { sid: `s-${i}`, task_id: `t-${i}`, title: `task ${i}` });
+    }
+
+    let totalDrafts = 0;
+    for (const i of ['ac1', 'ac2', 'ac3', 'ac4', 'ac5']) {
+      const out = skillMiner.mineSession(db, { sid: `s-${i}`, skillsRoot });
+      totalDrafts += out.drafts.length;
+    }
+    assert.ok(totalDrafts >= 3, `expected ≥3 drafts across 5 sessions, got ${totalDrafts}`);
+    const learned = fs.readdirSync(path.join(skillsRoot, 'learned'));
+    assert.ok(learned.length >= 3);
+  } finally { teardown(repoRoot, db); }
+});

package/orchestrator/tests/worktree-manager.test.cjs

@@ -0,0 +1,148 @@
+'use strict';
+
+// Phase 8B.3 — N-concurrent git worktree management.
+//
+// Session-runner (Phase 4.5) already encapsulates `git worktree add/remove`
+// for a single session. worktree-manager is the registry / batch layer:
+// allocate N, track them via `git worktree list --porcelain`, release one
+// or all (for crash recovery), detect filesystem orphans.
+//
+// AC (from PLAN §6 Phase 8B.3):
+//   - 3 concurrent slices → 3 independent worktrees, git worktree list
+//     shows them; main branch checkout untouched
+//   - 5 rapid allocations in one tick → no .git/config.lock contention
+//     (Node single-thread execFileSync is naturally serialized)
+//   - releaseAll cleans filesystem leftovers even when git forgot them
+
+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 wm = require('../worktree-manager.cjs');
+
+function mkRepo() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'ubp-wtmgr-'));
+  execFileSync('git', ['init', '-q'], { 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, 'README.md'), '# seed\n');
+  execFileSync('git', ['add', '-A'], { cwd: dir });
+  execFileSync('git', ['commit', '-q', '-m', 'seed'], { cwd: dir });
+  return dir;
+}
+
+function cleanup(dir) {
+  try { fs.rmSync(dir, { recursive: true, force: true }); } catch (_) { /* best-effort */ }
+}
+
+test('allocate: creates worktree under .ultra/worktrees/<sid> and returns path', () => {
+  const repo = mkRepo();
+  try {
+    const { worktree_path } = wm.allocate({ repoRoot: repo, sid: 'sess-abc' });
+    assert.ok(worktree_path.endsWith('.ultra/worktrees/sess-abc'));
+    assert.ok(fs.existsSync(worktree_path), 'worktree dir should exist');
+    assert.ok(fs.existsSync(path.join(worktree_path, 'README.md')), 'seed file visible');
+  } finally { cleanup(repo); }
+});
+
+test('release: removes worktree dir and unregisters from git', () => {
+  const repo = mkRepo();
+  try {
+    const { worktree_path } = wm.allocate({ repoRoot: repo, sid: 'sess-rel' });
+    wm.release({ repoRoot: repo, worktree_path });
+    assert.equal(fs.existsSync(worktree_path), false, 'dir should be removed');
+    const active = wm.listActive(repo);
+    assert.equal(active.length, 0, 'no slices should remain');
+  } finally { cleanup(repo); }
+});
+
+test('3 concurrent allocates → 3 independent worktrees visible via listActive', () => {
+  const repo = mkRepo();
+  try {
+    const sids = ['sess-a', 'sess-b', 'sess-c'];
+    const paths = sids.map((sid) => wm.allocate({ repoRoot: repo, sid }).worktree_path);
+    for (const p of paths) assert.ok(fs.existsSync(p), `${p} missing`);
+    const active = wm.listActive(repo);
+    const activeSids = active.map((a) => a.sid).sort();
+    assert.deepEqual(activeSids, sids.slice().sort());
+    // Every entry has a distinct worktree_path
+    const uniquePaths = new Set(active.map((a) => a.worktree_path));
+    assert.equal(uniquePaths.size, 3);
+  } finally { cleanup(repo); }
+});
+
+test('5 rapid allocates in one tick → no .git/config.lock contention', () => {
+  const repo = mkRepo();
+  try {
+    const sids = ['s1', 's2', 's3', 's4', 's5'];
+    // Execute synchronously back-to-back; Node single-thread guarantees
+    // serialized git calls, so no file-lock race.
+    for (const sid of sids) {
+      wm.allocate({ repoRoot: repo, sid });
+    }
+    assert.equal(wm.listActive(repo).length, 5);
+  } finally { cleanup(repo); }
+});
+
+test('listActive: only returns worktrees under .ultra/worktrees/ (main excluded)', () => {
+  const repo = mkRepo();
+  try {
+    // Manually add a worktree OUTSIDE .ultra/worktrees — should be ignored.
+    const outsideDir = path.join(repo, 'other-wt');
+    execFileSync('git', ['worktree', 'add', '--detach', outsideDir, 'HEAD'], {
+      cwd: repo, stdio: 'pipe',
+    });
+    wm.allocate({ repoRoot: repo, sid: 'sess-domain' });
+    const active = wm.listActive(repo);
+    assert.equal(active.length, 1);
+    assert.equal(active[0].sid, 'sess-domain');
+  } finally { cleanup(repo); }
+});
+
+test('listActive: empty repo → []', () => {
+  const repo = mkRepo();
+  try {
+    assert.deepEqual(wm.listActive(repo), []);
+  } finally { cleanup(repo); }
+});
+
+test('releaseAll: clears all allocated worktrees + filesystem orphans', () => {
+  const repo = mkRepo();
+  try {
+    wm.allocate({ repoRoot: repo, sid: 'x1' });
+    wm.allocate({ repoRoot: repo, sid: 'x2' });
+    // Create an orphan dir: git doesn't know about it, but fs exists.
+    const orphanDir = path.join(repo, '.ultra', 'worktrees', 'orphan-dir');
+    fs.mkdirSync(orphanDir, { recursive: true });
+    fs.writeFileSync(path.join(orphanDir, 'junk.txt'), 'x');
+
+    const result = wm.releaseAll(repo);
+    assert.equal(result.cleaned, 2, 'should report 2 git-tracked cleanups');
+    assert.equal(wm.listActive(repo).length, 0);
+    assert.equal(fs.existsSync(orphanDir), false, 'orphan must be swept');
+  } finally { cleanup(repo); }
+});
+
+test('allocate: baseRef honored — worktree checked out at given ref', () => {
+  const repo = mkRepo();
+  try {
+    // Make a second commit so we have two distinct SHAs.
+    fs.writeFileSync(path.join(repo, 'second.md'), '# second\n');
+    execFileSync('git', ['add', '-A'], { cwd: repo });
+    execFileSync('git', ['commit', '-q', '-m', 'second'], { cwd: repo });
+    const firstSha = execFileSync('git', ['rev-parse', 'HEAD~1'], {
+      cwd: repo, stdio: ['ignore', 'pipe', 'pipe'],
+    }).toString().trim();
+
+    const { worktree_path } = wm.allocate({
+      repoRoot: repo, sid: 'sess-ref', baseRef: firstSha,
+    });
+    const wtSha = execFileSync('git', ['rev-parse', 'HEAD'], {
+      cwd: worktree_path, stdio: ['ignore', 'pipe', 'pipe'],
+    }).toString().trim();
+    assert.equal(wtSha, firstSha);
+  } finally { cleanup(repo); }
+});