@bongos/core 1.17.0

package/tests/memory_pull.mjs

@@ -0,0 +1,429 @@
+// tests/memory_pull.mjs
+//
+// Unit tests for the memory pull-on-session-start hook (V3.R56 / #275 — the
+// PULL half of the ADR 0024 cloneable-memory chain). Covers the two surfaces a
+// security reviewer will attack:
+//
+//   1. decidePull — the newer/changed last-write-wins decision (ADR 0024 §3).
+//      Must pull when local is missing or server is strictly newer; must NOT
+//      clobber a local file that is newer/equal or whose timestamp is unknown.
+//   2. safeJoin — the path-traversal WRITE defense. A server-stored path that
+//      escapes the memory dir (including URL-encoded '..') must resolve to null
+//      so it is never written outside memDir.
+//
+// Plus a live filesystem round-trip of pullMemory against a stubbed global
+// fetch, proving: missing files are restored, identical files are skipped with
+// no content fetch, local-newer files are NOT overwritten, and a malicious
+// server path is rejected (no file lands outside memDir).
+//
+// Run:  node tests/memory_pull.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+const require = createRequire(import.meta.url);
+const pull = require('../.claude/hooks/pull-memory.js');
+
+let passed = 0;
+let failed = 0;
+function test(name, fn) {
+  try {
+    fn();
+    passed++;
+    console.log(`  ok  ${name}`);
+  } catch (err) {
+    failed++;
+    console.log(`  FAIL ${name}`);
+    console.log(`     ${err.message}`);
+  }
+}
+async function testAsync(name, fn) {
+  try {
+    await fn();
+    passed++;
+    console.log(`  ok  ${name}`);
+  } catch (err) {
+    failed++;
+    console.log(`  FAIL ${name}`);
+    console.log(`     ${err.message}`);
+  }
+}
+
+// ---------- decidePull (newer/changed decision) ----------
+
+test('decidePull: missing local → pull', () => {
+  const d = pull.decidePull({ sha256: 'a', updated_at: '2026-05-30T00:00:00Z' }, null);
+  assert.equal(d.action, 'pull');
+  assert.equal(d.reason, 'missing-locally');
+});
+
+test('decidePull: identical sha → skip (no fetch)', () => {
+  const d = pull.decidePull(
+    { sha256: 'abc', updated_at: '2026-05-30T00:00:00Z' },
+    { sha256: 'abc', mtimeMs: 1 }
+  );
+  assert.equal(d.action, 'skip');
+  assert.equal(d.reason, 'identical');
+});
+
+test('decidePull: differ + server strictly newer → pull', () => {
+  const serverMs = Date.parse('2026-05-30T12:00:00Z');
+  const localMs = Date.parse('2026-05-30T06:00:00Z');
+  const d = pull.decidePull(
+    { sha256: 'server', updated_at: new Date(serverMs).toISOString() },
+    { sha256: 'local', mtimeMs: localMs }
+  );
+  assert.equal(d.action, 'pull');
+  assert.equal(d.reason, 'server-newer');
+});
+
+test('decidePull: differ + local newer → skip (do not clobber unsynced work)', () => {
+  const serverMs = Date.parse('2026-05-30T06:00:00Z');
+  const localMs = Date.parse('2026-05-30T12:00:00Z');
+  const d = pull.decidePull(
+    { sha256: 'server', updated_at: new Date(serverMs).toISOString() },
+    { sha256: 'local', mtimeMs: localMs }
+  );
+  assert.equal(d.action, 'skip');
+  assert.equal(d.reason, 'local-newer-or-equal');
+});
+
+test('decidePull: differ + equal timestamps → skip (favor local)', () => {
+  const ms = Date.parse('2026-05-30T06:00:00Z');
+  const d = pull.decidePull(
+    { sha256: 'server', updated_at: new Date(ms).toISOString() },
+    { sha256: 'local', mtimeMs: ms }
+  );
+  assert.equal(d.action, 'skip');
+});
+
+test('decidePull: differ + missing server timestamp → skip (favor local)', () => {
+  const d = pull.decidePull(
+    { sha256: 'server' },
+    { sha256: 'local', mtimeMs: 123 }
+  );
+  assert.equal(d.action, 'skip');
+  assert.equal(d.reason, 'differ-but-timestamps-unknown-favor-local');
+});
+
+test('decidePull: falls back to mtime when updated_at absent', () => {
+  const serverMs = Date.parse('2026-05-30T12:00:00Z');
+  const localMs = Date.parse('2026-05-30T06:00:00Z');
+  const d = pull.decidePull(
+    { sha256: 'server', mtime: new Date(serverMs).toISOString() },
+    { sha256: 'local', mtimeMs: localMs }
+  );
+  assert.equal(d.action, 'pull');
+});
+
+// ---------- safeJoin (path-traversal WRITE defense) ----------
+
+const MEM = '/tmp/otb-test-memdir';
+
+test('safeJoin: plain relative path → inside memDir', () => {
+  const abs = pull.safeJoin(MEM, 'MEMORY.md');
+  assert.equal(abs, path.resolve(MEM, 'MEMORY.md'));
+});
+
+test('safeJoin: nested relative path → inside memDir', () => {
+  const abs = pull.safeJoin(MEM, 'sub/dir/notes.md');
+  assert.equal(abs, path.resolve(MEM, 'sub/dir/notes.md'));
+});
+
+test('safeJoin: literal ../ traversal → rejected', () => {
+  assert.equal(pull.safeJoin(MEM, '../evil'), null);
+  assert.equal(pull.safeJoin(MEM, '../../etc/passwd'), null);
+  assert.equal(pull.safeJoin(MEM, 'a/../../evil'), null);
+});
+
+test('safeJoin: URL-encoded ../ (%2e%2e) traversal → rejected', () => {
+  assert.equal(pull.safeJoin(MEM, '%2e%2e/evil'), null);
+  assert.equal(pull.safeJoin(MEM, '%2e%2e%2f%2e%2e%2fevil'), null);
+  assert.equal(pull.safeJoin(MEM, '..%2fevil'), null);
+});
+
+test('safeJoin: double-encoded ../ (%252e) traversal → rejected', () => {
+  assert.equal(pull.safeJoin(MEM, '%252e%252e/evil'), null);
+});
+
+test('safeJoin: absolute path → rejected', () => {
+  assert.equal(pull.safeJoin(MEM, '/etc/passwd'), null);
+  assert.equal(pull.safeJoin(MEM, '/tmp/otb-test-memdir-sibling/x'), null);
+});
+
+test('safeJoin: backslash / NUL → rejected', () => {
+  assert.equal(pull.safeJoin(MEM, 'a\\b'), null);
+  assert.equal(pull.safeJoin(MEM, 'a\0b'), null);
+});
+
+test('safeJoin: Windows drive-absolute → rejected', () => {
+  assert.equal(pull.safeJoin(MEM, 'C:\\evil'), null);
+});
+
+test('safeJoin: sibling-dir prefix attack (memdir-evil) → rejected', () => {
+  // A relative path can't reach a sibling without '..', but assert the
+  // containment check uses path.sep so '/memdir-evil' never matches '/memdir'.
+  const abs = pull.safeJoin(MEM, '../otb-test-memdir-evil/x');
+  assert.equal(abs, null);
+});
+
+test('safeJoin: empty / non-string → rejected', () => {
+  assert.equal(pull.safeJoin(MEM, ''), null);
+  assert.equal(pull.safeJoin(MEM, null), null);
+  assert.equal(pull.safeJoin(MEM, undefined), null);
+});
+
+test('safeJoin: bare "." (the dir itself) → rejected', () => {
+  assert.equal(pull.safeJoin(MEM, '.'), null);
+});
+
+// ---------- encodeProjectPath / tsToMs ----------
+
+test('encodeProjectPath: replaces / and . with -', () => {
+  assert.equal(pull.encodeProjectPath('/Users/x/Desktop/Claude-OTB'), '-Users-x-Desktop-Claude-OTB');
+});
+
+test('tsToMs: ISO string, epoch ms, Date, and garbage', () => {
+  assert.equal(pull.tsToMs('2026-05-30T00:00:00Z'), Date.parse('2026-05-30T00:00:00Z'));
+  assert.equal(pull.tsToMs(1234), 1234);
+  assert.equal(pull.tsToMs(new Date(5678)), 5678);
+  assert.equal(pull.tsToMs('not-a-date'), null);
+  assert.equal(pull.tsToMs(null), null);
+});
+
+// ---------- live filesystem round-trip of pullMemory (stubbed fetch) ----------
+
+await testAsync('pullMemory: restores missing, skips identical/local-newer, rejects traversal', async () => {
+  // Build a throwaway HOME with a session token + an empty memory dir keyed to
+  // a real git checkout (this repo's main worktree).
+  const tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'otb-pull-home-'));
+  const cfgDir = path.join(tmpHome, '.config', 'otb');
+  fs.mkdirSync(cfgDir, { recursive: true });
+  fs.writeFileSync(path.join(cfgDir, 'gds-session.json'), JSON.stringify({ token: 'fake-token', api_base: 'https://example.test' }));
+
+  const origHome = process.env.HOME;
+  const origConfig = process.env.CLAUDE_CONFIG_DIR;
+  const origFetch = globalThis.fetch;
+  process.env.HOME = tmpHome;
+  // Pin the memory base into the throwaway home so we don't touch the real one.
+  process.env.CLAUDE_CONFIG_DIR = path.join(tmpHome, '.claude');
+
+  // Resolve the memDir the hook will use (keyed to this repo's main worktree).
+  const memDir = pull.resolveMemoryDir(process.cwd());
+  assert.ok(memDir, 'memDir resolved');
+  fs.mkdirSync(memDir, { recursive: true });
+
+  // Seed local files:
+  //  - identical.md : same content as server (should be skipped, no fetch)
+  //  - local-new.md : differs, local mtime far in the future (should NOT be overwritten)
+  const identicalContent = 'identical body\n';
+  fs.writeFileSync(path.join(memDir, 'identical.md'), identicalContent);
+  fs.writeFileSync(path.join(memDir, 'local-new.md'), 'LOCAL WINS\n');
+  const future = new Date(Date.now() + 86_400_000);
+  fs.utimesSync(path.join(memDir, 'local-new.md'), future, future);
+
+  // sha256 helper matching the hook's.
+  const crypto = require('node:crypto');
+  const sha = (s) => crypto.createHash('sha256').update(Buffer.from(s, 'utf8')).digest('hex');
+
+  const newServerContent = 'fresh MEMORY from server\n';
+  const mismatchContent = 'real body the server will return\n';
+  const missingShaContent = 'body with no sha advertised\n';
+  const serverFiles = {
+    'MEMORY.md': { content: newServerContent, mtime: '2026-05-30T12:00:00Z', updated_at: '2026-05-30T12:00:00Z', sha256: sha(newServerContent) },
+    'identical.md': { content: identicalContent, mtime: '2026-05-30T12:00:00Z', updated_at: '2026-05-30T12:00:00Z', sha256: sha(identicalContent) },
+    'local-new.md': { content: 'server stale\n', mtime: '2020-01-01T00:00:00Z', updated_at: '2020-01-01T00:00:00Z', sha256: sha('server stale\n') },
+    '../evil.md': { content: 'PWNED\n', mtime: '2026-05-30T12:00:00Z', updated_at: '2026-05-30T12:00:00Z', sha256: sha('PWNED\n') },
+    // fix #1(a): list advertises a sha that does NOT match the content the
+    // server actually returns → must NOT be written (rejected, not pulled).
+    'mismatch.md': { content: mismatchContent, mtime: '2026-05-30T12:00:00Z', updated_at: '2026-05-30T12:00:00Z', sha256: sha('a DIFFERENT body than what is served') },
+    // fix #1(b): list entry with NO sha256 at all → unverifiable → must NOT be
+    // written, and must NOT even cost a content fetch (rejected in DECIDE).
+    'no-sha.md': { content: missingShaContent, mtime: '2026-05-30T12:00:00Z', updated_at: '2026-05-30T12:00:00Z', sha256: undefined },
+  };
+
+  let contentFetches = 0;
+  globalThis.fetch = async (urlStr) => {
+    const u = new URL(urlStr);
+    if (u.pathname === '/api/gds/memory/files') {
+      const files = Object.entries(serverFiles).map(([p, v]) => ({
+        path: p, sha256: v.sha256, byte_len: Buffer.byteLength(v.content), mtime: v.mtime, updated_at: v.updated_at,
+      }));
+      return new Response(JSON.stringify({ count: files.length, files }), { status: 200 });
+    }
+    if (u.pathname === '/api/gds/memory/file') {
+      contentFetches += 1;
+      const p = u.searchParams.get('path');
+      const v = serverFiles[p];
+      if (!v) return new Response(JSON.stringify({ error: 'not_found' }), { status: 404 });
+      return new Response(JSON.stringify({ path: p, content: v.content, sha256: v.sha256, mtime: v.mtime, updated_at: v.updated_at }), { status: 200 });
+    }
+    return new Response('{}', { status: 404 });
+  };
+
+  let summary;
+  try {
+    summary = await pull.pullMemory({ startCwd: process.cwd() });
+  } finally {
+    process.env.HOME = origHome;
+    if (origConfig === undefined) delete process.env.CLAUDE_CONFIG_DIR; else process.env.CLAUDE_CONFIG_DIR = origConfig;
+    globalThis.fetch = origFetch;
+  }
+
+  // MEMORY.md restored.
+  assert.equal(fs.readFileSync(path.join(memDir, 'MEMORY.md'), 'utf8'), newServerContent, 'MEMORY.md restored');
+  // identical.md untouched (and crucially, no content fetch for it).
+  assert.equal(fs.readFileSync(path.join(memDir, 'identical.md'), 'utf8'), identicalContent);
+  // local-new.md NOT overwritten (local mtime is in the future → local wins).
+  assert.equal(fs.readFileSync(path.join(memDir, 'local-new.md'), 'utf8'), 'LOCAL WINS\n', 'local-newer file preserved');
+  // The malicious '../evil.md' must NOT have been written anywhere outside memDir.
+  assert.equal(fs.existsSync(path.resolve(memDir, '..', 'evil.md')), false, 'traversal write rejected');
+  // fix #1(a): a sha256 MISMATCH must not write the file (content fetched, then
+  // rejected on verify) — and crucially the verified-good MEMORY.md still wins.
+  assert.equal(fs.existsSync(path.join(memDir, 'mismatch.md')), false, 'sha256-mismatch file not written');
+  // fix #1(b): a MISSING sha256 must not write the file (rejected pre-fetch).
+  assert.equal(fs.existsSync(path.join(memDir, 'no-sha.md')), false, 'missing-sha256 file not written');
+  // Content fetches: MEMORY.md (pulled+verified) + mismatch.md (fetched then
+  // rejected on verify) = 2. identical + local-new + evil + no-sha are all
+  // decided/rejected from list metadata, never fetched.
+  assert.equal(contentFetches, 2, `exactly two content fetches (got ${contentFetches})`);
+  assert.ok(/pulled 1 memory file/.test(summary), `summary mentions 1 pull: ${summary}`);
+
+  // Cleanup the throwaway home.
+  fs.rmSync(tmpHome, { recursive: true, force: true });
+});
+
+await testAsync('pullMemory: integrity — correct sha writes, mismatched/missing sha do not (summary reflects skips)', async () => {
+  // Focused on fix #1: three server files, all with NO local copy so all are
+  // "pull" candidates. Only the one whose served content matches its advertised
+  // sha256 gets written; the mismatch and the missing-sha are both skipped.
+  const tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'otb-pull-integrity-'));
+  const cfgDir = path.join(tmpHome, '.config', 'otb');
+  fs.mkdirSync(cfgDir, { recursive: true });
+  fs.writeFileSync(path.join(cfgDir, 'gds-session.json'), JSON.stringify({ token: 'fake-token', api_base: 'https://example.test' }));
+
+  const origHome = process.env.HOME;
+  const origConfig = process.env.CLAUDE_CONFIG_DIR;
+  const origFetch = globalThis.fetch;
+  process.env.HOME = tmpHome;
+  process.env.CLAUDE_CONFIG_DIR = path.join(tmpHome, '.claude');
+
+  const memDir = pull.resolveMemoryDir(process.cwd());
+  assert.ok(memDir, 'memDir resolved');
+  fs.mkdirSync(memDir, { recursive: true });
+
+  const crypto = require('node:crypto');
+  const sha = (s) => crypto.createHash('sha256').update(Buffer.from(s, 'utf8')).digest('hex');
+
+  const goodContent = 'verified good content\n';
+  const ts = { mtime: '2026-05-30T12:00:00Z', updated_at: '2026-05-30T12:00:00Z' };
+  const serverFiles = {
+    'good.md': { content: goodContent, ...ts, sha256: sha(goodContent) },           // (c) correct sha → written
+    'bad.md': { content: 'served body\n', ...ts, sha256: sha('claimed-but-wrong') }, // (a) mismatch → not written
+    'unsigned.md': { content: 'no sha here\n', ...ts, sha256: undefined },           // (b) missing sha → not written
+  };
+
+  let contentFetches = 0;
+  globalThis.fetch = async (urlStr) => {
+    const u = new URL(urlStr);
+    if (u.pathname === '/api/gds/memory/files') {
+      const files = Object.entries(serverFiles).map(([p, v]) => ({
+        path: p, sha256: v.sha256, byte_len: Buffer.byteLength(v.content), mtime: v.mtime, updated_at: v.updated_at,
+      }));
+      return new Response(JSON.stringify({ count: files.length, files }), { status: 200 });
+    }
+    if (u.pathname === '/api/gds/memory/file') {
+      contentFetches += 1;
+      const p = u.searchParams.get('path');
+      const v = serverFiles[p];
+      if (!v) return new Response(JSON.stringify({ error: 'not_found' }), { status: 404 });
+      return new Response(JSON.stringify({ path: p, content: v.content, sha256: v.sha256, mtime: v.mtime, updated_at: v.updated_at }), { status: 200 });
+    }
+    return new Response('{}', { status: 404 });
+  };
+
+  let summary;
+  try {
+    summary = await pull.pullMemory({ startCwd: process.cwd() });
+  } finally {
+    process.env.HOME = origHome;
+    if (origConfig === undefined) delete process.env.CLAUDE_CONFIG_DIR; else process.env.CLAUDE_CONFIG_DIR = origConfig;
+    globalThis.fetch = origFetch;
+  }
+
+  // (c) correct sha → written, content matches.
+  assert.equal(fs.readFileSync(path.join(memDir, 'good.md'), 'utf8'), goodContent, 'verified file written');
+  // (a) mismatch → not written.
+  assert.equal(fs.existsSync(path.join(memDir, 'bad.md')), false, 'sha-mismatch file not written');
+  // (b) missing sha → not written, not even fetched.
+  assert.equal(fs.existsSync(path.join(memDir, 'unsigned.md')), false, 'missing-sha file not written');
+  // Fetches: good.md + bad.md = 2 (unsigned.md rejected pre-fetch).
+  assert.equal(contentFetches, 2, `two content fetches (got ${contentFetches})`);
+  // Summary leads with the 1 pull (one file did write).
+  assert.ok(/pulled 1 memory file/.test(summary), `summary mentions 1 pull: ${summary}`);
+  assert.ok(/2 skipped/.test(summary), `summary mentions 2 skipped: ${summary}`);
+
+  fs.rmSync(tmpHome, { recursive: true, force: true });
+});
+
+await testAsync('pullMemory: 0 written + skips → summary does not read like a failure', async () => {
+  // fix #4: when nothing is written but files were skipped, the line must NOT
+  // lead with "pulled 0 memory files" (reads like the pull failed). One server
+  // file, no local copy, but its sha is missing → rejected, 0 written.
+  const tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'otb-pull-zero-'));
+  const cfgDir = path.join(tmpHome, '.config', 'otb');
+  fs.mkdirSync(cfgDir, { recursive: true });
+  fs.writeFileSync(path.join(cfgDir, 'gds-session.json'), JSON.stringify({ token: 'fake-token', api_base: 'https://example.test' }));
+
+  const origHome = process.env.HOME;
+  const origConfig = process.env.CLAUDE_CONFIG_DIR;
+  const origFetch = globalThis.fetch;
+  process.env.HOME = tmpHome;
+  process.env.CLAUDE_CONFIG_DIR = path.join(tmpHome, '.claude');
+
+  const memDir = pull.resolveMemoryDir(process.cwd());
+  fs.mkdirSync(memDir, { recursive: true });
+
+  globalThis.fetch = async (urlStr) => {
+    const u = new URL(urlStr);
+    if (u.pathname === '/api/gds/memory/files') {
+      const files = [{ path: 'orphan.md', byte_len: 3, mtime: '2026-05-30T12:00:00Z', updated_at: '2026-05-30T12:00:00Z' }];
+      return new Response(JSON.stringify({ count: files.length, files }), { status: 200 });
+    }
+    return new Response('{}', { status: 404 });
+  };
+
+  let summary;
+  try {
+    summary = await pull.pullMemory({ startCwd: process.cwd() });
+  } finally {
+    process.env.HOME = origHome;
+    if (origConfig === undefined) delete process.env.CLAUDE_CONFIG_DIR; else process.env.CLAUDE_CONFIG_DIR = origConfig;
+    globalThis.fetch = origFetch;
+  }
+
+  assert.ok(summary, 'summary returned');
+  assert.ok(/0 written/.test(summary), `summary says 0 written: ${summary}`);
+  assert.ok(!/pulled 0 memory file/.test(summary), `summary must not read like a failed pull: ${summary}`);
+
+  fs.rmSync(tmpHome, { recursive: true, force: true });
+});
+
+await testAsync('pullMemory: no session → silent null', async () => {
+  const tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), 'otb-pull-nosess-'));
+  const origHome = process.env.HOME;
+  process.env.HOME = tmpHome;
+  try {
+    const r = await pull.pullMemory({ startCwd: process.cwd() });
+    assert.equal(r, null);
+  } finally {
+    process.env.HOME = origHome;
+    fs.rmSync(tmpHome, { recursive: true, force: true });
+  }
+});
+
+console.log(`\n${passed} passed, ${failed} failed`);
+if (failed > 0) process.exit(1);

