amalgm 0.1.161 → 0.1.162

package/runtime/scripts/amalgm-mcp/workspace/merge.js

@@ -0,0 +1,290 @@
+'use strict';
+
+/**
+ * The coexistence engine.
+ *
+ * The workspace rule: every writer — human, agent, or remote machine —
+ * writes into the same working tree, and no writer's work is ever
+ * silently lost. This module is the mechanism. A peer's contribution to
+ * a local working tree is represented as a git tree oid ("base commit
+ * plus exactly the peer content folded in so far"), and the only verb is
+ * advance: move that contribution from the tree we hold to the tree the
+ * peer just published, file by file, around whatever else lives in the
+ * working tree.
+ *
+ * Per file, in order:
+ * - working file already matches the peer's version → fold without
+ *   writing (this is what makes echoes and replays no-ops);
+ * - working file untouched since the held version → take the peer's
+ *   version verbatim (create, update, or delete);
+ * - both sides changed text → content-level three-way merge; a clean
+ *   merge writes, an overlapping one holds the file aside untouched
+ *   with a named conflict kind. Both versions survive: local in the
+ *   tree, the peer's in their checkpoint.
+ *
+ * Everything here computes against the object database with scratch
+ * index files; the only worktree mutation is the final write set, which
+ * goes through transition.applyMergedFiles so it lands in the journal.
+ */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { execFile } = require('child_process');
+const { promisify } = require('util');
+const { GitError } = require('./git');
+const transition = require('./transition');
+
+const execFileAsync = promisify(execFile);
+
+const MERGE_ENV = {
+  GIT_OPTIONAL_LOCKS: '0',
+  GIT_TERMINAL_PROMPT: '0',
+  LC_ALL: 'C',
+};
+
+async function run(args, cwd, { env = {}, okCodes = [0], binary = false } = {}) {
+  try {
+    const { stdout } = await execFileAsync('git', args, {
+      cwd,
+      env: { ...process.env, ...MERGE_ENV, ...env },
+      timeout: 60_000,
+      maxBuffer: 64 * 1024 * 1024,
+      encoding: binary ? 'buffer' : 'utf8',
+    });
+    return { stdout, exitCode: 0 };
+  } catch (error) {
+    const exitCode = typeof error.code === 'number' ? error.code : 1;
+    if (okCodes.includes(exitCode)) {
+      return { stdout: error.stdout ?? (binary ? Buffer.alloc(0) : ''), exitCode };
+    }
+    throw new GitError(args, cwd, exitCode, String(error.stderr ?? error.message));
+  }
+}
+
+async function withScratch(fn) {
+  const dir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'amalgm-merge-'));
+  try {
+    return await fn(dir);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+/** The tree oid of a commit. */
+async function treeOf(worktreeRoot, commitOid) {
+  const { stdout } = await run(['rev-parse', `${commitOid}^{tree}`], worktreeRoot);
+  return stdout.trim();
+}
+
+/** Does this checkout's object store still contain the tree? */
+async function hasTree(worktreeRoot, treeOid) {
+  const result = await run(['cat-file', '-e', `${treeOid}^{tree}`], worktreeRoot, { okCodes: [0, 1, 128] });
+  return result.exitCode === 0;
+}
+
+/**
+ * The tree a captured worktree patch describes: base commit's tree with
+ * the patch applied. Computed entirely in a scratch index — the worktree
+ * is never touched, and the resulting tree lands in the object database
+ * where it is content-addressed and inspectable.
+ */
+async function treeOfPatch(worktreeRoot, baseOid, diff) {
+  if (!diff) return treeOf(worktreeRoot, baseOid);
+  return withScratch(async (dir) => {
+    const env = { GIT_INDEX_FILE: path.join(dir, 'index') };
+    const patchFile = path.join(dir, 'patch');
+    await fs.promises.writeFile(patchFile, diff);
+    await run(['read-tree', baseOid], worktreeRoot, { env });
+    await run(['apply', '--cached', '--whitespace=nowarn', patchFile], worktreeRoot, { env });
+    const { stdout } = await run(['write-tree'], worktreeRoot, { env });
+    return stdout.trim();
+  });
+}
+
+/** Paths that differ between two trees, no rename detection — exact adds/deletes. */
+async function changedPaths(worktreeRoot, treeA, treeB) {
+  const { stdout } = await run(
+    ['diff-tree', '-r', '-z', '--no-renames', '--name-status', treeA, treeB],
+    worktreeRoot,
+  );
+  const tokens = stdout.split('\0');
+  const paths = [];
+  for (let i = 0; i + 1 < tokens.length && tokens[i]; i += 2) {
+    paths.push(tokens[i + 1]);
+  }
+  return paths;
+}
+
+/** The blob entry at a path in a tree: { mode, type, oid } or null. */
+async function entryAt(worktreeRoot, treeOid, relPath) {
+  const { stdout } = await run(['ls-tree', '-z', treeOid, '--', relPath], worktreeRoot);
+  const line = stdout.split('\0')[0];
+  const match = line && line.match(/^(\d+) (\w+) ([0-9a-f]+)\t/);
+  return match ? { mode: match[1], type: match[2], oid: match[3] } : null;
+}
+
+async function readBlob(worktreeRoot, oid) {
+  const { stdout } = await run(['cat-file', 'blob', oid], worktreeRoot, { binary: true });
+  return stdout;
+}
+
+/** The working file as bytes: { kind: 'file'|'symlink', content, exec } or null. */
+function workFileState(worktreeRoot, relPath) {
+  const abs = path.join(worktreeRoot, relPath);
+  let stat;
+  try {
+    stat = fs.lstatSync(abs);
+  } catch {
+    return null;
+  }
+  if (stat.isSymbolicLink()) {
+    return { kind: 'symlink', content: Buffer.from(fs.readlinkSync(abs)), exec: false };
+  }
+  if (!stat.isFile()) return null;
+  return { kind: 'file', content: fs.readFileSync(abs), exec: (stat.mode & 0o100) !== 0 };
+}
+
+/** Does the working file hold exactly this tree entry's content? */
+function workMatches(work, entry, blobBytes) {
+  if (!entry) return work === null;
+  if (work === null) return false;
+  if (entry.mode === '120000') return work.kind === 'symlink' && work.content.equals(blobBytes);
+  return work.kind === 'file' && work.content.equals(blobBytes);
+}
+
+function isText(buffer) {
+  return buffer !== null && !buffer.includes(0);
+}
+
+/** Content-level three-way merge; { ok, content } — never writes markers to disk. */
+async function mergeFileContents(ours, base, theirs) {
+  return withScratch(async (dir) => {
+    const oursFile = path.join(dir, 'ours');
+    const baseFile = path.join(dir, 'base');
+    const theirsFile = path.join(dir, 'theirs');
+    await fs.promises.writeFile(oursFile, ours);
+    await fs.promises.writeFile(baseFile, base);
+    await fs.promises.writeFile(theirsFile, theirs);
+    const conflictCodes = Array.from({ length: 127 }, (_, i) => i + 1);
+    const result = await run(
+      ['merge-file', '-p', '-L', 'local', '-L', 'base', '-L', 'peer', oursFile, baseFile, theirsFile],
+      dir,
+      { okCodes: conflictCodes, binary: true },
+    );
+    return { ok: result.exitCode === 0, content: result.stdout };
+  });
+}
+
+/** heldTree with the given entries replaced/removed — via a scratch index. */
+async function updateHeldTree(worktreeRoot, heldTree, applied) {
+  return withScratch(async (dir) => {
+    const env = { GIT_INDEX_FILE: path.join(dir, 'index') };
+    await run(['read-tree', heldTree], worktreeRoot, { env });
+    for (const { path: relPath, entry } of applied) {
+      if (entry) {
+        await run(
+          ['update-index', '--add', '--cacheinfo', `${entry.mode},${entry.oid},${relPath}`],
+          worktreeRoot,
+          { env },
+        );
+      } else {
+        await run(['update-index', '--force-remove', '--', relPath], worktreeRoot, { env });
+      }
+    }
+    const { stdout } = await run(['write-tree'], worktreeRoot, { env });
+    return stdout.trim();
+  });
+}
+
+function unsafePath(relPath) {
+  return path.isAbsolute(relPath) || relPath.split('/').includes('..');
+}
+
+/**
+ * Advance the peer's contribution in this working tree from heldTree to
+ * targetTree. Returns { applied, conflicts, heldTree, wrote } — applied
+ * paths are folded into the returned heldTree; conflicted paths are left
+ * exactly as the working tree had them, each with a named kind.
+ */
+async function advance(worktreeRoot, heldTree, targetTree, { label } = {}) {
+  const applied = [];
+  const conflicts = [];
+  const writes = [];
+
+  for (const relPath of await changedPaths(worktreeRoot, heldTree, targetTree)) {
+    if (unsafePath(relPath)) {
+      conflicts.push({ path: relPath, kind: 'unsafe-path' });
+      continue;
+    }
+    const held = await entryAt(worktreeRoot, heldTree, relPath);
+    const target = await entryAt(worktreeRoot, targetTree, relPath);
+    if ((held && held.type !== 'blob') || (target && target.type !== 'blob')) {
+      conflicts.push({ path: relPath, kind: 'unsupported-entry' });
+      continue;
+    }
+    const heldBytes = held ? await readBlob(worktreeRoot, held.oid) : null;
+    const targetBytes = target ? await readBlob(worktreeRoot, target.oid) : null;
+    const work = workFileState(worktreeRoot, relPath);
+
+    if (workMatches(work, target, targetBytes)) {
+      // Already there — a replayed or echoed change folds without a write.
+      applied.push({ path: relPath, entry: target });
+      continue;
+    }
+    if (workMatches(work, held, heldBytes)) {
+      // Untouched locally since what we hold — take the peer's version.
+      writes.push(target
+        ? { path: relPath, content: targetBytes, mode: target.mode }
+        : { path: relPath, content: null });
+      applied.push({ path: relPath, entry: target });
+      continue;
+    }
+
+    // The working file differs from both what we hold and what the peer
+    // published: two writers touched it. Merge or preserve — never pick.
+    if (!target) {
+      conflicts.push({ path: relPath, kind: 'delete-vs-edit' });
+      continue;
+    }
+    if (!work) {
+      conflicts.push({ path: relPath, kind: 'edit-vs-delete' });
+      continue;
+    }
+    if (!held) {
+      conflicts.push({ path: relPath, kind: 'add-add' });
+      continue;
+    }
+    const mergeable = work.kind === 'file'
+      && target.mode !== '120000'
+      && held.mode !== '120000'
+      && isText(work.content) && isText(heldBytes) && isText(targetBytes);
+    if (!mergeable) {
+      conflicts.push({ path: relPath, kind: 'binary-overlap' });
+      continue;
+    }
+    const merged = await mergeFileContents(work.content, heldBytes, targetBytes);
+    if (!merged.ok) {
+      conflicts.push({ path: relPath, kind: 'content-overlap' });
+      continue;
+    }
+    writes.push({ path: relPath, content: merged.content, mode: work.exec ? '100755' : '100644' });
+    applied.push({ path: relPath, entry: target });
+  }
+
+  if (writes.length) await transition.applyMergedFiles(worktreeRoot, writes, label);
+  const newHeldTree = applied.length ? await updateHeldTree(worktreeRoot, heldTree, applied) : heldTree;
+  return {
+    applied: applied.map((a) => a.path),
+    conflicts,
+    heldTree: newHeldTree,
+    wrote: writes.length,
+  };
+}
+
+module.exports = {
+  advance,
+  hasTree,
+  treeOf,
+  treeOfPatch,
+};

package/runtime/scripts/amalgm-mcp/workspace/reconcile.js

@@ -0,0 +1,347 @@
+'use strict';
+
+/**
+ * Workspace reconciliation: reconcile this machine's checkouts toward
+ * what peer machines published — cards for where the repo stands (B),
+ * checkpoints for the uncommitted content (D).
+ *
+ * The workspace rule this implements: every writer — human, agent, or
+ * remote machine — writes into the same working tree, and no writer's
+ * work is ever silently lost. A peer's edits land here the way a local
+ * agent's would: non-overlapping changes coexist, overlapping changes
+ * preserve both versions and surface a named per-file conflict, git
+ * history moves (commit, branch) travel as card-controlled transitions,
+ * and ignored files never participate.
+ *
+ * Reconciliation is automatic for every eligible checkout. There is no
+ * per-machine enable flag and no directional relationship between
+ * machines. Authorization belongs at the user-level workspace membership
+ * boundary (owner, editor, viewer); this layer acts only on state admitted
+ * by that boundary. There is one movement verb — advance the peer's
+ * contribution in this tree from what we hold to what they published
+ * (merge.js) — and it subsumes apply, re-apply, and restore: a peer going
+ * clean is just an advance toward their bare base tree, removing exactly
+ * their content and nothing else. Because folding an already-present
+ * change is a no-op by content, echoed and replayed patches converge
+ * instead of looping.
+ *
+ * Frozen boundaries: only closed-list operations execute (fetch an exact
+ * branch from the approved remote, fast-forward, merged file writes via
+ * the journaled transition layer), local work is never overwritten, and
+ * every hold is a named, queryable state — never a silent skip. Each
+ * reconcile pass executes at most one movement per repo and re-observes;
+ * convergence happens across passes, on freshly verified state.
+ */
+
+const path = require('path');
+const { AMALGM_DIR } = require('../config');
+const { subscribeStateEvents } = require('../state/events');
+const { machineId } = require('./identity');
+const { listRepoCards, refreshRepoCards } = require('./cards');
+const { readWall } = require('./wall');
+const { captureWorktreeDiff, hasCommit, isAncestor } = require('./git');
+const {
+  MAX_DIFF_BYTES,
+  checkpointFile,
+  checkpointResourceId,
+  readCheckpoint,
+  repoKeyOfCard,
+  revisionOf,
+} = require('./checkpoint');
+const { ensureDocBound } = require('./binding');
+const { pairDigest, readPairState, saveRollback, writePairState } = require('./ledger');
+const merge = require('./merge');
+const transition = require('./transition');
+
+const RECONCILE_QUIET_MS = 750;
+const RECONCILE_INTERVAL_MS = 30_000;
+
+const service = {
+  started: false,
+  reconcileTimer: null,
+  intervalTimer: null,
+  unsubscribe: null,
+  watchedDocs: new Set([path.join(AMALGM_DIR, 'state', 'machine-cards.jsonl')]),
+  pairs: new Map(), // digest → last outcome, for stats
+  counters: { passes: 0, movements: 0, failures: 0 },
+  lastPass: null,
+};
+
+// --- same base: advance the peer's contribution ------------------------------
+
+function conflictSummary(conflicts) {
+  return conflicts.map((c) => `${c.kind}:${c.path}`).join(', ').slice(0, 300);
+}
+
+async function advanceSameBase(localCard, digest, entry, captured, localRevision) {
+  const root = localCard.path;
+  const pairState = readPairState(digest);
+  const baseTree = await merge.treeOf(root, captured.baseOid);
+  const held = (
+    pairState.baseOid === captured.baseOid
+    && pairState.heldTree
+    && await merge.hasTree(root, pairState.heldTree)
+  ) ? pairState.heldTree : baseTree;
+  const target = await merge.treeOfPatch(root, captured.baseOid, entry.diff || '');
+  const ownWork = localRevision !== null && localRevision !== (pairState.settledLocalRevision ?? null);
+
+  if (held === target) {
+    if (target === baseTree) {
+      return localRevision === null
+        ? { state: 'in-sync', reason: null }
+        : { state: 'local-work', reason: 'peer-clean' };
+    }
+    return { state: 'applied', reason: ownWork ? 'with-local-work' : null };
+  }
+
+  // A conflicted attempt is only repeated when something changed: the
+  // peer published anew, or the local files moved. Otherwise report the
+  // standing conflict without touching anything.
+  if (
+    pairState.peerRevision === entry.revision
+    && pairState.heldTree === held
+    && pairState.conflicts?.length
+    && pairState.settledLocalRevision === localRevision
+  ) {
+    return { state: 'conflict', reason: conflictSummary(pairState.conflicts), conflicts: pairState.conflicts };
+  }
+
+  saveRollback(digest, captured.diff);
+  const result = await merge.advance(root, held, target, { label: entry.revision || 'peer-clean' });
+  const recaptured = await captureWorktreeDiff(root, { maxBytes: MAX_DIFF_BYTES * 2 });
+  writePairState(digest, {
+    peerMachine: entry.machine,
+    repoKey: entry.repoKey,
+    baseOid: captured.baseOid,
+    heldTree: result.heldTree,
+    holdsContent: result.heldTree !== baseTree,
+    peerRevision: entry.revision,
+    conflicts: result.conflicts,
+    settledLocalRevision: recaptured.diff ? revisionOf(recaptured.baseOid, recaptured.diff) : null,
+  });
+
+  const moved = result.applied.length > 0;
+  if (result.conflicts.length) {
+    return { state: 'conflict', reason: conflictSummary(result.conflicts), conflicts: result.conflicts, moved };
+  }
+  if (target === baseTree) {
+    return recaptured.diff === ''
+      ? { state: 'in-sync', reason: 'restored-peer-went-clean', moved }
+      : { state: 'local-work', reason: 'peer-clean', moved };
+  }
+  return { state: 'applied', reason: ownWork ? 'coexisting-with-local-work' : null, moved };
+}
+
+// --- one repo, one pass -----------------------------------------------------
+
+/**
+ * Reconcile one local checkout toward one peer's published state.
+ * Executes at most one movement, returns { state, reason } — every branch
+ * of the decision has a name that survives into stats.
+ */
+async function reconcilePair(localCard, peerCard, entry, digest) {
+  if (localCard.operation !== 'none') return { state: 'waiting', reason: 'local-operation-in-flight' };
+  if (!entry) return { state: 'waiting', reason: 'no-peer-checkpoint-yet' };
+  if (!entry.baseOid) return { state: 'waiting', reason: 'peer-unborn' };
+
+  const captured = await captureWorktreeDiff(localCard.path, { maxBytes: MAX_DIFF_BYTES });
+  if (captured.diff === null) return { state: 'blocked', reason: `local-capture-${captured.reason}` };
+  const localRevision = captured.diff === '' ? null : revisionOf(captured.baseOid, captured.diff);
+
+  if (entry.baseOid === captured.baseOid) {
+    // A peer whose dirty state couldn't travel is a hold, not a signal to
+    // move — what we already folded in stays exactly where it is.
+    if (entry.skipped) return { state: 'waiting', reason: `peer-skipped-${entry.skipped}` };
+    return advanceSameBase(localCard, digest, entry, captured, localRevision);
+  }
+
+  // The peer's base commit differs from ours.
+  if (await isAncestor(localCard.path, entry.baseOid, captured.baseOid)) {
+    return { state: 'peer-behind', reason: null };
+  }
+  if (!(await hasCommit(localCard.path, entry.baseOid))) {
+    const branch = entry.branch || peerCard.head?.branch;
+    const approvedSource = localCard.repo.remote && localCard.repo.remote === peerCard.repo?.remote;
+    if (!approvedSource || !branch) return { state: 'blocked', reason: 'missing-objects-no-approved-source' };
+    await transition.fetchBranch(localCard.path, 'origin', branch);
+    if (!(await hasCommit(localCard.path, entry.baseOid))) {
+      return { state: 'blocked', reason: 'missing-objects-after-fetch' };
+    }
+  }
+  if (localCard.head.branch !== (entry.branch || peerCard.head?.branch)) {
+    return { state: 'blocked', reason: 'branch-mismatch' };
+  }
+  if (!(await isAncestor(localCard.path, captured.baseOid, entry.baseOid))) {
+    return { state: 'diverged', reason: 'histories-diverged' };
+  }
+
+  // Fast-forward. Held peer content the peer has since committed is
+  // absorbed by the checkout (content-equal files simply become clean);
+  // unrelated local work rides along untouched. If git refuses because
+  // real local work overlaps the update, first unwind what we ourselves
+  // hold and retry next pass — our own applied content is always ours to
+  // remove, other work never is.
+  try {
+    await transition.fastForwardTo(localCard.path, entry.baseOid);
+  } catch (error) {
+    const pairState = readPairState(digest);
+    if (pairState.holdsContent && pairState.baseOid === captured.baseOid && pairState.heldTree) {
+      const baseTree = await merge.treeOf(localCard.path, captured.baseOid);
+      saveRollback(digest, captured.diff);
+      const result = await merge.advance(localCard.path, pairState.heldTree, baseTree, { label: 'unwind-before-forward' });
+      writePairState(digest, {
+        heldTree: result.heldTree,
+        holdsContent: result.heldTree !== baseTree,
+        conflicts: result.conflicts,
+      });
+      return { state: 'restoring', reason: 'unwound-before-forward', moved: result.applied.length > 0 };
+    }
+    return { state: 'blocked', reason: 'local-work-overlaps-forward' };
+  }
+  writePairState(digest, {
+    peerMachine: entry.machine,
+    repoKey: entry.repoKey,
+    baseOid: entry.baseOid,
+    heldTree: null,
+    holdsContent: false,
+    peerRevision: null,
+    conflicts: [],
+    settledLocalRevision: null,
+  });
+  return { state: 'forwarded', reason: null, moved: true };
+}
+
+// --- the sweep --------------------------------------------------------------
+
+async function runReconcile() {
+  service.counters.passes += 1;
+  const startedAt = Date.now();
+  const self = machineId();
+  let moved = false;
+
+  const locals = new Map();
+  for (const card of listRepoCards()) {
+    if (card.health !== 'healthy' || card.kind !== 'primary') continue;
+    const key = repoKeyOfCard(card);
+    if (key && !locals.has(key)) locals.set(key, card);
+  }
+
+  for (const wallEntry of readWall()) {
+    if (wallEntry.machine === self) continue;
+    for (const peerCard of wallEntry.cards || []) {
+      if (peerCard.kind !== 'primary' || (peerCard.health && peerCard.health !== 'healthy')) continue;
+      const repoKey = repoKeyOfCard(peerCard);
+      const localCard = repoKey && locals.get(repoKey);
+      if (!localCard) continue;
+
+      const digest = pairDigest(wallEntry.machine, repoKey);
+      const record = (outcome) => {
+        service.pairs.set(digest, {
+          peerMachine: wallEntry.machine,
+          repoKey,
+          path: localCard.path,
+          ...outcome,
+          at: new Date().toISOString(),
+        });
+      };
+      try {
+        const file = checkpointFile(wallEntry.machine, repoKey);
+        const binding = await ensureDocBound({
+          resourceId: checkpointResourceId(wallEntry.machine, repoKey),
+          filePath: file,
+          create: false,
+        });
+        service.watchedDocs.add(file);
+        if (!binding.bound) {
+          record({ state: 'waiting', reason: `checkpoint-${binding.state}` });
+          continue;
+        }
+        const entry = readCheckpoint(wallEntry.machine, repoKey);
+        const outcome = await reconcilePair(localCard, peerCard, entry, digest);
+        if (outcome.moved) {
+          moved = true;
+          service.counters.movements += 1;
+        }
+        record(outcome);
+      } catch (error) {
+        service.counters.failures += 1;
+        record({ state: 'error', reason: error.message });
+        console.warn(`[WorkspaceReconcile] ${localCard.path}:`, error.message);
+      }
+    }
+  }
+
+  service.lastPass = { at: new Date().toISOString(), durationMs: Date.now() - startedAt, moved };
+  if (moved) {
+    // A movement changed real repo state: re-card promptly so our own
+    // published truth (and any follow-up movement) doesn't wait a cycle.
+    refreshRepoCards().catch(() => {});
+    scheduleReconcile();
+  }
+}
+
+let running = null;
+let queuedRun = null;
+
+function reconcileNow() {
+  if (running) {
+    queuedRun ??= running.catch(() => {}).then(() => reconcileNow());
+    return queuedRun;
+  }
+  queuedRun = null;
+  running = runReconcile().finally(() => {
+    running = null;
+  });
+  return running;
+}
+
+function scheduleReconcile() {
+  if (!service.started || service.reconcileTimer) return;
+  service.reconcileTimer = setTimeout(() => {
+    service.reconcileTimer = null;
+    reconcileNow().catch((error) => console.warn('[WorkspaceReconcile] reconcile failed:', error.message));
+  }, RECONCILE_QUIET_MS);
+  service.reconcileTimer.unref?.();
+}
+
+function startWorkspaceReconciler() {
+  if (service.started) return;
+  service.started = true;
+  service.unsubscribe = subscribeStateEvents((event) => {
+    const docChanged = typeof event.resource === 'string'
+      && event.resource.startsWith('doc:')
+      && service.watchedDocs.has(event.id);
+    if (docChanged || event.resource === 'repo-cards') scheduleReconcile();
+  });
+  service.intervalTimer = setInterval(scheduleReconcile, RECONCILE_INTERVAL_MS);
+  service.intervalTimer.unref?.();
+  scheduleReconcile();
+}
+
+function stopWorkspaceReconciler() {
+  if (!service.started) return;
+  service.started = false;
+  service.unsubscribe?.();
+  service.unsubscribe = null;
+  if (service.reconcileTimer) clearTimeout(service.reconcileTimer);
+  service.reconcileTimer = null;
+  if (service.intervalTimer) clearInterval(service.intervalTimer);
+  service.intervalTimer = null;
+}
+
+function reconciliationStats() {
+  return {
+    started: service.started,
+    ...service.counters,
+    lastPass: service.lastPass,
+    pairs: [...service.pairs.values()],
+  };
+}
+
+module.exports = {
+  reconciliationStats,
+  reconcileNow,
+  reconcilePair,
+  startWorkspaceReconciler,
+  stopWorkspaceReconciler,
+};