amalgm 0.1.262 → 0.1.263

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

@@ -35,6 +35,24 @@ function createRepoFollowers({ observer, registry, repoStates, recordForRoot, on
   const followers = new Map(); // observer rootId -> { path, uuid, follower }
   let stopped = false;
 
+  /**
+   * A scoped capture reuses an unsuspected untracked entry WITHOUT its
+   * bytes. The persisted state must stay whole — transport cargo packs
+   * untracked content straight from it — so the bytes are carried forward
+   * from the previous settled state: a memory copy, never a disk read.
+   * The transient `reused` flag never persists.
+   */
+  function hydrateReusedUntracked(next, previous) {
+    const entries = next?.checkpoint?.untracked;
+    if (!entries?.some((file) => file.reused)) return;
+    const prior = new Map((previous?.checkpoint?.untracked ?? []).map((file) => [file.path, file]));
+    next.checkpoint.untracked = entries.map((file) => {
+      if (!file.reused) return file;
+      const { reused, ...kept } = file;
+      return { ...kept, content: prior.get(file.path)?.content ?? null };
+    });
+  }
+
   function close(rootId) {
     const entry = followers.get(rootId);
     if (!entry) return;
@@ -74,14 +92,32 @@ function createRepoFollowers({ observer, registry, repoStates, recordForRoot, on
         // 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;
+        // The repo UUID rides along so the transport packs the current
+        // worktree identity map from the registry.
+        captureFn: async (repoPath, { suspects } = {}) => {
+          const withBundle = typeof prepareRepo === 'function';
+          // The warm checkpoint: the last settled state's untracked entries
+          // ((path, mode, sha256) — content is never persisted) let a scoped
+          // capture reuse every unsuspected file without opening it. Cloud
+          // cargo captures (withBundle) need content and read everything;
+          // capture() enforces that side of the contract itself.
+          const previous = withBundle ? null : repoStates.get(record.uuid);
+          const captured = await worker.capture(repoPath, {
+            withBundle,
+            suspects,
+            previousUntracked: previous?.checkpoint?.untracked?.map(
+              ({ path: rel, mode, sha256 }) => ({ path: rel, mode, sha256 }),
+            ) ?? null,
+          });
+          return withBundle && !captured?.busy
+            ? prepareRepo(captured, { entityUuid: record.uuid })
+            : captured;
         },
         emit: (next) => {
           // ONE settled Card + Checkpoint state is ONE registry transition on
           // the repo entity. Raw filesystem events never write Git state.
           const previous = repoStates.get(record.uuid);
+          hydrateReusedUntracked(next, previous);
           registry.transaction(() => {
             repoStates.put(record.uuid, next);
             registry.attest(record.uuid, { type: 'repo.git', payloadVersion: next.stateId });
@@ -115,7 +151,10 @@ function createRepoFollowers({ observer, registry, repoStates, recordForRoot, on
       sync();
       return;
     }
-    if (event.type === 'repo.changed') followers.get(event.rootId)?.follower.ring();
+    // The ding's hint (the named path, rebased to the repo's ground, or
+    // null for "anywhere") rides into the follower's scope: it is what
+    // lets the next capture patch one file instead of re-reading the world.
+    if (event.type === 'repo.changed') followers.get(event.rootId)?.follower.ring(event.hint ?? null);
   }
 
   function stop() {

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

@@ -28,13 +28,18 @@ function decodeBytes(encoded) {
 /** 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 } = {}) {
+ * the bundle bytes; SQLite retains only the content head that names them.
+ * The identity map is transport cargo too: it names the repo's enrolled
+ * worktree entities so a receiving machine binds the SAME child UUIDs
+ * instead of minting competitors — derived from the registry whenever a
+ * transport is packed, never persisted beside the local state. */
+function pack(state, { includeBundle = true, transportVersion = state.transportVersion ?? null, identity = null } = {}) {
   return JSON.stringify({
     stateId: state.stateId,
     cardId: state.cardId,
     checkpointId: state.checkpointId,
     transportVersion,
+    ...(identity ? { identity } : {}),
     card: {
       ...state.card,
       bundle: includeBundle && state.card.bundle ? {
@@ -59,6 +64,7 @@ function unpack(text) {
   return {
     ...state,
     transportVersion: typeof state.transportVersion === 'string' ? state.transportVersion : null,
+    identity: Array.isArray(state.identity) ? state.identity : null,
     card: {
       ...state.card,
       bundle: state.card.bundle && {
@@ -81,15 +87,19 @@ 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');
+ * vary without changing repository identity. `identity` is the enrolled
+ * worktree's path → { uuid, type } entries: repo children never travel as
+ * individual cloud records, so their permanent UUIDs ride here — inside
+ * the one state parcel — and `amalgm add` binds them from this map. */
+function transportBytes(state, identity = null) {
+  return Buffer.from(pack(state, { includeBundle: true, transportVersion: null, identity }), 'utf8');
 }
 
 function localState(state, transportVersion) {
   return {
     ...state,
     transportVersion,
+    identity: null,
     card: { ...state.card, bundle: null },
   };
 }

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

@@ -52,6 +52,7 @@ const {
   migrateLegacyToolboxCatalog,
 } = require('../toolbox/artifacts');
 const { createObserver } = require('../observer');
+const { gitDirTruth } = require('../observer/scan');
 const { shouldEnroll } = require('../workspace/tree/inclusion');
 const { classifyFile } = require('./classify');
 const { createEntityCloud } = require('./entity-cloud');
@@ -106,13 +107,37 @@ function createRegistrationService({
   const repoTransportHeads = new Map(); // semantic stateId -> immutable content hash
   const importedRepoStates = new Map(); // cloud UUID -> verified bundle-free state
 
+  /** The identity map a settled repo state travels with: every enrolled
+   * record beneath the repo boundary (stopping at nested repo boundaries,
+   * which pack their own maps). Repo children never journal their own
+   * cloud mutations, so this map — inside the one transport parcel — is
+   * the only way their permanent UUIDs reach another machine. */
+  function worktreeIdentity(repoUuid) {
+    const registry = boundary.current?.registry;
+    if (!registry) return null;
+    const entries = [];
+    const visit = (parentUuid, base) => {
+      for (const child of registry.children(parentUuid)) {
+        if (child.status !== 'active') continue;
+        const childPath = base ? `${base}/${child.name}` : child.name;
+        entries.push({ path: childPath, uuid: child.uuid, type: child.type });
+        if (child.type === 'folder') visit(child.uuid, childPath);
+      }
+    };
+    visit(repoUuid, '');
+    return entries;
+  }
+
   /** 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) {
+   * SQLite so a large clone cannot bloat the device registry. Registration
+   * supplies the freshly assigned identity entries; a settled follower
+   * names its repo UUID instead and the map is read from the registry. */
+  function prepareRepo(captured, { identity = null, entityUuid = null } = {}) {
     if (captured?.busy) return captured;
-    const artifact = entityContent.captureBytes({ bytes: transportBytes(captured) });
+    const transportIdentity = identity ?? (entityUuid ? worktreeIdentity(entityUuid) : null);
+    const artifact = entityContent.captureBytes({ bytes: transportBytes(captured, transportIdentity) });
     repoTransportHeads.set(captured.stateId, artifact.contentHash);
     return localState(captured, artifact.contentHash);
   }
@@ -148,7 +173,7 @@ function createRegistrationService({
       db: identityDb,
       sentinelPath: path.join(dir, 'identity.epoch'),
       journal: entityCloud.journal,
-      captureRepo: (repoPath) => prepareRepo(capture(repoPath, { withBundle: true })),
+      captureRepo: (repoPath, options) => prepareRepo(capture(repoPath, { withBundle: true }), options),
       prepareRepo,
       repoStateAt: (uuid) => importedRepoStates.get(uuid) || null,
     }),
@@ -158,10 +183,12 @@ function createRegistrationService({
 
   let closed = false;
 
-  /** Count only the same eligible shape that registration will see.  This is
+  /** Count only the records that will actually TRAVEL to the cloud.  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. */
+   * thousands of individually compacted mutations. A repository counts as
+   * ONE — its children ride the transport parcel, never the cloud graph —
+   * so registering even a 40,000-file repo is a single ordinary mutation. */
   function estimatedRegistrationRecords(targetPath, limit = ATOMIC_REGISTRATION_THRESHOLD) {
     let total = 0;
     const visit = (candidate) => {
@@ -170,6 +197,7 @@ function createRegistrationService({
       let stat;
       try { stat = fs.lstatSync(candidate); } catch { return; }
       if (!stat.isDirectory() || stat.isSymbolicLink()) return;
+      if (gitDirTruth(candidate) === 'present') return;
       let entries;
       try { entries = fs.readdirSync(candidate, { withFileTypes: true }); } catch { return; }
       for (const entry of entries) {
@@ -482,15 +510,50 @@ function createRegistrationService({
       group.push(record);
       children.set(record.parentUUID, group);
     }
+    // Unpacking a transport decodes the whole bundle from base64; one unpack
+    // per repository, not one per caller.
+    const repoStatesByUuid = new Map();
     function repoState(record) {
+      const cached = repoStatesByUuid.get(record.uuid);
+      if (cached) return cached;
       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`);
       }
+      repoStatesByUuid.set(record.uuid, state);
       return state;
     }
 
+    /** The identity a repo's transport carries for one worktree address:
+     * the same permanent UUID the registering machine minted, synthesized
+     * into the record shape the structural walk verifies. Records under a
+     * repository no longer live in the cloud catalog — the map inside the
+     * one state parcel is their identity carrier. */
+    function repoChildIdentity(repoRecord, repoRelativePath) {
+      const state = repoState(repoRecord);
+      if (!Array.isArray(state.identity)) return null;
+      const byPath = state.identityByPath
+        || (state.identityByPath = new Map(state.identity.map((entry) => [entry.path, entry])));
+      const entry = byPath.get(repoRelativePath);
+      if (!entry) return null;
+      // A nested repository does not travel (the repo travel law), so the
+      // transport cannot promise this ground materializes as a repo here.
+      // The receiving walk decides what the ground actually is and mints
+      // fresh local identity for it.
+      if (entry.type === 'repo.git') return null;
+      const slash = repoRelativePath.lastIndexOf('/');
+      const parentEntry = slash === -1 ? null : byPath.get(repoRelativePath.slice(0, slash));
+      return {
+        uuid: entry.uuid,
+        type: entry.type,
+        parentUUID: parentEntry ? parentEntry.uuid : repoRecord.uuid,
+        name: repoRelativePath.slice(slash + 1),
+        status: 'active',
+        payloadVersion: null,
+      };
+    }
+
     for (const { contentHash } of entityCloud.contentHeads(active)) {
       if (!entityContent.complete({ contentHash })) return false;
     }
@@ -535,9 +598,21 @@ function createRegistrationService({
     function identityAt(relativePath) {
       if (!relativePath) return root;
       let cursor = root;
-      for (const name of relativePath.split('/')) {
-        cursor = (children.get(cursor.uuid) || []).find((record) => record.name === name) || null;
-        if (!cursor) return null;
+      const parts = relativePath.split('/');
+      for (let index = 0; index < parts.length; index += 1) {
+        const next = (children.get(cursor.uuid) || []).find((record) => record.name === parts[index]) || null;
+        if (next) {
+          cursor = next;
+          continue;
+        }
+        // Inside a repository boundary the catalog goes quiet: the rest of
+        // the address is answered by that repo's transport identity map.
+        // (A snapshot from before the repo travel law still carries child
+        // records; those keep answering above, exactly as they used to.)
+        if (cursor.type === 'repo.git') {
+          return repoChildIdentity(records.get(cursor.uuid) || cursor, parts.slice(index).join('/'));
+        }
+        return null;
       }
       return records.get(cursor.uuid) || null;
     }
@@ -621,12 +696,18 @@ function createRegistrationService({
       return crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex');
     }
 
+    // One unpack per repository: the live projection consults the same
+    // state for its drift check, its registry preload, and its apply.
+    const repoStatesByUuid = new Map();
     function repoState(record) {
+      const cached = repoStatesByUuid.get(record.uuid);
+      if (cached) return cached;
       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`);
       }
+      repoStatesByUuid.set(record.uuid, state);
       return state;
     }
 
@@ -908,9 +989,15 @@ function createRegistrationService({
           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;
+      // The snapshot must describe whatever actually committed, even when a
+      // later path refuses (each path is durable alone): without journal
+      // rows, a committed-but-unsnapshotted registration would be local
+      // truth with zero cloud delivery intent — a ghost nothing repairs.
+      try {
+        return boundary.current.registry.withoutJournal(() => boundary.current.addMany(targetPaths));
+      } finally {
+        entityCloud.replaceSnapshot(boundary.current.registry.syncRecords());
+      }
     },
     /** `amalgm add <cloud-root-uuid> [parent-directory]` — cloud to local. */
     add: async ({ uuid, targetPath }) => {

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

@@ -44,6 +44,57 @@ function isRepository(dirPath) {
   return gitDirTruth(dirPath) === 'present';
 }
 
+/**
+ * Assign every enrolled worktree entity its permanent UUID BEFORE the
+ * repo's transport is packed, so the transport's identity map and the
+ * records this walk then creates name the exact same UUIDs. Repo children
+ * never travel as individual cloud records (the repo travel law); this
+ * map, riding inside the one state parcel, is how a receiving machine
+ * binds the same child identities instead of minting competitors.
+ *
+ * The walk mirrors registerDirectory's classification exactly — same
+ * readdir order, same enrollment gate, same lstat shape — and stops at a
+ * nested repository boundary: that repo's own capture owns its own map.
+ */
+function collectWorktreeIdentity(repoPath, { shouldEnroll, identityFor }) {
+  const assignment = new Map(); // repo-relative path -> { uuid, type }
+  const walk = (dirPath, relativePath) => {
+    let entries;
+    try {
+      entries = fs.readdirSync(dirPath, { withFileTypes: true })
+        .sort((a, b) => a.name.localeCompare(b.name));
+    } catch (error) {
+      if (error.code === 'EACCES' || error.code === 'EPERM') return;
+      throw error;
+    }
+    for (const entry of entries) {
+      const entryPath = path.join(dirPath, entry.name);
+      const entryRelativePath = relativePath ? `${relativePath}/${entry.name}` : entry.name;
+      if (!shouldEnroll(entryPath)) continue;
+      let stat;
+      try {
+        stat = fs.lstatSync(entryPath);
+      } catch {
+        continue; // raced away between readdir and look; the create-walk decides
+      }
+      let type;
+      if (stat.isSymbolicLink()) type = 'link';
+      else if (stat.isDirectory()) type = isRepository(entryPath) ? 'repo.git' : 'folder';
+      else if (stat.isFile()) type = 'file.text';
+      else continue;
+      const uuid = identityFor?.(entryRelativePath) || crypto.randomUUID();
+      assignment.set(entryRelativePath, { uuid, type });
+      if (type === 'folder') walk(entryPath, entryRelativePath);
+    }
+  };
+  walk(repoPath, '');
+  return assignment;
+}
+
+function transportIdentity(assignment) {
+  return [...assignment].map(([entryPath, { uuid, type }]) => ({ path: entryPath, uuid, type }));
+}
+
 /**
  * Create the root record, its witness, and every entity below ordinary
  * directory ground. The caller supplies a root that is already known to the
@@ -90,47 +141,58 @@ 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) {
+   * Ordinary local registration has no seeded UUID and captures fresh truth:
+   * the worktree's UUIDs are assigned FIRST so the packed transport's
+   * identity map and the created child records agree exactly. */
+  function repoStateFor(identity, repoPath, relativePath) {
     if (identity.uuid) {
       const imported = repoStateAt?.(identity.uuid);
-      if (imported?.stateId === identity.payloadVersion) return imported;
+      if (imported?.stateId === identity.payloadVersion) return { state: imported, assignment: null };
       const saved = repoStates.get(identity.uuid);
-      if (saved?.stateId === identity.payloadVersion) return saved;
+      if (saved?.stateId === identity.payloadVersion) return { state: saved, assignment: null };
     }
-    return captureInitialRepo(repoPath, captureRepo);
+    const assignment = collectWorktreeIdentity(repoPath, {
+      shouldEnroll,
+      identityFor: (repoRelativePath) => identityAt?.(
+        relativePath ? `${relativePath}/${repoRelativePath}` : repoRelativePath,
+      )?.uuid || null,
+    });
+    return {
+      state: captureInitialRepo(repoPath, captureRepo, transportIdentity(assignment)),
+      assignment,
+    };
   }
 
   return registry.transaction(() => {
     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;
+    const initial = 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 rootUuid = rootIdentity.uuid || (initial ? crypto.randomUUID() : undefined);
     const record = registry.enrollRoot({
       type: rootIdentity.type,
       name: path.basename(root.path),
-      payloadVersion: initialState?.stateId ?? rootIdentity.payloadVersion ?? null,
+      payloadVersion: initial?.state.stateId ?? rootIdentity.payloadVersion ?? null,
       uuid: rootUuid,
     });
     memory.bind(root.rootId, root.rootId, record.uuid);
-    if (initialState) repoStates.put(record.uuid, initialState);
+    if (initial) repoStates.put(record.uuid, initial.state);
 
     if (root.kind === 'files' || root.kind === 'repo') {
       registerDirectory(root.path, record.uuid, {
         registry, shouldEnroll, captureRepo, repoStates, identityAt, repoStateAt, repoStateFor, seeded, relativePath: '',
-      });
+      }, initial?.assignment ? { base: '', byPath: initial.assignment } : null);
     }
     return record;
   });
 }
 
-function captureInitialRepo(repoPath, captureRepo) {
-  const state = captureRepo(repoPath);
+function captureInitialRepo(repoPath, captureRepo, identityEntries = null) {
+  const state = captureRepo(repoPath, { identity: identityEntries });
   if (state?.busy) {
     throw new Error(`cannot register ${repoPath}: Git is unsettled (${state.busy})`);
   }
@@ -142,7 +204,7 @@ function captureInitialRepo(repoPath, captureRepo) {
 
 function registerDirectory(dirPath, parentUUID, {
   registry, shouldEnroll, captureRepo, repoStates, identityAt, repoStateAt, repoStateFor, seeded, relativePath,
-}) {
+}, assigned = null) {
   let entries;
   try {
     entries = fs.readdirSync(dirPath, { withFileTypes: true })
@@ -155,6 +217,20 @@ function registerDirectory(dirPath, parentUUID, {
     throw error;
   }
 
+  // The UUID a pre-capture assignment reserved for this exact ground. The
+  // transport's identity map was packed from these, so the created record
+  // must wear the same UUID — unless the ground changed shape between the
+  // assignment walk and this one, in which case the walk's truth wins and
+  // the map entry is honestly stale.
+  const assignedFor = (entryRelativePath, type) => {
+    if (!assigned) return undefined;
+    const repoRelativePath = assigned.base
+      ? entryRelativePath.slice(assigned.base.length + 1)
+      : entryRelativePath;
+    const seat = assigned.byPath.get(repoRelativePath);
+    return seat && seat.type === type ? seat.uuid : undefined;
+  };
+
   for (const entry of entries) {
     const entryPath = path.join(dirPath, entry.name);
     const entryRelativePath = relativePath ? `${relativePath}/${entry.name}` : entry.name;
@@ -173,7 +249,7 @@ function registerDirectory(dirPath, parentUUID, {
         // Preserve it through the structural bind; normal local registration
         // still leaves this null until Watch observes the filesystem.
         payloadVersion: identity.payloadVersion ?? null,
-        uuid: identity.uuid,
+        uuid: identity.uuid ?? assignedFor(entryRelativePath, 'link'),
       });
       continue;
     }
@@ -182,19 +258,27 @@ function registerDirectory(dirPath, parentUUID, {
       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 initial = type === 'repo.git' ? repoStateFor(identity, entryPath, entryRelativePath) : null;
+      const uuid = identity.uuid
+        ?? assignedFor(entryRelativePath, type)
+        ?? (initial ? crypto.randomUUID() : undefined);
       const record = registry.create({
         type: identity.type,
         parentUUID,
         name: entry.name,
-        payloadVersion: state?.stateId ?? identity.payloadVersion ?? null,
+        payloadVersion: initial?.state.stateId ?? identity.payloadVersion ?? null,
         uuid,
       });
-      if (state) repoStates.put(record.uuid, state);
+      if (initial) repoStates.put(record.uuid, initial.state);
+      // A repository starts its own assignment scope: its transport's map
+      // covers exactly its worktree, so its children draw from it — never
+      // from an enclosing repo's map.
+      const childAssigned = type === 'repo.git'
+        ? (initial?.assignment ? { base: entryRelativePath, byPath: initial.assignment } : null)
+        : assigned;
       registerDirectory(entryPath, record.uuid, {
         registry, shouldEnroll, captureRepo, repoStates, identityAt, repoStateAt, repoStateFor, seeded, relativePath: entryRelativePath,
-      });
+      }, childAssigned);
       continue;
     }
     if (stat.isFile()) {
@@ -206,7 +290,7 @@ function registerDirectory(dirPath, parentUUID, {
         parentUUID,
         name: entry.name,
         payloadVersion: identity.payloadVersion ?? null,
-        uuid: identity.uuid,
+        uuid: identity.uuid ?? assignedFor(entryRelativePath, 'file.text'),
       });
     }
   }

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

@@ -62,13 +62,50 @@ function remoteList(repoPath) {
   }).sort((a, b) => (a.name < b.name ? -1 : 1));
 }
 
-function untrackedFiles(repoPath) {
+/** Is `rel` named by the suspect list — itself, or under a named directory? */
+function makeSuspectTest(suspects) {
+  const named = new Set(suspects);
+  return (rel) => {
+    if (named.has(rel)) return true;
+    let prefix = rel;
+    for (;;) {
+      const cut = prefix.lastIndexOf('/');
+      if (cut < 0) return false;
+      prefix = prefix.slice(0, cut);
+      if (named.has(prefix)) return true;
+    }
+  };
+}
+
+/**
+ * The warm half of the checkpoint. Git keeps the Card's ledger itself and
+ * its index makes the tracked diffs cheap — the one cost with no cache was
+ * untracked files, re-read in full on every capture. With `suspects` (the
+ * doorbell's named paths since the last settled state) and the previous
+ * state's untracked entries, an unsuspected file's (mode, sha256) is
+ * REUSED without opening it: silence from the doorbell is the proof the
+ * written answer is still true. Everything else stays a fresh read — a
+ * suspect, a new path, or any capture without both inputs (suspects null
+ * means "everything is suspect": first capture, flush, catch-up, a command
+ * ending). Reused entries carry `content: null`; ids derive from
+ * (path, mode, sha256) alone, so a scoped capture's ids are byte-identical
+ * to a from-scratch one over the same ground.
+ */
+function untrackedFiles(repoPath, { suspects = null, previousUntracked = null } = {}) {
+  const reusable = suspects !== null && previousUntracked
+    ? new Map(previousUntracked.map((file) => [file.path, file]))
+    : null;
+  const suspect = reusable ? makeSuspectTest(suspects) : null;
   const out = runGit(repoPath, ['ls-files', '--others', '--exclude-standard', '-z']).toString('utf8');
   return out.split('\0').filter(Boolean).sort().flatMap((rel) => {
     // A trailing slash is git marking a repo boundary it will not enter — a
     // nested repository or linked worktree. That is its own territory with
     // its own card; the parent's checkpoint must not contain it.
     if (rel.endsWith('/')) return [];
+    if (reusable && !suspect(rel)) {
+      const prev = reusable.get(rel);
+      if (prev) return [{ path: rel, mode: prev.mode, content: null, sha256: prev.sha256, reused: true }];
+    }
     const abs = path.join(repoPath, rel);
     try {
       const stat = fs.lstatSync(abs);
@@ -123,9 +160,14 @@ function deriveCheckpointId(checkpoint) {
   }));
 }
 
-function capture(repoPath, { withBundle = true } = {}) {
+function capture(repoPath, { withBundle = true, suspects = null, previousUntracked = null } = {}) {
   const busy = busyReason(repoPath);
   if (busy) return { busy };
+  // Untracked reuse is bundle-free (local) captures only: cloud cargo
+  // (prepareRepo) consumes untracked CONTENT, and a reused entry carries
+  // none. Teaching the cargo path to dedupe by sha256 is the named next
+  // step; until then a withBundle capture always reads every byte.
+  const scoped = withBundle ? {} : { suspects, previousUntracked };
 
   const branch = tryGitText(repoPath, ['symbolic-ref', '-q', '--short', 'HEAD']); // null = detached
   const commit = tryGitText(repoPath, ['rev-parse', '-q', '--verify', 'HEAD']);   // null = unborn
@@ -146,7 +188,7 @@ function capture(repoPath, { withBundle = true } = {}) {
     // raw non-UTF-8 bytes, and a string conversion would corrupt it silently.
     stagedPatch: runGit(repoPath, ['diff', '--cached', '--binary', '--full-index', commit ? 'HEAD' : EMPTY_TREE]),
     unstagedPatch: runGit(repoPath, ['diff', '--binary', '--full-index']),
-    untracked: untrackedFiles(repoPath),
+    untracked: untrackedFiles(repoPath, scoped),
   };
 
   const cardId = deriveCardId(card);