amalgm 0.1.257 → 0.1.259

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

@@ -47,6 +47,10 @@ const Database = require('better-sqlite3');
 const { STORAGE_DIR } = require('../config');
 const { ensureDir } = require('../lib/storage');
 const { ensureUserHome } = require('../lib/layout');
+const {
+  materializeSystemToolArtifacts,
+  migrateLegacyToolboxCatalog,
+} = require('../toolbox/artifacts');
 const { createObserver } = require('../observer');
 const { shouldEnroll } = require('../workspace/tree/inclusion');
 const { classifyFile } = require('./classify');
@@ -58,8 +62,8 @@ const { transportBytes, localState, unpack } = require('./repo-states');
 const { machineId, userId } = require('../workspace/identity');
 
 const ENTITIES_DIR = path.join(STORAGE_DIR, 'entities');
-const USER_HOME_CLOUD_CONTRACT = 'amalgm-user-home@1';
-const USER_HOME_CLOUD_SCHEMA_VERSION = 1;
+const USER_HOME_CLOUD_CONTRACT = 'amalgm-user-home@2';
+const USER_HOME_CLOUD_SCHEMA_VERSION = 2;
 const ATOMIC_REGISTRATION_THRESHOLD = 500;
 
 let live = null;
@@ -260,6 +264,19 @@ function createRegistrationService({
    */
   async function bootstrapUserHome({ identitySnapshot = null } = {}) {
     const declaration = ensureUserHome(homeDir);
+    // Materialize every built-in tool before the shared registration boundary
+    // first sees `toolbox/`. Each file is an exact managed child; user tools
+    // remain ordinary sibling files. A legacy aggregate is moved outside the
+    // watched tree only after per-tool replacements exist.
+    const toolbox = declaration.roots.find((entry) => entry.key === 'toolbox');
+    if (!toolbox) throw new Error('declared user-home is missing its toolbox root');
+    const migrated = migrateLegacyToolboxCatalog({ toolboxDir: toolbox.path });
+    const systemTools = materializeSystemToolArtifacts({ toolboxDir: toolbox.path });
+    declaration.materializedExactPaths = [
+      ...(declaration.materializedExactPaths || []),
+      ...(migrated.artifactPaths || []).map((target) => path.relative(homeDir, target).split(path.sep).join('/')),
+      ...(systemTools.changedRelativePaths || []),
+    ];
     const seeds = identitySeeds(identitySnapshot, declaration);
     const addedRoots = boundary.current.addMany(declaration.roots.map((entry) => ({
       targetPath: entry.path,
@@ -274,25 +291,50 @@ function createRegistrationService({
       };
     });
 
-    const system = roots.find((entry) => entry.key === 'system');
-    if (!system) throw new Error('declared user home has no system root');
-    const tree = boundary.current.tree(system.path);
-    if (!tree?.root()) throw new Error(`declared system root was not registered: ${system.path}`);
-
-    const recordAt = (relativePath) => {
+    const recordAt = (rootKey, relativePath, { required = true } = {}) => {
+      const root = roots.find((entry) => entry.key === rootKey);
+      if (!root) throw new Error(`declared user-home root was not registered: ${rootKey}`);
+      const tree = boundary.current.tree(root.path);
+      if (!tree?.root()) throw new Error(`declared user-home root was not registered: ${root.path}`);
       let record = tree.root();
       for (const name of relativePath.split('/')) {
         record = tree.registry.activeAt(record.uuid, name);
-        if (!record) throw new Error(`declared user-home target was not registered: ${relativePath}`);
+        if (!record) {
+          if (!required) return null;
+          throw new Error(`declared user-home target was not registered: ${rootKey}/${relativePath}`);
+        }
       }
       return record;
     };
 
+    // An upgraded installation can already watch an older declared root.
+    // Re-registering that root must remain only an availability check, so the
+    // narrow exception is a root holding an exact node that the layout just
+    // materialized or that the registry proves missing. Detect and Record
+    // still create/update its identity through the shared boundary.
+    const rootsToReconcile = new Set((declaration.materializedExactPaths || [])
+      .map((relativePath) => relativePath.split('/')[0]));
+    for (const entry of declaration.exactManaged) {
+      if (entry.relativePath === entry.rootKey) continue;
+      const relativePath = entry.relativePath.slice(entry.rootKey.length + 1);
+      if (!recordAt(entry.rootKey, relativePath, { required: false })) {
+        rootsToReconcile.add(entry.rootKey);
+      }
+    }
+    for (const rootKey of rootsToReconcile) {
+      const root = roots.find((candidate) => candidate.key === rootKey);
+      if (!root) throw new Error(`declared user-home root was not registered: ${rootKey}`);
+      boundary.current.reconcileDeclared(root.path);
+      roots = roots.map((candidate) => candidate.key === rootKey
+        ? { ...candidate, record: boundary.current.tree(candidate.path).root() }
+        : candidate);
+    }
+
     let exactManaged = declaration.exactManaged.map((entry) => {
       const root = roots.find((candidate) => candidate.key === entry.rootKey);
       const isRoot = entry.relativePath === entry.rootKey;
       const relativePath = isRoot ? '' : entry.relativePath.slice(entry.rootKey.length + 1);
-      const record = isRoot ? root?.record : recordAt(relativePath);
+      const record = isRoot ? root?.record : recordAt(entry.rootKey, relativePath);
       if (!record) throw new Error(`declared user-home managed target was not registered: ${entry.relativePath}`);
       return {
         key: entry.key,
@@ -767,6 +809,66 @@ function createRegistrationService({
     }
   }
 
+  /** The status surface composes each layer's own facts without creating a
+   * second registry or treating local paths as cloud metadata.  A cloud-only
+   * catalog record is intentionally visible with `localPath: null`; only
+   * `amalgm add` creates a watcher binding for it. */
+  function status() {
+    const cloud = entityCloud.status();
+    const localRecords = boundary.current.registry.syncRecords();
+    const localByUuid = new Map(localRecords.map((record) => [record.uuid, record]));
+    const cloudByUuid = new Map(cloud.catalog.records.map((record) => [record.uuid, record]));
+    function cloudPathOf(uuid) {
+      const names = [];
+      const seen = new Set();
+      let record = cloudByUuid.get(uuid) || null;
+      while (record) {
+        if (seen.has(record.uuid)) return null;
+        seen.add(record.uuid);
+        names.unshift(record.name);
+        if (record.parentUUID === null) break;
+        record = cloudByUuid.get(record.parentUUID) || null;
+        if (!record) return null;
+      }
+      return names.length > 0 ? names.join('/') : null;
+    }
+    const roots = observer.status().map((root) => {
+      const tree = boundary.current.tree(root.path);
+      const record = tree ? tree.root() : null;
+      return {
+        uuid: record?.uuid || null,
+        path: root.path,
+        kind: root.kind,
+        watching: root.watching,
+        degraded: root.degraded,
+        addressWatching: root.addressWatching,
+        addressDegraded: root.addressDegraded,
+      };
+    });
+    const rootByUuid = new Map(roots.filter((root) => root.uuid !== null).map((root) => [root.uuid, root]));
+    const uuids = new Set([...localByUuid.keys(), ...cloudByUuid.keys()]);
+    const entities = [...uuids].sort().map((uuid) => {
+      const local = localByUuid.get(uuid) || null;
+      const record = cloudByUuid.get(uuid) || local;
+      let localPath = null;
+      if (local) {
+        try { localPath = boundary.current.addressOf(uuid); } catch {}
+      }
+      return {
+        ...record,
+        // A local journal projects its intent into the catalog before the
+        // gateway acknowledges it.  Call that fact `catalogued`, not
+        // `cloudBacked`: the enclosing cloud summary says whether the
+        // catalog is actually pinned to an authoritative current head.
+        catalogued: cloudByUuid.has(uuid),
+        cloudPath: cloudByUuid.has(uuid) ? cloudPathOf(uuid) : null,
+        localPath,
+        root: rootByUuid.get(uuid) || null,
+      };
+    });
+    return { cloud, roots, entities };
+  }
+
   return {
     dir,
     homeDir,
@@ -820,9 +922,13 @@ function createRegistrationService({
       const received = entityCloud.receiveDownload({
         resourceId, contentHash, kind, partIndex, sha256, dataBase64,
       });
-      advanceMaterializations();
+      // A mid-file part cannot complete any waiting tree; only a finished
+      // content head can. Advancing on every part re-walks every waiting
+      // job once per part, which is quadratic over a large download.
+      if (received?.complete) advanceMaterializations();
       return received;
     },
+    status,
     advanceMaterializations,
     bootstrapUserHome,
     exactUserHomeCloudRecords,

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

@@ -686,7 +686,7 @@ function createRegistry(options) {
 
     /**
      * First cloud bootstrap may meet a pre-cloud local safe home. Its six
-     * roots and three exact managed nodes are platform truth, so they may
+     * roots and ten exact managed nodes are platform truth, so they may
      * adopt the authenticated cloud UUIDs without changing any user-owned
      * descendant identity. This is one atomic graph rekey, never a delete or
      * local-wins merge, and callers must prove that no ordinary entity-cloud

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

@@ -70,15 +70,23 @@ function untrackedFiles(repoPath) {
     // its own card; the parent's checkpoint must not contain it.
     if (rel.endsWith('/')) return [];
     const abs = path.join(repoPath, rel);
-    const stat = fs.lstatSync(abs);
-    if (stat.isSymbolicLink()) {
-      const content = Buffer.from(fs.readlinkSync(abs));
-      return [{ path: rel, mode: '120000', content, sha256: sha256(content) }];
+    try {
+      const stat = fs.lstatSync(abs);
+      if (stat.isSymbolicLink()) {
+        const content = Buffer.from(fs.readlinkSync(abs));
+        return [{ path: rel, mode: '120000', content, sha256: sha256(content) }];
+      }
+      if (stat.isDirectory()) return []; // same boundary, unmarked: never read a directory as a file
+      const content = fs.readFileSync(abs);
+      const mode = stat.mode & 0o111 ? '100755' : '100644';
+      return [{ path: rel, mode, content, sha256: sha256(content) }];
+    } catch (error) {
+      // Git's file listing is necessarily a point-in-time observation. A file
+      // may be removed or renamed before it can be read; the next watch event
+      // captures its replacement, while this capture truthfully omits it.
+      if (error && error.code === 'ENOENT') return [];
+      throw error;
     }
-    if (stat.isDirectory()) return []; // same boundary, unmarked: never read a directory as a file
-    const content = fs.readFileSync(abs);
-    const mode = stat.mode & 0o111 ? '100755' : '100644';
-    return [{ path: rel, mode, content, sha256: sha256(content) }];
   });
 }
 

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

@@ -316,6 +316,12 @@ async function handleEntityRoutes(ctx) {
     return true;
   }
 
+  if (ctx.pathname === '/entities/status' && ctx.method === 'GET') {
+    ctx.res.setHeader('Cache-Control', 'no-store');
+    ctx.sendJson(200, registrationService().status());
+    return true;
+  }
+
   const materializationMatch = /^\/entities\/add\/(mat_[A-Za-z0-9_-]+)$/.exec(ctx.pathname);
   if (materializationMatch && ctx.method === 'GET') {
     const service = registrationService();

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

@@ -76,6 +76,37 @@ test('a signed-in registration is refused until the cloud entity resource is act
   assert.doesNotThrow(() => cloud.assertRegistrationReady());
 });
 
+test('entity-cloud status reports an unsettled catalog as catching up without repairing it', () => {
+  const db = new Database(':memory:');
+  const cloud = createEntityCloud({ db, userId: 'user-1', deviceId: 'device-1' });
+  const registry = createRegistry({ db, ephemeral: true, emit: () => {}, journal: cloud.journal });
+  const root = registry.enrollRoot({ type: 'workspace', name: 'ground' });
+  const bootstrap = cloud.bootstrap(registry.syncRecords());
+  cloud.install({
+    registry,
+    resourceId: bootstrap.resourceId,
+    authorityEpoch: 1,
+    headVersion: 0,
+    snapshotBase64: bootstrap.snapshotBase64,
+    snapshotChecksum: bootstrap.snapshotChecksum,
+  });
+
+  const current = cloud.status();
+  assert.equal(current.catalog.current, true);
+  assert.equal(current.catalog.records[0].uuid, root.uuid);
+  assert.equal(current.outbox.pending, 0);
+
+  const child = registry.create({ type: 'folder', parentUUID: root.uuid, name: 'child' });
+  const catchingUp = cloud.status();
+  assert.equal(catchingUp.catalog.current, false, 'an unacknowledged local mutation never masquerades as an active cloud head');
+  assert.equal(catchingUp.outbox.pending, 1);
+  assert.equal(catchingUp.catalog.records.some((record) => record.uuid === child.uuid), true,
+    'status may show the local catalog projection while naming it catching up');
+
+  const after = cloud.status();
+  assert.deepEqual(after, catchingUp, 'status is read-only: it does not claim, retry, or repair delivery');
+});
+
 test('a large registration replaces the complete graph in one cloud operation and a recipient waits for its compacted snapshot', () => {
   const db = new Database(':memory:');
   const cloud = createEntityCloud({ db, userId: 'user-1', deviceId: 'device-1' });
@@ -244,7 +275,7 @@ test('a compacted remote snapshot enters the cloud catalog, not locally watched
   fs.rmSync(targetDir, { recursive: true, force: true });
 });
 
-test('add accepts only a catalog installed by the active compacted snapshot, never a snapshot plus a mutation tail', () => {
+test('add follows in-order mirrored mutations and refuses after a version gap until the compacted snapshot returns', () => {
   const sourceDb = new Database(':memory:');
   const sourceCloud = createEntityCloud({ db: sourceDb, userId: 'user-1', deviceId: 'source-device' });
   const sourceRegistry = createRegistry({ db: sourceDb, ephemeral: true, emit: () => {}, journal: sourceCloud.journal });
@@ -277,7 +308,7 @@ test('add accepts only a catalog installed by the active compacted snapshot, nev
       envelope: {
         resourceId,
         mutationId: 'ent_remote_change',
-        contract: 'amalgm-entity-registry@2',
+        contract: 'amalgm-entity-registry@3',
         schemaVersion: 1,
         operationKind: 'entity.upsert',
         operation: { kind: 'entity.upsert', record: changed },
@@ -286,25 +317,53 @@ test('add accepts only a catalog installed by the active compacted snapshot, nev
       committedAt: '2026-08-04T00:00:00.000Z',
     });
 
+    // Version 13 arrived in official order on a snapshot-consistent catalog:
+    // the catalog IS the compacted head, so add needs no re-download.
+    const inOrder = path.join(targetDir, 'in-order');
+    fs.mkdirSync(inOrder);
+    assert.equal(
+      targetCloud.startMaterialization({ uuid: root.uuid, targetPath: inOrder }).headVersion,
+      13,
+      'an in-order mirrored mutation keeps the catalog materializable at the new head',
+    );
+
+    // Version 15 skips 14: the catalog can no longer prove it equals the
+    // head, so add refuses until a fresh compacted snapshot is installed.
+    const gapped = { ...changed, name: 'gapped.md', version: 'd'.repeat(64) };
+    targetCloud.ingest({
+      registry: targetRegistry,
+      envelope: {
+        resourceId,
+        mutationId: 'ent_remote_gap',
+        contract: 'amalgm-entity-registry@3',
+        schemaVersion: 1,
+        operationKind: 'entity.upsert',
+        operation: { kind: 'entity.upsert', record: gapped },
+      },
+      version: 15,
+      committedAt: '2026-08-04T00:00:01.000Z',
+    });
+    const afterGap = path.join(targetDir, 'after-gap');
+    fs.mkdirSync(afterGap);
     assert.throws(
-      () => targetCloud.startMaterialization({ uuid: root.uuid, targetPath: targetDir }),
+      () => targetCloud.startMaterialization({ uuid: root.uuid, targetPath: afterGap }),
       /catalog is not pinned to the active cloud head/,
-      'the mutation updated live catalog facts, but not the snapshot barrier',
+      'a version gap drops the snapshot barrier until compaction returns',
     );
 
     const cloudRoot = initialSnapshot.records.find((record) => record.uuid === root.uuid);
-    const compactedBytes = Buffer.from(JSON.stringify(snapshotFromRecords([cloudRoot, changed])), 'utf8');
+    const compactedBytes = Buffer.from(JSON.stringify(snapshotFromRecords([cloudRoot, gapped])), 'utf8');
     targetCloud.install({
       registry: targetRegistry,
       resourceId,
       authorityEpoch: 3,
-      headVersion: 13,
+      headVersion: 15,
       snapshotBase64: compactedBytes.toString('base64'),
       snapshotChecksum: require('crypto').createHash('sha256').update(compactedBytes).digest('hex'),
     });
     assert.equal(
-      targetCloud.startMaterialization({ uuid: root.uuid, targetPath: targetDir }).headVersion,
-      13,
+      targetCloud.startMaterialization({ uuid: root.uuid, targetPath: afterGap }).headVersion,
+      15,
       'the fresh compacted snapshot—not a history replay—makes add available again',
     );
   } finally {

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

@@ -189,7 +189,7 @@ test('an added ordinary workspace stays live: a later cloud file head replaces l
       envelope: {
         resourceId: sourceCloud.identity().resourceId,
         mutationId: 'ent_remote_file_change',
-        contract: 'amalgm-entity-registry@2',
+        contract: 'amalgm-entity-registry@3',
         schemaVersion: 1,
         operationKind: 'entity.upsert',
         operation: { kind: 'entity.upsert', record: remoteRecord },
@@ -296,7 +296,7 @@ test('add preserves a symlink UUID and later retargets the same literal link wit
     const ingested = target.ingestCloudMutation({
       envelope: {
         resourceId: sourceCloud.identity().resourceId, mutationId: 'ent_remote_link_change',
-        contract: 'amalgm-entity-registry@2', schemaVersion: 1,
+        contract: 'amalgm-entity-registry@3', schemaVersion: 1,
         operationKind: 'entity.upsert', operation: { kind: 'entity.upsert', record: sourceRegistry.syncRecord(changed.uuid) },
       },
       version: 42, committedAt: '2026-08-05T00:00:00.000Z',
@@ -420,7 +420,7 @@ test('add recreates an actual Git repository from verified Repocard cargo, then
     const ingested = target.ingestCloudMutation({
       envelope: {
         resourceId: bootstrap.resourceId, mutationId: 'ent_remote_repo_change',
-        contract: 'amalgm-entity-registry@2', schemaVersion: 1,
+        contract: 'amalgm-entity-registry@3', schemaVersion: 1,
         operationKind: 'entity.upsert', operation: { kind: 'entity.upsert', record: remoteRecord },
       },
       version: 2, committedAt: '2026-08-05T00:00:00.000Z',

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

@@ -655,3 +655,88 @@ test('watcher death rebuilds the doorbell and reconciles the gap once', () => {
     fs.watch = realWatch;
   }
 });
+
+// --- the scoped scan ------------------------------------------------------
+// A NAMED doorbell earns a look at its own directory, never a walk of the
+// world; anything structural escalates to the full walk unchanged. The
+// injected enrollment policy is the witness: the full walk asks it about
+// every directory's entries, so a scoped look must never ask about a
+// sibling directory's ground.
+
+const { fakeWatchKit } = require('./observer.rig');
+
+function scopedRig() {
+  const dir = makeDir('scoped');
+  fs.mkdirSync(path.join(dir, 'a'));
+  fs.mkdirSync(path.join(dir, 'b'));
+  fs.writeFileSync(path.join(dir, 'a', 'one.md'), 'v1');
+  fs.writeFileSync(path.join(dir, 'b', 'two.md'), 'v1');
+  const asked = [];
+  const bells = fakeWatchKit();
+  const { observer, events } = makeObserver({
+    settleMs: 15,
+    watch: bells.watch,
+    shouldEnroll: (relPath) => {
+      asked.push(relPath);
+      return true;
+    },
+  });
+  observer.enrollRoot(dir);
+  observer.start();
+  events.length = 0;
+  asked.length = 0;
+  return { dir, asked, bells, observer, events };
+}
+
+async function settled(events, arrived, deadlineMs = 5_000) {
+  const deadline = Date.now() + deadlineMs;
+  while (!arrived() && Date.now() < deadline) {
+    await new Promise((resolve) => setTimeout(resolve, 10));
+  }
+  return arrived();
+}
+
+test('a named doorbell scans only its own directory', async () => {
+  const { dir, asked, bells, observer, events } = scopedRig();
+  fs.writeFileSync(path.join(dir, 'a', 'one.md'), 'v2');
+  bells.ring(dir, 'a/one.md');
+  assert.ok(await settled(events, () => eventsOf(events, 'file.changed').length > 0));
+  observer.stop();
+
+  const changed = eventsOf(events, 'file.changed');
+  assert.equal(changed.length, 1);
+  assert.equal(changed[0].path, 'a/one.md');
+  assert.ok(asked.includes('a/one.md'), 'the rung directory was read');
+  assert.ok(!asked.includes('b/two.md'), `the sibling directory was never walked: ${asked.join(', ')}`);
+});
+
+test('a create under a named doorbell escalates to the full walk', async () => {
+  const { dir, asked, bells, observer, events } = scopedRig();
+  fs.writeFileSync(path.join(dir, 'a', 'new.md'), 'fresh');
+  bells.ring(dir, 'a/new.md');
+  assert.ok(await settled(events, () => eventsOf(events, 'file.created').length > 0));
+  observer.stop();
+
+  const created = eventsOf(events, 'file.created');
+  assert.equal(created.length, 1);
+  assert.equal(created[0].path, 'a/new.md');
+  assert.ok(asked.includes('b/two.md'), 'structural news pays for the whole walk');
+});
+
+test('a cross-directory move naming only the new side still concludes a rename', async () => {
+  const { dir, bells, observer, events } = scopedRig();
+  fs.renameSync(path.join(dir, 'a', 'one.md'), path.join(dir, 'b', 'moved.md'));
+  // A rename may lawfully deliver only the NEW name: the scoped look sees
+  // an orphan entry, refuses to conclude, and the full walk's inode rescue
+  // names the move — never a create beside a ghost.
+  bells.ring(dir, 'b/moved.md');
+  assert.ok(await settled(events, () => eventsOf(events, 'file.renamed').length > 0));
+  observer.stop();
+
+  const renamed = eventsOf(events, 'file.renamed');
+  assert.equal(renamed.length, 1);
+  assert.equal(renamed[0].from, 'a/one.md');
+  assert.equal(renamed[0].to, 'b/moved.md');
+  assert.equal(eventsOf(events, 'file.created').length, 0);
+  assert.equal(eventsOf(events, 'file.deleted').length, 0);
+});

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

@@ -54,6 +54,7 @@ const { ENTITIES_DIR, createRegistrationService, registrationService } = require
 const { adapterFor } = require('../adapters');
 const { createRuntimeHttpServer } = require('../server/http-service');
 const { createLocalServiceRouter } = require('../server/local-service-router');
+const { SYSTEM_TOOL_ARTIFACTS } = require('../lib/layout');
 
 const services = [];
 let server;
@@ -203,6 +204,7 @@ test('user-home bootstrap creates only declared roots and registers them through
       ['agents-root', 'exact'], ['apps-root', 'exact'], ['automations-root', 'exact'],
       ['toolbox-root', 'exact'], ['workspaces-root', 'exact'], ['system-root', 'exact'],
       ['home-manifest', 'exact'], ['defaults', 'exact'], ['policy', 'exact'],
+      ...SYSTEM_TOOL_ARTIFACTS.map((entry) => [entry.key, 'exact']),
     ],
   );
   for (const entry of bootstrapped.exactManaged) {
@@ -218,7 +220,7 @@ test('user-home bootstrap creates only declared roots and registers them through
   }
 
   const cloudRecords = await service.exactUserHomeCloudRecords();
-  assert.equal(cloudRecords.length, 9,
+  assert.equal(cloudRecords.length, 16,
     'the declared home is the entire graph eligible to repair a legacy empty cloud registry');
   assert.deepEqual(
     new Set(cloudRecords.map((record) => record.uuid)),
@@ -233,6 +235,46 @@ test('user-home bootstrap creates only declared roots and registers them through
   );
 });
 
+test('an upgraded declared home registers every built-in tool through Detect and Record', async () => {
+  const home = path.join(tempRoot, 'user-home-upgrade');
+  const service = createRegistrationService({
+    dir: path.join(tempRoot, 'state-user-home-upgrade'),
+    homeDir: home,
+  });
+  services.push(service);
+
+  for (const root of ['agents', 'apps', 'automations', 'toolbox', 'workspaces', 'system']) {
+    fs.mkdirSync(path.join(home, root), { recursive: true });
+  }
+  fs.mkdirSync(path.join(home, 'system', 'defaults'));
+  fs.mkdirSync(path.join(home, 'system', 'policy'));
+  fs.writeFileSync(path.join(home, 'system', 'home.json'), JSON.stringify({
+    schemaVersion: 1,
+    kind: 'amalgm-user-home',
+    roots: [],
+    exactManaged: [],
+  }));
+  service.registration.addMany(['agents', 'apps', 'automations', 'toolbox', 'workspaces', 'system']
+    .map((root) => path.join(home, root)));
+
+  const bootstrapped = await service.bootstrapUserHome();
+  const toolbox = bootstrapped.roots.find((entry) => entry.key === 'toolbox');
+  const browser = bootstrapped.exactManaged.find((entry) => entry.key === 'amalgm-browser');
+  const manifest = bootstrapped.exactManaged.find((entry) => entry.key === 'home-manifest');
+  assert.equal(browser.record.parentUUID, toolbox.record.uuid,
+    'the declared browser tool is a real child of the existing toolbox root');
+  assert.equal(browser.record.type, 'file.text');
+  assert.equal(service.registration.registry.syncRecord(manifest.record.uuid).payloadVersion, require('crypto')
+    .createHash('sha256')
+    .update(fs.readFileSync(path.join(home, 'system', 'home.json')))
+    .digest('hex'), 'the rewritten exact manifest is observed before its cloud identity is returned');
+  for (const artifact of SYSTEM_TOOL_ARTIFACTS) {
+    assert.ok(fs.existsSync(path.join(home, artifact.relativePath)), `${artifact.key} is materialized`);
+    assert.ok(bootstrapped.exactManaged.some((entry) => entry.key === artifact.key),
+      `${artifact.key} is an exact managed entity`);
+  }
+});
+
 test('entity-cloud bootstrap publishes only the verified user home when an old local repo exists', async () => {
   const service = createRegistrationService({
     dir: path.join(tempRoot, 'state-user-home-cloud-boundary'),
@@ -248,13 +290,13 @@ test('entity-cloud bootstrap publishes only the verified user home when an old l
   });
 
   const records = await service.exactUserHomeCloudRecords();
-  assert.equal(records.length, 9);
+  assert.equal(records.length, 16);
   assert.equal(records.some((record) => record.uuid === oldRepo.uuid), false,
     'login never turns existing user-selected ground into an implicit cloud registration');
 
   const bootstrap = service.entityCloud.bootstrap(records);
   const snapshot = JSON.parse(Buffer.from(bootstrap.snapshotBase64, 'base64').toString('utf8'));
-  assert.equal(snapshot.records.length, 9);
+  assert.equal(snapshot.records.length, 16);
   service.entityCloud.install({
     registry: service.registration.registry,
     resourceId: bootstrap.resourceId,
@@ -393,6 +435,56 @@ test('a signed-in register call writes every entity delivery intent in identity.
   }
 });
 
+test('service status exposes only a verified cloud path as a navigable workspace', async () => {
+  const service = createRegistrationService({
+    dir: path.join(tempRoot, 'state-cloud-status'),
+    homeDir: path.join(tempRoot, 'cloud-status-home'),
+    cloudUserId: 'user-cloud-status',
+    cloudDeviceId: 'computer-cloud-status',
+  });
+  const bootstrap = service.entityCloud.bootstrap(service.registration.registry.syncRecords());
+  service.entityCloud.install({
+    registry: service.registration.registry,
+    resourceId: bootstrap.resourceId,
+    authorityEpoch: 1,
+    headVersion: 0,
+    snapshotBase64: bootstrap.snapshotBase64,
+    snapshotChecksum: bootstrap.snapshotChecksum,
+  });
+  const ground = makeGround('cloud-status');
+  fs.mkdirSync(path.join(ground, 'src'));
+
+  try {
+    const registered = await service.register(ground);
+    const beforeAcknowledgement = service.status();
+    assert.equal(beforeAcknowledgement.cloud.catalog.current, false,
+      'a pending local registration is visible to status but not a navigable verified cloud workspace');
+
+    let version = 0;
+    for (;;) {
+      const [claim] = service.entityCloud.claim();
+      if (!claim) break;
+      version += 1;
+      service.entityCloud.acknowledge({
+        resourceId: claim.resourceId,
+        mutationId: claim.mutationId,
+        version,
+        committedAt: '2026-08-05T00:00:00.000Z',
+      });
+    }
+
+    const status = service.status();
+    assert.equal(status.cloud.catalog.current, true);
+    const root = status.entities.find((entity) => entity.uuid === registered.record.uuid);
+    assert.equal(root.cloudPath, path.basename(ground));
+    const child = status.entities.find((entity) => entity.cloudPath === `${path.basename(ground)}/src`);
+    assert.ok(child, 'the cloud path is derived from canonical parentage, never a local absolute path');
+    assert.equal(child.localPath, path.join(ground, 'src'));
+  } finally {
+    service.close();
+  }
+});
+
 test('a large signed-in register call publishes one complete cloud graph before Watch begins', async () => {
   const service = createRegistrationService({
     dir: path.join(tempRoot, 'state-cloud-register-large'),

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

@@ -175,6 +175,27 @@ test('an unborn repo with staged and untracked work round-trips', () => {
   assert.equal(state.card.bundle, null);
 });
 
+test('a file that disappears after Git lists it is omitted instead of aborting capture', () => {
+  const source = makeRepo('vanishing-untracked');
+  const gone = path.join(source, 'gone-during-capture.md');
+  fs.writeFileSync(gone, 'transient');
+  const originalLstat = fs.lstatSync;
+  fs.lstatSync = (candidate, ...args) => {
+    if (candidate === gone) {
+      const error = new Error('gone');
+      error.code = 'ENOENT';
+      throw error;
+    }
+    return originalLstat(candidate, ...args);
+  };
+  try {
+    const state = capture(source, { withBundle: false });
+    assert.equal(state.checkpoint.untracked.some((file) => file.path === 'gone-during-capture.md'), false);
+  } finally {
+    fs.lstatSync = originalLstat;
+  }
+});
+
 // --- identity ------------------------------------------------------------------
 
 test('capture is deterministic: same state, same ids, twice', () => {