package/tests/merge_lease.mjs

@@ -0,0 +1,100 @@
+// tests/merge_lease.mjs — server-side merge lease (task 585 / idea 124).
+// db.js lease helpers against a stubbed pool + merge-lock.withServerMergeLease composition (pure).
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+// Stub the GDS pool (seed the require cache BEFORE requiring db.js, like tests/security_docs.mjs).
+const calls = [];
+let queued = [];
+const fakePool = {
+  query: async (text, params) => {
+    calls.push({ text, params });
+    return queued.length ? queued.shift() : { rows: [], rowCount: 0 };
+  },
+};
+const poolPath = require.resolve(path.join(ROOT, 'src', 'bongos', 'pool.js'));
+require.cache[poolPath] = { id: poolPath, filename: poolPath, loaded: true, exports: { pool: fakePool, instanceDbName: () => undefined } };
+
+// the merge-lease db helpers + merge-lock lib carved to the lifecycle module at BV1.R86.
+const db = require(path.join(ROOT, 'modules', 'lifecycle', 'db.js'));
+const mergeLock = require(path.join(ROOT, 'modules', 'lifecycle', 'merge-lock.js'));
+
+const lastSql = () => calls[calls.length - 1].text.replace(/\s+/g, ' ');
+
+test('acquireMergeLease: acquired when the upsert RETURNs a row', async () => {
+  calls.length = 0; queued = [{ rows: [{ holder: 'box-a', expires_at: 'T1' }] }];
+  const r = await db.acquireMergeLease({ key: 'main', holder: 'box-a', ttlSeconds: 300 });
+  assert.deepEqual(r, { acquired: true, holder: 'box-a', expires_at: 'T1' });
+  const sql = calls[0].text.replace(/\s+/g, ' ');
+  assert.match(sql, /INSERT INTO merge_lease/);
+  assert.match(sql, /ON CONFLICT \(key\) DO UPDATE/);
+  // the atomic guard: only steal an expired lease or renew our own
+  assert.match(sql, /WHERE merge_lease\.expires_at <= now\(\) OR merge_lease\.holder = EXCLUDED\.holder/);
+  assert.deepEqual(calls[0].params, ['main', 'box-a', 300]);
+});
+
+test('acquireMergeLease: NOT acquired when held → returns the current holder', async () => {
+  calls.length = 0; queued = [{ rows: [] }, { rows: [{ holder: 'box-b', expires_at: 'T2' }] }];
+  const r = await db.acquireMergeLease({ key: 'main', holder: 'box-a' });
+  assert.deepEqual(r, { acquired: false, holder: 'box-b', expires_at: 'T2' });
+  assert.match(lastSql(), /SELECT holder, expires_at FROM merge_lease WHERE key = \$1/);
+});
+
+test('acquireMergeLease: holder is required', async () => {
+  await assert.rejects(() => db.acquireMergeLease({ key: 'main' }), /holder is required/);
+});
+
+test('releaseMergeLease: deletes only when key+holder match (rowCount)', async () => {
+  calls.length = 0; queued = [{ rowCount: 1 }];
+  assert.deepEqual(await db.releaseMergeLease({ key: 'main', holder: 'box-a' }), { released: true });
+  assert.match(lastSql(), /DELETE FROM merge_lease WHERE key = \$1 AND holder = \$2/);
+  assert.deepEqual(calls[0].params, ['main', 'box-a']);
+  queued = [{ rowCount: 0 }];
+  assert.deepEqual(await db.releaseMergeLease({ holder: 'box-a' }), { released: false });
+});
+
+test('mergeLeaseStatus: returns the row (with computed expired) or null', async () => {
+  queued = [{ rows: [{ key: 'main', holder: 'box-a', expired: false }] }];
+  assert.equal((await db.mergeLeaseStatus()).holder, 'box-a');
+  queued = [{ rows: [] }];
+  assert.equal(await db.mergeLeaseStatus({ key: 'nope' }), null);
+});
+
+test('withServerMergeLease: acquires, runs fn, releases (success)', async () => {
+  const events = [];
+  const lease = {
+    acquire: async (o) => { events.push(['acq', o.holder]); return { acquired: true, holder: o.holder }; },
+    release: async (o) => { events.push(['rel', o.holder]); },
+  };
+  const out = await mergeLock.withServerMergeLease('box-a', async () => { events.push(['fn']); return 42; }, { lease });
+  assert.equal(out, 42);
+  assert.deepEqual(events, [['acq', 'box-a'], ['fn'], ['rel', 'box-a']]);
+});
+
+test('withServerMergeLease: releases even when fn throws', async () => {
+  let released = false;
+  const lease = { acquire: async () => ({ acquired: true }), release: async () => { released = true; } };
+  await assert.rejects(() => mergeLock.withServerMergeLease('h', async () => { throw new Error('boom'); }, { lease }), /boom/);
+  assert.equal(released, true);
+});
+
+test('withServerMergeLease: throws MERGE_LEASE_HELD when another machine holds it, fn never runs', async () => {
+  let ran = false;
+  const lease = { acquire: async () => ({ acquired: false, holder: 'box-b', expires_at: 'T9' }), release: async () => {} };
+  await assert.rejects(
+    () => mergeLock.withServerMergeLease('box-a', async () => { ran = true; }, { lease }),
+    (e) => e.code === 'MERGE_LEASE_HELD' && /box-b/.test(e.message)
+  );
+  assert.equal(ran, false);
+});
+
+test('withServerMergeLease: no backend → runs fn directly (single-machine model)', async () => {
+  const out = await mergeLock.withServerMergeLease('h', async () => 'ok', {});
+  assert.equal(out, 'ok');
+});