amalgm 0.1.256 → 0.1.258

package/lib/cli.js

@@ -120,7 +120,7 @@ function usage() {
     '  amalgm stop',
     '  amalgm register [path ...] Register local ground (default: current directory)',
     '  amalgm add <entity-uuid> [directory] Add a cloud-backed tree to this machine',
-    '  amalgm status',
+    '  amalgm status [path-or-uuid] Show cloud-backed entity and watcher state',
     '  amalgm doctor',
     '  amalgm service [install|start|stop|status|uninstall] [--mode auto|systemd|launchd|windows|portable]',
     '  amalgm update [--tag latest|canary]',
@@ -1112,7 +1112,7 @@ async function waitForServices(timeoutMs) {
   return latest;
 }
 
-async function status() {
+async function runtimeStatus() {
   const pid = readPid();
   const record = loadComputerRecord({ migrate: true });
   const runtimeState = readJson(RUNTIME_STATE_FILE, null);
@@ -1177,6 +1177,75 @@ async function status() {
   }
 }
 
+/** `amalgm status [path-or-uuid]` is a read-only view of entity truth.  The
+ * runtime owns paths, bindings, and cloud freshness; the CLI only narrows and
+ * renders the returned facts.  Daemon status remains available as
+ * `amalgm service status`. */
+async function entityStatus(positionals) {
+  if (positionals.length > 1) throw new Error('Usage: amalgm status [path-or-uuid]');
+  const port = servicePorts().find(([name]) => name === 'amalgm-mcp')?.[1];
+  let answer = null;
+  if (port) {
+    try {
+      answer = await runtimeGet(port, '/entities/status');
+    } catch (error) {
+      if (error.code !== 'ECONNREFUSED') throw error;
+    }
+  }
+  if (!answer) {
+    console.error('Amalgm runtime is not running. Start it with `amalgm start`.');
+    process.exitCode = 1;
+    return;
+  }
+  if (answer.status !== 200 || !answer.payload) {
+    console.error(`Error: ${answer.payload?.error || `runtime responded ${answer.status}`}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const status = answer.payload;
+  const selector = positionals[0] || null;
+  const uuid = selector && /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(selector)
+    ? selector.toLowerCase()
+    : null;
+  const localPath = selector && !uuid ? path.resolve(selector) : null;
+  const entities = (status.entities || []).filter((entity) => !selector
+    || entity.uuid === uuid || entity.localPath === localPath);
+  if (selector && entities.length === 0) {
+    console.error(`No cloud-backed entity matches ${selector}.`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const cloud = status.cloud || {};
+  const replica = cloud.replica;
+  if (!replica) {
+    console.log(`Cloud: ${cloud.identity?.enabled ? 'initializing' : 'not signed in'}`);
+  } else {
+    console.log(`Cloud: ${cloud.catalog?.current ? 'current' : 'catching up'} (head ${replica.headVersion})`);
+  }
+  const outbox = cloud.outbox || {};
+  console.log(`Delivery: ${outbox.pending || 0} pending, ${outbox.syncing || 0} sending, ${outbox.rejected || 0} rejected`);
+  const jobs = cloud.materializations || {};
+  if ((jobs.waitingForContent || 0) + (jobs.materializing || 0) + (jobs.failed || 0) > 0) {
+    console.log(`Materializations: ${jobs.waitingForContent || 0} waiting, ${jobs.materializing || 0} applying, ${jobs.failed || 0} failed`);
+  }
+  if (entities.length === 0) {
+    console.log('Entities: none on this cloud replica.');
+    return;
+  }
+  console.log('Entities:');
+  for (const entity of entities) {
+    console.log(`  ${entity.uuid}  ${entity.type}  ${entity.status}`);
+    if (entity.localPath) console.log(`    Local: ${entity.localPath}`);
+    else console.log('    Local: not materialized on this machine');
+    if (entity.root) {
+      const watcher = entity.root.watching && !entity.root.degraded ? 'on' : 'unavailable';
+      console.log(`    Watching: ${watcher}`);
+    }
+  }
+}
+
 async function doctor() {
   ensureBaseDirs();
 
@@ -1649,7 +1718,7 @@ async function main(argv) {
   if (command === 'stop') return stop();
   if (command === 'register') return register(positionals);
   if (command === 'add') return add(positionals);
-  if (command === 'status') return status();
+  if (command === 'status') return entityStatus(positionals);
   if (command === 'doctor') return doctor();
   if (command === 'service') return serviceCommand(options, positionals);
   if (command === 'update') return update(options);

package/lib/layout.js

@@ -33,7 +33,9 @@ const ROOT_MANIFEST_NAME = '.amalgm-root.json';
 const USER_MANIFEST_NAME = '.amalgm-user.json';
 const LAYOUT_VERSION = 1;
 const USER_HOME_MANIFEST_NAME = 'home.json';
-const USER_HOME_SCHEMA_VERSION = 1;
+// Changing the declared exact graph changes the identity contract. A client
+// must never accept a prior graph and silently invent a new managed child.
+const USER_HOME_SCHEMA_VERSION = 2;
 
 // Stable per-user product namespaces. Their authority is NOT inferred from
 // their path: user content and exact platform-managed targets are declared
@@ -59,6 +61,19 @@ const USER_HOME_ROOTS = Object.freeze([
 // Platform management is an exact-node fact. It deliberately does not
 // cascade from `system/`: human permissions may still inherit normally, while
 // only these particular entities are product-managed.
+//
+// A Toolbox tool is one complete entity: its definition and actions travel in
+// the same file. These names are deliberately stable and human-readable.
+const SYSTEM_TOOL_ARTIFACTS = Object.freeze([
+  { key: 'amalgm-automations', toolId: 'automations', relativePath: 'toolbox/amalgm-automations.json', rootKey: 'toolbox' },
+  { key: 'amalgm-notifications', toolId: 'notifications', relativePath: 'toolbox/amalgm-notifications.json', rootKey: 'toolbox' },
+  { key: 'amalgm-memories', toolId: 'memories', relativePath: 'toolbox/amalgm-memories.json', rootKey: 'toolbox' },
+  { key: 'amalgm-agents', toolId: 'agents', relativePath: 'toolbox/amalgm-agents.json', rootKey: 'toolbox' },
+  { key: 'amalgm-apps', toolId: 'apps', relativePath: 'toolbox/amalgm-apps.json', rootKey: 'toolbox' },
+  { key: 'amalgm-cua', toolId: 'computer-use', relativePath: 'toolbox/amalgm-cua.json', rootKey: 'toolbox' },
+  { key: 'amalgm-browser', toolId: 'browser', relativePath: 'toolbox/amalgm-browser.json', rootKey: 'toolbox' },
+]);
+
 const USER_HOME_EXACT_MANAGED = Object.freeze([
   ...USER_HOME_ROOTS.map(({ key, relativePath }) => ({
     key: `${key}-root`, relativePath, rootKey: key,
@@ -66,6 +81,7 @@ const USER_HOME_EXACT_MANAGED = Object.freeze([
   { key: 'home-manifest', relativePath: 'system/home.json', rootKey: 'system' },
   { key: 'defaults', relativePath: 'system/defaults', rootKey: 'system' },
   { key: 'policy', relativePath: 'system/policy', rootKey: 'system' },
+  ...SYSTEM_TOOL_ARTIFACTS,
 ]);
 
 function readJson(file, fallback = null) {
@@ -106,6 +122,7 @@ function declaredUserHome(userDir) {
  */
 function ensureUserHome(userDir) {
   const declaration = declaredUserHome(userDir);
+  const materializedExactPaths = [];
   for (const root of declaration.roots) {
     fs.mkdirSync(root.path, { recursive: true, mode: 0o700 });
   }
@@ -115,15 +132,18 @@ function ensureUserHome(userDir) {
   }
 
   const manifest = declaration.exactManaged.find((entry) => entry.key === 'home-manifest');
-  if (manifest && !fs.existsSync(manifest.path)) {
-    writeJson(manifest.path, {
-      schemaVersion: USER_HOME_SCHEMA_VERSION,
-      kind: 'amalgm-user-home',
-      roots: declaration.roots.map(({ key, relativePath }) => ({ key, path: relativePath })),
-      exactManaged: declaration.exactManaged.map(({ key, relativePath, scope }) => ({ key, path: relativePath, scope })),
-    });
+  const manifestContents = {
+    schemaVersion: USER_HOME_SCHEMA_VERSION,
+    kind: 'amalgm-user-home',
+    roots: declaration.roots.map(({ key, relativePath }) => ({ key, path: relativePath })),
+    exactManaged: declaration.exactManaged.map(({ key, relativePath, scope }) => ({ key, path: relativePath, scope })),
+  };
+  if (manifest && JSON.stringify(readJson(manifest.path, null)) !== JSON.stringify(manifestContents)) {
+    writeJson(manifest.path, manifestContents);
+    materializedExactPaths.push(manifest.relativePath);
   }
-  return declaration;
+
+  return { ...declaration, materializedExactPaths };
 }
 
 function lstatOrNull(target) {
@@ -401,6 +421,7 @@ module.exports = {
   LAYOUT_VERSION,
   PRIMITIVE_DIRS,
   ROOT_MANIFEST_NAME,
+  SYSTEM_TOOL_ARTIFACTS,
   USER_MANIFEST_NAME,
   USER_HOME_EXACT_MANAGED,
   USER_HOME_MANIFEST_NAME,

package/lib/shared-realtime-tunnel.js

@@ -19,8 +19,8 @@ const RETRY_MS = 1_000;
 const REAUTHORIZE_MS = 30_000;
 const REPO_OBJECT_REQUEST_TIMEOUT_MS = 15_000;
 const COOKIE_PRIVATE_CONTRACT = 'browser-cookie-jar@1';
-const USER_HOME_PRIVATE_CONTRACT = 'amalgm-user-home@1';
-const ENTITY_REGISTRY_PRIVATE_CONTRACT = 'amalgm-entity-registry@1';
+const USER_HOME_PRIVATE_CONTRACT = 'amalgm-user-home@2';
+const ENTITY_REGISTRY_PRIVATE_CONTRACT = 'amalgm-entity-registry@3';
 
 function createSharedRealtimeTunnel({
   send,
@@ -938,13 +938,10 @@ function createSharedRealtimeTunnel({
         committedAt: frame.committed_at,
       }).then((ack) => {
         entityMutationInflight.delete(frame.request_id);
-        // An acknowledgement advances the official head. Re-read the
-        // private resource immediately: the gateway compacts that head into
-        // one immutable snapshot before replying, so this device never has
-        // to use its mutation tail as an `amalgm add` starting point. A
-        // legacy empty entity resource is seeded in ordered records first;
-        // intermediate heads are intentionally not imported as a usable
-        // snapshot, because they are not the complete declared home yet.
+        // The runtime reports whether it converged its catalog locally from
+        // this acknowledgement. Only when it could not (a version gap, a
+        // reconciliation handshake, a stale local view) is the compacted
+        // snapshot re-downloaded; the ordinary in-order ack costs nothing.
         if (ack?.requiresSnapshot !== false) void ensurePrivateEntityRegistry();
         scheduleEntityMutationDrain();
       }).catch(() => {
@@ -1109,11 +1106,12 @@ function createSharedRealtimeTunnel({
       version: frame.version,
       committedAt: frame.committed_at,
       actorUserId: frame.actor_user_id,
-    })).then(() => {
-      if (entityRegistryMutation) {
-        // The live frame is useful for collaboration, but cannot become the
-        // reconstruction path for a new local binding. Ask the authority to
-        // compact and return its active snapshot before `add` can continue.
+    })).then((result) => {
+      if (entityRegistryMutation && result?.requiresSnapshot !== false) {
+        // The runtime could not converge its catalog from this frame alone
+        // (a gap, a snapshot replacement, or a stale local view). Ask the
+        // authority to compact and return its active snapshot; an in-order
+        // frame needs no re-download.
         void ensurePrivateEntityRegistry();
       }
     }).catch((error) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "amalgm",
-  "version": "0.1.256",
+  "version": "0.1.258",
   "description": "Amalgm local computer runtime: login, MCP, chat, events, previews, and tunnels.",
   "license": "UNLICENSED",
   "private": false,
@@ -17,7 +17,7 @@
     "sync-runtime": "node ../../scripts/sync-npm-package-runtime.mjs",
     "prepack": "node ../../scripts/sync-npm-package-runtime.mjs",
     "pack:dry": "npm pack --dry-run",
-    "check": "node --check bin/amalgm.js && node --check lib/app-chat.js && node --check lib/react.js && node --check lib/auth-store.js && node --check lib/cli.js && node --check lib/identity-adopt.js && node --check lib/layout.js && node --check lib/migrate-layout.js && node --check lib/paths.js && node --check lib/process-cleanup.js && node --check lib/runtime-identity.js && node --check lib/runtime-manifest.js && node --check lib/service.js && node --check lib/state-migration.js && node --check lib/supervisor.js && node --check lib/tunnel-chat.js && node --check lib/tunnel-events.js && node --check lib/updater.js && node --check runtime/lib/runtime-manifest.js && node --check runtime/scripts/runtime-auth.js && node --check runtime/scripts/proxy-token-store.js && node --check runtime/scripts/local-gateway.js && node --check runtime/scripts/port-monitor.js && node --check runtime/scripts/chat-server.js && node --check runtime/scripts/chat-server/index.js && node --check runtime/scripts/chat-server/config.js && node --check runtime/scripts/chat-core/tooling/native-binaries.js && node --check runtime/scripts/chat-core/tooling/package-import.js && node --check runtime/scripts/chat-core/tooling/runtime-home.js && node --check runtime/scripts/amalgm-mcp/index.js && node --check runtime/scripts/amalgm-mcp/config.js && node --check runtime/scripts/amalgm-mcp/events/pr-check-runner.js && node --check runtime/scripts/amalgm-mcp/registration/entity-cloud.js && node --check runtime/scripts/amalgm-mcp/registration/entity-content.js && node --check runtime/scripts/amalgm-mcp/registration/service.js && node --check runtime/scripts/amalgm-mcp/server/routes/entities.js && node --check runtime/scripts/lib/project-paths.js && node --check runtime/scripts/lib/runtime-paths.js"
+    "check": "node --check bin/amalgm.js && node --check lib/app-chat.js && node --check lib/react.js && node --check lib/auth-store.js && node --check lib/cli.js && node --check lib/identity-adopt.js && node --check lib/layout.js && node --check lib/migrate-layout.js && node --check lib/paths.js && node --check lib/process-cleanup.js && node --check lib/runtime-identity.js && node --check lib/runtime-manifest.js && node --check lib/service.js && node --check lib/state-migration.js && node --check lib/supervisor.js && node --check lib/tunnel-chat.js && node --check lib/tunnel-events.js && node --check lib/updater.js && node --check runtime/lib/runtime-manifest.js && node --check runtime/scripts/runtime-auth.js && node --check runtime/scripts/proxy-token-store.js && node --check runtime/scripts/local-gateway.js && node --check runtime/scripts/port-monitor.js && node --check runtime/scripts/chat-server.js && node --check runtime/scripts/chat-server/index.js && node --check runtime/scripts/chat-server/config.js && node --check runtime/scripts/chat-core/tooling/native-binaries.js && node --check runtime/scripts/chat-core/tooling/package-import.js && node --check runtime/scripts/chat-core/tooling/runtime-home.js && node --check runtime/scripts/amalgm-mcp/index.js && node --check runtime/scripts/amalgm-mcp/config.js && node --check runtime/scripts/amalgm-mcp/events/pr-check-runner.js && node --check runtime/scripts/amalgm-mcp/registration/entity-cloud.js && node --check runtime/scripts/amalgm-mcp/registration/entity-content.js && node --check runtime/scripts/amalgm-mcp/registration/service.js && node --check runtime/scripts/amalgm-mcp/toolbox/artifacts.js && node --check runtime/scripts/amalgm-mcp/server/routes/entities.js && node --check runtime/scripts/lib/project-paths.js && node --check runtime/scripts/lib/runtime-paths.js"
   },
   "engines": {
     "node": ">=20"

package/runtime/scripts/amalgm-mcp/lib/layout.js

@@ -33,7 +33,9 @@ const ROOT_MANIFEST_NAME = '.amalgm-root.json';
 const USER_MANIFEST_NAME = '.amalgm-user.json';
 const LAYOUT_VERSION = 1;
 const USER_HOME_MANIFEST_NAME = 'home.json';
-const USER_HOME_SCHEMA_VERSION = 1;
+// Changing the declared exact graph changes the identity contract. A client
+// must never accept a prior graph and silently invent a new managed child.
+const USER_HOME_SCHEMA_VERSION = 2;
 
 // Stable per-user product namespaces. Their authority is NOT inferred from
 // their path: user content and exact platform-managed targets are declared
@@ -59,6 +61,21 @@ const USER_HOME_ROOTS = Object.freeze([
 // Platform management is an exact-node fact. It deliberately does not
 // cascade from `system/`: human permissions may still inherit normally, while
 // only these particular entities are product-managed.
+//
+// A Toolbox tool is one complete entity: its definition and actions travel in
+// the same file. These names are deliberately stable and human-readable. They
+// are not an `amalgm/` subtree because that would falsely imply ownership
+// cascades to every future child of that directory.
+const SYSTEM_TOOL_ARTIFACTS = Object.freeze([
+  { key: 'amalgm-automations', toolId: 'automations', relativePath: 'toolbox/amalgm-automations.json', rootKey: 'toolbox' },
+  { key: 'amalgm-notifications', toolId: 'notifications', relativePath: 'toolbox/amalgm-notifications.json', rootKey: 'toolbox' },
+  { key: 'amalgm-memories', toolId: 'memories', relativePath: 'toolbox/amalgm-memories.json', rootKey: 'toolbox' },
+  { key: 'amalgm-agents', toolId: 'agents', relativePath: 'toolbox/amalgm-agents.json', rootKey: 'toolbox' },
+  { key: 'amalgm-apps', toolId: 'apps', relativePath: 'toolbox/amalgm-apps.json', rootKey: 'toolbox' },
+  { key: 'amalgm-cua', toolId: 'computer-use', relativePath: 'toolbox/amalgm-cua.json', rootKey: 'toolbox' },
+  { key: 'amalgm-browser', toolId: 'browser', relativePath: 'toolbox/amalgm-browser.json', rootKey: 'toolbox' },
+]);
+
 const USER_HOME_EXACT_MANAGED = Object.freeze([
   ...USER_HOME_ROOTS.map(({ key, relativePath }) => ({
     key: `${key}-root`, relativePath, rootKey: key,
@@ -66,6 +83,7 @@ const USER_HOME_EXACT_MANAGED = Object.freeze([
   { key: 'home-manifest', relativePath: 'system/home.json', rootKey: 'system' },
   { key: 'defaults', relativePath: 'system/defaults', rootKey: 'system' },
   { key: 'policy', relativePath: 'system/policy', rootKey: 'system' },
+  ...SYSTEM_TOOL_ARTIFACTS,
 ]);
 
 function readJson(file, fallback = null) {
@@ -106,6 +124,7 @@ function declaredUserHome(userDir) {
  */
 function ensureUserHome(userDir) {
   const declaration = declaredUserHome(userDir);
+  const materializedExactPaths = [];
   for (const root of declaration.roots) {
     fs.mkdirSync(root.path, { recursive: true, mode: 0o700 });
   }
@@ -115,15 +134,18 @@ function ensureUserHome(userDir) {
   }
 
   const manifest = declaration.exactManaged.find((entry) => entry.key === 'home-manifest');
-  if (manifest && !fs.existsSync(manifest.path)) {
-    writeJson(manifest.path, {
-      schemaVersion: USER_HOME_SCHEMA_VERSION,
-      kind: 'amalgm-user-home',
-      roots: declaration.roots.map(({ key, relativePath }) => ({ key, path: relativePath })),
-      exactManaged: declaration.exactManaged.map(({ key, relativePath, scope }) => ({ key, path: relativePath, scope })),
-    });
+  const manifestContents = {
+    schemaVersion: USER_HOME_SCHEMA_VERSION,
+    kind: 'amalgm-user-home',
+    roots: declaration.roots.map(({ key, relativePath }) => ({ key, path: relativePath })),
+    exactManaged: declaration.exactManaged.map(({ key, relativePath, scope }) => ({ key, path: relativePath, scope })),
+  };
+  if (manifest && JSON.stringify(readJson(manifest.path, null)) !== JSON.stringify(manifestContents)) {
+    writeJson(manifest.path, manifestContents);
+    materializedExactPaths.push(manifest.relativePath);
   }
-  return declaration;
+
+  return { ...declaration, materializedExactPaths };
 }
 
 function lstatOrNull(target) {
@@ -401,6 +423,7 @@ module.exports = {
   LAYOUT_VERSION,
   PRIMITIVE_DIRS,
   ROOT_MANIFEST_NAME,
+  SYSTEM_TOOL_ARTIFACTS,
   USER_MANIFEST_NAME,
   USER_HOME_EXACT_MANAGED,
   USER_HOME_MANIFEST_NAME,

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

@@ -11,7 +11,13 @@
 
 const crypto = require('crypto');
 
-const ENTITY_CLOUD_CONTRACT = 'amalgm-entity-registry@1';
+// `@1` could project arbitrary pre-cloud registrations. `@2` omitted the
+// declared built-in tool entities, so its toolbox root could not prove the
+// snapshot membership it named. A resource contract names immutable authority
+// semantics: both remain quarantined rather than reinterpreted or overwritten.
+// `@3` begins with the complete verified user home; later user ground enters
+// exclusively through `amalgm register`.
+const ENTITY_CLOUD_CONTRACT = 'amalgm-entity-registry@3';
 const ENTITY_CLOUD_SCHEMA_VERSION = 1;
 const BOOTSTRAP_RECONCILIATION_STATE = 'reconciling-bootstrap';
 const SNAPSHOT_REPLACE_OPERATION = 'entity.snapshot.replace';
@@ -186,6 +192,56 @@ function createEntityCloud({ db, userId, deviceId, content = null, repoStates =
     };
   }
 
+  // The catalog mirrors the compacted cloud head as long as every head
+  // advance since the last installed snapshot was applied to it in order:
+  // journal() upserts this device's own records, ingest() upserts remote
+  // ones, and the gateway's fold regenerates only derived container
+  // versions, which every catalog consumer already tolerates. A version
+  // gap, a remote snapshot replacement, or a restart drops this back to
+  // whatever the durable pin proves, and the next snapshot download
+  // re-establishes it.
+  let catalogLive = null;
+  // Mutation rows whose content-upload cursors already exist on disk.
+  const contentQueuedSequences = new Set();
+
+  function catalogPinnedAtHead(current) {
+    if (!current) return false;
+    const pin = db.prepare(`
+      SELECT resource_id, authority_epoch, snapshot_version
+      FROM entity_cloud_catalog_state WHERE singleton = 1
+    `).get();
+    return Boolean(pin && pin.resource_id === current.resourceId
+      && Number(pin.authority_epoch) === current.authorityEpoch
+      && Number(pin.snapshot_version) === current.headVersion);
+  }
+
+  function unsettledMutationCount(resourceId) {
+    return Number(db.prepare(`
+      SELECT COUNT(*) AS count FROM entity_cloud_mutations
+      WHERE resource_id = ? AND mutation_state <> 'synced'
+    `).get(resourceId).count);
+  }
+
+  function catalogIsLive(current) {
+    if (catalogLive === null) {
+      catalogLive = catalogPinnedAtHead(current) && unsettledMutationCount(current.resourceId) === 0;
+    }
+    return catalogLive;
+  }
+
+  function pinCatalogState({ resourceId, authorityEpoch, headVersion }) {
+    db.prepare(`
+      INSERT INTO entity_cloud_catalog_state (
+        singleton, resource_id, authority_epoch, snapshot_version, updated_at
+      ) VALUES (1, ?, ?, ?, ?)
+      ON CONFLICT(singleton) DO UPDATE SET
+        resource_id = excluded.resource_id,
+        authority_epoch = excluded.authority_epoch,
+        snapshot_version = excluded.snapshot_version,
+        updated_at = excluded.updated_at
+    `).run(resourceId, authorityEpoch, headVersion, now());
+  }
+
   function saveReplica(value) {
     db.prepare(`
       INSERT INTO entity_cloud_replica (
@@ -231,16 +287,7 @@ function createEntityCloud({ db, userId, deviceId, content = null, repoStates =
       // A later mutation may update an individual catalog row so live state
       // can be inspected, but that must never make the whole catalog look
       // like a newly compacted snapshot that is safe to materialize.
-      db.prepare(`
-        INSERT INTO entity_cloud_catalog_state (
-          singleton, resource_id, authority_epoch, snapshot_version, updated_at
-        ) VALUES (1, ?, ?, ?, ?)
-        ON CONFLICT(singleton) DO UPDATE SET
-          resource_id = excluded.resource_id,
-          authority_epoch = excluded.authority_epoch,
-          snapshot_version = excluded.snapshot_version,
-          updated_at = excluded.updated_at
-      `).run(resourceId, authorityEpoch, headVersion, now());
+      pinCatalogState({ resourceId, authorityEpoch, headVersion });
     })();
     return normalized;
   }
@@ -518,6 +565,7 @@ function createEntityCloud({ db, userId, deviceId, content = null, repoStates =
         });
         enqueueBootstrapReconciliation(trustedBootstrap, next);
       })();
+      catalogLive = false;
       return {
         resourceId,
         records: snapshot.records.length,
@@ -552,6 +600,7 @@ function createEntityCloud({ db, userId, deviceId, content = null, repoStates =
         state: complete ? 'active' : BOOTSTRAP_RECONCILIATION_STATE,
         snapshotCutoff: null,
       });
+      catalogLive = complete;
       return {
         resourceId,
         records: snapshot.records.length,
@@ -599,6 +648,10 @@ function createEntityCloud({ db, userId, deviceId, content = null, repoStates =
       state: 'active',
       snapshotCutoff: null,
     });
+    // A snapshot installed over unsettled local mutations replaced their
+    // catalog upserts; liveness returns with the install that finds an
+    // empty outbox.
+    catalogLive = unsettledMutationCount(resourceId) === 0;
     return {
       resourceId,
       records: snapshot.records.length,
@@ -705,6 +758,58 @@ function createEntityCloud({ db, userId, deviceId, content = null, repoStates =
     return materialization(db.prepare('SELECT * FROM entity_materializations WHERE job_id = ?').get(jobId));
   }
 
+  /** Read-only cloud-replica truth for `amalgm status`.  This deliberately
+   * reports a stale catalog as stale instead of presenting its records as a
+   * head that is safe to materialize.  Status is an observer of authority,
+   * never a repair or a hidden snapshot handshake. */
+  function status() {
+    const current = replica();
+    const resourceId = current?.resourceId || null;
+    const mutationCounts = new Map();
+    if (resourceId) {
+      for (const row of db.prepare(`
+        SELECT mutation_state, COUNT(*) AS count
+        FROM entity_cloud_mutations
+        WHERE resource_id = ?
+        GROUP BY mutation_state
+      `).all(resourceId)) {
+        mutationCounts.set(row.mutation_state, Number(row.count));
+      }
+    }
+    const materializationCounts = new Map();
+    if (resourceId) {
+      for (const row of db.prepare(`
+        SELECT state, COUNT(*) AS count
+        FROM entity_materializations
+        WHERE resource_id = ?
+        GROUP BY state
+      `).all(resourceId)) {
+        materializationCounts.set(row.state, Number(row.count));
+      }
+    }
+    const pending = (mutationCounts.get('pending') || 0) + (mutationCounts.get('syncing') || 0);
+    const pinned = current ? catalogPinnedAtHead(current) : false;
+    return {
+      identity: identity(),
+      replica: current,
+      catalog: {
+        pinned,
+        current: Boolean(current?.state === 'active' && pinned && pending === 0),
+        records: resourceId ? catalogRecords(resourceId) : [],
+      },
+      outbox: {
+        pending: mutationCounts.get('pending') || 0,
+        syncing: mutationCounts.get('syncing') || 0,
+        rejected: mutationCounts.get('rejected') || 0,
+      },
+      materializations: {
+        waitingForContent: materializationCounts.get('waiting_for_content') || 0,
+        materializing: materializationCounts.get('materializing') || 0,
+        failed: materializationCounts.get('failed') || 0,
+      },
+    };
+  }
+
   /** A completed add is a live binding, not a one-time download.  A remote
    * record beneath that binding moves the durable job back to its content
    * gate.  The service owns the later filesystem application; this module
@@ -805,17 +910,21 @@ function createEntityCloud({ db, userId, deviceId, content = null, repoStates =
     // Later registrations journal their record transactionally in SQLite.
     // Derive its content-upload cursor only after that commit exists, so a
     // failed transaction cannot publish a private object no entity names.
+    // Each mutation's operation is immutable, so it is scanned once per
+    // process; a restart simply rescans the still-unsettled rows.
     const rows = db.prepare(`
-      SELECT operation_json FROM entity_cloud_mutations
+      SELECT sequence, operation_json FROM entity_cloud_mutations
       WHERE resource_id = ? AND mutation_state IN ('pending', 'syncing')
       ORDER BY sequence ASC
     `).all(current.resourceId);
     for (const row of rows) {
+      if (contentQueuedSequences.has(row.sequence)) continue;
       const operation = JSON.parse(row.operation_json);
       const records = operation?.kind === SNAPSHOT_REPLACE_OPERATION
         ? operation?.snapshot?.records
         : [operation?.record];
       for (const record of records || []) queueContent(record, current.resourceId, { queue: true });
+      contentQueuedSequences.add(row.sequence);
     }
     return content.claim({ resourceId: current.resourceId, leaseMs });
   }
@@ -845,31 +954,59 @@ function createEntityCloud({ db, userId, deviceId, content = null, repoStates =
         .get(resourceId, mutationId);
       if (!row) throw new Error(`unknown entity cloud mutation ${mutationId}`);
       if (row.mutation_state === 'synced') {
-        const unsettled = db.prepare('SELECT COUNT(*) AS count FROM entity_cloud_mutations WHERE resource_id = ? AND mutation_state <> \'synced\'')
-          .get(resourceId);
         return {
           duplicate: true,
           version: Number(row.official_version),
-          requiresSnapshot: current.state !== BOOTSTRAP_RECONCILIATION_STATE || Number(unsettled.count) === 0,
+          requiresSnapshot: current.state === BOOTSTRAP_RECONCILIATION_STATE
+            ? unsettledMutationCount(resourceId) === 0
+            : !catalogIsLive(current),
         };
       }
       if (!['pending', 'syncing'].includes(row.mutation_state)) throw new Error(`entity cloud mutation ${mutationId} cannot sync from ${row.mutation_state}`);
+      const live = current.state === BOOTSTRAP_RECONCILIATION_STATE ? false : catalogIsLive(current);
       db.prepare(`
         UPDATE entity_cloud_mutations
         SET mutation_state = 'synced', official_version = ?, cloud_committed_at = ?,
             next_attempt_at = NULL, last_error = NULL, updated_at = ?
         WHERE sequence = ?
       `).run(Number(version), String(committedAt || now()), now(), row.sequence);
-      if (Number(version) > current.headVersion) {
+      const previousHead = current.headVersion;
+      if (Number(version) > previousHead) {
         saveReplica({ ...current, headVersion: Number(version) });
       }
-      const unsettled = db.prepare('SELECT COUNT(*) AS count FROM entity_cloud_mutations WHERE resource_id = ? AND mutation_state <> \'synced\'')
-        .get(resourceId);
-      return {
-        duplicate: false,
-        version: Number(version),
-        requiresSnapshot: current.state !== BOOTSTRAP_RECONCILIATION_STATE || Number(unsettled.count) === 0,
-      };
+      const unsettled = unsettledMutationCount(resourceId);
+      if (current.state === BOOTSTRAP_RECONCILIATION_STATE) {
+        return { duplicate: false, version: Number(version), requiresSnapshot: unsettled === 0 };
+      }
+      // Local convergence instead of a snapshot re-download per ack. This
+      // device journaled these exact records into the catalog when the
+      // mutation was created, so an in-order acknowledgement leaves the
+      // catalog equal to the compacted head by construction. Anything out
+      // of order gives liveness up until the next installed snapshot.
+      let operation = null;
+      try { operation = JSON.parse(row.operation_json); } catch {}
+      if (operation?.kind === SNAPSHOT_REPLACE_OPERATION) {
+        if (unsettled === 0 && Array.isArray(operation?.snapshot?.records)) {
+          // The replacement operation IS the complete graph at this version.
+          replaceCatalog({
+            resourceId,
+            authorityEpoch: current.authorityEpoch,
+            headVersion: Number(version),
+            records: operation.snapshot.records,
+          });
+          catalogLive = true;
+        } else {
+          catalogLive = false;
+        }
+      } else if (!operation || Number(version) !== previousHead + 1) {
+        catalogLive = false;
+      } else {
+        catalogLive = live;
+        if (catalogLive && unsettled === 0) {
+          pinCatalogState({ resourceId, authorityEpoch: current.authorityEpoch, headVersion: Number(version) });
+        }
+      }
+      return { duplicate: false, version: Number(version), requiresSnapshot: !catalogLive };
     })();
   }
 
@@ -907,10 +1044,17 @@ function createEntityCloud({ db, userId, deviceId, content = null, repoStates =
     if (envelope?.operationKind === SNAPSHOT_REPLACE_OPERATION
       && envelope?.operation?.kind === SNAPSHOT_REPLACE_OPERATION) {
       // The complete replacement is imported only from the active snapshot
-      // the gateway makes before acknowledgement. Consuming its tail would
-      // reintroduce the very partial-graph state this operation prevents.
+      // the gateway compacts at lookup. Consuming its tail would reintroduce
+      // the very partial-graph state this operation prevents.
       if (Number(version) > current.headVersion) saveReplica({ ...current, headVersion: Number(version) });
-      return { duplicate: true, version: Number(version), snapshotRequired: true, materializations: [] };
+      catalogLive = false;
+      return {
+        duplicate: true,
+        version: Number(version),
+        snapshotRequired: true,
+        requiresSnapshot: true,
+        materializations: [],
+      };
     }
     if (envelope?.operationKind !== 'entity.upsert' || envelope?.operation?.kind !== 'entity.upsert') {
       throw new Error('cloud entity mutation does not belong to this registry');
@@ -946,10 +1090,24 @@ function createEntityCloud({ db, userId, deviceId, content = null, repoStates =
       headVersion: Number(version),
       record,
     });
-    if (Number(version) > current.headVersion) saveReplica({ ...current, headVersion: Number(version) });
+    // A remote record applied in official order keeps the catalog at the
+    // compacted head, so no snapshot re-download is needed for it either.
+    const live = catalogIsLive(current);
+    const previousHead = current.headVersion;
+    if (Number(version) > previousHead) saveReplica({ ...current, headVersion: Number(version) });
+    if (Number(version) !== previousHead + 1) {
+      catalogLive = false;
+    } else if (live && unsettledMutationCount(current.resourceId) === 0) {
+      pinCatalogState({
+        resourceId: current.resourceId,
+        authorityEpoch: current.authorityEpoch,
+        headVersion: Number(version),
+      });
+    }
     return {
       duplicate: true,
       version: Number(version),
+      requiresSnapshot: !catalogLive,
       materializations: refreshMaterializations({ resourceId: current.resourceId, record, version }),
     };
   }
@@ -975,6 +1133,7 @@ function createEntityCloud({ db, userId, deviceId, content = null, repoStates =
     completeMaterialization,
     failMaterialization,
     materializationStatus,
+    status,
     hasUnsettledLocalMutation,
     catalogTree,
     replica,