amalgm 0.1.263 → 0.1.265

package/package.json

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

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

@@ -15,8 +15,10 @@
  * (its own future head and rail), never an identity boundary. Every
  * top-level enrolled ground — a workspace, a repository, a single file,
  * or an explicitly added link — is such a tree, with one evidence LENS
- * over its observer root (nested repo territories live INSIDE their
- * tree as repo.git records; they are never trees of their own). A
+ * over its observer root. A Git territory noticed inside another watched
+ * tree is observer-only until an explicit registration admits it; that
+ * selected repo is then a tree of its own even if the outer watcher covers
+ * its local address. A
  * TREE'S IDENTITY IS ITS UUID, PERMANENT; its root path is only the
  * current local address — lenses are keyed by the observer's rootId
  * (the witness), the observer rescues moved ground by physical
@@ -65,7 +67,8 @@ 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
 // retargeted pointer, repo ground moving under its card (a worktree
@@ -85,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');
@@ -108,16 +115,32 @@ function createRegistration(options) {
     registry,
     repoStates,
     prepareRepo: opened.prepareRepo ?? null,
+    captureRepoAsync,
     recordForRoot: repoRecordForRoot,
     onSettled: reconcileSettledRepo,
   });
 
-  /** Tree roots are the non-enclosed observer roots: a nested repo
-   * territory belongs to the tree that encloses it. */
+  /**
+   * A semantic tree is defined by its parentless identity record, never by
+   * directory containment.  `amalgm add` may materialize a cloud repo inside
+   * the local `workspaces/` directory, and `amalgm register` may select a
+   * repo already sitting there: both remain their own cloud root.  The outer
+   * workspace watcher supplies coverage, but it does not own the repo's
+   * Card + Checkpoint or identity tree.
+   *
+   * An unbound observer root is a tree candidate only when no other observer
+   * root physically encloses it.  That preserves the admission rule for a
+   * newly discovered nested repo: Watch can notice it, but only explicit
+   * registration can give it a cloud identity and state.
+   */
   function treeRoots() {
     const roots = observer.listRoots();
-    return roots.filter((root) => !roots.some((other) =>
-      other.rootId !== root.rootId && root.path.startsWith(`${other.path}/`)));
+    return roots.filter((root) => {
+      const record = rootRecordOf(root.rootId);
+      if (record) return record.parentUUID === null;
+      return !roots.some((other) => other.rootId !== root.rootId
+        && root.path.startsWith(`${other.path}/`));
+    });
   }
 
   function treeRootCovering(absPath) {
@@ -413,6 +436,239 @@ function createRegistration(options) {
     }
   }
 
