amalgm 0.1.264 → 0.1.266

package/package.json

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

package/runtime/scripts/amalgm-mcp/observer/README.md

@@ -94,7 +94,10 @@ never merges, never decides truth — it emits facts for the layers above.
    (catch-up for the window we were dead), watcher death (rebuild the
    doorbell, reconcile the gap once), and whenever a consumer asks — a sync
    session opening, a document opening, an app regaining focus are events
-   too, and they belong to the layer above.
+   too, and they belong to the layer above. A freshly registered repo is the
+   one adapter-defined birth exception: its Card + Checkpoint is already the
+   complete first observation, so it arms Watch without scanning every child
+   again. Restart still performs the ordinary conservative catch-up scan.
 4. **Echo suppression is content, not bookkeeping.** A writer records its own
    write (`noteWrite`); a scan that finds the recorded hash finds nothing.
 5. **Identity has two axes, never mixed — and KIND decides which axis

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

@@ -1229,6 +1229,22 @@ function createObserver(options) {
       }
       scanFilesRoot(root, { allowRootRepository: true });
     },
+    /**
+     * Structural registration already knows its nested Git boundaries from
+     * the same state parcel that names them.  Refresh only that in-memory
+     * forwarding map after it installs those observer roots; this is not a
+     * filesystem census and it neither reads nor records worktree files.
+     */
+    refreshRepoTerritories(rootId) {
+      const root = store.listRoots().find((row) => row.rootId === rootId);
+      if (!root || root.kind !== 'repo') {
+        throw new Error(`refreshRepoTerritories requires a live repo root: ${rootId}`);
+      }
+      const state = live.get(root.rootId);
+      if (!state) return;
+      state.territories = new Set(childRepoRoots(root)
+        .map((child) => child.path.slice(root.path.length + 1)));
+    },
     scanNow,
 
     // The referee (verify.js): re-hash every enrolled byte, report every
@@ -1313,7 +1329,7 @@ function createObserver(options) {
       return statusOf(root);
     },
 
