amalgm 0.1.245 → 0.1.246

package/runtime/scripts/amalgm-mcp/tests/repofollow.test.js

@@ -0,0 +1,675 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const { execFileSync, spawn } = require('child_process');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const Database = require('better-sqlite3');
+const { createObserver } = require('../observer');
+const { capture, createFollower, createCaptureWorker } = require('../repocard');
+
+const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'amalgm-repofollow-test-'));
+test.after(() => {
+  fs.rmSync(tempRoot, { recursive: true, force: true });
+});
+
+function git(dir, ...args) {
+  return execFileSync('git', args, { cwd: dir, stdio: ['pipe', 'pipe', 'pipe'] }).toString('utf8').trim();
+}
+
+function makeRepo(name) {
+  const dir = fs.realpathSync(fs.mkdtempSync(path.join(tempRoot, `${name}-`)));
+  git(dir, 'init', '--quiet');
+  git(dir, 'config', 'user.email', 'follow@amalgm.test');
+  git(dir, 'config', 'user.name', 'Follow');
+  git(dir, 'config', 'commit.gpgsign', 'false');
+  fs.writeFileSync(path.join(dir, '.gitignore'), 'ignored/\n');
+  fs.writeFileSync(path.join(dir, 'a.md'), 'v1\n');
+  git(dir, 'add', '-A');
+  git(dir, 'commit', '--quiet', '-m', 'first');
+  return dir;
+}
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+async function until(predicate, ms = 4_000) {
+  const deadline = Date.now() + ms;
+  while (!predicate() && Date.now() < deadline) await sleep(15);
+  return predicate();
+}
+
+/** Fast timings: settle short, cap well above it. */
+const T = { settleMs: 40, capMs: 500 };
+const SETTLED = T.settleMs + 150; // one full quiet cycle plus margin
+
+function makeFollower(repoPath, overrides = {}) {
+  const events = [];
+  const follower = createFollower({ repoPath, emit: (event) => events.push(event), ...T, ...overrides });
+  return { follower, events };
+}
+
+// --- identity semantics -----------------------------------------------------
+
+test('birth is one card event; an unchanged repo re-rung is silence', async () => {
+  const dir = makeRepo('birth');
+  const { follower, events } = makeFollower(dir);
+
+  follower.start();
+  await until(() => events.length > 0);
+  assert.equal(events.length, 1);
+  assert.equal(events[0].type, 'card.changed');
+  assert.ok(events[0].cardId && events[0].checkpointId && events[0].stateId);
+
+  follower.ring();
+  await sleep(SETTLED);
+  assert.equal(events.length, 1, 'an unchanged repo must stay silent');
+  follower.close();
+});
+
+test('a seeded follower resumes without re-announcing the world', async () => {
+  const dir = makeRepo('resume');
+  const known = capture(dir, { withBundle: false });
+  const { follower, events } = makeFollower(dir, { last: known });
+
+  follower.start();
+  await sleep(SETTLED);
+  assert.equal(events.length, 0);
+
+  fs.writeFileSync(path.join(dir, 'a.md'), 'edited after resume\n');
+  follower.ring();
+  await until(() => events.length > 0);
+  assert.equal(events.length, 1);
+  assert.equal(events[0].type, 'checkpoint.changed');
+  follower.close();
+});
+
+test('an edit is one checkpoint event; a commit is one card event', async () => {
+  const dir = makeRepo('classify');
+  const { follower, events } = makeFollower(dir, { last: capture(dir, { withBundle: false }) });
+  follower.start();
+
+  fs.writeFileSync(path.join(dir, 'a.md'), 'v2\n');
+  follower.ring();
+  await until(() => events.length === 1);
+  assert.equal(events[0].type, 'checkpoint.changed');
+
+  git(dir, 'add', '-A');
+  git(dir, 'commit', '--quiet', '-m', 'v2');
+  follower.ring();
+  await until(() => events.length === 2);
+  assert.equal(events[1].type, 'card.changed');
+  await sleep(SETTLED);
+  assert.equal(events.length, 2);
+  follower.close();
+});
+
+test('ignored churn rings loudly and emits nothing', async () => {
+  const dir = makeRepo('ignored');
+  const { follower, events } = makeFollower(dir, { last: capture(dir, { withBundle: false }) });
+  follower.start();
+
+  fs.mkdirSync(path.join(dir, 'ignored'));
+  for (let i = 0; i < 20; i += 1) {
+    fs.writeFileSync(path.join(dir, 'ignored', `noise-${i}.log`), `${i}\n`);
+    follower.ring();
+  }
+  await sleep(SETTLED + T.capMs);
+  assert.equal(events.length, 0, 'ignored churn changed no id and must be silence');
+  follower.close();
+});
+
+// --- the torn-read guard ------------------------------------------------------
+
+test('a capture raced by a write is discarded and retried by the follower itself', async () => {
+  const dir = makeRepo('raced');
+  let captures = 0;
+  let sabotage = 1;
+  const events = [];
+  const follower = createFollower({
+    repoPath: dir,
+    emit: (event) => events.push(event),
+    ...T,
+    captureFn: (repo) => {
+      captures += 1;
+      const snap = capture(repo, { withBundle: false });
+      if (sabotage > 0) {
+        // A write lands between the two reads: the pair must disagree, the
+        // half-written moment must never travel, and — deliberately — NO
+        // doorbell rings for this write. The retry must be the follower's own.
+        sabotage -= 1;
+        fs.writeFileSync(path.join(dir, 'a.md'), 'the final content\n');
+      }
+      return snap;
+    },
+    last: capture(dir, { withBundle: false }),
+  });
+
+  fs.writeFileSync(path.join(dir, 'a.md'), 'racing\n');
+  follower.ring();
+  await until(() => events.length > 0);
+  await sleep(SETTLED);
+
+  assert.equal(events.length, 1, 'the raced capture must not emit a second event');
+  assert.equal(events[0].type, 'checkpoint.changed');
+  assert.ok(captures >= 4, 'the raced pair must be retried as a fresh pair, not trusted');
+  const settled = capture(dir, { withBundle: false });
+  assert.equal(events[0].stateId, settled.stateId, 'only the final still state may travel');
+  follower.close();
+});
+
+test('an emit failure never advances the remembered state — the event is re-offered', async () => {
+  const dir = makeRepo('emit-fail');
+  const events = [];
+  let failures = 1;
+  const follower = createFollower({
+    repoPath: dir,
+    emit: (event) => {
+      if (failures > 0) {
+        failures -= 1;
+        throw new Error('consumer down');
+      }
+      events.push(event);
+    },
+    ...T,
+    last: capture(dir, { withBundle: false }),
+  });
+
+  fs.writeFileSync(path.join(dir, 'a.md'), 'must not be lost\n');
+  follower.ring();
+  // No further rings: the re-offer must be the follower's own retry.
+  const delivered = await until(() => events.length > 0, 5_000);
+  assert.ok(delivered, 'a failed emit silently advanced the remembered state — the event is lost');
+  assert.equal(events.length, 1);
+  assert.equal(events[0].type, 'checkpoint.changed');
+  const truth = capture(dir, { withBundle: false });
+  assert.equal(events[0].stateId, truth.stateId);
+  assert.deepEqual(follower.ids(), { cardId: truth.cardId, checkpointId: truth.checkpointId });
+  follower.close();
+});
+
+test('under endless churn the cap still speaks — via a proven-still capture', async () => {
+  const dir = makeRepo('cap');
+  const events = [];
+  // Churn every 60ms: settle (100ms) never fires. The cap does, and the
+  // double-read proof passes because ignored churn cannot move the ids.
+  const follower = createFollower({
+    repoPath: dir,
+    emit: (event) => events.push(event),
+    settleMs: 100,
+    capMs: 300,
+    last: capture(dir, { withBundle: false }),
+  });
+
+  fs.writeFileSync(path.join(dir, 'a.md'), 'the real change\n');
+  fs.mkdirSync(path.join(dir, 'ignored'));
+  let beat = 0;
+  const churn = setInterval(() => {
+    beat += 1;
+    fs.writeFileSync(path.join(dir, 'ignored', 'noise.log'), `${beat}\n`);
+    follower.ring();
+  }, 60);
+
+  const spoke = await until(() => events.length > 0, 6_000);
+  clearInterval(churn);
+  assert.ok(spoke, 'sustained churn starved detection: the cap never landed a capture');
+  assert.equal(events[0].type, 'checkpoint.changed');
+  follower.close();
+});
+
+// --- git's own boundaries -----------------------------------------------------
+
+test('a busy merge emits nothing; its resolution is one card event', async () => {
+  const dir = makeRepo('busy');
+  git(dir, 'checkout', '--quiet', '-b', 'left');
+  fs.writeFileSync(path.join(dir, 'a.md'), 'left\n');
+  git(dir, 'add', '-A');
+  git(dir, 'commit', '--quiet', '-m', 'left');
+  git(dir, 'checkout', '--quiet', '-');
+  fs.writeFileSync(path.join(dir, 'a.md'), 'right\n');
+  git(dir, 'add', '-A');
+  git(dir, 'commit', '--quiet', '-m', 'right');
+
+  const { follower, events } = makeFollower(dir, { last: capture(dir, { withBundle: false }) });
+  follower.start();
+
+  assert.throws(() => git(dir, 'merge', '--quiet', 'left'));
+  follower.ring();
+  await sleep(SETTLED + T.capMs);
+  assert.equal(events.length, 0, 'a mid-merge repo must never travel');
+
+  git(dir, 'add', '-A');
+  git(dir, 'commit', '--quiet', '--no-edit');
+  follower.ring();
+  await until(() => events.length > 0);
+  assert.equal(events.length, 1);
+  assert.equal(events[0].type, 'card.changed');
+  follower.close();
+});
+
+test('ref-less commands travel as checkpoint moves: staging, then hard reset', async () => {
+  // The axiom's second half: commands that move no ref (add, reset --hard
+  // HEAD; clean has its own test) still end at a new checkpointId.
+  const dir = makeRepo('refless');
+  fs.writeFileSync(path.join(dir, 'a.md'), 'dirty\n');
+  const seed = capture(dir, { withBundle: false });
+  const { follower, events } = makeFollower(dir, { last: seed });
+  follower.start();
+  await sleep(SETTLED);
+  assert.equal(events.length, 0, 'the seeded dirty state must be silence');
+
+  git(dir, 'add', '-A'); // index-only: no worktree file touched, no ref moved
+  follower.ring();
+  await until(() => events.length === 1);
+  assert.equal(events[0].type, 'checkpoint.changed');
+  assert.equal(events[0].cardId, seed.cardId, 'staging must not move the card');
+
+  git(dir, 'reset', '--quiet', '--hard', 'HEAD'); // reverts index+worktree; HEAD stays put
+  follower.ring();
+  await until(() => events.length === 2);
+  assert.equal(events[1].type, 'checkpoint.changed');
+  assert.equal(events[1].cardId, seed.cardId, 'a hard reset to HEAD must not move the card');
+  assert.notEqual(events[1].checkpointId, events[0].checkpointId);
+  await sleep(SETTLED);
+  assert.equal(events.length, 2);
+  follower.close();
+});
+
+/** A living process holding the lock file open — what a real git does. */
+function holdOpen(filePath) {
+  const child = spawn(process.execPath, ['-e',
+    'const fs=require("fs");fs.openSync(process.argv[1],"w");process.stdout.write("held\\n");setInterval(()=>{},1000);',
+    filePath], { stdio: ['ignore', 'pipe', 'ignore'] });
+  return new Promise((resolve, reject) => {
+    child.once('error', reject);
+    child.stdout.once('data', () => resolve(child));
+  });
+}
+async function releaseHolder(child) {
+  child.kill('SIGKILL');
+  await new Promise((resolve) => child.once('exit', resolve));
+}
+
+test('a lock held by a living process blocks capture and reports it; release recovers', async () => {
+  const dir = makeRepo('lock-held');
+  const lock = path.join(dir, '.git', 'index.lock');
+  const { follower, events } = makeFollower(dir, { last: capture(dir, { withBundle: false }) });
+
+  const holder = await holdOpen(lock);
+  fs.writeFileSync(path.join(dir, 'a.md'), 'edited under a held lock\n');
+  follower.ring();
+  // Well past settle AND cap: a held lock has no timer that ends in a bypass.
+  await sleep(SETTLED + T.capMs + 200);
+  assert.equal(events.length, 0, 'a held lock means git may be mid-write — nothing may travel');
+  assert.equal(follower.status().blocked, 'index.lock', 'the block must be reported, not silent');
+
+  await releaseHolder(holder);
+  fs.rmSync(lock);
+  follower.ring(); // in the composed system, the lock's deletion rings
+  await until(() => events.length > 0);
+  assert.equal(events.length, 1);
+  assert.equal(events[0].type, 'checkpoint.changed');
+  assert.equal(follower.status().blocked, null, 'recovery must clear the reported block');
+  follower.close();
+});
+
+test('an unheld lock is litter: edits, cleans, and card changes all still travel', async () => {
+  const dir = makeRepo('lock-stale');
+  fs.mkdirSync(path.join(dir, 'loose'));
+  for (let i = 0; i < 5; i += 1) fs.writeFileSync(path.join(dir, 'loose', `u${i}.md`), `${i}\n`);
+  const { follower, events } = makeFollower(dir, { last: capture(dir, { withBundle: false }) });
+  // Nobody holds this lock — a crashed git left it. It stops neither
+  // editors nor `git clean` nor `update-ref`, so it must not stop us.
+  fs.writeFileSync(path.join(dir, '.git', 'index.lock'), 'left by a crash');
+
+  fs.writeFileSync(path.join(dir, 'a.md'), 'edited behind a stale lock\n');
+  follower.ring();
+  await until(() => events.length === 1);
+  assert.equal(events[0].type, 'checkpoint.changed', 'a direct edit must travel past a stale lock');
+  assert.equal(follower.status().blocked, null, 'litter is not a block');
+
+  git(dir, 'clean', '-fdq'); // succeeds with the stale lock in place
+  follower.ring();
+  await until(() => events.length === 2);
+  assert.equal(events[1].type, 'checkpoint.changed', 'a bulk clean must travel past a stale lock');
+  assert.deepEqual(events[1].checkpoint.untracked, []);
+
+  git(dir, 'update-ref', 'refs/heads/side', 'HEAD'); // a CARD change the lock does not stop
+  follower.ring();
+  await until(() => events.length === 3);
+  assert.equal(events[2].type, 'card.changed', 'a card change must travel past a stale lock');
+  assert.ok(fs.existsSync(path.join(dir, '.git', 'index.lock')), 'the litter never moved');
+  follower.close();
+});
+
+test('flush() recovers the state even when the lock deletion doorbell was lost', async () => {
+  const dir = makeRepo('lock-lost-bell');
+  const lock = path.join(dir, '.git', 'index.lock');
+  const { follower, events } = makeFollower(dir, { last: capture(dir, { withBundle: false }) });
+
+  const holder = await holdOpen(lock);
+  fs.writeFileSync(path.join(dir, 'a.md'), 'changed while blocked\n');
+  follower.ring();
+  await sleep(SETTLED + T.capMs + 200);
+  assert.equal(events.length, 0);
+  assert.equal(follower.status().blocked, 'index.lock');
+
+  // The lock vanishes and its doorbell is LOST — no ring arrives, ever.
+  await releaseHolder(holder);
+  fs.rmSync(lock);
+  assert.equal(follower.status().blocked, null, 'status must read disk, not its own memory');
+
+  follower.flush(); // the consumer moment: a session opening, an app regaining focus
+  await until(() => events.length > 0);
+  assert.equal(events.length, 1);
+  assert.equal(events[0].type, 'checkpoint.changed');
+  const truth = capture(dir, { withBundle: false });
+  assert.equal(events[0].stateId, truth.stateId);
+  follower.close();
+});
+
+test('a consumer that flushes from inside emit does not recurse or double-speak', async () => {
+  const dir = makeRepo('reentrant');
+  const events = [];
+  let follower; // referenced by emit before assignment completes
+  follower = createFollower({
+    repoPath: dir,
+    emit: (event) => {
+      events.push(event);
+      follower.flush(); // a greedy consumer asking for more, mid-delivery
+    },
+    ...T,
+    last: capture(dir, { withBundle: false }),
+  });
+
+  fs.writeFileSync(path.join(dir, 'a.md'), 'one fact\n');
+  follower.ring();
+  await until(() => events.length > 0);
+  await sleep(SETTLED + T.capMs);
+  assert.equal(events.length, 1, 'a re-entrant flush must not re-speak the same state');
+  assert.equal(events[0].type, 'checkpoint.changed');
+  follower.close();
+});
+
+// --- the amalgm-owned boundary --------------------------------------------------
+
+test('an owned command is exactly one event at its declared end', async () => {
+  const dir = makeRepo('owned');
+  const { follower, events } = makeFollower(dir, { last: capture(dir, { withBundle: false }) });
+
+  follower.command(() => {
+    fs.writeFileSync(path.join(dir, 'a.md'), 'step 1\n');
+    follower.ring();
+    fs.writeFileSync(path.join(dir, 'b.md'), 'step 2\n');
+    follower.ring();
+    git(dir, 'add', '-A');
+    git(dir, 'commit', '--quiet', '-m', 'owned work');
+    follower.ring();
+  });
+
+  await until(() => events.length > 0);
+  await sleep(SETTLED);
+  assert.equal(events.length, 1, 'the command boundary must collapse everything to one event');
+  assert.equal(events[0].type, 'card.changed');
+  follower.close();
+});
+
+test('an owned async command may stall past every timer: still one event, at its end', async () => {
+  const dir = makeRepo('owned-async');
+  const { follower, events } = makeFollower(dir, { last: capture(dir, { withBundle: false }) });
+
+  await follower.command(async () => {
+    fs.writeFileSync(path.join(dir, 'a.md'), 'half-written\n');
+    follower.ring();
+    // The stall their plan asked for: longer than settle AND cap. Inside an
+    // owned boundary the half-written state must never leak.
+    await sleep(SETTLED + T.capMs);
+    assert.equal(events.length, 0, 'a stalled owned command leaked an intermediate state');
+    fs.writeFileSync(path.join(dir, 'a.md'), 'finished\n');
+    follower.ring();
+  });
+
+  await until(() => events.length > 0);
+  await sleep(SETTLED);
+  assert.equal(events.length, 1);
+  assert.equal(events[0].type, 'checkpoint.changed');
+  const truth = capture(dir, { withBundle: false });
+  assert.equal(events[0].stateId, truth.stateId, 'only the command-end state may travel');
+  follower.close();
+});
+
+test('nested owned commands capture once, at the outermost end', async () => {
+  const dir = makeRepo('owned-nested');
+  const { follower, events } = makeFollower(dir, { last: capture(dir, { withBundle: false }) });
+
+  await follower.command(async () => {
+    fs.writeFileSync(path.join(dir, 'a.md'), 'outer step\n');
+    follower.command(() => {
+      fs.writeFileSync(path.join(dir, 'b.md'), 'inner step\n');
+      follower.ring();
+    });
+    await sleep(SETTLED);
+    assert.equal(events.length, 0, 'the inner command end must not fire inside the outer one');
+    git(dir, 'add', '-A');
+    git(dir, 'commit', '--quiet', '-m', 'nested work');
+  });
+
+  await until(() => events.length > 0);
+  await sleep(SETTLED);
+  assert.equal(events.length, 1, 'nesting must still collapse to one event');
+  assert.equal(events[0].type, 'card.changed');
+  follower.close();
+});
+
+test('a failing owned command still captures at its boundary', async () => {
+  const dir = makeRepo('owned-fail');
+  const { follower, events } = makeFollower(dir, { last: capture(dir, { withBundle: false }) });
+
+  assert.throws(() => follower.command(() => {
+    fs.writeFileSync(path.join(dir, 'a.md'), 'work before the crash\n');
+    follower.ring();
+    throw new Error('command failed');
+  }), /command failed/);
+
+  await until(() => events.length > 0);
+  assert.equal(events.length, 1, 'a failed command still ended — its residue must travel');
+  assert.equal(events[0].type, 'checkpoint.changed');
+  follower.close();
+});
+
+test('an owned command that changed nothing is silence', async () => {
+  const dir = makeRepo('owned-noop');
+  const { follower, events } = makeFollower(dir, { last: capture(dir, { withBundle: false }) });
+
+  follower.command(() => {
+    git(dir, 'status', '--porcelain');
+    follower.ring();
+  });
+  await sleep(SETTLED);
+  assert.equal(events.length, 0);
+  follower.close();
+});
+
+test('a repo containing a nested repo still travels: no crash, no retry loop', async () => {
+  const dir = makeRepo('nested');
+  const nested = path.join(dir, 'sub');
+  fs.mkdirSync(nested);
+  git(nested, 'init', '--quiet');
+  fs.writeFileSync(path.join(nested, 'inner.md'), 'child territory\n');
+
+  const { follower, events } = makeFollower(dir, { last: capture(dir, { withBundle: false }) });
+  fs.writeFileSync(path.join(dir, 'a.md'), 'edited beside a nested repo\n');
+  follower.ring();
+  await until(() => events.length === 1);
+  assert.equal(events[0].type, 'checkpoint.changed');
+  assert.equal(events[0].checkpoint.untracked.some((file) => file.path.startsWith('sub')), false,
+    'the nested territory must not leak into the parent checkpoint');
+
+  await sleep(T.capMs + 200); // a crash-looping capture would keep re-firing here
+  assert.equal(events.length, 1, 'one edit must stay one event');
+  follower.close();
+});
+
+// --- async capture: pairs that take time open races timers can't see ---------
+
+test('a doorbell during an in-flight capture pair is not swallowed', async () => {
+  const dir = makeRepo('inflight');
+  const calls = [];
+  const { follower, events } = makeFollower(dir, {
+    last: capture(dir, { withBundle: false }),
+    captureFn: () => new Promise((resolve) => calls.push(resolve)),
+  });
+
+  fs.writeFileSync(path.join(dir, 'a.md'), 'first change\n');
+  const snapA = capture(dir, { withBundle: false });
+  follower.ring();
+  await until(() => calls.length === 1);
+
+  // While the pair is in flight the repo moves again; the new doorbell's
+  // timer fires straight into the firing guard and is consumed.
+  fs.writeFileSync(path.join(dir, 'a.md'), 'second change\n');
+  follower.ring();
+  await sleep(SETTLED);
+
+  // The pair honestly agrees on the FIRST state — it was read before the
+  // second change — so it travels. Without pendingWake, the story ends here.
+  calls.shift()(snapA);
+  await until(() => calls.length === 2, 2_000);
+  calls.shift()(snapA);
+  await until(() => events.length === 1);
+  assert.equal(events[0].stateId, snapA.stateId);
+
+  // The follower must have re-armed itself for the swallowed doorbell.
+  const snapB = capture(dir, { withBundle: false });
+  await until(() => calls.length === 3, 2_000);
+  calls.shift()(snapB);
+  await until(() => calls.length === 4, 2_000);
+  calls.shift()(snapB);
+  await until(() => events.length === 2);
+  assert.equal(events[1].stateId, snapB.stateId);
+  follower.close();
+});
+
+test('close() during an in-flight capture pair is never spoken over', async () => {
+  const dir = makeRepo('close-race');
+  const calls = [];
+  const { follower, events } = makeFollower(dir, {
+    captureFn: () => new Promise((resolve) => calls.push(resolve)),
+  });
+  follower.start();
+  await until(() => calls.length === 1);
+
+  follower.close();
+  calls.shift()(capture(dir, { withBundle: false }));
+  await sleep(SETTLED);
+  assert.equal(events.length, 0, 'a closed follower must not announce a stale pair');
+  assert.equal(calls.length, 0, 'a closed follower must not keep capturing');
+});
+
+test('a command that begins mid-pair discards the stale pair and speaks once at its end', async () => {
+  const dir = makeRepo('owned-race');
+  let live = false; // stalled pair first, real captures after
+  const calls = [];
+  const captureFn = (repo) => (live ? capture(repo, { withBundle: false }) : new Promise((resolve) => calls.push(resolve)));
+  const { follower, events } = makeFollower(dir, { last: capture(dir, { withBundle: false }), captureFn });
+
+  fs.writeFileSync(path.join(dir, 'a.md'), 'mid\n');
+  const stale = capture(dir, { withBundle: false });
+  follower.ring();
+  await until(() => calls.length === 1);
+
+  follower.beginCommand(); // amalgm takes the boundary while the pair is in flight
+  live = true;
+  calls.shift()(stale);
+  await sleep(SETTLED);
+  assert.equal(events.length, 0, 'a pair resolving inside an owned command must stay silent');
+
+  fs.writeFileSync(path.join(dir, 'a.md'), 'final\n');
+  follower.endCommand();
+  await until(() => events.length === 1);
+  assert.equal(events[0].stateId, capture(dir, { withBundle: false }).stateId, 'the command end must speak the final truth');
+  follower.close();
+});
+
+test('the capture worker feeds a follower off the event loop with identical truth', async () => {
+  const dir = makeRepo('worker');
+  const pool = createCaptureWorker();
+  try {
+    const sync = capture(dir, { withBundle: false });
+    const off = await pool.capture(dir, { withBundle: false });
+    assert.equal(off.stateId, sync.stateId, 'worker capture must derive identical ids');
+    assert.ok(Buffer.isBuffer(off.checkpoint.stagedPatch), 'patch bytes must re-hydrate to Buffers');
+    assert.deepEqual(off.checkpoint.unstagedPatch, sync.checkpoint.unstagedPatch);
+
+    const { follower, events } = makeFollower(dir, {
+      last: sync,
+      captureFn: (repo) => pool.capture(repo, { withBundle: false }),
+    });
+    fs.writeFileSync(path.join(dir, 'a.md'), 'from the worker\n');
+    follower.ring();
+    await until(() => events.length === 1, 8_000);
+    assert.equal(events[0].type, 'checkpoint.changed');
+    assert.equal(events[0].stateId, capture(dir, { withBundle: false }).stateId);
+    follower.close();
+  } finally {
+    await pool.close();
+  }
+});
+
+// --- composed: real observer doorbells driving the follower ------------------------
+
+test('composed: a checkout through real doorbells is one card event, zero file events', async () => {
+  const dir = makeRepo('composed');
+  for (let i = 0; i < 40; i += 1) {
+    fs.writeFileSync(path.join(dir, `f${i}.md`), `main ${i}\n`);
+  }
+  git(dir, 'add', '-A');
+  git(dir, 'commit', '--quiet', '-m', 'main files');
+  git(dir, 'checkout', '--quiet', '-b', 'alt');
+  for (let i = 0; i < 40; i += 1) {
+    fs.writeFileSync(path.join(dir, `f${i}.md`), `alt ${i}\n`);
+  }
+  git(dir, 'add', '-A');
+  git(dir, 'commit', '--quiet', '-m', 'alt files');
+  git(dir, 'checkout', '--quiet', '-');
+
+  const observerEvents = [];
+  const observer = createObserver({
+    db: new Database(':memory:'),
+    emit: (event) => observerEvents.push(event),
+    settleMs: 25,
+  });
+  const root = observer.enrollRoot(dir);
+  assert.equal(root.kind, 'repo', 'a directory with a .git enrolls as repo territory');
+
+  const events = [];
+  const follower = createFollower({
+    repoPath: dir,
+    emit: (event) => events.push(event),
+    ...T,
+    last: capture(dir, { withBundle: false }),
+  });
+  observer.start(); // catch-up doorbell arrives below via the wire
+  const wire = setInterval(() => {
+    while (wire.cursor < observerEvents.length) {
+      if (observerEvents[wire.cursor].type === 'repo.changed') follower.ring();
+      wire.cursor += 1;
+    }
+  }, 5);
+  wire.cursor = 0;
+
+  git(dir, 'checkout', '--quiet', 'alt');
+  const spoke = await until(() => events.length > 0, 8_000);
+  await sleep(SETTLED + T.capMs);
+  clearInterval(wire);
+  observer.stop();
+  follower.close();
+
+  assert.ok(spoke, 'the checkout was never detected');
+  assert.equal(events.length, 1, 'a checkout must travel as exactly one event');
+  assert.equal(events[0].type, 'card.changed');
+  assert.equal(events[0].card.head.branch, 'alt');
+  assert.equal(observerEvents.filter((event) => event.type.startsWith('file.')).length, 0);
+});