amalgm 0.1.250 → 0.1.252

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "amalgm",
-  "version": "0.1.250",
+  "version": "0.1.252",
   "description": "Amalgm local computer runtime: login, MCP, chat, events, previews, and tunnels.",
   "license": "UNLICENSED",
   "private": false,

package/runtime/scripts/amalgm-mcp/registration/entity-cloud.js

@@ -14,6 +14,8 @@ const crypto = require('crypto');
 const ENTITY_CLOUD_CONTRACT = 'amalgm-entity-registry@1';
 const ENTITY_CLOUD_SCHEMA_VERSION = 1;
 const BOOTSTRAP_RECONCILIATION_STATE = 'reconciling-bootstrap';
+const SNAPSHOT_REPLACE_OPERATION = 'entity.snapshot.replace';
+const SNAPSHOT_REPLACE_MAX_BYTES = 8 * 1024 * 1024;
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 const TYPES = new Set([
   'workspace', 'folder', 'repo.git', 'file.text', 'file.binary', 'link', 'reference',
@@ -57,12 +59,21 @@ function assertRecord(value) {
     || typeof value.name !== 'string' || !value.name || value.name.includes('/') || value.name.includes('\0')
     || !['active', 'trashed', 'deleted'].includes(value.status)
     || typeof value.version !== 'string' || !/^[0-9a-f]{64}$/.test(value.version)
-    || (value.payloadVersion !== null && typeof value.payloadVersion !== 'string')) {
+    || (value.payloadVersion !== null && typeof value.payloadVersion !== 'string')
+    || (value.transportVersion !== undefined && value.transportVersion !== null
+      && (typeof value.transportVersion !== 'string' || !CONTENT_HEAD.test(value.transportVersion)))) {
     throw new Error('cloud entity snapshot has an invalid record');
   }
   if (value.parentUUID === null && !ROOT_TYPES.has(value.type)) {
     throw new Error(`cloud entity ${value.uuid} is not a valid tree root`);
   }
+  const transportVersion = value.transportVersion ?? null;
+  if (value.type === 'repo.git' && transportVersion !== null && !CONTENT_HEAD.test(transportVersion)) {
+    throw new Error('cloud repository transport head is invalid');
+  }
+  if (value.type !== 'repo.git' && transportVersion !== null) {
+    throw new Error('only repository entities may declare a transport head');
+  }
   return {
     uuid: value.uuid.toLowerCase(),
     type: value.type,
@@ -71,6 +82,7 @@ function assertRecord(value) {
     status: value.status,
     version: value.version,
     payloadVersion: value.payloadVersion,
+    transportVersion,
   };
 }
 
@@ -106,26 +118,48 @@ function parseSnapshot(bytes) {
  * no watcher imports: a cloud record may be known on this machine long before
  * `amalgm add <uuid>` chooses and validates local ground for it.
  */
-function createEntityCloud({ db, userId, deviceId, content = null }) {
+function createEntityCloud({ db, userId, deviceId, content = null, repoStates = null, repoTransportFor = null }) {
   if (!db) throw new Error('createEntityCloud requires an identity database');
   const ownerUserId = typeof userId === 'string' && userId ? userId : null;
   const localDeviceId = typeof deviceId === 'string' && deviceId ? deviceId : null;
 
+  function cloudRecord(record) {
+    const normalized = assertRecord(record);
+    if (normalized.type !== 'repo.git' || normalized.transportVersion !== null) return normalized;
+    const supplied = repoTransportFor?.(normalized) || null;
+    const state = repoStates?.get(normalized.uuid);
+    const transportVersion = supplied || state?.transportVersion || null;
+    if ((state && state.stateId !== normalized.payloadVersion) || !CONTENT_HEAD.test(String(transportVersion || ''))) {
+      throw new Error(`repository ${normalized.uuid} has no immutable Repocard transport for state ${normalized.payloadVersion || 'none'}`);
+    }
+    return { ...normalized, transportVersion };
+  }
+
   function contentHead(record) {
-    return ['file.text', 'file.binary'].includes(record?.type)
-      && typeof record?.payloadVersion === 'string'
-      && CONTENT_HEAD.test(record.payloadVersion);
+    if (['file.text', 'file.binary'].includes(record?.type)
+      && typeof record?.payloadVersion === 'string' && CONTENT_HEAD.test(record.payloadVersion)) {
+      return record.payloadVersion;
+    }
+    if (record?.type === 'repo.git' && typeof record?.transportVersion === 'string'
+      && CONTENT_HEAD.test(record.transportVersion)) return record.transportVersion;
+    return null;
   }
 
-  function queueContent(record, resourceId, { queue = false } = {}) {
-    if (!contentHead(record)) return;
+  function cloudSnapshot(records) {
+    return snapshotFromRecords(records.map(cloudRecord));
+  }
+
+  function queueContent(input, resourceId, { queue = false } = {}) {
+    const record = cloudRecord(input);
+    const head = contentHead(record);
+    if (!head) return;
     if (!content || typeof content.has !== 'function') {
       throw new Error('file entity content is unavailable: registration must capture bytes before it records their cloud head');
     }
-    if (!content.has({ contentHash: record.payloadVersion })) {
+    if (!content.has({ contentHash: head })) {
       throw new Error('file entity bytes were not captured before its cloud head committed');
     }
-    if (queue) content.ensureUpload({ resourceId, contentHash: record.payloadVersion });
+    if (queue) content.ensureUpload({ resourceId, contentHash: head });
   }
 
   function replica() {
@@ -301,15 +335,16 @@ function createEntityCloud({ db, userId, deviceId, content = null }) {
     // The SQLite mutation is the durable delivery intent. Its post-commit
     // content drain creates the filesystem upload cursor; doing that here
     // would let a rolled-back identity write upload unreachable bytes.
-    queueContent(record, current.resourceId);
+    const cloud = cloudRecord(record);
+    queueContent(cloud, current.resourceId);
     upsertCatalogRecord({
       resourceId: current.resourceId,
       authorityEpoch: current.authorityEpoch,
       headVersion: current.headVersion,
-      record,
+      record: cloud,
     });
     const mutationId = `ent_${crypto.randomBytes(18).toString('base64url')}`;
-    const operation = { kind: 'entity.upsert', record: assertRecord(record) };
+    const operation = { kind: 'entity.upsert', record: cloud };
     const createdAt = now();
     db.prepare(`
       INSERT INTO entity_cloud_mutations (
@@ -319,6 +354,45 @@ function createEntityCloud({ db, userId, deviceId, content = null }) {
     `).run(current.resourceId, mutationId, stableJson(operation), createdAt, createdAt);
   }
 
+  /** Publish one complete logical graph as one atomic cloud operation.  A
+   * large registration must never expose a half-created parent/child graph
+   * between individual acknowledgements. Ordinary watcher edits remain
+   * single-record operations. */
+  function replaceSnapshot(records) {
+    const current = replica();
+    if (!current || current.state !== 'active') {
+      throw new Error('entity cloud registry is not ready yet; wait for the signed-in runtime to finish its first cloud handshake');
+    }
+    const unsettled = db.prepare(`
+      SELECT COUNT(*) AS count FROM entity_cloud_mutations
+      WHERE resource_id = ? AND mutation_state <> 'synced'
+    `).get(current.resourceId);
+    if (Number(unsettled.count) !== 0) {
+      throw new Error('entity cloud registration is already uploading another change; wait for it before registering this large tree');
+    }
+    const snapshot = cloudSnapshot(records);
+    const operation = { kind: SNAPSHOT_REPLACE_OPERATION, snapshot };
+    const bytes = Buffer.byteLength(stableJson(operation), 'utf8');
+    if (bytes > SNAPSHOT_REPLACE_MAX_BYTES) {
+      throw new Error(`registered entity graph is ${bytes} bytes; the atomic cloud registration limit is ${SNAPSHOT_REPLACE_MAX_BYTES} bytes`);
+    }
+    for (const record of snapshot.records) queueContent(record, current.resourceId, { queue: true });
+    const createdAt = now();
+    db.prepare(`
+      INSERT INTO entity_cloud_mutations (
+        resource_id, mutation_id, operation_json, mutation_state,
+        created_at, updated_at
+      ) VALUES (?, ?, ?, 'pending', ?, ?)
+    `).run(
+      current.resourceId,
+      `ent_${crypto.randomBytes(18).toString('base64url')}`,
+      stableJson(operation),
+      createdAt,
+      createdAt,
+    );
+    return { records: snapshot.records.length, bytes };
+  }
+
   function enqueueBootstrapReconciliation(records, current) {
     const pending = db.prepare('SELECT COUNT(*) AS count FROM entity_cloud_mutations WHERE resource_id = ? AND mutation_state <> \'synced\'')
       .get(current.resourceId);
@@ -327,7 +401,7 @@ function createEntityCloud({ db, userId, deviceId, content = null }) {
     }
     const insert = db.prepare('INSERT INTO entity_cloud_mutations (resource_id, mutation_id, operation_json, mutation_state, created_at, updated_at) VALUES (?, ?, ?, \'pending\', ?, ?)');
     const createdAt = now();
-    for (const record of snapshotFromRecords(records).records) {
+    for (const record of cloudSnapshot(records).records) {
       queueContent(record, current.resourceId, { queue: true });
       insert.run(
         current.resourceId,
@@ -357,7 +431,7 @@ function createEntityCloud({ db, userId, deviceId, content = null }) {
     if (existing?.state === 'active') {
       throw new Error('entity cloud registry already exists locally; cloud lookup must not create it again');
     }
-    const snapshot = snapshotFromRecords(registry.syncRecords());
+    const snapshot = cloudSnapshot(registry.syncRecords());
     const cutoff = db.prepare('SELECT COALESCE(MAX(sequence), 0) AS sequence FROM entity_cloud_mutations').get().sequence;
     saveReplica({
       resourceId: currentIdentity.resourceId,
@@ -397,7 +471,7 @@ function createEntityCloud({ db, userId, deviceId, content = null }) {
       || !Number.isInteger(Number(headVersion)) || Number(headVersion) < 0) {
       throw new Error('entity cloud registry authority is invalid');
     }
-    const local = snapshotFromRecords(registry.syncRecords());
+    const local = cloudSnapshot(registry.syncRecords());
     const current = replica();
     const bootstrapping = current?.state === 'bootstrapping';
     const reconciling = current?.state === BOOTSTRAP_RECONCILIATION_STATE;
@@ -526,7 +600,7 @@ function createEntityCloud({ db, userId, deviceId, content = null }) {
     if (typeof targetPath !== 'string' || !targetPath) throw new Error('materialization requires a destination path');
     const tree = catalogTree({ resourceId: current.resourceId, uuid });
     if (tree[0].status !== 'active') throw new Error(`cloud entity ${uuid} is not active`);
-    const unsupported = tree.find((record) => ['repo.git', 'link', 'reference'].includes(record.type));
+    const unsupported = tree.find((record) => ['link', 'reference'].includes(record.type));
     if (unsupported) {
       throw new Error(`cloud entity ${unsupported.uuid} is ${unsupported.type}; this first materializer supports ordinary workspace and file trees only`);
     }
@@ -563,13 +637,14 @@ function createEntityCloud({ db, userId, deviceId, content = null }) {
       if (job.resourceId !== current.resourceId) continue;
       const tree = catalogTree({ resourceId: job.resourceId, uuid: job.entityUuid });
       for (const record of tree) {
-        if (!['file.text', 'file.binary'].includes(record.type) || record.status !== 'active') continue;
-        if (!contentHead(record)) throw new Error(`cloud file ${record.uuid} has no immutable content head`);
-        const part = content.missingPart({ contentHash: record.payloadVersion });
+        if (record.status !== 'active') continue;
+        const head = contentHead(record);
+        if (!head) continue;
+        const part = content.missingPart({ contentHash: head });
         if (!part) continue;
         return {
           resourceId: job.resourceId,
-          contentHash: record.payloadVersion,
+          contentHash: head,
           kind: part.kind,
           partIndex: part.partIndex,
           sha256: part.sha256,
@@ -644,7 +719,9 @@ function createEntityCloud({ db, userId, deviceId, content = null }) {
     `).all(replica()?.resourceId || '');
     return rows.some((row) => {
       try {
-        return JSON.parse(row.operation_json)?.record?.uuid === uuid;
+        const operation = JSON.parse(row.operation_json);
+        return operation?.record?.uuid === uuid
+          || operation?.snapshot?.records?.some((record) => record?.uuid === uuid) === true;
       } catch {
         // A corrupt local outbox must never authorize an overwrite.
         return true;
@@ -680,8 +757,13 @@ function createEntityCloud({ db, userId, deviceId, content = null }) {
         // The logical mutation is intentionally held behind the immutable
         // content manifest. A cloud graph never advances to a file head
         // whose bytes have not reached private R2 storage.
-        if (contentHead(operation?.record)
-          && (!content || !content.uploaded({ resourceId: current.resourceId, contentHash: operation.record.payloadVersion }))) {
+        const records = operation?.kind === SNAPSHOT_REPLACE_OPERATION
+          ? operation?.snapshot?.records
+          : [operation?.record];
+        if ((records || []).some((record) => {
+          const head = contentHead(record);
+          return head && (!content || !content.uploaded({ resourceId: current.resourceId, contentHash: head }));
+        })) {
           return [];
         }
         claimRow.run(current.headVersion, leaseUntil, started, row.sequence);
@@ -693,7 +775,7 @@ function createEntityCloud({ db, userId, deviceId, content = null }) {
           baseVersion: current.headVersion,
           contract: ENTITY_CLOUD_CONTRACT,
           schemaVersion: ENTITY_CLOUD_SCHEMA_VERSION,
-          operationKind: 'entity.upsert',
+          operationKind: operation.kind,
           operation,
         }];
       });
@@ -712,8 +794,11 @@ function createEntityCloud({ db, userId, deviceId, content = null }) {
       ORDER BY sequence ASC
     `).all(current.resourceId);
     for (const row of rows) {
-      const record = JSON.parse(row.operation_json)?.record;
-      queueContent(record, current.resourceId, { queue: true });
+      const operation = JSON.parse(row.operation_json);
+      const records = operation?.kind === SNAPSHOT_REPLACE_OPERATION
+        ? operation?.snapshot?.records
+        : [operation?.record];
+      for (const record of records || []) queueContent(record, current.resourceId, { queue: true });
     }
     return content.claim({ resourceId: current.resourceId, leaseMs });
   }
@@ -799,9 +884,18 @@ function createEntityCloud({ db, userId, deviceId, content = null }) {
     }
     if (envelope?.resourceId !== current.resourceId
       || envelope?.contract !== ENTITY_CLOUD_CONTRACT
-      || Number(envelope?.schemaVersion) !== ENTITY_CLOUD_SCHEMA_VERSION
-      || envelope?.operationKind !== 'entity.upsert'
-      || envelope?.operation?.kind !== 'entity.upsert') {
+      || Number(envelope?.schemaVersion) !== ENTITY_CLOUD_SCHEMA_VERSION) {
+      throw new Error('cloud entity mutation does not belong to this registry');
+    }
+    if (envelope?.operationKind === SNAPSHOT_REPLACE_OPERATION
+      && envelope?.operation?.kind === SNAPSHOT_REPLACE_OPERATION) {
+      // The complete replacement is imported only from the active snapshot
+      // the gateway makes before acknowledgement. Consuming its tail would
+      // reintroduce the very partial-graph state this operation prevents.
+      if (Number(version) > current.headVersion) saveReplica({ ...current, headVersion: Number(version) });
+      return { duplicate: true, version: Number(version), snapshotRequired: true, materializations: [] };
+    }
+    if (envelope?.operationKind !== 'entity.upsert' || envelope?.operation?.kind !== 'entity.upsert') {
       throw new Error('cloud entity mutation does not belong to this registry');
     }
     const record = assertRecord(envelope.operation.record);
@@ -846,6 +940,7 @@ function createEntityCloud({ db, userId, deviceId, content = null }) {
   return {
     identity,
     journal,
+    replaceSnapshot,
     assertRegistrationReady,
     bootstrap,
     install,

package/runtime/scripts/amalgm-mcp/registration/entity-content.js

@@ -168,6 +168,34 @@ function createEntityContent({ dir }) {
     return installed;
   }
 
+  /** Capture immutable bytes that do not originate as a standalone file.
+   * Repocard transport is the first caller: its Git bundle plus checkpoint
+   * are one verified payload, while identity.db stores only the resulting
+   * content head.  The supplied bytes must already equal that head; this is
+   * the same content-addressed rule as captureFile, not a second storage
+   * format. */
+  function captureBytes({ bytes, contentHash = null }) {
+    const fullBytes = Buffer.from(bytes || []);
+    const head = contentHash || digest(fullBytes);
+    assertHash(head);
+    if (digest(fullBytes) !== head) throw new Error('entity content bytes do not match their declared head');
+    ensureDirs();
+    const existing = manifest(head);
+    if (existing) return existing;
+    const chunks = [];
+    for (let offset = 0; offset < fullBytes.length; offset += CHUNK_BYTES) {
+      const part = fullBytes.subarray(offset, Math.min(offset + CHUNK_BYTES, fullBytes.length));
+      const checksum = digest(part);
+      writeChunk(checksum, part);
+      chunks.push({ sha256: checksum, bytes: part.length });
+    }
+    const captured = { contract: CONTENT_CONTRACT, contentHash: head, bytes: fullBytes.length, chunks };
+    writeJson(manifestFile(head), captured);
+    const installed = manifest(head);
+    if (!installed) throw new Error('captured entity content bytes did not persist');
+    return installed;
+  }
+
   function initialUpload(resourceId, contentHash) {
     return {
       contract: CONTENT_CONTRACT,
@@ -414,6 +442,7 @@ function createEntityContent({ dir }) {
 
   return {
     captureFile,
+    captureBytes,
     ensureUpload,
     queueRecords,
     claim,

package/runtime/scripts/amalgm-mcp/registration/index.js

@@ -84,6 +84,11 @@ function createRegistration(options) {
   }
 
   const opened = openIdentity();
+  const captureRepo = opened.captureRepo || ((repoPath) => capture(repoPath, { withBundle: false }));
+  const repoStateAt = opened.repoStateAt ?? null;
+  if (repoStateAt !== null && typeof repoStateAt !== 'function') {
+    throw new Error('openIdentity.repoStateAt must be a function when supplied');
+  }
   const registry = createRegistry({
     db: opened.db,
     sentinelPath: opened.sentinelPath,
@@ -92,7 +97,7 @@ function createRegistration(options) {
     journal: opened.journal ?? null,
   });
   const memory = createEvidenceMemory(opened.db);
-  const repoStates = createRepoStates(opened.db);
+  const repoStates = opened.repoStates || createRepoStates(opened.db);
   const lenses = new Map(); // rootId (permanent witness) -> evidence lens
   let reported = []; // the latest edge pass's refusals
   let edgesDirty = false;
@@ -102,6 +107,7 @@ function createRegistration(options) {
     observer,
     registry,
     repoStates,
+    prepareRepo: opened.prepareRepo ?? null,
     recordForRoot: repoRecordForRoot,
     onSettled: reconcileSettledRepo,
   });
@@ -237,8 +243,9 @@ function createRegistration(options) {
           registry,
           memory,
           shouldEnroll: observer.shouldEnroll,
-          captureRepo: (repoPath) => capture(repoPath, { withBundle: false }),
+          captureRepo,
           repoStates,
+          repoStateAt,
         });
       } catch (error) {
         // An observer root is only coverage until its one structural
@@ -520,8 +527,9 @@ function createRegistration(options) {
         registry,
         memory,
         shouldEnroll: observer.shouldEnroll,
-        captureRepo: (repoPath) => capture(repoPath, { withBundle: false }),
+        captureRepo,
         repoStates,
+        repoStateAt,
         identityAt,
       });
       if (suppressJournal) registry.withoutJournal(register);
@@ -745,6 +753,10 @@ function createRegistration(options) {
     /** The latest edge pass's refusals — visible, never silent. */
     reported: () => [...reported],
     addressOf,
+    // Composition owns the one database handle; exposing this narrow state
+    // store lets the cloud adapter name verified repository cargo without
+    // opening a competing registry over the same SQLite file.
+    repoStates,
     repoState: (uuid) => repoStates.get(uuid),
     tree: treeAt,
     trees: () => new Map(treeRoots()

package/runtime/scripts/amalgm-mcp/registration/repo-followers.js

@@ -25,7 +25,7 @@
 
 const { createFollower, createCaptureWorker } = require('../repocard');
 
-function createRepoFollowers({ observer, registry, repoStates, recordForRoot, onSettled }) {
+function createRepoFollowers({ observer, registry, repoStates, recordForRoot, onSettled, prepareRepo = null }) {
   if (!observer || !registry || !repoStates || typeof recordForRoot !== 'function'
     || typeof onSettled !== 'function') {
     throw new Error('createRepoFollowers requires { observer, registry, repoStates, recordForRoot, onSettled }');
@@ -71,7 +71,13 @@ function createRepoFollowers({ observer, registry, repoStates, recordForRoot, on
       const follower = createFollower({
         repoPath: root.path,
         last: baseline && { cardId: baseline.cardId, checkpointId: baseline.checkpointId },
-        captureFn: (repoPath) => worker.capture(repoPath, { withBundle: false }),
+        // The service can turn a full capture into immutable cloud cargo
+        // before the one stateId attestation commits. Local-only callers
+        // retain the lightweight bundle-free capture used historically.
+        captureFn: async (repoPath) => {
+          const captured = await worker.capture(repoPath, { withBundle: typeof prepareRepo === 'function' });
+          return typeof prepareRepo === 'function' && !captured?.busy ? prepareRepo(captured) : captured;
+        },
         emit: (next) => {
           // ONE settled Card + Checkpoint state is ONE registry transition on
           // the repo entity. Raw filesystem events never write Git state.

package/runtime/scripts/amalgm-mcp/registration/repo-states.js

@@ -25,17 +25,22 @@ function decodeBytes(encoded) {
   return Buffer.from(encoded || '', 'base64');
 }
 
-function pack(state) {
+/** The durable local state deliberately omits a Git bundle.  Bundles are
+ * transport cargo: keeping them in identity.db would turn a small registry
+ * into a second, unbounded object store.  The immutable content store owns
+ * the bundle bytes; SQLite retains only the content head that names them. */
+function pack(state, { includeBundle = true, transportVersion = state.transportVersion ?? null } = {}) {
   return JSON.stringify({
     stateId: state.stateId,
     cardId: state.cardId,
     checkpointId: state.checkpointId,
+    transportVersion,
     card: {
       ...state.card,
-      bundle: state.card.bundle && {
+      bundle: includeBundle && state.card.bundle ? {
         ...state.card.bundle,
         bytes: encodeBytes(state.card.bundle.bytes),
-      },
+      } : null,
     },
     checkpoint: {
       ...state.checkpoint,
@@ -53,6 +58,7 @@ function unpack(text) {
   const state = JSON.parse(text);
   return {
     ...state,
+    transportVersion: typeof state.transportVersion === 'string' ? state.transportVersion : null,
     card: {
       ...state.card,
       bundle: state.card.bundle && {
@@ -72,6 +78,22 @@ function unpack(text) {
   };
 }
 
+/** A Repocard transport document contains its bundle and checkpoint bytes,
+ * but never names itself: its SHA-256 is the immutable cloud content head.
+ * The semantic `stateId` remains on the repo entity, so bundle packing can
+ * vary without changing repository identity. */
+function transportBytes(state) {
+  return Buffer.from(pack(state, { includeBundle: true, transportVersion: null }), 'utf8');
+}
+
+function localState(state, transportVersion) {
+  return {
+    ...state,
+    transportVersion,
+    card: { ...state.card, bundle: null },
+  };
+}
+
 function createRepoStates(db) {
   if (!db) throw new Error('createRepoStates requires the identity database');
   const read = db.prepare('SELECT state_json FROM repo_states WHERE entity_uuid = ?');
@@ -106,4 +128,4 @@ function createRepoStates(db) {
   };
 }
 
-module.exports = { createRepoStates };
+module.exports = { createRepoStates, transportBytes, localState, unpack };

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

@@ -53,11 +53,14 @@ const { classifyFile } = require('./classify');
 const { createEntityCloud } = require('./entity-cloud');
 const { createEntityContent } = require('./entity-content');
 const { createRegistration } = require('./index');
+const { capture, apply: applyRepo } = require('../repocard');
+const { transportBytes, localState, unpack } = require('./repo-states');
 const { machineId, userId } = require('../workspace/identity');
 
 const ENTITIES_DIR = path.join(STORAGE_DIR, 'entities');
 const USER_HOME_CLOUD_CONTRACT = 'amalgm-user-home@1';
 const USER_HOME_CLOUD_SCHEMA_VERSION = 1;
+const ATOMIC_REGISTRATION_THRESHOLD = 500;
 
 let live = null;
 
@@ -80,11 +83,32 @@ function createRegistrationService({
   const evidenceDb = new Database(path.join(dir, 'observer.db'));
   const identityDb = new Database(path.join(dir, 'identity.db'));
   const entityContent = createEntityContent({ dir });
+  // createRegistration owns the schema migration. Give entity-cloud a stable
+  // lookup facade now, then connect it to that one migrated state store once
+  // the boundary exists; never open a second registry just to read Git state.
+  let repoStates = null;
+  const repoStateLookup = { get: (uuid) => repoStates?.get(uuid) || null };
+  const repoTransportHeads = new Map(); // semantic stateId -> immutable content hash
+  const importedRepoStates = new Map(); // cloud UUID -> verified bundle-free state
+
+  /** Git transport is immutable content, not identity-database cargo.  The
+   * semantic repo stateId remains the entity head; this prepares the exact
+   * Card + Checkpoint + bundle payload and leaves only its content hash in
+   * SQLite so a large clone cannot bloat the device registry. */
+  function prepareRepo(captured) {
+    if (captured?.busy) return captured;
+    const artifact = entityContent.captureBytes({ bytes: transportBytes(captured) });
+    repoTransportHeads.set(captured.stateId, artifact.contentHash);
+    return localState(captured, artifact.contentHash);
+  }
+
   const entityCloud = createEntityCloud({
     db: identityDb,
     userId: cloudUserId,
     deviceId: cloudDeviceId,
     content: entityContent,
+    repoStates: repoStateLookup,
+    repoTransportFor: (record) => repoTransportHeads.get(record.payloadVersion) || null,
   });
 
   // The observer emits before the boundary exists (its constructor
@@ -103,12 +127,41 @@ function createRegistrationService({
       db: identityDb,
       sentinelPath: path.join(dir, 'identity.epoch'),
       journal: entityCloud.journal,
+      captureRepo: (repoPath) => prepareRepo(capture(repoPath, { withBundle: true })),
+      prepareRepo,
+      repoStateAt: (uuid) => importedRepoStates.get(uuid) || null,
     }),
     classify: classifyFile,
   });
+  repoStates = boundary.current.repoStates;
 
   let closed = false;
 
+  /** Count only the same eligible shape that registration will see.  This is
+   * not a second registration walker: it is a bounded routing decision that
+   * lets a large tree use one atomic cloud graph replacement instead of
+   * thousands of individually compacted mutations. */
+  function estimatedRegistrationRecords(targetPath, limit = ATOMIC_REGISTRATION_THRESHOLD) {
+    let total = 0;
+    const visit = (candidate) => {
+      total += 1;
+      if (total >= limit) return;
+      let stat;
+      try { stat = fs.lstatSync(candidate); } catch { return; }
+      if (!stat.isDirectory() || stat.isSymbolicLink()) return;
+      let entries;
+      try { entries = fs.readdirSync(candidate, { withFileTypes: true }); } catch { return; }
+      for (const entry of entries) {
+        if (total >= limit) return;
+        const child = path.join(candidate, entry.name);
+        if (!shouldEnroll(child)) continue;
+        visit(child);
+      }
+    };
+    visit(targetPath);
+    return total;
+  }
+
   const publicRecord = (record) => ({
     uuid: record.uuid,
     type: record.type,
@@ -304,14 +357,27 @@ function createRegistrationService({
       group.push(record);
       children.set(record.parentUUID, group);
     }
+    function repoState(record) {
+      if (!record.transportVersion) throw new Error(`cloud repository ${record.uuid} has no Repocard transport head`);
+      const state = unpack(entityContent.bytes({ contentHash: record.transportVersion }));
+      if (state.stateId !== record.payloadVersion) {
+        throw new Error(`cloud repository ${record.uuid} transport does not name its declared state`);
+      }
+      return state;
+    }
+
     for (const record of active) {
       if (['file.text', 'file.binary'].includes(record.type)
         && !entityContent.complete({ contentHash: record.payloadVersion })) {
         return false;
       }
+      if (record.type === 'repo.git'
+        && (!record.transportVersion || !entityContent.complete({ contentHash: record.transportVersion }))) {
+        return false;
+      }
     }
-    if (!['workspace', 'file.text', 'file.binary'].includes(root.type)) {
-      throw new Error(`cloud root ${root.uuid} is ${root.type}; this materializer supports workspace and file trees only`);
+    if (!['workspace', 'repo.git', 'file.text', 'file.binary'].includes(root.type)) {
+      throw new Error(`cloud root ${root.uuid} is ${root.type}; this materializer supports workspace, repository, and file trees only`);
     }
 
     const parent = fs.realpathSync(job.targetPath);
@@ -330,6 +396,10 @@ function createRegistrationService({
         }
         return;
       }
+      if (record.type === 'repo.git') {
+        applyRepo(target, repoState(record));
+        return;
+      }
       if (record.type === 'file.text' || record.type === 'file.binary') {
         fs.writeFileSync(target, entityContent.bytes({ contentHash: record.payloadVersion }), { mode: 0o600, flag: 'wx' });
         return;
@@ -351,6 +421,14 @@ function createRegistrationService({
       write(root, staging);
       fs.renameSync(staging, destination);
       promoted = true;
+      // Bind imported repo UUIDs to the verified state before registration's
+      // structural walk. The walk then reuses these facts instead of making
+      // a second bundle while it arms the local Git follower.
+      for (const record of active.filter((candidate) => candidate.type === 'repo.git')) {
+        const state = repoState(record);
+        importedRepoStates.set(record.uuid, localState(state, record.transportVersion));
+        repoTransportHeads.set(state.stateId, record.transportVersion);
+      }
       const bound = boundary.current.add(destination, { identityAt, suppressJournal: true });
       if (bound.record.uuid !== root.uuid) {
         throw new Error(`materialized cloud root ${root.uuid} bound to unexpected local UUID ${bound.record.uuid}`);
@@ -379,16 +457,18 @@ function createRegistrationService({
     const tree = entityCloud.catalogTree({ resourceId: job.resourceId, uuid: job.entityUuid });
     const root = tree[0];
     const active = tree.filter((record) => record.status === 'active');
-    const unsupported = tree.find((record) => ['repo.git', 'link', 'reference'].includes(record.type));
+    const unsupported = tree.find((record) => ['link', 'reference'].includes(record.type));
     if (unsupported) {
       throw new Error(`live cloud add for ${unsupported.type} is not available yet; the binding was left unchanged`);
     }
-    if (!['workspace', 'file.text', 'file.binary'].includes(root.type)) {
-      throw new Error(`cloud root ${root.uuid} is ${root.type}; this live materializer supports workspace and file trees only`);
+    if (!['workspace', 'repo.git', 'file.text', 'file.binary'].includes(root.type)) {
+      throw new Error(`cloud root ${root.uuid} is ${root.type}; this live materializer supports workspace, repository, and file trees only`);
     }
     for (const record of active) {
       if (['file.text', 'file.binary'].includes(record.type)
         && !entityContent.complete({ contentHash: record.payloadVersion })) return false;
+      if (record.type === 'repo.git'
+        && (!record.transportVersion || !entityContent.complete({ contentHash: record.transportVersion }))) return false;
     }
 
     const parent = fs.realpathSync(job.targetPath);
@@ -419,6 +499,15 @@ function createRegistrationService({
       return crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex');
     }
 
+    function repoState(record) {
+      if (!record.transportVersion) throw new Error(`cloud repository ${record.uuid} has no Repocard transport head`);
+      const state = unpack(entityContent.bytes({ contentHash: record.transportVersion }));
+      if (state.stateId !== record.payloadVersion) {
+        throw new Error(`cloud repository ${record.uuid} transport does not name its declared state`);
+      }
+      return state;
+    }
+
     // Before changing logical identity, prove that every local byte we could
     // overwrite is still the byte named by the old authoritative record.
     // An unsent local edit or an out-of-band edit is a conflict, never an
@@ -429,6 +518,16 @@ function createRegistrationService({
       if (entityCloud.hasUnsettledLocalMutation(record.uuid)) {
         throw new Error(`local change for ${record.uuid} is still waiting for cloud; refusing to overwrite it`);
       }
+      if (current.type === 'repo.git') {
+        const currentPath = addressOf(record.uuid);
+        const observed = currentPath && fs.existsSync(currentPath)
+          ? capture(currentPath, { withBundle: false })
+          : null;
+        if (!observed || observed.busy || observed.stateId !== current.payloadVersion) {
+          throw new Error(`local repository ${currentPath || record.uuid} changed outside Amalgm; refusing to overwrite it`);
+        }
+        continue;
+      }
       if (!['file.text', 'file.binary'].includes(current.type)) continue;
       const currentPath = addressOf(record.uuid);
       if (!currentPath || !fs.existsSync(currentPath)) {
@@ -499,6 +598,10 @@ function createRegistrationService({
         }
         return;
       }
+      if (record.type === 'repo.git') {
+        applyRepo(target, repoState(record));
+        return;
+      }
       if (!['file.text', 'file.binary'].includes(record.type)) {
         throw new Error(`cloud entity ${record.uuid} is ${record.type}; this live materializer cannot write it`);
       }
@@ -511,6 +614,11 @@ function createRegistrationService({
     }
 
     boundary.current.registry.withoutJournal(() => {
+      for (const record of active.filter((candidate) => candidate.type === 'repo.git')) {
+        const state = repoState(record);
+        repoStates.put(record.uuid, localState(state, record.transportVersion));
+        repoTransportHeads.set(state.stateId, record.transportVersion);
+      }
       applyKnownRecords();
       project(root, destination);
       const observerRoot = observer.listRoots().find((entry) => entry.path === destination);
@@ -545,12 +653,26 @@ function createRegistrationService({
     /** `amalgm register <path>` — register, then begin Watch + Detect. */
     register: async (targetPath) => {
       entityCloud.assertRegistrationReady();
-      return boundary.current.add(targetPath);
+      if (estimatedRegistrationRecords(targetPath) < ATOMIC_REGISTRATION_THRESHOLD) {
+        return boundary.current.add(targetPath);
+      }
+      const result = boundary.current.registry.withoutJournal(() => boundary.current.add(targetPath));
+      entityCloud.replaceSnapshot(boundary.current.registry.syncRecords());
+      return result;
     },
-    /** `amalgm register <path>...` — the same primitive for each selected root. */
+    /** `amalgm register <path>...` — the same primitive for each selected root.
+     * A large tree has one atomic cloud replacement record: partial graph
+     * acknowledgements would make an R2 active head that no receiver may
+     * materialize. Small selections retain their ordinary per-entity intent. */
     registerMany: async (targetPaths) => {
       entityCloud.assertRegistrationReady();
-      return boundary.current.addMany(targetPaths);
+      const needsAtomicReplacement = targetPaths.some((targetPath) => (
+        estimatedRegistrationRecords(targetPath) >= ATOMIC_REGISTRATION_THRESHOLD
+      ));
+      if (!needsAtomicReplacement) return boundary.current.addMany(targetPaths);
+      const results = boundary.current.registry.withoutJournal(() => boundary.current.addMany(targetPaths));
+      entityCloud.replaceSnapshot(boundary.current.registry.syncRecords());
+      return results;
     },
     /** `amalgm add <cloud-root-uuid> [parent-directory]` — cloud to local. */
     add: async ({ uuid, targetPath }) => {

package/runtime/scripts/amalgm-mcp/registration/tree.js

@@ -28,6 +28,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const crypto = require('crypto');
 
 function rootType(rootPath, kind) {
   if (kind === 'repo') return 'repo.git';
@@ -55,7 +56,7 @@ function isRepository(dirPath) {
  * directory ground. The caller supplies a root that is already known to the
  * observer but is not yet watched or scanned.
  */
-function registerTree({ root, registry, memory, shouldEnroll, captureRepo, repoStates, identityAt = null }) {
+function registerTree({ root, registry, memory, shouldEnroll, captureRepo, repoStates, identityAt = null, repoStateAt = null }) {
   if (!root || !registry || !memory || typeof shouldEnroll !== 'function'
     || typeof captureRepo !== 'function' || !repoStates) {
     throw new Error('registerTree requires { root, registry, memory, shouldEnroll, captureRepo, repoStates }');
@@ -93,23 +94,42 @@ function registerTree({ root, registry, memory, shouldEnroll, captureRepo, repoS
     };
   }
 
+  /** An imported repository already has a verified Repocard artifact in the
+   * local state table before it is bound to Watch. Reuse that exact state;
+   * recapturing would waste a second Git bundle and could race the import.
+   * Ordinary local registration has no seeded UUID and captures fresh truth. */
+  function repoStateFor(identity, repoPath) {
+    if (identity.uuid) {
+      const imported = repoStateAt?.(identity.uuid);
+      if (imported?.stateId === identity.payloadVersion) return imported;
+      const saved = repoStates.get(identity.uuid);
+      if (saved?.stateId === identity.payloadVersion) return saved;
+    }
+    return captureInitialRepo(repoPath, captureRepo);
+  }
+
   return registry.transaction(() => {
-    const initialState = root.kind === 'repo' ? captureInitialRepo(root.path, captureRepo) : null;
     const rootIdentity = seeded('', {
       type: rootType(root.path, root.kind), parentUUID: null, name: path.basename(root.path), root: true,
     });
+    const initialState = root.kind === 'repo' ? repoStateFor(rootIdentity, root.path) : null;
+    // A repo's immutable transport head is already held by the injected
+    // cloud-cargo lookup before its entity journal runs. Allocate the UUID,
+    // create the FK parent, then persist its bundle-free state in this same
+    // transaction. A rollback removes both durable facts together.
+    const rootUuid = rootIdentity.uuid || (initialState ? crypto.randomUUID() : undefined);
     const record = registry.enrollRoot({
       type: rootIdentity.type,
       name: path.basename(root.path),
       payloadVersion: initialState?.stateId ?? rootIdentity.payloadVersion ?? null,
-      uuid: rootIdentity.uuid,
+      uuid: rootUuid,
     });
     memory.bind(root.rootId, root.rootId, record.uuid);
     if (initialState) repoStates.put(record.uuid, initialState);
 
     if (root.kind === 'files' || root.kind === 'repo') {
       registerDirectory(root.path, record.uuid, {
-        registry, shouldEnroll, captureRepo, repoStates, identityAt, seeded, relativePath: '',
+        registry, shouldEnroll, captureRepo, repoStates, identityAt, repoStateAt, repoStateFor, seeded, relativePath: '',
       });
     }
     return record;
@@ -128,7 +148,7 @@ function captureInitialRepo(repoPath, captureRepo) {
 }
 
 function registerDirectory(dirPath, parentUUID, {
-  registry, shouldEnroll, captureRepo, repoStates, identityAt, seeded, relativePath,
+  registry, shouldEnroll, captureRepo, repoStates, identityAt, repoStateAt, repoStateFor, seeded, relativePath,
 }) {
   let entries;
   try {
@@ -157,20 +177,21 @@ function registerDirectory(dirPath, parentUUID, {
     }
     if (stat.isDirectory()) {
       const type = isRepository(entryPath) ? 'repo.git' : 'folder';
-      const state = type === 'repo.git' ? captureInitialRepo(entryPath, captureRepo) : null;
       const identity = seeded(entryRelativePath, {
         type, parentUUID, name: entry.name, root: false,
       });
+      const state = type === 'repo.git' ? repoStateFor(identity, entryPath) : null;
+      const uuid = identity.uuid || (state ? crypto.randomUUID() : undefined);
       const record = registry.create({
         type: identity.type,
         parentUUID,
         name: entry.name,
         payloadVersion: state?.stateId ?? identity.payloadVersion ?? null,
-        uuid: identity.uuid,
+        uuid,
       });
       if (state) repoStates.put(record.uuid, state);
       registerDirectory(entryPath, record.uuid, {
-        registry, shouldEnroll, captureRepo, repoStates, identityAt, seeded, relativePath: entryRelativePath,
+        registry, shouldEnroll, captureRepo, repoStates, identityAt, repoStateAt, repoStateFor, seeded, relativePath: entryRelativePath,
       });
       continue;
     }

package/runtime/scripts/amalgm-mcp/server/routes/health.js

@@ -3,36 +3,10 @@
 const { activeAgentConversations } = require('../../agents/talk');
 
 // /healthz is a liveness signal: the parent supervisor kills this process
-// after three slow answers, so the handler must never touch disk. Counts are
-// informational — serve a cached snapshot and refresh it off the request path.
-const COUNTS_TTL_MS = 30_000;
-let cachedCounts = { automations: 0, enabledAutomations: 0, apps: 0, customAgents: 0 };
-let countsRefreshedAt = 0;
-let countsRefreshing = false;
-
-function refreshCountsSoon() {
-  if (countsRefreshing || Date.now() - countsRefreshedAt < COUNTS_TTL_MS) return;
-  countsRefreshing = true;
-  setImmediate(() => {
-    try {
-      const { loadAgents } = require('../../agents/store');
-      const { loadApps } = require('../../apps/store');
-      const { listAutomations } = require('../../automations/store');
-      const automations = listAutomations();
-      cachedCounts = {
-        automations: automations.length,
-        enabledAutomations: automations.filter((automation) => automation.enabled !== false).length,
-        apps: loadApps().apps.length,
-        customAgents: loadAgents().agents.length,
-      };
-      countsRefreshedAt = Date.now();
-    } catch {
-      // Counts stay stale; liveness must not depend on store reads succeeding.
-    } finally {
-      countsRefreshing = false;
-    }
-  });
-}
+// after three slow answers. It therefore performs no I/O and starts no
+// follow-up work. Operational counts belong on diagnostic routes: allowing a
+// liveness probe to inspect the  user's state store made a large, healthy
+// installation look dead by blocking its own event loop.
 
 async function handleHealthRoutes(ctx) {
   if (ctx.pathname !== '/healthz') return false;
@@ -43,10 +17,8 @@ async function handleHealthRoutes(ctx) {
     runtime_label: process.env.AMALGM_RUNTIME_LABEL || 'main',
     runtime_instance_id: process.env.AMALGM_RUNTIME_INSTANCE_ID || '',
     pid: process.pid,
-    ...cachedCounts,
     activeAgentConversations: activeAgentConversations.size,
   });
-  refreshCountsSoon();
   return true;
 }
 

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

@@ -76,6 +76,56 @@ test('a signed-in registration is refused until the cloud entity resource is act
   assert.doesNotThrow(() => cloud.assertRegistrationReady());
 });
 
+test('a large registration replaces the complete graph in one cloud operation and a recipient waits for its compacted snapshot', () => {
+  const db = new Database(':memory:');
+  const cloud = createEntityCloud({ db, userId: 'user-1', deviceId: 'device-1' });
+  const registry = createRegistry({ db, ephemeral: true, emit: () => {}, journal: cloud.journal });
+  const root = registry.enrollRoot({ type: 'workspace', name: 'large-ground' });
+  const bootstrap = cloud.bootstrap(registry);
+  cloud.install({
+    registry,
+    resourceId: bootstrap.resourceId,
+    authorityEpoch: 1,
+    headVersion: 0,
+    snapshotBase64: bootstrap.snapshotBase64,
+    snapshotChecksum: bootstrap.snapshotChecksum,
+  });
+  registry.withoutJournal(() => {
+    for (let index = 0; index < 600; index += 1) {
+      registry.create({ type: 'folder', parentUUID: root.uuid, name: `folder-${index}` });
+    }
+  });
+  const replacement = cloud.replaceSnapshot(registry.syncRecords());
+  assert.equal(replacement.records, 601);
+  assert.equal(db.prepare('SELECT COUNT(*) AS count FROM entity_cloud_mutations').get().count, 1);
+  const claim = cloud.claim();
+  assert.equal(claim.length, 1);
+  assert.equal(claim[0].operationKind, 'entity.snapshot.replace');
+  assert.equal(claim[0].operation.snapshot.records.length, 601);
+
+  const recipientDb = new Database(':memory:');
+  const recipient = createEntityCloud({ db: recipientDb, userId: 'user-1', deviceId: 'device-2' });
+  const recipientRegistry = createRegistry({ db: recipientDb, ephemeral: true, emit: () => {}, journal: recipient.journal });
+  recipient.install({
+    registry: recipientRegistry,
+    resourceId: bootstrap.resourceId,
+    authorityEpoch: 1,
+    headVersion: 0,
+    snapshotBase64: bootstrap.snapshotBase64,
+    snapshotChecksum: bootstrap.snapshotChecksum,
+  });
+  const inbound = recipient.ingest({
+    registry: recipientRegistry,
+    envelope: { ...claim[0], operationKind: 'entity.snapshot.replace' },
+    version: 1,
+    committedAt: '2026-08-05T00:00:00.000Z',
+  });
+  assert.equal(inbound.snapshotRequired, true);
+  assert.equal(recipient.replica().headVersion, 1);
+  assert.deepEqual(recipientRegistry.syncRecords(), [], 'the replacement tail never becomes partially bound local identity');
+  recipientDb.close();
+});
+
 test('only an exact verified bootstrap graph can repair a legacy empty entity resource', () => {
   const db = new Database(':memory:');
   const cloud = createEntityCloud({ db, userId: 'user-1', deviceId: 'device-1' });

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

@@ -3,6 +3,7 @@
 const test = require('node:test');
 const assert = require('node:assert/strict');
 const crypto = require('crypto');
+const { execFileSync } = require('child_process');
 const fs = require('fs');
 const os = require('os');
 const path = require('path');
@@ -12,6 +13,8 @@ const { createRegistry } = require('../registry');
 const { createEntityCloud, snapshotFromRecords } = require('../registration/entity-cloud');
 const { createEntityContent } = require('../registration/entity-content');
 const { createRegistrationService } = require('../registration/service');
+const { capture, verify } = require('../repocard');
+const { transportBytes, localState } = require('../registration/repo-states');
 
 function sha256(bytes) {
   return crypto.createHash('sha256').update(bytes).digest('hex');
@@ -28,6 +31,10 @@ function uploadedParts(content, resourceId, contentHash) {
   }
 }
 
+function git(repo, args) {
+  execFileSync('git', args, { cwd: repo, stdio: 'pipe' });
+}
+
 test('add materializes one compacted cloud head, preserves its UUIDs, and starts a local watcher without creating an outbound history replay', async () => {
   const rootDir = fs.mkdtempSync(path.join(os.tmpdir(), 'amalgm-add-materialization-'));
   const sourceDir = path.join(rootDir, 'source');
@@ -93,7 +100,7 @@ test('add materializes one compacted cloud head, preserves its UUIDs, and starts
     }
 
     const job = await target.add({ uuid: root.uuid, targetPath: targetParent });
-    assert.equal(job.state, 'complete');
+    assert.equal(job.state, 'complete', job.error);
     const destination = path.join(targetParent, 'project');
     assert.deepEqual(fs.readFileSync(path.join(destination, 'readme.md')), bytes);
     assert.equal(target.registration.registry.syncRecord(root.uuid).uuid, root.uuid);
@@ -221,3 +228,132 @@ test('an added ordinary workspace stays live: a later cloud file head replaces l
     fs.rmSync(rootDir, { recursive: true, force: true });
   }
 });
+
+test('add recreates an actual Git repository from verified Repocard cargo, then arms its local watcher', async () => {
+  const rootDir = fs.mkdtempSync(path.join(os.tmpdir(), 'amalgm-add-repo-materialization-'));
+  const sourceState = path.join(rootDir, 'source-state');
+  const targetState = path.join(rootDir, 'target-state');
+  const sourceRepo = path.join(rootDir, 'source-repo');
+  const targetParent = path.join(rootDir, 'checkout');
+  fs.mkdirSync(sourceRepo, { 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');
+  git(sourceRepo, ['add', 'tracked.md']);
+  git(sourceRepo, ['commit', '--quiet', '-m', 'initial']);
+  fs.writeFileSync(path.join(sourceRepo, 'tracked.md'), '# changed locally\n');
+  fs.writeFileSync(path.join(sourceRepo, 'untracked.txt'), 'not committed\n');
+
+  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);
+    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);
+    const sourceDb = new Database(path.join(sourceState, 'identity.db'), { readonly: true });
+    const operations = sourceDb.prepare('SELECT operation_json FROM entity_cloud_mutations ORDER BY sequence').all()
+      .map((row) => JSON.parse(row.operation_json));
+    sourceDb.close();
+    const repoCloudRecord = operations.map((operation) => operation.record)
+      .find((record) => record?.uuid === registered.record.uuid);
+    assert.ok(repoCloudRecord?.transportVersion, 'the repo entity names immutable Repocard transport cargo');
+    const records = source.registration.registry.syncRecords().map((record) => (
+      record.uuid === registered.record.uuid ? repoCloudRecord : record
+    ));
+    const snapshot = snapshotFromRecords(records);
+    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 heads = new Set(records.flatMap((record) => {
+      if (['file.text', 'file.binary'].includes(record.type) && record.payloadVersion) return [record.payloadVersion];
+      if (record.type === 'repo.git' && record.transportVersion) return [record.transportVersion];
+      return [];
+    }));
+    for (const head of heads) {
+      const parts = uploadedParts(source.entityContent, bootstrap.resourceId, head);
+      for (const part of [...parts.filter((entry) => entry.kind === 'manifest'), ...parts.filter((entry) => entry.kind === 'chunk')]) {
+        target.receiveCloudContent({
+          resourceId: bootstrap.resourceId, contentHash: head, 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, path.basename(sourceRepo));
+    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.observer.status().find((entry) => entry.path === fs.realpathSync(destination))?.watching, true,
+      'the same successful add starts the destination repository watcher');
+
+    // A Git-only change exercises the ongoing Add binding without also
+    // changing child-file heads: the repo entity must remain a live source
+    // of truth after its first materialization, and the receiver must not
+    // echo its own applied state back into the cloud outbox.
+    git(sourceRepo, ['tag', 'amalgm-live-proof']);
+    const changedState = capture(sourceRepo, { withBundle: true });
+    const changedTransport = source.entityContent.captureBytes({ bytes: transportBytes(changedState) });
+    const changedLocalState = localState(changedState, changedTransport.contentHash);
+    let changedRecord;
+    source.registration.registry.transaction(() => {
+      source.registration.repoStates.put(registered.record.uuid, changedLocalState);
+      changedRecord = source.registration.registry.attest(registered.record.uuid, {
+        type: 'repo.git', payloadVersion: changedState.stateId,
+      });
+    });
+    const latest = new Database(path.join(sourceState, 'identity.db'), { readonly: true });
+    const remoteRecord = JSON.parse(latest.prepare(`
+      SELECT operation_json FROM entity_cloud_mutations
+      WHERE json_extract(operation_json, '$.record.uuid') = ?
+      ORDER BY sequence DESC LIMIT 1
+    `).get(registered.record.uuid).operation_json).record;
+    latest.close();
+    assert.equal(remoteRecord.transportVersion, changedTransport.contentHash);
+    const ingested = target.ingestCloudMutation({
+      envelope: {
+        resourceId: bootstrap.resourceId, mutationId: 'ent_remote_repo_change',
+        contract: 'amalgm-entity-registry@1', schemaVersion: 1,
+        operationKind: 'entity.upsert', operation: { kind: 'entity.upsert', record: remoteRecord },
+      },
+      version: 2, committedAt: '2026-08-05T00:00:00.000Z',
+    });
+    assert.equal(ingested.materializations.length, 1, 'the finished repository add becomes a live pending application');
+    const changedParts = uploadedParts(source.entityContent, bootstrap.resourceId, changedTransport.contentHash);
+    for (const part of [...changedParts.filter((entry) => entry.kind === 'manifest'), ...changedParts.filter((entry) => entry.kind === 'chunk')]) {
+      target.receiveCloudContent({
+        resourceId: bootstrap.resourceId, contentHash: changedTransport.contentHash,
+        kind: part.kind, partIndex: part.kind === 'manifest' ? 0 : part.partIndex,
+        sha256: part.sha256, dataBase64: part.dataBase64,
+      });
+    }
+    assert.equal(verify(destination, changedLocalState).ok, true,
+      'a later cloud repo state re-materializes exactly on the existing checkout');
+    const targetDb = new Database(path.join(targetState, 'identity.db'), { readonly: true });
+    assert.equal(targetDb.prepare('SELECT COUNT(*) AS count FROM entity_cloud_mutations').get().count, 0,
+      'the receiver never echoes its downloaded Git state upstream');
+    targetDb.close();
+  } finally {
+    source.close();
+    target.close();
+    fs.rmSync(rootDir, { recursive: true, force: true });
+  }
+});

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

@@ -0,0 +1,20 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+
+test('/healthz is an I/O-free liveness response', async () => {
+  const { handleHealthRoutes } = require('../server/routes/health');
+  const replies = [];
+  const handled = await handleHealthRoutes({
+    pathname: '/healthz',
+    sendJson: (status, body) => replies.push({ status, body }),
+  });
+
+  assert.equal(handled, true);
+  assert.equal(replies.length, 1);
+  assert.equal(replies[0].status, 200);
+  assert.equal(replies[0].body.status, 'ok');
+  assert.equal(Object.hasOwn(replies[0].body, 'automations'), false);
+  assert.equal(Object.hasOwn(replies[0].body, 'apps'), false);
+});

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

@@ -303,6 +303,43 @@ test('a signed-in register call writes every entity delivery intent in identity.
   }
 });
 
+test('a large signed-in register call publishes one complete cloud graph before Watch begins', async () => {
+  const service = createRegistrationService({
+    dir: path.join(tempRoot, 'state-cloud-register-large'),
+    homeDir: path.join(tempRoot, 'cloud-user-home-large'),
+    cloudUserId: 'user-cloud-register-large',
+    cloudDeviceId: 'computer-cloud-register-large',
+  });
+  const bootstrap = service.entityCloud.bootstrap(service.registration.registry);
+  service.entityCloud.install({
+    registry: service.registration.registry,
+    resourceId: bootstrap.resourceId,
+    authorityEpoch: 1,
+    headVersion: 0,
+    snapshotBase64: bootstrap.snapshotBase64,
+    snapshotChecksum: bootstrap.snapshotChecksum,
+  });
+  const ground = makeGround('cloud-register-large');
+  for (let index = 0; index < 500; index += 1) fs.mkdirSync(path.join(ground, `folder-${index}`));
+
+  try {
+    const registered = await service.register(ground);
+    const db = new Database(path.join(service.dir, 'identity.db'), { readonly: true });
+    const rows = db.prepare('SELECT operation_json, mutation_state FROM entity_cloud_mutations ORDER BY sequence').all();
+    db.close();
+    assert.equal(rows.length, 1, 'the cloud never sees a partially registered large tree');
+    const operation = JSON.parse(rows[0].operation_json);
+    assert.equal(operation.kind, 'entity.snapshot.replace');
+    assert.equal(operation.snapshot.records.length, 501, 'the root and every folder share one authoritative graph');
+    assert.equal(rows[0].mutation_state, 'pending');
+    assert.equal(service.observer.status().some((root) => (
+      root.path === registered.rootPath && root.watching && !root.degraded
+    )), true, 'the same registered root begins local watching');
+  } finally {
+    service.close();
+  }
+});
+
 test('register registers the named ground and every file beneath it', async () => {
   const service = makeService('add');
   const ground = makeGround('add');