-    start(rootId = null) {
+    start(rootId = null, { census = true } = {}) {
       const firstStart = !started;
       if (firstStart) started = true;
       if (!firstStart && rootId === null) return;
@@ -1328,10 +1344,19 @@ function createObserver(options) {
         const state = attach(root, { watch: true });
         state.held = false;
       }
-      try {
-        for (const root of roots) scanNow(root.rootId);
-      } catch (error) {
-        console.warn('[Observer] initial scan failed:', error?.message || error);
+      // A normal root needs its first observed census before its structural
+      // registration can become evidence. A freshly registered Git root is
+      // different: its already-committed Card + Checkpoint is that complete
+      // initial observation. Re-walking its worktree here would duplicate
+      // the adapter's state (and can block the runtime for a large repo).
+      // `census: false` is therefore only the repo adapter's birth path;
+      // later recoveries and runtime start retain the conservative census.
+      if (census) {
+        try {
+          for (const root of roots) scanNow(root.rootId);
+        } catch (error) {
+          console.warn('[Observer] initial scan failed:', error?.message || error);
+        }
       }
     },
 

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

@@ -67,7 +67,7 @@ const { capture } = require('../repocard');
 const { refusal } = require('./refusal');
 const { createRepoFollowers } = require('./repo-followers');
 const { createRepoStates } = require('./repo-states');
-const { registerTree } = require('./tree');
+const { collectWorktreeIdentityAsync, registerTree, transportIdentity } = require('./tree');
 const { gitDirTruth } = require('../observer/scan');
 
 // Events that can change what the recorded edges reach: a new or
@@ -88,6 +88,10 @@ function createRegistration(options) {
 
   const opened = openIdentity();
   const captureRepo = opened.captureRepo || ((repoPath) => capture(repoPath, { withBundle: false }));
+  const captureRepoAsync = opened.captureRepoAsync ?? null;
+  if (captureRepoAsync !== null && typeof captureRepoAsync !== 'function') {
+    throw new Error('openIdentity.captureRepoAsync must be a function when supplied');
+  }
   const repoStateAt = opened.repoStateAt ?? null;
   if (repoStateAt !== null && typeof repoStateAt !== 'function') {
     throw new Error('openIdentity.repoStateAt must be a function when supplied');
@@ -111,6 +115,7 @@ function createRegistration(options) {
     registry,
     repoStates,
     prepareRepo: opened.prepareRepo ?? null,
+    captureRepoAsync,
     recordForRoot: repoRecordForRoot,
     onSettled: reconcileSettledRepo,
   });
@@ -167,13 +172,14 @@ function createRegistration(options) {
     for (const { scopeId } of memory.allBindings()) {
       if (!liveIds.has(scopeId)) memory.dropScope(scopeId);
     }
-    for (const [rootId] of [...lenses]) {
-      const row = observer.listRoots().find((member) => member.rootId === rootId);
-      if (!row) {
-        lenses.delete(rootId);
-        continue;
-      }
-      const record = rootRecordOf(rootId);
+    // Retirement is decided from durable witness bindings, not from the
+    // in-memory lens map. A fresh runtime has no lenses yet, but it may have
+    // restarted halfway through retiring an adopted tree; letting that old
+    // observer root survive would make its next start look like a second
+    // tree. The binding is the evidence that survives the crash, so it is
+    // the only honest starting point.
+    for (const row of observer.listRoots()) {
+      const record = rootRecordOf(row.rootId);
       const nestedRepoScope = row.kind === 'repo' && record?.type === 'repo.git'
         && observer.listRoots().some((other) => other.rootId !== row.rootId
           && row.path.startsWith(`${other.path}/`));
@@ -185,15 +191,18 @@ function createRegistration(options) {
         // sweep above collects. The reverse order once minted a duplicate
         // tree: an unbound living root looks like fresh ground.
         const family = observer.listRoots()
-          .filter((member) => member.rootId === rootId || member.path.startsWith(`${row.path}/`));
+          .filter((member) => member.rootId === row.rootId || member.path.startsWith(`${row.path}/`));
         for (const member of family) {
-          if (member.rootId !== rootId) observer.removeRoot(member.rootId);
+          if (member.rootId !== row.rootId) observer.removeRoot(member.rootId);
         }
-        observer.removeRoot(rootId);
-        memory.dropScope(rootId);
-        lenses.delete(rootId);
+        observer.removeRoot(row.rootId);
+        memory.dropScope(row.rootId);
+        lenses.delete(row.rootId);
       }
     }
+    for (const [rootId] of [...lenses]) {
+      if (!observer.listRoots().some((row) => row.rootId === rootId)) lenses.delete(rootId);
+    }
     for (const root of treeRoots()) {
       if (lenses.has(root.rootId)) continue;
       const lens = createEvidence({ observer, registry, memory, rootId: root.rootId, classify });
@@ -438,8 +447,14 @@ function createRegistration(options) {
    * same territory), so the only missing fact is the repo's atomic
    * Card+Checkpoint-backed identity birth.
    */
-  function registerRepositoryInsideCoveredGround(ground, { identityAt = null, suppressJournal = false } = {}) {
+  function registerRepositoryInsideCoveredGround(ground, {
+    identityAt = null,
+    suppressJournal = false,
+    preparedRepoAt = null,
+    watcherAlreadyHeld = false,
+  } = {}) {
     let root = observer.listRoots().find((candidate) => candidate.path === ground) || null;
+    const rootAlreadyExisted = root !== null;
     if (!root) root = observer.enrollRoot(ground, { scan: false, watch: false });
     if (root.kind !== 'repo') {
       throw new Error(`expected Git repository ground at ${ground}, found ${root.kind}`);
@@ -462,8 +477,12 @@ function createRegistration(options) {
       return { rootPath: ground, record };
     }
 
+    let watcherHeld = watcherAlreadyHeld;
     try {
-      requireWatchBirth(root);
+      if (!watcherHeld) {
+        requireWatchBirth(root);
+        watcherHeld = true;
+      }
       assertWitnessed({ observer, registry, memory });
       const register = () => registry.transaction(() => {
         registerTree({
@@ -475,6 +494,7 @@ function createRegistration(options) {
           repoStates,
           repoStateAt,
           identityAt,
+          preparedRepoAt,
         });
         assertWatchedThroughCommit(root.path);
       });
@@ -483,23 +503,225 @@ function createRegistration(options) {
     } catch (error) {
       // A root that existed only because the outer watcher discovered its
       // territory must remain coverage after a refused explicit admission;
-      // do not remove it (the parent still owns the OS watcher).  A root this
-      // call itself enrolled has no durable identity and can safely retire.
+      // do not remove it (the parent still owns the OS watcher).  Release a
+      // held doorbell before returning the refusal; otherwise a failed
+      // registration would silently turn a healthy observer territory into
+      // a permanently mute one.  A root this call itself enrolled has no
+      // durable identity and can safely retire in the outer caller.
+      if (watcherHeld && rootAlreadyExisted) observer.start(root.rootId);
       throw error;
     }
 
-    const startWatch = () => {
-      observer.start(root.rootId);
-      ensureTrees();
-      reconcileInitialRepoWorktrees(root.path);
-      flushIfDirty();
-      requireLiveWatchers(root.path);
-    };
+    const startWatch = () => startRepositoryFromBaseline(root);
     if (suppressJournal) registry.withoutJournal(startWatch);
     else startWatch();
     return { rootPath: root.path, record: rootRecordOf(root.rootId) };
   }
 
+  /**
+   * A repo's initial Card + Checkpoint is not preliminary data awaiting a
+   * generic filesystem census: it *is* the first complete state. Start its
+   * follower while the watcher is held, then release the watcher without
+   * scanning every worktree child a second time. The next raw ding reaches
+   * the follower and exactly one settled state authorizes the ordinary child
+   * reconciliation. This keeps Register synchronous without duplicating
+   * either its cargo capture or its initial Detect pass.
+   */
+  function startRepositoryFromBaseline(root) {
+    // Structural registration already knows every nested repo boundary from
+    // the same assignment that packed its state. Install those territories
+    // directly from that identity graph; discovering them again by walking
+    // files would reintroduce the duplicate initial census this adapter
+    // exists to avoid.
+    const territories = [];
+    for (const record of registry.activeByType('repo.git')) {
+      const repoPath = addressOf(record.uuid);
+      if (repoPath === null || (repoPath !== root.path && !repoPath.startsWith(`${root.path}/`))) continue;
+      let territory = observer.listRoots().find((candidate) => candidate.path === repoPath) ?? null;
+      if (!territory) territory = observer.enrollRoot(repoPath, { scan: false, watch: false });
+      if (territory.kind !== 'repo') {
+        throw new Error(`registered repository ${repoPath} is no longer Git ground before Watch began`);
+      }
+      memory.bind(territory.rootId, territory.rootId, record.uuid);
+      if (!lenses.has(territory.rootId)) {
+        // A repo baseline is already authoritative state. The lens exists so
+        // callers can address the tree, but does not reconcile absent
+        // observer child rows as if that state had never been captured.
+        lenses.set(territory.rootId, createEvidence({
+          observer, registry, memory, rootId: territory.rootId, classify,
+        }));
+      }
+      territories.push(territory);
+    }
+    territories.sort((left, right) => left.path.length - right.path.length);
+    // The outer raw watcher must forward a nested repo's first later ding
+    // to that nested follower. Its territory set is normally filled by a
+    // census; structural registration already supplied the same boundaries,
+    // so refresh the forwarding map without performing that census.
+    for (const territory of territories) observer.refreshRepoTerritories(territory.rootId);
+    repoFollowers.sync({ startOnBirth: false });
+    for (const territory of territories) observer.start(territory.rootId, { census: false });
+    requireLiveWatchers(root.path);
+
+    // Edge discovery is a distinct registration promise. It only reads link
+    // surfaces (repo roots answer that with a link census), never converts
+    // the just-packed worktree into generic per-file evidence. The newly
+    // reached roots then receive their usual identity/lens setup.
+    edgesDirty = true;
+    tryFollow();
+    ensureTrees();
+    repoFollowers.sync({ startOnBirth: false });
+  }
+
+  /**
+   * Plan all repository cargo under one selected root before its identity
+   * transaction begins.  This work can be slow (a Card contains a Git bundle
+   * and its Checkpoint may contain real work), but it creates no registry
+   * fact.  Its watcher is already held by the caller, so every ding remains
+   * available to Start's catch-up once the plan commits.
+   *
+   * Every nested repo has its own identity map and own state parcel.  The
+   * outer map names the nested repo boundary; the nested parcel names its
+   * children.  That is the same travel law used later by Send, merely used
+   * here for the first state.
+   */
+  async function prepareRepositoryPlans(root, identityAt) {
+    if (typeof captureRepoAsync !== 'function') return null;
+    const plans = new Map(); // absolute repo path -> { state, assignment }
+
+    const assertState = (repoPath, state) => {
+      if (state?.busy) {
+        throw new Error(`cannot register ${repoPath}: Git is unsettled (${state.busy})`);
+      }
+      if (!state?.stateId || !state.cardId || !state.checkpointId) {
+        throw new Error(`cannot register ${repoPath}: Git did not produce a Card + Checkpoint state`);
+      }
+      return state;
+    };
+
+    const planRepo = async (repoPath, rootRelativePath) => {
+      const assignment = await collectWorktreeIdentityAsync(repoPath, {
+        shouldEnroll: observer.shouldEnroll,
+        identityFor: (repoRelativePath) => identityAt?.(
+          rootRelativePath ? `${rootRelativePath}/${repoRelativePath}` : repoRelativePath,
+        )?.uuid || null,
+      });
+      const state = assertState(repoPath, await captureRepoAsync(repoPath, {
+        identity: transportIdentity(assignment),
+      }));
+      plans.set(repoPath, { state, assignment });
+      for (const [entryRelativePath, entry] of assignment) {
+        if (entry.type !== 'repo.git') continue;
+        await planRepo(
+          path.join(repoPath, entryRelativePath),
+          rootRelativePath ? `${rootRelativePath}/${entryRelativePath}` : entryRelativePath,
+        );
+      }
+    };
+
+    // A direct repo is its own initial state.  An ordinary folder can still
+    // contain repo boundaries, and those must never fall back to a blocking
+    // main-thread capture just because the user selected their parent.
+    if (root.kind === 'repo') {
+      await planRepo(root.path, '');
+      return (repoPath) => plans.get(repoPath) || null;
+    }
+
+    let visited = 0;
+    const yieldIfNeeded = async () => {
+      visited += 1;
+      if (visited % 256 !== 0) return;
+      await new Promise((resolve) => setImmediate(resolve));
+    };
+    const discover = async (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) {
+        await yieldIfNeeded();
+        const entryPath = path.join(dirPath, entry.name);
+        const entryRelativePath = relativePath ? `${relativePath}/${entry.name}` : entry.name;
+        if (!observer.shouldEnroll(entryPath)) continue;
+        let stat;
+        try {
+          stat = fs.lstatSync(entryPath);
+        } catch {
+          continue;
+        }
+        if (!stat.isDirectory()) continue;
+        if (gitDirTruth(entryPath) === 'present') await planRepo(entryPath, entryRelativePath);
+        else await discover(entryPath, entryRelativePath);
+      }
+    };
+    await discover(root.path, '');
+    return (repoPath) => plans.get(repoPath) || null;
+  }
+
+  /**
+   * The public operation remains synchronous in its result: it returns only
+   * after the watcher, complete identity tree, state parcel, and journal all
+   * agree.  Its preparation is asynchronous solely so large immutable cargo
+   * cannot freeze the HTTP runtime that owns the watcher proof.
+   */
+  async function addAsync(targetPath, options = {}) {
+    const identityAt = options.identityAt ?? null;
+    const suppressJournal = options.suppressJournal === true;
+    if (identityAt !== null && typeof identityAt !== 'function') {
+      throw new Error('addAsync identityAt must be a function when supplied');
+    }
+    if (typeof captureRepoAsync !== 'function') return add(targetPath, options);
+
+    let address;
+    let ground;
+    try {
+      const parent = fs.realpathSync(path.dirname(targetPath));
+      address = path.join(parent, path.basename(targetPath));
+      ground = fs.lstatSync(address).isSymbolicLink() ? address : fs.realpathSync(address);
+    } catch (error) {
+      if (error.code !== 'ENOENT' && error.code !== 'ENOTDIR') throw error;
+      throw refusal(`refusing to add ${targetPath}: there is no ground at that address`);
+    }
+
+    // Links intentionally retain link semantics even if their target is a
+    // repo.  That is the same address law as `add`, not a hidden realpath.
+    const rootKind = fs.lstatSync(ground).isDirectory() && gitDirTruth(ground) === 'present'
+      ? 'repo'
+      : null;
+    if (rootKind !== 'repo') return add(targetPath, options);
+
+    let root = observer.listRoots().find((candidate) => candidate.path === ground) || null;
+    const rootAlreadyExisted = root !== null;
+    if (!root) root = observer.enrollRoot(ground, { scan: false, watch: false });
+    if (root.kind !== 'repo') return add(targetPath, options);
+    const bound = memory.boundTo(root.rootId);
+    if (bound !== undefined) return add(targetPath, options);
+
+    let watcherHeld = false;
+    try {
+      requireWatchBirth(root);
+      watcherHeld = true;
+      const preparedRepoAt = await prepareRepositoryPlans(root, identityAt);
+      return registerRepositoryInsideCoveredGround(ground, {
+        identityAt,
+        suppressJournal,
+        preparedRepoAt,
+        watcherAlreadyHeld: true,
+      });
+    } catch (error) {
+      // No identity was committed before preparation.  A new root is only
+      // this failed request's temporary witness; an existing discovered root
+      // stays covered, but its held doorbell must be released.
+      if (!rootAlreadyExisted) observer.removeRoot(root.rootId);
+      else if (watcherHeld) observer.start(root.rootId);
+      throw error;
+    }
+  }
+
   /** Real ground -> the UUID of the entity that owns it, across trees. */
   function resolveGround(real) {
     const home = treeRootCovering(real);
@@ -707,6 +929,7 @@ function createRegistration(options) {
     // mutation. Keep the whole first Watch/Detect transition inside the
     // existing journal boundary used for the seeded structural bind.
     const startWatch = () => {
+      if (root.kind === 'repo') return startRepositoryFromBaseline(root);
       observer.start(root.rootId);
       ensureTrees();
       reconcileInitialRepoWorktrees(root.path);
@@ -746,6 +969,30 @@ function createRegistration(options) {
     return normalized.map(({ targetPath, identityAt }) => add(targetPath, { identityAt }));
   }
 
+  /** Same declared batch contract as `addMany`, while allowing a large Git
+   * cargo plan to run off the runtime event loop.  Entries remain ordered and
+   * individually durable: this adds no second transaction model. */
+  async function addManyAsync(entries, { suppressJournal = false } = {}) {
+    if (!Array.isArray(entries) || entries.length === 0) {
+      throw new Error('addManyAsync requires one or more target paths');
+    }
+    const normalized = entries.map((entry) => {
+      if (typeof entry === 'string') return { targetPath: entry, identityAt: null };
+      if (!entry || typeof entry !== 'object' || typeof entry.targetPath !== 'string') {
+        throw new Error('addManyAsync entries must be paths or { targetPath, identityAt }');
+      }
+      if (entry.identityAt !== undefined && entry.identityAt !== null && typeof entry.identityAt !== 'function') {
+        throw new Error('addManyAsync identityAt must be a function when supplied');
+      }
+      return { targetPath: entry.targetPath, identityAt: entry.identityAt ?? null };
+    });
+    const results = [];
+    for (const { targetPath, identityAt } of normalized) {
+      results.push(await addAsync(targetPath, { identityAt, suppressJournal }));
+    }
+    return results;
+  }
+
   /** Reconcile one already-watched tree after the platform has materialized
    * a newly declared exact default inside it. This is deliberately not part
    * of ordinary re-registration: the caller must have already named the
@@ -783,6 +1030,13 @@ function createRegistration(options) {
     return clean;
   }
 
+  // Reopen every persisted observer before the first reconciliation.  An
+  // identity database survives a runtime restart; its Watch proof must too.
+  // `start()` opens physical owners and restores covered roots through the
+  // same coverage law as a new registration, then its census catches up on
+  // dings that occurred while this process was absent.
+  observer.start();
+
   // Startup is the same act as running — the one convergence pass,
   // nothing less. The projection must not wait for an event: a
   // rendering whose deletion was detected before a crash is equal
@@ -795,7 +1049,9 @@ function createRegistration(options) {
     // observer bindings remain private to this registration composition.
     registry,
     add,
+    addAsync,
     addMany,
+    addManyAsync,
     reconcileDeclared,
 
     /**

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

@@ -25,12 +25,23 @@
 
 const { createFollower, createCaptureWorker } = require('../repocard');
 
-function createRepoFollowers({ observer, registry, repoStates, recordForRoot, onSettled, prepareRepo = null }) {
+function createRepoFollowers({
+  observer,
+  registry,
+  repoStates,
+  recordForRoot,
+  onSettled,
+  prepareRepo = null,
+  captureRepoAsync = null,
+}) {
   if (!observer || !registry || !repoStates || typeof recordForRoot !== 'function'
     || typeof onSettled !== 'function') {
     throw new Error('createRepoFollowers requires { observer, registry, repoStates, recordForRoot, onSettled }');
   }
 
+  // Production cloud-cargo captures are already complete in the service's
+  // dedicated worker (bundle -> transport -> immutable content head).  The
+  // local/test fallback owns its lightweight capture worker here.
   const worker = createCaptureWorker();
   const followers = new Map(); // observer rootId -> { path, uuid, follower }
   let stopped = false;
@@ -65,7 +76,16 @@ function createRepoFollowers({ observer, registry, repoStates, recordForRoot, on
    * move, be adopted, or cease being a repository; in every case the old
    * follower is closed before a replacement can speak.
    */
-  function sync() {
+  /**
+   * A freshly registered repo already has a Card + Checkpoint baseline and
+   * its watcher is still held.  Its follower must exist before that hold is
+   * released, but it must not immediately spend a second pair of full Git
+   * captures just to rediscover the state it was born with.  Any ding heard
+   * during the release rings this follower normally.  A cold runtime restart
+   * keeps the default (`startOnBirth: true`) and independently proves the
+   * persisted baseline against disk.
+   */
+  function sync({ startOnBirth = true } = {}) {
     if (stopped) return;
     const roots = observer.listRoots().filter((root) => root.kind === 'repo');
     const live = new Set(roots.map((root) => root.rootId));
@@ -102,13 +122,17 @@ function createRepoFollowers({ observer, registry, repoStates, recordForRoot, on
           // 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, {
+          const options = {
             withBundle,
             suspects,
             previousUntracked: previous?.checkpoint?.untracked?.map(
               ({ path: rel, mode, sha256 }) => ({ path: rel, mode, sha256 }),
             ) ?? null,
-          });
+          };
+          if (withBundle && captureRepoAsync) {
+            return captureRepoAsync(repoPath, { entityUuid: record.uuid, ...options });
+          }
+          const captured = await worker.capture(repoPath, options);
           return withBundle && !captured?.busy
             ? prepareRepo(captured, { entityUuid: record.uuid })
             : captured;
@@ -128,9 +152,10 @@ function createRepoFollowers({ observer, registry, repoStates, recordForRoot, on
         },
       });
       followers.set(root.rootId, { path: root.path, uuid: record.uuid, follower });
-      // Birth captures the initial Card + Checkpoint. The follower owns its
-      // retry policy; registration must not invent an alternate Git scanner.
-      void follower.start();
+      // A restart catches up from disk; a fresh Register has already
+      // captured its exact baseline and will receive held doorbells when
+      // Watch releases, so it does not duplicate the expensive birth pair.
+      if (startOnBirth) void follower.start();
     }
   }
 

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

@@ -58,7 +58,7 @@ 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 { capture, apply: applyRepo, createCaptureWorker } = require('../repocard');
 const { transportBytes, localState, unpack } = require('./repo-states');
 const { machineId, userId } = require('../workspace/identity');
 
@@ -99,6 +99,11 @@ function createRegistrationService({
     handle.pragma('synchronous = NORMAL');
   }
   const entityContent = createEntityContent({ dir });
+  // Git bundles and their encoded immutable transports can be hundreds of
+  // megabytes.  Build and chunk them off the runtime thread so its local
+  // health endpoint and already-live watchers stay responsive throughout a
+  // synchronous Register operation.
+  const cargoCaptureWorker = createCaptureWorker();
   // 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.
@@ -142,6 +147,27 @@ function createRegistrationService({
     return localState(captured, artifact.contentHash);
   }
 
+  async function captureRepoAsync(repoPath, {
+    identity = null,
+    entityUuid = null,
+    suspects = null,
+    previousUntracked = null,
+  } = {}) {
+    const transportIdentity = identity ?? (entityUuid ? worktreeIdentity(entityUuid) : null);
+    const captured = await cargoCaptureWorker.capture(repoPath, {
+      withBundle: true,
+      suspects,
+      previousUntracked,
+      cargo: { dir, identity: transportIdentity },
+    });
+    if (captured?.busy) return captured;
+    if (!captured?.stateId || !captured?.transportVersion) {
+      throw new Error(`repo cargo capture did not produce a state and immutable transport: ${repoPath}`);
+    }
+    repoTransportHeads.set(captured.stateId, captured.transportVersion);
+    return captured;
+  }
+
   // Entity-cloud needs only logical ancestry to choose a content plan. It
   // never owns a watcher or address; this facade is available after the
   // registration boundary is constructed below.
@@ -174,6 +200,7 @@ function createRegistrationService({
       sentinelPath: path.join(dir, 'identity.epoch'),
       journal: entityCloud.journal,
       captureRepo: (repoPath, options) => prepareRepo(capture(repoPath, { withBundle: true }), options),
+      captureRepoAsync,
       prepareRepo,
       repoStateAt: (uuid) => importedRepoStates.get(uuid) || null,
     }),
@@ -972,9 +999,9 @@ function createRegistrationService({
       // signed-out registration is allowed.
       const cloudActive = entityCloud.replica()?.state === 'active';
       if (!cloudActive || estimatedRegistrationRecords(targetPath) < ATOMIC_REGISTRATION_THRESHOLD) {
-        return boundary.current.add(targetPath);
+        return (await boundary.current.addManyAsync([targetPath]))[0];
       }
-      const result = boundary.current.registry.withoutJournal(() => boundary.current.add(targetPath));
+      const result = (await boundary.current.addManyAsync([targetPath], { suppressJournal: true }))[0];
       entityCloud.replaceSnapshot(boundary.current.registry.syncRecords());
       return result;
     },
@@ -988,13 +1015,13 @@ function createRegistrationService({
         && targetPaths.some((targetPath) => (
           estimatedRegistrationRecords(targetPath) >= ATOMIC_REGISTRATION_THRESHOLD
         ));
-      if (!needsAtomicReplacement) return boundary.current.addMany(targetPaths);
+      if (!needsAtomicReplacement) return boundary.current.addManyAsync(targetPaths);
       // 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));
+        return await boundary.current.addManyAsync(targetPaths, { suppressJournal: true });
       } finally {
         entityCloud.replaceSnapshot(boundary.current.registry.syncRecords());
       }
@@ -1049,6 +1076,7 @@ function createRegistrationService({
       closed = true;
       observer.stop();       // doorbells and their timers
       boundary.current.stop(); // and the pass they may already have scheduled
+      void cargoCaptureWorker.close();
       evidenceDb.close();
       identityDb.close();
     },

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

@@ -23,7 +23,10 @@
  * although they have identical behavior today. A structural walk therefore
  * uses file.text as the content-free ordinary-file placeholder. The first
  * Detect pass immediately attests the actual bytes and corrects that
- * representation through the normal one-observation transition.
+ * representation through the first later settled repo reconciliation. The
+ * initial Card + Checkpoint is authoritative content state; repeating a
+ * generic per-file scan merely to refine this local physical label would
+ * duplicate that state and can freeze large registration.
  */
 
 const fs = require('fs');
@@ -91,6 +94,56 @@ function collectWorktreeIdentity(repoPath, { shouldEnroll, identityFor }) {
   return assignment;
 }
 
+/**
+ * The asynchronous twin of the identity walk.  It has exactly the same
+ * shape rules as `collectWorktreeIdentity`, but returns to Node between
+ * bounded batches.  A large initial repo registration may take time to
+ * inspect, yet its held watcher and the runtime's health endpoint must stay
+ * alive while that inspection is in flight.  This is planning only: no
+ * identity row exists until `registerTree` commits the finished plan.
+ */
+async function collectWorktreeIdentityAsync(repoPath, { shouldEnroll, identityFor, yieldEvery = 256 }) {
+  const assignment = new Map(); // repo-relative path -> { uuid, type }
+  let visited = 0;
+  const yieldIfNeeded = async () => {
+    visited += 1;
+    if (visited % yieldEvery !== 0) return;
+    await new Promise((resolve) => setImmediate(resolve));
+  };
+  const walk = async (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) {
+      await yieldIfNeeded();
+      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') await walk(entryPath, entryRelativePath);
+    }
+  };
+  await walk(repoPath, '');
+  return assignment;
+}
+
 function transportIdentity(assignment) {
   return [...assignment].map(([entryPath, { uuid, type }]) => ({ path: entryPath, uuid, type }));
 }
@@ -100,7 +153,17 @@ function transportIdentity(assignment) {
  * 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, repoStateAt = null }) {
+function registerTree({
+  root,
+  registry,
+  memory,
+  shouldEnroll,
+  captureRepo,
+  repoStates,
+  identityAt = null,
+  repoStateAt = null,
+  preparedRepoAt = null,
+}) {
   if (!root || !registry || !memory || typeof shouldEnroll !== 'function'
     || typeof captureRepo !== 'function' || !repoStates) {
     throw new Error('registerTree requires { root, registry, memory, shouldEnroll, captureRepo, repoStates }');
@@ -109,6 +172,9 @@ function registerTree({ root, registry, memory, shouldEnroll, captureRepo, repoS
   if (identityAt !== null && typeof identityAt !== 'function') {
     throw new Error('registerTree identityAt must be a function when supplied');
   }
+  if (preparedRepoAt !== null && typeof preparedRepoAt !== 'function') {
+    throw new Error('registerTree preparedRepoAt must be a function when supplied');
+  }
 
   function seeded(relativePath, { type, parentUUID, name, root: isRoot }) {
     const identity = identityAt?.(relativePath) || null;
@@ -151,6 +217,8 @@ function registerTree({ root, registry, memory, shouldEnroll, captureRepo, repoS
       const saved = repoStates.get(identity.uuid);
       if (saved?.stateId === identity.payloadVersion) return { state: saved, assignment: null };
     }
+    const prepared = preparedRepoAt?.(repoPath) || null;
+    if (prepared) return prepared;
     const assignment = collectWorktreeIdentity(repoPath, {
       shouldEnroll,
       identityFor: (repoRelativePath) => identityAt?.(
@@ -296,4 +364,4 @@ function registerDirectory(dirPath, parentUUID, {
   }
 }
 
-module.exports = { registerTree };
+module.exports = { collectWorktreeIdentityAsync, registerTree, transportIdentity };

package/runtime/scripts/amalgm-mcp/registry/evidence.js

@@ -622,7 +622,20 @@ function createEvidence(options) {
         const parentUuid = ensureDir(path.dirname(territory) === '.' ? '' : path.dirname(territory), root);
         const name = path.basename(territory);
         const at = registry.activeAt(parentUuid, name);
-        if (at?.type !== 'repo.git') continue;
+        if (at?.type === 'repo.git') continue;
+        const territoryRoot = observer.listRoots()
+          .find((row) => row.kind === 'repo' && row.path === path.join(groundPath, territory));
+        const arrivedRecord = arrivedTree(territoryRoot?.device, territoryRoot?.inode, REPO_TREE);
+        if (!arrivedRecord) continue;
+        // A Git territory is the repo-shaped form of the same adoption law
+        // directories use above. Its initial Card + Checkpoint already
+        // travels with the existing repo UUID, so the new observer root must
+        // adopt that identity — never mint or ignore a half-repository.
+        if (at) {
+          nowDivergent.set(territory, null); // two identity claims: decide neither
+          continue;
+        }
+        registry.move(arrivedRecord.uuid, { parentUUID: parentUuid, name });
       }
       // A lifted lens is the reverse transition on the same record.
       for (const { record, rel } of walkActive(root.uuid, '', [])) {

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

@@ -750,6 +750,13 @@ function createRegistry(options) {
     /** Full logical graph for cloud snapshots. Machine bindings and evidence
      * are intentionally absent. */
     syncRecords: () => store.allEntities().map(syncRecord),
+    /** Active records of one physical type. This is a query primitive for
+     * type adapters; it does not expose storage writes or weaken the single
+     * registry boundary. */
+    activeByType: (type) => {
+      if (!TYPES.has(type)) throw new Error(`unknown entity type ${JSON.stringify(type)}`);
+      return store.activeByType(type).map(record);
+    },
     /** Every registered tree's top record. */
     roots: () => store.activeRoots().map(record),
     /** Every active managed reference with the identity it targets. The

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

@@ -20,9 +20,31 @@ const { Worker, isMainThread, parentPort } = require('worker_threads');
 
 if (!isMainThread) {
   const { capture } = require('./capture');
+  const { createEntityContent } = require('../registration/entity-content');
+  const { transportBytes, localState } = require('../registration/repo-states');
+
+  /**
+   * A cloud-bound initial repo capture is deliberately completed here, not
+   * handed back as a giant Git bundle for the runtime thread to JSON-encode
+   * and chunk.  The runtime's job is to remain the responsive authority for
+   * Watch + Register; this worker owns the expensive, immutable cargo build.
+   * It returns only the bundle-free state plus its content head.
+   */
+  function captureCargo(repoPath, options) {
+    const cargo = options?.cargo;
+    if (!cargo || typeof cargo.dir !== 'string') return capture(repoPath, options);
+    const snap = capture(repoPath, { ...options, withBundle: true });
+    if (snap?.busy) return snap;
+    const content = createEntityContent({ dir: cargo.dir });
+    const artifact = content.captureBytes({
+      bytes: transportBytes(snap, Array.isArray(cargo.identity) ? cargo.identity : null),
+    });
+    return localState(snap, artifact.contentHash);
+  }
+
   parentPort.on('message', ({ id, repoPath, options }) => {
     try {
-      parentPort.postMessage({ id, snap: capture(repoPath, options) });
+      parentPort.postMessage({ id, snap: captureCargo(repoPath, options) });
     } catch (error) {
       parentPort.postMessage({ id, error: error?.message || String(error) });
     }

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

@@ -608,13 +608,17 @@ test('adding a repository registers its allowed tree and saves its initial Repoc
   assert.ok(initialState?.stateId, 'registration saved the initial Card + Checkpoint');
   assert.ok(initialState.checkpoint.untracked.some((file) => file.path === 'readme.md'),
     'the persisted baseline contains the actual working checkpoint, not only its hash');
+  const observerRoot = service.observer.listRoots().find((root) => root.path === repo);
+  assert.deepEqual(service.observer.filesForRoot(observerRoot.rootId), [],
+    'repo birth does not perform a second per-file census after its Card + Checkpoint is saved');
   assert.equal(tree.root().version, registered.version,
     'add returned only after the repo entity pointed at its saved baseline');
   const readme = tree.registry.activeAt(registered.uuid, 'readme.md');
   const src = tree.registry.activeAt(registered.uuid, 'src');
   assert.equal(readme.type, 'file.text');
   assert.equal(src.type, 'folder');
-  assert.equal(tree.registry.activeAt(src.uuid, 'blob.bin').type, 'file.binary');
+  assert.equal(tree.registry.activeAt(src.uuid, 'blob.bin').type, 'file.text',
+    'repo birth records structural leaf shape; the Card + Checkpoint owns its actual bytes without a second read');
   assert.equal(tree.registry.activeAt(registered.uuid, 'node_modules'), null,
     'the same enrollment policy excludes dependency trees inside repos');
   const initial = tree.root();
@@ -657,6 +661,28 @@ test('adding a repository registers its allowed tree and saves its initial Repoc
   assert.equal(tree.root().uuid, after.uuid);
 });
 
+test('a production repository register builds its immutable Git cargo off the runtime thread', async () => {
+  const service = makeService('repo-cargo-worker');
+  const repo = makeGround('repo-cargo-worker');
+  execFileSync('git', ['init', '-q'], { cwd: repo });
+  fs.writeFileSync(path.join(repo, 'history.md'), '# committed history\n');
+  execFileSync('git', ['add', '.'], { cwd: repo });
+  execFileSync('git', [
+    '-c', 'user.name=Amalgm Test',
+    '-c', 'user.email=amalgm-test@example.invalid',
+    'commit', '-qm', 'initial history',
+  ], { cwd: repo });
+
+  const { record } = await service.register(repo);
+  const state = service.registration.repoState(record.uuid);
+  assert.equal(record.type, 'repo.git');
+  assert.ok(state?.transportVersion, 'the saved state names one immutable transport object');
+  assert.equal(state.card.bundle, null,
+    'identity.db holds only bundle-free state; the worker left history in immutable content');
+  assert.ok(service.entityContent.bytes({ contentHash: state.transportVersion }).length > 0,
+    'the worker finished the transport before Register committed the repo head');
+});
+
 test('an edge-reached repository gets the same complete registration as a directly added repo', async () => {
   const service = makeService('edge-repo-card');
   const holder = makeGround('edge-repo-holder');
@@ -959,6 +985,25 @@ test('identity survives a real close-and-reopen over the same directory', async
   assert.equal(after, before, 'the tree keeps its permanent UUID across processes');
 });
 
+test('a restarted runtime reopens the persisted watcher before it reports the tree healthy', async () => {
+  const dir = path.join(tempRoot, 'state-reopen-watch');
+  const ground = makeGround('reopen-watch');
+  fs.writeFileSync(path.join(ground, 'notes.md'), 'persisted ground\n');
+
+  const first = createRegistrationService({ dir });
+  const registered = await first.register(ground);
+  first.close();
+
+  const reopened = createRegistrationService({ dir });
+  services.push(reopened);
+  const root = reopened.observer.status().find((entry) => entry.path === ground);
+  assert.ok(root, 'the original observer root survived the restart');
+  assert.equal(root.watching, true, 'the restarted runtime has a live Watch rail');
+  assert.equal(root.degraded, false);
+  assert.equal(reopened.registration.tree(ground).root().uuid, registered.record.uuid,
+    'the watcher reopened over the same permanent identity');
+});
+
 // --- the policies are the real ones ---------------------------------------
 
 test("amalgm's enrollment policy is in force, and refuses loudly", async () => {