amalgm 0.1.256 → 0.1.258

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

@@ -15,7 +15,10 @@ const fs = require('fs');
 const path = require('path');
 
 const CONTENT_CONTRACT = 'amalgm-entity-content@1';
-const CHUNK_BYTES = 256 * 1024;
+// One chunk is one WAN round trip. The gateway accepts parts up to this same
+// bound (ENTITY_CONTENT_PART_BYTES); older 256KB chunks remain valid because
+// the manifest rule is `bytes <= CHUNK_BYTES`, never an exact size.
+const CHUNK_BYTES = 4 * 1024 * 1024;
 const HASH = /^[0-9a-f]{64}$/;
 
 function digest(bytes) {
@@ -41,6 +44,10 @@ function createEntityContent({ dir }) {
   const chunksDir = path.join(root, 'chunks');
   const manifestsDir = path.join(root, 'manifests');
   const uploadsDir = path.join(root, 'uploads');
+  // Unfinished uploads per resource, so claim() does not re-read the whole
+  // ledger directory for every part it sends. The on-disk ledger stays the
+  // durable truth; this set is rebuilt from it once per process.
+  const pendingUploads = new Map();
 
   function ensureDirs() {
     for (const target of [chunksDir, manifestsDir, uploadsDir]) {
@@ -236,14 +243,27 @@ function createEntityContent({ dir }) {
     }
   }
 
+  function pendingSet(resourceId) {
+    let pending = pendingUploads.get(resourceId);
+    if (!pending) {
+      pending = new Set(uploadEntries(resourceId));
+      pendingUploads.set(resourceId, pending);
+    }
+    return pending;
+  }
+
   function ensureUpload({ resourceId, contentHash }) {
     if (typeof resourceId !== 'string' || !resourceId) throw new Error('entity content upload requires a resource id');
     const content = manifest(contentHash);
     if (!content) throw new Error(`content ${contentHash} was not captured before its entity record committed`);
     const current = readUpload(resourceId, contentHash, content);
-    if (current) return current;
+    if (current) {
+      if (!current.manifestUploaded) pendingSet(resourceId).add(contentHash);
+      return current;
+    }
     const created = initialUpload(resourceId, contentHash);
     saveUpload(created);
+    pendingSet(resourceId).add(contentHash);
     return created;
   }
 
@@ -269,11 +289,15 @@ function createEntityContent({ dir }) {
   function claim({ resourceId, leaseMs = 30_000 }) {
     ensureDirs();
     const at = Date.now();
-    for (const contentHash of uploadEntries(resourceId)) {
+    const pending = pendingSet(resourceId);
+    for (const contentHash of pending) {
       const content = manifest(contentHash);
       if (!content) throw new Error(`entity content ${contentHash} disappeared from the local cache`);
       const upload = readUpload(resourceId, contentHash, content);
-      if (!upload || upload.manifestUploaded) continue;
+      if (!upload || upload.manifestUploaded) {
+        pending.delete(contentHash);
+        continue;
+      }
       if (upload.leaseUntil && Date.parse(upload.leaseUntil) > at) continue;
       const next = { ...upload, leaseUntil: new Date(at + Math.max(1_000, Number(leaseMs) || 30_000)).toISOString(), updatedAt: now() };
       if (next.nextPart < content.chunks.length) {
@@ -333,6 +357,7 @@ function createEntityContent({ dir }) {
     current.leaseUntil = null;
     current.updatedAt = now();
     saveUpload(current);
+    if (current.manifestUploaded) pendingUploads.get(resourceId)?.delete(contentHash);
     return { duplicate: false, uploaded: current.manifestUploaded };
   }
 
@@ -412,9 +437,11 @@ function createEntityContent({ dir }) {
     if (!current) return { kind: 'manifest', partIndex: 0, sha256: null };
     for (let partIndex = 0; partIndex < current.chunks.length; partIndex += 1) {
       const chunk = current.chunks[partIndex];
+      // Presence + size only: every chunk file was hash-verified before it
+      // was written (capture or receive), writes are write-once, and final
+      // assembly (`bytes`) re-verifies the whole content head.
       try {
-        const bytes = fs.readFileSync(chunkFile(chunk.sha256));
-        if (bytes.length === chunk.bytes && digest(bytes) === chunk.sha256) continue;
+        if (fs.statSync(chunkFile(chunk.sha256)).size === chunk.bytes) continue;
       } catch (error) {
         if (error.code !== 'ENOENT') throw error;
       }

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

@@ -596,6 +596,26 @@ function createRegistration(options) {
     return normalized.map(({ targetPath, identityAt }) => add(targetPath, { identityAt }));
   }
 
+  /** 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
+   * exact platform node it needs, and the normal Detect → Record path still
+   * decides the resulting record. */
+  function reconcileDeclared(targetPath) {
+    let ground;
+    try {
+      ground = fs.lstatSync(targetPath).isSymbolicLink() ? path.resolve(targetPath) : fs.realpathSync(targetPath);
+    } catch {
+      throw new Error(`declared user-home root is unavailable: ${targetPath}`);
+    }
+    const covering = treeRootCovering(ground);
+    if (!covering) throw new Error(`declared user-home root was not registered: ${targetPath}`);
+    observer.scanNow(covering.rootId);
+    flushIfDirty();
+    requireLiveWatchers(covering.path);
+    return { rootPath: covering.path, record: rootRecordOf(covering.rootId) };
+  }
+
   /** The boundary's whole convergence pass, one act: loss convicted
    * first (loudly — a conviction is never a retry), edges followed,
    * lenses reconciled, renderings projected. Startup, the explicit
@@ -626,6 +646,7 @@ function createRegistration(options) {
     registry,
     add,
     addMany,
+    reconcileDeclared,
 
     /**
      * `amalgm register <existing-path> --as <address>` — the managed

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,51 @@ 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]));
+    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),
+        localPath,
+        root: rootByUuid.get(uuid) || null,
+      };
+    });
+    return { cloud, roots, entities };
+  }
+
   return {
     dir,
     homeDir,
@@ -820,9 +907,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/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@1',
+        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@1',
+        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@1', 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@1', 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/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,

package/runtime/scripts/amalgm-mcp/tests/system-catalog.test.js

@@ -35,7 +35,7 @@ test('system toolbox catalog exposes first-party default tools', () => {
   );
 });
 
-test('system toolbox catalog merge preserves persisted records', () => {
+test('system toolbox catalog merge preserves user records but keeps built-ins authoritative', () => {
   const merged = mergeSystemToolboxCatalog({
     version: 1,
     tools: {
@@ -59,12 +59,9 @@ test('system toolbox catalog merge preserves persisted records', () => {
     },
   });
 
-  assert.equal(merged.tools.browser.name, 'Persisted Browser');
+  assert.equal(merged.tools.browser.name, 'Browser');
   assert.equal(merged.tools['custom.cli'].name, 'Custom CLI');
-  assert.equal(
-    merged.toolActions['browser.browser_open'].name,
-    'persisted_navigate',
-  );
+  assert.equal(merged.toolActions['browser.browser_open'], undefined);
   assert.equal(merged.toolActions['apps.apps_list'].name, 'apps_list');
 });
 

package/runtime/scripts/amalgm-mcp/tests/toolbox-artifacts.test.js

@@ -0,0 +1,88 @@
+'use strict';
+
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const test = require('node:test');
+
+const {
+  SYSTEM_TOOL_ARTIFACTS,
+  artifactPathForTool,
+  isSystemToolId,
+  materializeSystemToolArtifacts,
+  migrateLegacyToolboxCatalog,
+  readToolArtifacts,
+  writeToolArtifact,
+} = require('../toolbox/artifacts');
+
+function temporaryToolbox() {
+  const home = fs.mkdtempSync(path.join(os.tmpdir(), 'amalgm-toolbox-artifacts-'));
+  const toolboxDir = path.join(home, 'toolbox');
+  fs.mkdirSync(toolboxDir);
+  return { home, toolboxDir };
+}
+
+test('each built-in tool materializes as one distinct managed artifact', () => {
+  const { home, toolboxDir } = temporaryToolbox();
+  try {
+    const first = materializeSystemToolArtifacts({ toolboxDir });
+    assert.deepEqual(first.changedRelativePaths, SYSTEM_TOOL_ARTIFACTS.map((entry) => entry.relativePath));
+    const catalog = readToolArtifacts({ toolboxDir });
+    assert.deepEqual(Object.keys(catalog.tools).sort(), SYSTEM_TOOL_ARTIFACTS.map((entry) => entry.toolId).sort());
+    for (const entry of SYSTEM_TOOL_ARTIFACTS) {
+      const tool = catalog.tools[entry.toolId];
+      assert.equal(tool.origin, 'system');
+      assert.equal(tool.owner, 'amalgm');
+      assert.deepEqual(tool.source, { transport: 'amalgm-runtime', service: 'mcp' },
+        'the cloud artifact has no machine-local port');
+      assert.equal(path.basename(artifactPathForTool(tool, { toolboxDir })), path.basename(entry.relativePath));
+      assert.equal(isSystemToolId(tool.id), true);
+    }
+    assert.deepEqual(materializeSystemToolArtifacts({ toolboxDir }).changedRelativePaths, [],
+      'rerunning login does not rewrite an unchanged built-in tool');
+  } finally {
+    fs.rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test('a user tool is a sibling artifact and remains independent of built-in ownership', () => {
+  const { home, toolboxDir } = temporaryToolbox();
+  try {
+    materializeSystemToolArtifacts({ toolboxDir });
+    const tool = { id: 'aayush.stock-price', name: 'Stock Price', origin: 'user', owner: 'aayush' };
+    const actions = [{ id: 'aayush.stock-price.lookup', toolId: tool.id, name: 'lookup' }];
+    const target = writeToolArtifact({ tool, actions }, { toolboxDir });
+    assert.equal(path.basename(target), 'tool-aayush.stock-price.json');
+    const catalog = readToolArtifacts({ toolboxDir });
+    assert.equal(catalog.tools[tool.id].origin, 'user');
+    assert.equal(catalog.toolActions[actions[0].id].toolId, tool.id);
+    assert.equal(isSystemToolId(tool.id), false);
+  } finally {
+    fs.rmSync(home, { recursive: true, force: true });
+  }
+});
+
+test('a legacy aggregate catalog becomes user tool artifacts before leaving the registered toolbox tree', () => {
+  const { home, toolboxDir } = temporaryToolbox();
+  try {
+    fs.writeFileSync(path.join(toolboxDir, 'toolbox.json'), JSON.stringify({
+      version: 1,
+      tools: {
+        'user.example': { id: 'user.example', name: 'Example', origin: 'user', owner: 'user' },
+      },
+      toolActions: {
+        'user.example.run': { id: 'user.example.run', toolId: 'user.example', name: 'run' },
+      },
+    }));
+    const migrated = migrateLegacyToolboxCatalog({ toolboxDir });
+    assert.equal(migrated.migrated, true);
+    assert.equal(fs.existsSync(path.join(toolboxDir, 'toolbox.json')), false);
+    assert.equal(fs.existsSync(path.join(home, 'toolbox.legacy.json')), true);
+    const catalog = readToolArtifacts({ toolboxDir });
+    assert.equal(catalog.tools['user.example'].name, 'Example');
+    assert.equal(catalog.toolActions['user.example.run'].name, 'run');
+  } finally {
+    fs.rmSync(home, { recursive: true, force: true });
+  }
+});