amalgm 0.1.262 → 0.1.264

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

@@ -369,6 +369,11 @@ test('add recreates an actual Git repository from verified Repocard cargo, then
       snapshotChecksum: sha256(snapshotBytes),
     });
 
+    // This is the real user destination: a repo lands below an already-live
+    // local workspaces-like container.  Physical containment supplies watcher
+    // coverage only; the cloud repo must retain its parentless root identity.
+    target.registration.add(targetParent, { suppressJournal: true });
+
     const planned = source.entityCloud.contentHeads(records);
     assert.deepEqual(
       planned.map(({ contentHash }) => contentHash),
@@ -406,6 +411,8 @@ test('add recreates an actual Git repository from verified Repocard cargo, then
     const expected = source.registration.repoState(registered.record.uuid);
     assert.equal(verify(destination, expected).ok, true, 'the downloaded Git state reproduces its Card + Checkpoint IDs');
     assert.equal(target.registration.registry.syncRecord(registered.record.uuid).uuid, registered.record.uuid);
+    assert.equal(target.registration.registry.syncRecord(registered.record.uuid).parentUUID, null,
+      'a repo materialized beneath an existing local workspace keeps its cloud root position');
     assert.equal(target.observer.status().find((entry) => entry.path === fs.realpathSync(destination))?.watching, true,
       'the same successful add starts the destination repository watcher');
 
@@ -461,3 +468,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();
+});

package/runtime/scripts/amalgm-mcp/tests/registration.service.test.js

@@ -724,6 +724,45 @@ test('a nested repository has its own baseline and watcher, while its tree remai
   assert.equal(tree.registry.activeAt(src.uuid, 'live.js').type, 'file.text');
 });
 
+test('a repo discovered inside watched workspace ground stays unregistered until explicit register gives it one complete repo root', async () => {
+  const service = makeService('workspace-repo-admission');
+  const workspace = makeGround('workspace-repo-admission');
+  const { record: workspaceRecord } = await service.register(workspace);
+  const repo = path.join(workspace, 't3code');
+  fs.mkdirSync(repo);
+  execFileSync('git', ['init', '-q'], { cwd: repo });
+  fs.writeFileSync(path.join(repo, 'readme.md'), '# T3\n');
+
+  // This is the production ordering that convicted the live Fly run: the
+  // outer workspace watcher discovers a newly cloned repository first.
+  const workspaceRoot = service.observer.listRoots().find((root) => root.path === workspace);
+  service.observer.scanNow(workspaceRoot.rootId);
+  await new Promise((resolve) => setImmediate(resolve));
+  service.registration.flushIfDirty();
+
+  const territory = service.observer.listRoots().find((root) => root.path === repo);
+  assert.equal(territory?.kind, 'repo', 'Watch knows the local Git territory');
+  assert.notEqual(
+    service.registration.tree(workspace).registry.activeAt(workspaceRecord.uuid, 't3code')?.type,
+    'repo.git',
+    'generic filesystem evidence never mints a half-repository with no Card + Checkpoint',
+  );
+
+  const { record } = await service.register(repo);
+  assert.equal(record.type, 'repo.git');
+  assert.equal(record.parentUUID, null,
+    'selected repo is its own cloud tree even though its local address is inside workspaces');
+  assert.equal(service.registration.tree(repo).root().uuid, record.uuid,
+    'the nested observer root now witnesses that selected tree');
+  assert.ok(service.registration.repoState(record.uuid)?.stateId,
+    'its identity and initial Card + Checkpoint were committed together');
+  assert.equal(
+    service.observer.status().some((row) => row.path === repo && row.watching && !row.degraded),
+    true,
+    'the selected repo is live after the atomic registration',
+  );
+});
+
 test('a reopened repo watcher resumes from the saved Card + Checkpoint baseline', async () => {
   const service = makeService('repo-reopen');
   const repo = makeGround('repo-reopen');
@@ -770,15 +809,21 @@ test('register registers every entity before it starts Watch', async () => {
     identity.close();
     assert.ok(nested, 'the folder already has a durable identity');
     assert.ok(file, 'so does the file within it');
-    assert.equal(service.observer.status()[0].watching, false,
-      'the observer has not begun watching while registration is in progress');
+    // Watcher FIRST, conclusions LAST: by the time identity commits, the
+    // doorbell is already alive (it was proven before the walk began) —
+    // but HELD, so nothing has been observed or concluded yet. start()
+    // releasing the hold is the first moment Watch may speak.
+    assert.equal(service.observer.status()[0].watching, true,
+      'the doorbell was born and proven before identity committed');
+    assert.equal(service.observer.filesForRoot(rootId).length, 0,
+      'and held: no observation concluded while registration was in progress');
     checked = true;
     return start(rootId);
   };
 
   const { rootPath } = await service.register(ground);
   assert.equal(rootPath, ground);
-  assert.equal(checked, true, 'Watch begins only after the structural walk commits');
+  assert.equal(checked, true, 'the held doorbell releases only after the structural walk commits');
 });
 
 test('register never reserves or mutates a user filename for watching', async () => {

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

@@ -911,13 +911,13 @@ test('add is one operation: a bare file registers, covered ground returns its tr
     'ground that would swallow a registered root refuses loudly');
 });
 
-test('add never claims success when a required watcher cannot open', () => {
+test('add refuses before identity commits when a required watcher cannot be born', () => {
   const dir = makeDir('degraded-add');
   const observer = createObserver({
     db: new Database(':memory:'),
     emit: () => {},
     shouldEnroll: () => true,
-    watch: () => ({ degraded: true, close: () => {} }),
+    watch: () => ({ degraded: true, reason: 'ENOSPC', close: () => {} }),
   });
   const identityDb = new Database(':memory:');
   const registration = createRegistration({
@@ -926,10 +926,14 @@ test('add never claims success when a required watcher cannot open', () => {
     classify: () => 'file.text',
   });
   try {
-    assert.throws(() => registration.add(dir), /could not start required watcher/,
-      'a registered tree with no live doorbell is an incomplete add, never a success');
-    assert.ok(registration.tree(dir)?.root(),
-      'identity remains durable for a later explicit retry; add only refuses to lie about Watch');
+    // Registration is synchronous, never optimistic: the watcher is proven
+    // FIRST, so a doorbell that cannot be born refuses with its reason and
+    // the remedy — and leaves NOTHING behind. No half-registered ghost, no
+    // local record the cloud never heard of.
+    assert.throws(() => registration.add(dir), /watcher could not be born \(ENOSPC\).*fs\.inotify\.max_user_watches/,
+      'the refusal names the kernel budget and the fix');
+    assert.ok(!registration.tree(dir)?.root(), 'no identity row survives the refusal');
+    assert.equal(observer.listRoots().length, 0, 'no observer root survives it either — zero residue');
   } finally {
     registration.stop();
     observer.stop();