amalgm 0.1.262 → 0.1.263

package/runtime/scripts/amalgm-mcp/repocard/follow.js

@@ -95,12 +95,24 @@ function createFollower(options) {
     last = null,    // resume seed: { cardId, checkpointId }
     // May return a promise (e.g. a capture worker): the follower awaits it,
     // and any doorbell that lands mid-pair re-arms a retry (`pendingWake`).
-    captureFn = (repo) => capture(repo, { withBundle: false }),
+    // Called with { suspects }: the worktree paths rung since the last
+    // settled state, or null when everything is suspect.
+    captureFn = (repo, { suspects } = {}) => capture(repo, { withBundle: false, suspects }),
   } = options;
   if (!repoPath) throw new Error('createFollower requires { repoPath }');
   if (typeof emit !== 'function') throw new Error('createFollower requires { emit }');
 
   let known = last ? { cardId: last.cardId, checkpointId: last.checkpointId } : null;
+  // The warm-checkpoint scope: which worktree paths the doorbell has named
+  // since the last settled state. Each entry remembers the GENERATION of
+  // the ring that named it, so a path rung again mid-pair keeps its
+  // suspicion when the pair's success consumes the older hints. A nameless
+  // ring — or any entrance that may follow missed doorbells (birth, flush,
+  // a command ending) — makes EVERYTHING suspect until a pair settles.
+  const SCOPE_CAP = 512;
+  const scope = new Map(); // repo-relative path -> generation
+  let scopeGen = 0;
+  let scopeAllGen = 0; // >0: everything is suspect (set at birth, flush, command end, nameless ring)
   let owned = 0; // depth of amalgm-owned commands in flight
   let blocked = null; // lock name while the last capture attempt met a held lock
   let blockedPath = null;