+  /**
+   * A repository selected inside already-watched ground is still a new
+   * registered TREE, not a child record of the outer workspace.  The outer
+   * watcher already knows its territory (or this enrollment establishes that
+   * same territory), so the only missing fact is the repo's atomic
+   * Card+Checkpoint-backed identity birth.
+   */
+  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}`);
+    }
+
+    const bound = memory.boundTo(root.rootId);
+    if (bound !== undefined) {
+      const record = registry.record(bound);
+      if (record?.type !== 'repo.git') {
+        throw new Error(`repository watcher ${ground} is bound to non-repository entity ${bound}`);
+      }
+      if (record.parentUUID !== null) {
+        // This is the explicit nested-boundary case created as part of an
+        // already-registered enclosing repo.  It already has a complete
+        // Card+Checkpoint state and cannot be duplicated at one address.
+        requireLiveWatchers(ground);
+        return { rootPath: ground, record };
+      }
+      requireLiveWatchers(ground);
+      return { rootPath: ground, record };
+    }
+
+    let watcherHeld = watcherAlreadyHeld;
+    try {
+      if (!watcherHeld) {
+        requireWatchBirth(root);
+        watcherHeld = true;
+      }
+      assertWitnessed({ observer, registry, memory });
+      const register = () => registry.transaction(() => {
+        registerTree({
+          root,
+          registry,
+          memory,
+          shouldEnroll: observer.shouldEnroll,
+          captureRepo,
+          repoStates,
+          repoStateAt,
+          identityAt,
+          preparedRepoAt,
+        });
+        assertWatchedThroughCommit(root.path);
+      });
+      if (suppressJournal) registry.withoutJournal(register);
+      else register();
+    } 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).  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);
+    };
+    if (suppressJournal) registry.withoutJournal(startWatch);
+    else startWatch();
+    return { rootPath: root.path, record: rootRecordOf(root.rootId) };
+  }
+
+  /**
+   * 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);
@@ -542,6 +798,23 @@ function createRegistration(options) {
     }
     const covering = treeRootCovering(ground);
     if (covering) {
+      // A repository has a different state adapter from the workspace that
+      // happens to contain its local address.  Its observer territory may
+      // already exist, but it is not registered until this explicit command
+      // creates the parentless repo tree with its initial Card + Checkpoint.
+      // The same branch is used by cloud `add`: materialized repos commonly
+      // land under the default `workspaces/` directory while retaining their
+      // cloud root UUID and parentless graph position.
+      const isRepository = fs.lstatSync(ground).isDirectory() && gitDirTruth(ground) === 'present';
+      if (isRepository) {
+        const exact = observer.listRoots().find((root) => root.path === ground);
+        const known = exact && memory.boundTo(exact.rootId) !== undefined
+          ? registry.record(memory.boundTo(exact.rootId))
+          : null;
+        if (!known || known.type !== 'repo.git' || known.parentUUID === null) {
+          return registerRepositoryInsideCoveredGround(ground, { identityAt, suppressJournal });
+        }
+      }
       // This address is already registered ground. Its prior Register →
       // Watch transition remains the proof of its identity; repeating a
       // harmless "ensure the safe home exists" request must not rescan every
@@ -642,6 +915,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
@@ -679,6 +976,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
@@ -691,7 +995,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;
@@ -102,13 +113,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;

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

@@ -91,6 +91,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 +150,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 +169,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 +214,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 +361,4 @@ function registerDirectory(dirPath, parentUUID, {
   }
 }
 
-module.exports = { registerTree };
+module.exports = { collectWorktreeIdentityAsync, registerTree, transportIdentity };

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

@@ -80,7 +80,8 @@
  *     the folder record and every descendant's derived address follows,
  *     which is why folders reconcile before files, parents before
  *     children;
- *   - repo territories as repo.git type transitions on the slot's record;
+ *   - repo territories as observer truth, with an explicitly registered
+ *     repository boundary supplying the corresponding repo.git record;
  *   - ADOPTION, the channel law completing across trees: unclaimed
  *     ground wearing the physical identity of an orphaned top-level tree
  *     is that tree's arrival — one lawful parent update on its
@@ -604,23 +605,24 @@ function createEvidence(options) {
       };
       settleClaims(claimsOf(desiredDirs, 'dir'), 'dir');
 
-      // Territories after folder continuity, before file ground: a
-      // boundary is a repo.git type transition on the slot's record, and
-      // the slot must already be where its folder channel says it is.
+      // Territories after folder continuity, before file ground.  A Git
+      // boundary is NOT ordinary filesystem evidence: every repo.git record
+      // needs a Card + Checkpoint state and immutable transport before it can
+      // travel.  This generic lens has neither, so it may only recognize a
+      // boundary that the registration adapter already made whole.  An
+      // unregistered repository remains a local observer territory until
+      // `amalgm register <repo>` admits it through that adapter.
+      //
+      // This is deliberately not a convenience gate.  Letting this layer
+      // mint or promote repo.git would create an identity record whose cloud
+      // head names no state — the exact invalid half-repository the cloud
+      // contract rejects.  Folders and files are evidence-shaped; Git is a
+      // type-specific state carrier.
       for (const territory of [...territories].sort()) {
         const parentUuid = ensureDir(path.dirname(territory) === '.' ? '' : path.dirname(territory), root);
         const name = path.basename(territory);
         const at = registry.activeAt(parentUuid, name);
-        if (!at) {
-          // Adoption before birth here too: a registered top-level repo
-          // TREE that moved in arrives as its own record, never a fresh
-          // territory record. The enclosed observer root's identity is
-          // the evidence — the same physical dir the orphaned tree owns.
-          const enclosed = observer.listRoots().find((row) => row.path === path.join(groundPath, territory));
-          const arrivedRecord = enclosed ? arrivedTree(enclosed.device, enclosed.inode, REPO_TREE) : null;
-          if (arrivedRecord) registry.move(arrivedRecord.uuid, { parentUUID: parentUuid, name });
-          else registry.create({ type: 'repo.git', parentUUID: parentUuid, name });
-        } else if (at.type !== 'repo.git') registry.changeType(at.uuid, 'repo.git');
+        if (at?.type !== 'repo.git') continue;
       }
       // A lifted lens is the reverse transition on the same record.
       for (const { record, rel } of walkActive(root.uuid, '', [])) {

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/entity-materialization.test.js

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

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

@@ -657,6 +657,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');
@@ -724,6 +746,45 @@ test('a nested repository has its own baseline and watcher, while its tree remai
   assert.equal(tree.registry.activeAt(src.uuid, 'live.js').type, 'file.text');
 });
 
+test('a repo discovered inside watched workspace ground stays unregistered until explicit register gives it one complete repo root', async () => {
+  const service = makeService('workspace-repo-admission');
+  const workspace = makeGround('workspace-repo-admission');
+  const { record: workspaceRecord } = await service.register(workspace);
+  const repo = path.join(workspace, 't3code');
+  fs.mkdirSync(repo);
+  execFileSync('git', ['init', '-q'], { cwd: repo });
+  fs.writeFileSync(path.join(repo, 'readme.md'), '# T3\n');
+
+  // This is the production ordering that convicted the live Fly run: the
+  // outer workspace watcher discovers a newly cloned repository first.
+  const workspaceRoot = service.observer.listRoots().find((root) => root.path === workspace);
+  service.observer.scanNow(workspaceRoot.rootId);
+  await new Promise((resolve) => setImmediate(resolve));
+  service.registration.flushIfDirty();
+
+  const territory = service.observer.listRoots().find((root) => root.path === repo);
+  assert.equal(territory?.kind, 'repo', 'Watch knows the local Git territory');
+  assert.notEqual(
+    service.registration.tree(workspace).registry.activeAt(workspaceRecord.uuid, 't3code')?.type,
+    'repo.git',
+    'generic filesystem evidence never mints a half-repository with no Card + Checkpoint',
+  );
+
+  const { record } = await service.register(repo);
+  assert.equal(record.type, 'repo.git');
+  assert.equal(record.parentUUID, null,
+    'selected repo is its own cloud tree even though its local address is inside workspaces');
+  assert.equal(service.registration.tree(repo).root().uuid, record.uuid,
+    'the nested observer root now witnesses that selected tree');
+  assert.ok(service.registration.repoState(record.uuid)?.stateId,
+    'its identity and initial Card + Checkpoint were committed together');
+  assert.equal(
+    service.observer.status().some((row) => row.path === repo && row.watching && !row.degraded),
+    true,
+    'the selected repo is live after the atomic registration',
+  );
+});
+
 test('a reopened repo watcher resumes from the saved Card + Checkpoint baseline', async () => {
   const service = makeService('repo-reopen');
   const repo = makeGround('repo-reopen');
@@ -920,6 +981,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 () => {