amalgm 0.1.257 → 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@2';
+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.257",
+  "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,