@@ -210,12 +222,15 @@ function createFollower(options) {
 
     // The torn-read guard: two consecutive reads must agree before a state
     // may travel — a repo mid-mutation cannot produce the same ids twice.
+    // Both halves of the pair read the SAME scope: the paths rung so far.
+    const genNow = scopeGen;
+    const suspects = scopeAllGen > 0 ? null : [...scope.keys()];
     let first;
     let second;
     try {
-      first = await captureFn(repoPath);
+      first = await captureFn(repoPath, { suspects });
       if (closed || owned > 0) return; // the pair is stale before it finished
-      second = first && !first.busy ? await captureFn(repoPath) : null;
+      second = first && !first.busy ? await captureFn(repoPath, { suspects }) : null;
     } catch (error) {
       if (closed) return;
       // A read tripping over a mid-flight writer (a file vanishing between
@@ -234,11 +249,34 @@ function createFollower(options) {
       retry(settleMs);
       return;
     }
-    if (!speak(second)) retry(capMs); // consumer failure: patient, loud, never lost
+    if (!speak(second)) {
+      retry(capMs); // consumer failure: patient, loud, never lost
+      return;
+    }
+    // The settled pair proved the ground the scope described: hints from
+    // BEFORE the pair began are consumed; anything rung mid-pair keeps its
+    // newer generation and stays suspect for the pendingWake retry.
+    if (scopeAllGen > 0 && scopeAllGen <= genNow) scopeAllGen = 0;
+    for (const [rel, gen] of scope) {
+      if (gen <= genNow) scope.delete(rel);
+    }
   }
 
-  function ring() {
+  function ring(hint) {
     if (closed || owned > 0) return; // the command's end is the boundary
+    // Accumulate the warm-checkpoint scope. A .git-area hint never touches
+    // untracked ground, so it schedules a capture without widening the
+    // scope; a nameless hint (or an overflowing scope) suspects everything.
+    scopeGen += 1;
+    if (hint === null || hint === undefined) {
+      scopeAllGen = scopeGen;
+    } else if (hint !== '.git' && !hint.startsWith('.git/')) {
+      scope.set(hint, scopeGen);
+      if (scope.size > SCOPE_CAP) {
+        scope.clear();
+        scopeAllGen = scopeGen;
+      }
+    }
     if (settleTimer) clearTimeout(settleTimer);
     settleTimer = setTimeout(() => {
       settleTimer = null;
@@ -262,7 +300,13 @@ function createFollower(options) {
 
   function endCommand() {
     owned = Math.max(0, owned - 1);
-    if (owned === 0 && !closed) fire();
+    // Rings were suppressed while the command ran: its writes are nobody's
+    // hints, so the capture at the boundary suspects everything.
+    if (owned === 0 && !closed) {
+      scopeGen += 1;
+      scopeAllGen = scopeGen;
+      fire();
+    }
   }
 
   /** Run an amalgm-owned command: no captures while it runs, one at its end. */
@@ -284,10 +328,21 @@ function createFollower(options) {
 
   return {
     ring,
-    /** Birth: capture once, immediately. With a seeded `last`, an unchanged repo is silence. */
-    start: () => fire(),
-    /** Consumer-requested capture — the "scanNow" of this layer. */
-    flush: () => fire(),
+    /** Birth: capture once, immediately, suspecting everything — rings
+     * before birth were nobody's. With a seeded `last`, an unchanged
+     * repo is silence. */
+    start: () => {
+      scopeGen += 1;
+      scopeAllGen = scopeGen;
+      return fire();
+    },
+    /** Consumer-requested capture — the "scanNow" of this layer. Its whole
+     * purpose is catching a LOST doorbell, so it never trusts the scope. */
+    flush: () => {
+      scopeGen += 1;
+      scopeAllGen = scopeGen;
+      return fire();
+    },
     beginCommand,
     endCommand,
     command,

package/runtime/scripts/amalgm-mcp/tests/entity-cloud.test.js

@@ -371,3 +371,93 @@ test('add follows in-order mirrored mutations and refuses after a version gap un
     fs.rmSync(targetDir, { recursive: true, force: true });
   }
 });
+
+// --- the repo travel law -----------------------------------------------------
+
+function activeCloud({ content = { has: () => true, ensureUpload: () => {} }, repoTransportFor = null } = {}) {
+  const db = new Database(':memory:');
+  let registry = null;
+  const cloud = createEntityCloud({
+    db,
+    userId: 'user-1',
+    deviceId: 'device-1',
+    content,
+    repoTransportFor,
+    recordAt: (uuid) => {
+      try { return registry.syncRecord(uuid); } catch { return null; }
+    },
+  });
+  registry = createRegistry({ db, ephemeral: true, emit: () => {}, journal: cloud.journal });
+  const root = registry.enrollRoot({ type: 'workspace', name: 'ground' });
+  const bootstrap = cloud.bootstrap(registry.syncRecords());
+  cloud.install({
+    registry,
+    resourceId: bootstrap.resourceId,
+    authorityEpoch: 1,
+    headVersion: 0,
+    snapshotBase64: bootstrap.snapshotBase64,
+    snapshotChecksum: bootstrap.snapshotChecksum,
+  });
+  return { db, cloud, registry, root, resourceId: bootstrap.resourceId };
+}
+
+test('a record enclosed by a repository never journals its own cloud mutation — the repo state parcel is the carrier', () => {
+  const transportHead = 'a'.repeat(64);
+  const { db, registry, root, resourceId } = activeCloud({
+    repoTransportFor: () => transportHead,
+  });
+
+  const repo = registry.create({ type: 'repo.git', parentUUID: root.uuid, name: 'engine', payloadVersion: 'state-1' });
+  assert.equal(db.prepare('SELECT COUNT(*) AS count FROM entity_cloud_mutations').get().count, 1,
+    'the repository record itself travels');
+
+  const folder = registry.create({ type: 'folder', parentUUID: repo.uuid, name: 'src' });
+  registry.create({ type: 'file.text', parentUUID: folder.uuid, name: 'index.js', payloadVersion: 'b'.repeat(64) });
+  registry.create({ type: 'link', parentUUID: repo.uuid, name: 'current', payloadVersion: 'src' });
+  assert.equal(db.prepare('SELECT COUNT(*) AS count FROM entity_cloud_mutations').get().count, 1,
+    'worktree children mail no postcards: a register or a rebase is one parcel on the repo entity');
+
+  const catalog = db.prepare('SELECT entity_uuid FROM entity_cloud_catalog WHERE resource_id = ? ORDER BY entity_uuid').all(resourceId)
+    .map((row) => row.entity_uuid).sort();
+  assert.deepEqual(catalog, [root.uuid, repo.uuid].sort(),
+    'the cloud catalog holds the traveling graph only — no rows for repo-enclosed children');
+
+  // A later Detect correction on the child (type/payload) stays local too.
+  const inner = registry.activeAt(folder.uuid, 'index.js');
+  registry.attest(inner.uuid, { type: 'file.binary', payloadVersion: 'c'.repeat(64) });
+  assert.equal(db.prepare('SELECT COUNT(*) AS count FROM entity_cloud_mutations').get().count, 1,
+    'the census drip is dead: child corrections never reach the outbox');
+});
+
+test('an atomic snapshot replacement excludes repo-enclosed records and never demands their bytes', () => {
+  const transportHead = 'd'.repeat(64);
+  const childHead = 'e'.repeat(64);
+  const { db, cloud, registry, root, resourceId } = activeCloud({
+    repoTransportFor: () => transportHead,
+    content: {
+      ensureUpload: () => {},
+      has: ({ contentHash }) => {
+        assert.notEqual(contentHash, childHead, 'an enclosed child head must never be demanded as separate cloud cargo');
+        return true;
+      },
+    },
+  });
+
+  registry.withoutJournal(() => {
+    const repo = registry.create({ type: 'repo.git', parentUUID: root.uuid, name: 'engine', payloadVersion: 'state-1' });
+    registry.create({ type: 'file.text', parentUUID: repo.uuid, name: 'inner.md', payloadVersion: childHead });
+    registry.create({ type: 'file.text', parentUUID: root.uuid, name: 'loose.md', payloadVersion: 'f'.repeat(64) });
+  });
+
+  cloud.replaceSnapshot(registry.syncRecords());
+  const operation = JSON.parse(db.prepare(`
+    SELECT operation_json FROM entity_cloud_mutations
+    WHERE resource_id = ? ORDER BY sequence DESC LIMIT 1
+  `).get(resourceId).operation_json);
+  assert.equal(operation.kind, 'entity.snapshot.replace');
+  const types = operation.snapshot.records.map((record) => record.type).sort();
+  assert.deepEqual(types, ['file.text', 'repo.git', 'workspace'],
+    'the atomic graph carries the workspace, the loose file, and ONE record per repository');
+  assert.ok(!operation.snapshot.records.some((record) => record.name === 'inner.md'),
+    'repo children stay out of the published graph');
+});

package/runtime/scripts/amalgm-mcp/tests/entity-materialization.test.js

@@ -461,3 +461,239 @@ test('add recreates an actual Git repository from verified Repocard cargo, then
     fs.rmSync(rootDir, { recursive: true, force: true });
   }
 });
+
+test('the repo travel law end to end: one traveling record, child UUIDs ride the transport map, and add binds the exact same identities', async () => {
+  const rootDir = fs.mkdtempSync(path.join(os.tmpdir(), 'amalgm-repo-travel-law-'));
+  const sourceState = path.join(rootDir, 'source-state');
+  const targetState = path.join(rootDir, 'target-state');
+  const sourceRepo = path.join(rootDir, 'engine');
+  const targetParent = path.join(rootDir, 'checkout');
+  fs.mkdirSync(path.join(sourceRepo, 'src'), { recursive: true });
+  fs.mkdirSync(targetParent, { recursive: true });
+  git(sourceRepo, ['init', '--quiet']);
+  git(sourceRepo, ['config', 'user.email', 'test@example.com']);
+  git(sourceRepo, ['config', 'user.name', 'Amalgm Test']);
+  fs.writeFileSync(path.join(sourceRepo, 'tracked.md'), '# committed\n');
+  fs.writeFileSync(path.join(sourceRepo, 'src', 'index.js'), 'module.exports = 1;\n');
+  git(sourceRepo, ['add', '.']);
+  git(sourceRepo, ['commit', '--quiet', '-m', 'initial']);
+  fs.writeFileSync(path.join(sourceRepo, 'untracked.txt'), 'not committed\n');
+
+  const { unpack } = require('../registration/repo-states');
+  const source = createRegistrationService({
+    dir: sourceState, homeDir: path.join(rootDir, 'source-home'),
+    cloudUserId: 'user-1', cloudDeviceId: 'source-device',
+  });
+  const target = createRegistrationService({
+    dir: targetState, homeDir: path.join(rootDir, 'target-home'),
+    cloudUserId: 'user-1', cloudDeviceId: 'target-device',
+  });
+  const mutationOps = (stateDir) => {
+    const handle = new Database(path.join(stateDir, 'identity.db'), { readonly: true });
+    try {
+      return handle.prepare('SELECT operation_json FROM entity_cloud_mutations ORDER BY sequence').all()
+        .map((row) => JSON.parse(row.operation_json));
+    } finally {
+      handle.close();
+    }
+  };
+  try {
+    const bootstrap = source.entityCloud.bootstrap(source.registration.registry.syncRecords());
+    source.entityCloud.install({
+      registry: source.registration.registry, resourceId: bootstrap.resourceId,
+      authorityEpoch: 1, headVersion: 0, snapshotBase64: bootstrap.snapshotBase64,
+      snapshotChecksum: bootstrap.snapshotChecksum,
+    });
+    const registered = await source.register(sourceRepo);
+
+    // ONE traveling record: the repository. No child postcards, ever.
+    const ops = mutationOps(sourceState);
+    assert.equal(ops.length, 1, `a repository register is one cloud mutation, got ${JSON.stringify(ops.map((op) => op.record?.name))}`);
+    assert.equal(ops[0].kind, 'entity.upsert');
+    assert.equal(ops[0].record.uuid, registered.record.uuid);
+    assert.ok(ops[0].record.transportVersion, 'the one record names its Repocard transport');
+
+    // The transport parcel carries the worktree identity map, and the map
+    // names the exact UUIDs the local registry minted.
+    const transport = unpack(source.entityContent.bytes({ contentHash: ops[0].record.transportVersion }).toString('utf8'));
+    assert.ok(Array.isArray(transport.identity), 'the transport carries the identity map');
+    const mapByPath = new Map(transport.identity.map((entry) => [entry.path, entry]));
+    const localByPath = new Map();
+    const walkLocal = (parentUuid, base) => {
+      for (const child of source.registration.registry.children(parentUuid)) {
+        if (child.status !== 'active') continue;
+        const childPath = base ? `${base}/${child.name}` : child.name;
+        localByPath.set(childPath, child.uuid);
+        walkLocal(child.uuid, childPath);
+      }
+    };
+    walkLocal(registered.record.uuid, '');
+    for (const relPath of ['tracked.md', 'src', 'src/index.js', 'untracked.txt']) {
+      assert.equal(mapByPath.get(relPath)?.uuid, localByPath.get(relPath),
+        `the transport map and the local registry agree on ${relPath}`);
+    }
+
+    // The gateway would fold that one mutation into the active head: the
+    // authoritative snapshot contains exactly the traveling graph.
+    const snapshot = snapshotFromRecords([ops[0].record]);
+    const snapshotBytes = Buffer.from(JSON.stringify(snapshot), 'utf8');
+    target.entityCloud.install({
+      registry: target.registration.registry, resourceId: bootstrap.resourceId,
+      authorityEpoch: 1, headVersion: 1, snapshotBase64: snapshotBytes.toString('base64'),
+      snapshotChecksum: sha256(snapshotBytes),
+    });
+    const uploaded = [];
+    while (true) {
+      const part = source.entityCloud.claimContent();
+      if (!part) break;
+      uploaded.push(part);
+      source.entityCloud.acknowledgeContent({
+        resourceId: bootstrap.resourceId, contentHash: part.contentHash,
+        kind: part.kind, partIndex: part.partIndex,
+      });
+    }
+    for (const part of [...uploaded.filter((entry) => entry.kind === 'manifest'), ...uploaded.filter((entry) => entry.kind === 'chunk')]) {
+      target.receiveCloudContent({
+        resourceId: bootstrap.resourceId, contentHash: part.contentHash, kind: part.kind,
+        partIndex: part.kind === 'manifest' ? 0 : part.partIndex,
+        sha256: part.sha256, dataBase64: part.dataBase64,
+      });
+    }
+    const job = await target.add({ uuid: registered.record.uuid, targetPath: targetParent });
+    assert.equal(job.state, 'complete', job.error);
+    const destination = path.join(targetParent, 'engine');
+    assert.equal(verify(destination, source.registration.repoState(registered.record.uuid)).ok, true);
+
+    // The receiving machine wears the SAME child UUIDs — bound from the
+    // transport map, never minted as competitors.
+    for (const [relPath, uuid] of localByPath) {
+      const bound = target.registration.registry.syncRecord(uuid);
+      assert.equal(bound?.name, path.basename(relPath), `${relPath} keeps its permanent UUID across machines`);
+    }
+    assert.equal(mutationOps(targetState).length, 0, 'the add binding echoes nothing upstream');
+
+    // A live edit settles as the NEXT parcel: still one mutation on the
+    // repo entity, still no child postcards, map still riding along.
+    await new Promise((resolve) => setTimeout(resolve, 250));
+    fs.writeFileSync(path.join(sourceRepo, 'later.md'), 'a later change\n');
+    const deadline = Date.now() + 30_000;
+    while (mutationOps(sourceState).length < 2) {
+      if (Date.now() > deadline) assert.fail('timed out waiting for the settled repo parcel');
+      await new Promise((resolve) => setTimeout(resolve, 50));
+    }
+    await new Promise((resolve) => setTimeout(resolve, 500));
+    const settledOps = mutationOps(sourceState);
+    assert.ok(settledOps.every((op) => op.record?.uuid === registered.record.uuid),
+      `every traveling mutation is the repo entity itself, got ${JSON.stringify(settledOps.map((op) => op.record?.name))}`);
+    const settled = settledOps[settledOps.length - 1];
+    const settledTransport = unpack(source.entityContent.bytes({ contentHash: settled.record.transportVersion }).toString('utf8'));
+    assert.equal(
+      new Map(settledTransport.identity.map((entry) => [entry.path, entry])).get('tracked.md')?.uuid,
+      localByPath.get('tracked.md'),
+      'a settled parcel repacks the registry-held identity map with the same permanent UUIDs',
+    );
+  } finally {
+    source.close();
+    target.close();
+    fs.rmSync(rootDir, { recursive: true, force: true });
+  }
+});
+
+test('a workspace containing a repository travels as its loose records plus ONE repo record, and add binds repo children from the map', async () => {
+  const rootDir = fs.mkdtempSync(path.join(os.tmpdir(), 'amalgm-workspace-repo-travel-'));
+  const sourceState = path.join(rootDir, 'source-state');
+  const targetState = path.join(rootDir, 'target-state');
+  const workspace = path.join(rootDir, 'ambient');
+  const repo = path.join(workspace, 'engine');
+  const targetParent = path.join(rootDir, 'checkout');
+  fs.mkdirSync(repo, { recursive: true });
+  fs.mkdirSync(targetParent, { recursive: true });
+  fs.writeFileSync(path.join(workspace, 'notes.md'), '# loose ground\n');
+  git(repo, ['init', '--quiet']);
+  git(repo, ['config', 'user.email', 'test@example.com']);
+  git(repo, ['config', 'user.name', 'Amalgm Test']);
+  fs.writeFileSync(path.join(repo, 'tracked.md'), '# committed\n');
+  git(repo, ['add', '.']);
+  git(repo, ['commit', '--quiet', '-m', 'initial']);
+
+  const { unpack } = require('../registration/repo-states');
+  const source = createRegistrationService({
+    dir: sourceState, homeDir: path.join(rootDir, 'source-home'),
+    cloudUserId: 'user-1', cloudDeviceId: 'source-device',
+  });
+  const target = createRegistrationService({
+    dir: targetState, homeDir: path.join(rootDir, 'target-home'),
+    cloudUserId: 'user-1', cloudDeviceId: 'target-device',
+  });
+  try {
+    const bootstrap = source.entityCloud.bootstrap(source.registration.registry.syncRecords());
+    source.entityCloud.install({
+      registry: source.registration.registry, resourceId: bootstrap.resourceId,
+      authorityEpoch: 1, headVersion: 0, snapshotBase64: bootstrap.snapshotBase64,
+      snapshotChecksum: bootstrap.snapshotChecksum,
+    });
+    const registered = await source.register(workspace);
+
+    const sourceDb = new Database(path.join(sourceState, 'identity.db'), { readonly: true });
+    const ops = sourceDb.prepare('SELECT operation_json FROM entity_cloud_mutations ORDER BY sequence').all()
+      .map((row) => JSON.parse(row.operation_json));
+    sourceDb.close();
+    const traveled = ops.map((op) => op.record);
+    // A loose file lawfully journals twice (structural create, then its
+    // first Detect attest); what matters is WHICH entities travel at all.
+    assert.deepEqual(
+      [...new Set(traveled.map((record) => record.name))].sort(),
+      ['ambient', 'engine', 'notes.md'],
+      'the workspace, its loose file, and ONE record per repository travel — repo children do not',
+    );
+    const repoRecord = traveled.find((record) => record.type === 'repo.git');
+    const trackedUuid = (() => {
+      const children = source.registration.registry.children(repoRecord.uuid);
+      return children.find((child) => child.name === 'tracked.md').uuid;
+    })();
+
+    // The gateway's fold keeps the LAST record per UUID; mirror that here.
+    const snapshot = snapshotFromRecords([...new Map(traveled.map((record) => [record.uuid, record])).values()]);
+    const snapshotBytes = Buffer.from(JSON.stringify(snapshot), 'utf8');
+    target.entityCloud.install({
+      registry: target.registration.registry, resourceId: bootstrap.resourceId,
+      authorityEpoch: 1, headVersion: 3, snapshotBase64: snapshotBytes.toString('base64'),
+      snapshotChecksum: sha256(snapshotBytes),
+    });
+    const uploaded = [];
+    while (true) {
+      const part = source.entityCloud.claimContent();
+      if (!part) break;
+      uploaded.push(part);
+      source.entityCloud.acknowledgeContent({
+        resourceId: bootstrap.resourceId, contentHash: part.contentHash,
+        kind: part.kind, partIndex: part.partIndex,
+      });
+    }
+    for (const part of [...uploaded.filter((entry) => entry.kind === 'manifest'), ...uploaded.filter((entry) => entry.kind === 'chunk')]) {
+      target.receiveCloudContent({
+        resourceId: bootstrap.resourceId, contentHash: part.contentHash, kind: part.kind,
+        partIndex: part.kind === 'manifest' ? 0 : part.partIndex,
+        sha256: part.sha256, dataBase64: part.dataBase64,
+      });
+    }
+
+    const job = await target.add({ uuid: registered.record.uuid, targetPath: targetParent });
+    assert.equal(job.state, 'complete', job.error);
+    const destination = path.join(targetParent, 'ambient');
+    assert.equal(fs.readFileSync(path.join(destination, 'engine', 'tracked.md'), 'utf8'), '# committed\n');
+    assert.equal(target.registration.registry.syncRecord(trackedUuid)?.name, 'tracked.md',
+      'a file inside the nested repository keeps its permanent UUID across machines via the transport map');
+    const targetDb = new Database(path.join(targetState, 'identity.db'), { readonly: true });
+    try {
+      assert.equal(targetDb.prepare('SELECT COUNT(*) AS count FROM entity_cloud_mutations').get().count, 0,
+        'binding the workspace echoes nothing upstream');
+    } finally {
+      targetDb.close();
+    }
+  } finally {
+    source.close();
+    target.close();
+    fs.rmSync(rootDir, { recursive: true, force: true });
+  }
+});

package/runtime/scripts/amalgm-mcp/tests/observer.coverage.test.js

@@ -0,0 +1,197 @@
+'use strict';
+
+/**
+ * The coverage law under exam: one OS watcher per outermost tree.
+ *
+ * Claims, each proven against a REAL fs.watch or the deterministic kit:
+ * 1. A nested repo opens ZERO watchers of its own — the encloser's
+ *    doorbell is its doorbell, and dings still reach its follower raw.
+ * 2. Adoption demotes: a self-owned root that becomes enclosed closes
+ *    its handle. Departure promotes: losing the encloser reopens it.
+ * 3. Held doorbells (watchNow) prove the watcher without concluding
+ *    anything; start() releases them into the ordinary catch-up.
+ * 4. An owner's death reconciles the whole covered family, not just
+ *    the owner.
+ * 5. status() tells the truth for covered roots: their health IS the
+ *    owner's health.
+ */
+
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const path = require('path');
+const test = require('node:test');
+
+const {
+  cleanup, eventsOf, fakeWatchKit, makeDir, makeObserver, nudgeUntil, realRepo,
+} = require('./observer.rig');
+
+test.after(() => cleanup());
+
+/** Watcher handles the kit has open, by watched path. */
+function kitWithBells() {
+  const kit = fakeWatchKit();
+  const open = new Set();
+  const inner = kit.watch;
+  kit.watch = (rootPath, onDirty, onDead) => {
+    open.add(rootPath);
+    const handle = inner(rootPath, onDirty, onDead);
+    const close = handle.close;
+    handle.close = () => { open.delete(rootPath); close(); };
+    return handle;
+  };
+  kit.open = open;
+  return kit;
+}
+
+test('a nested repo owns no watcher: the encloser holds the only handle', () => {
+  const dir = makeDir('coverage-dedup');
+  const repo = path.join(dir, 'project');
+  fs.mkdirSync(repo);
+  fs.mkdirSync(path.join(repo, '.git'));
+  fs.writeFileSync(path.join(repo, '.git', 'HEAD'), 'ref: refs/heads/main\n');
+  fs.writeFileSync(path.join(repo, 'app.js'), 'code');
+
+  const kit = kitWithBells();
+  const { observer } = makeObserver({ watch: kit.watch });
+  observer.enrollRoot(dir);
+  observer.start();
+
+  const roots = observer.listRoots();
+  assert.equal(roots.length, 2, 'workspace and nested repo are both roots');
+  assert.deepEqual([...kit.open], [dir],
+    'exactly ONE recursive handle exists, on the outermost tree');
+
+  const repoRoot = roots.find((root) => root.kind === 'repo');
+  const covered = observer.status().find((row) => row.rootId === repoRoot.rootId);
+  assert.equal(covered.coveredBy, roots.find((root) => root.kind === 'files').rootId);
+  assert.ok(covered.watching, 'covered ground reports watching through its owner');
+  observer.stop();
+});
+
+test('a covered repo still hears raw dings: the encloser forwards, rebased', () => {
+  const dir = makeDir('coverage-forward');
+  const repo = path.join(dir, 'project');
+  fs.mkdirSync(repo);
+  fs.mkdirSync(path.join(repo, '.git'));
+  fs.writeFileSync(path.join(repo, '.git', 'HEAD'), 'ref: refs/heads/main\n');
+  fs.writeFileSync(path.join(repo, 'app.js'), 'code');
+
+  const kit = kitWithBells();
+  const { observer, events } = makeObserver({ watch: kit.watch });
+  observer.enrollRoot(dir);
+  observer.start();
+  const repoRoot = observer.listRoots().find((root) => root.kind === 'repo');
+  const mark = events.length;
+
+  // The ding lands on the WORKSPACE watcher, named from the workspace.
+  kit.ring(dir, 'project/app.js');
+  const spoken = events.slice(mark).filter((event) => event.type === 'repo.changed');
+  assert.deepEqual(spoken, [{
+    type: 'repo.changed', rootId: repoRoot.rootId, areas: ['worktree'], hint: 'app.js',
+  }], 'one raw repo doorbell, instantly, rebased to the repo\'s own ground');
+
+  // A git-area ding forwards with its area intact.
+  kit.ring(dir, 'project/.git/HEAD');
+  const gitSpoken = events.filter((event) => event.type === 'repo.changed'
+    && event.areas.length === 1 && event.areas[0] === 'git');
+  assert.equal(gitSpoken.length, 1, 'the .git ding forwards as git-area news');
+  observer.stop();
+});
+
+test('adoption demotes and departure promotes: handles follow the outermost tree', () => {
+  const parent = makeDir('coverage-parent');
+  const repoDir = path.join(parent, 'standalone');
+  fs.mkdirSync(repoDir);
+  fs.mkdirSync(path.join(repoDir, '.git'));
+  fs.writeFileSync(path.join(repoDir, '.git', 'HEAD'), 'ref: refs/heads/main\n');
+  fs.writeFileSync(path.join(repoDir, 'main.js'), 'code');
+
+  const kit = kitWithBells();
+  const { observer } = makeObserver({ watch: kit.watch });
+  observer.enrollRoot(repoDir);
+  observer.start();
+  assert.deepEqual([...kit.open], [repoDir], 'standalone: the repo owns its handle');
+
+  // A workspace registered ABOVE it adopts the coverage.
+  observer.enrollRoot(parent);
+  assert.deepEqual([...kit.open], [parent],
+    'enclosed by watched ground: the repo handle closes, the workspace handle is the doorbell');
+
+  // The workspace leaving promotes the repo back to self-owned.
+  const workspaceRoot = observer.listRoots().find((root) => root.path === parent);
+  observer.removeRoot(workspaceRoot.rootId);
+  assert.deepEqual([...kit.open], [repoDir], 'departure promotes: the repo reopens its own handle');
+  observer.stop();
+});
+
+test('watchNow proves the doorbell and holds it; start() releases into catch-up', () => {
+  const dir = makeDir('coverage-held');
+  fs.writeFileSync(path.join(dir, 'note.md'), 'v1');
+  const kit = kitWithBells();
+  const { observer, events } = makeObserver({ watch: kit.watch });
+  const root = observer.enrollRoot(dir, { scan: false, watch: false });
+
+  const health = observer.watchNow(root.rootId);
+  assert.ok(health.watching, 'the watcher is born and provable before anything commits');
+  assert.deepEqual([...kit.open], [dir], 'the handle exists during the hold');
+
+  kit.ring(dir, 'note.md');
+  assert.deepEqual(events, [], 'held dings conclude nothing — no scan, no event');
+
+  observer.start(root.rootId);
+  assert.ok(eventsOf(events, 'file.created').some((event) => event.path === 'note.md'),
+    'start() releases the hold and its scan is the catch-up');
+  observer.stop();
+});
+
+test('an owner death reconciles the covered family', async () => {
+  const dir = makeDir('coverage-death');
+  const repo = path.join(dir, 'project');
+  fs.mkdirSync(repo);
+  fs.mkdirSync(path.join(repo, '.git'));
+  fs.writeFileSync(path.join(repo, '.git', 'HEAD'), 'ref: refs/heads/main\n');
+
+  let dieNow = null;
+  const kit = kitWithBells();
+  const inner = kit.watch;
+  kit.watch = (rootPath, onDirty, onDead) => {
+    const handle = inner(rootPath, onDirty, onDead);
+    if (rootPath === dir) dieNow = () => { handle.degraded = true; onDead?.(); };
+    return handle;
+  };
+  const { observer, events } = makeObserver({ watch: kit.watch });
+  observer.enrollRoot(dir);
+  observer.start();
+  const repoRoot = observer.listRoots().find((root) => root.kind === 'repo');
+  const mark = events.length;
+
+  dieNow();
+  const caughtUp = events.slice(mark).filter((event) => event.type === 'repo.changed'
+    && event.rootId === repoRoot.rootId && event.hint === null);
+  assert.equal(caughtUp.length, 1,
+    'the revived owner reconciles the covered repo too: one unconditional catch-up doorbell');
+  observer.stop();
+});
+
+test('live ground truth: a real nested repo change reaches its follower through the shared watcher', async () => {
+  const dir = makeDir('coverage-live');
+  const repo = path.join(dir, 'project');
+  fs.mkdirSync(repo);
+  fs.mkdirSync(path.join(repo, '.git'));
+  fs.writeFileSync(path.join(repo, '.git', 'HEAD'), 'ref: refs/heads/main\n');
+  fs.writeFileSync(path.join(repo, 'app.js'), 'v1');
+
+  const { observer, events } = makeObserver(); // REAL fs.watch
+  observer.enrollRoot(dir);
+  observer.start();
+  const repoRoot = observer.listRoots().find((root) => root.kind === 'repo');
+  const mark = events.length;
+
+  const arrived = await nudgeUntil(
+    () => fs.writeFileSync(path.join(repo, 'app.js'), 'v2'),
+    () => events.slice(mark).some((event) => event.type === 'repo.changed'
+      && event.rootId === repoRoot.rootId),
+  );
+  assert.ok(arrived, 'a real OS event on covered ground reaches the repo through the one shared watcher');
+  observer.stop();
+});