amalgm 0.1.257 → 0.1.259

package/lib/cli.js

@@ -120,7 +120,10 @@ 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 ls [entity]       List the verified cloud workspace',
+    '  amalgm cd <entity>       Resolve a materialized cloud directory',
+    '  amalgm status [path-or-uuid] Show cloud-backed entity and watcher state',
+    '  amalgm shell init zsh    Enable `amalgm cd` in the current shell',
     '  amalgm doctor',
     '  amalgm service [install|start|stop|status|uninstall] [--mode auto|systemd|launchd|windows|portable]',
     '  amalgm update [--tag latest|canary]',
@@ -1112,7 +1115,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 +1180,203 @@ async function status() {
   }
 }
 
+/** One runtime read for every navigation command.  The endpoint owns facts;
+ * these commands only select and render them, so navigating never becomes a
+ * backdoor mutation or cloud refresh. */
+async function readEntityStatus() {
+  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 null;
+  }
+  if (answer.status !== 200 || !answer.payload) {
+    console.error(`Error: ${answer.payload?.error || `runtime responded ${answer.status}`}`);
+    process.exitCode = 1;
+    return null;
+  }
+  return answer.payload;
+}
+
+/** A selector is deliberately exact: full UUID, local address, canonical
+ * cloud path, or an unambiguous entity name.  A guessed fuzzy match would
+ * make a cloud navigation command choose the wrong ground. */
+function selectEntity(status, selector) {
+  const entities = status.entities || [];
+  if (!selector) return 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 cloudPath = uuid ? null : String(selector).replace(/^\/+|\/+$/g, '');
+  const matches = entities.filter((entity) => entity.uuid === uuid
+    || entity.localPath === localPath
+    || entity.cloudPath === cloudPath
+    || entity.name === selector);
+  if (matches.length === 0) throw new Error(`No cloud-backed entity matches ${selector}.`);
+  if (matches.length > 1) {
+    throw new Error(`Entity selector ${selector} is ambiguous: ${matches.map((entity) => entity.cloudPath || entity.uuid).join(', ')}. Use a UUID or canonical cloud path.`);
+  }
+  return matches[0];
+}
+
+function requireCurrentCloudWorkspace(status) {
+  const cloud = status.cloud || {};
+  if (!cloud.replica) {
+    throw new Error(cloud.identity?.enabled
+      ? 'Cloud workspace is initializing; wait for the signed-in runtime to finish its handshake.'
+      : 'Cloud workspace is unavailable because this machine is not signed in.');
+  }
+  if (!cloud.catalog?.current) {
+    throw new Error('Cloud workspace is catching up; wait for the active verified cloud head before listing it.');
+  }
+}
+
+function printEntityLine(entity) {
+  const where = entity.localPath ? 'local' : 'cloud only';
+  console.log(`  ${entity.name}\t${entity.type}\t${entity.status}\t${where}\t${entity.uuid}`);
+}
+
+/** `amalgm status [path-or-uuid]` is a read-only health view.  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 status = await readEntityStatus();
+  if (!status) return;
+  const selector = positionals[0] || null;
+  let entities = status.entities || [];
+  if (selector) {
+    try {
+      entities = [selectEntity(status, selector)];
+    } catch (error) {
+      console.error(error.message);
+      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}`);
+    }
+  }
+}
+
+/** `amalgm ls [entity]` lists the canonical cloud graph, never this
+ * machine's incidental directory.  A stale catalog is useful in `status`,
+ * but is never presented as a navigable workspace here. */
+async function entityList(positionals) {
+  if (positionals.length > 1) throw new Error('Usage: amalgm ls [entity]');
+  const status = await readEntityStatus();
+  if (!status) return;
+  try {
+    requireCurrentCloudWorkspace(status);
+    const selected = positionals[0] ? selectEntity(status, positionals[0]) : null;
+    if (selected && !selected.catalogued) {
+      throw new Error(`Entity ${selected.uuid} is not in the verified cloud workspace yet.`);
+    }
+    const entities = (status.entities || []).filter((entity) => entity.catalogued
+      && entity.status === 'active'
+      && (selected ? entity.parentUUID === selected.uuid : entity.parentUUID === null))
+      .sort((left, right) => left.name.localeCompare(right.name));
+    if (selected) console.log(`${selected.cloudPath || selected.uuid}:`);
+    console.log('NAME\tTYPE\tSTATE\tLOCATION\tUUID');
+    for (const entity of entities) printEntityLine(entity);
+  } catch (error) {
+    console.error(error.message);
+    process.exitCode = 1;
+  }
+}
+
+async function resolveEntityDirectory(positionals) {
+  if (positionals.length !== 1) throw new Error('Usage: amalgm cd <entity>');
+  const status = await readEntityStatus();
+  if (!status) return null;
+  const entity = selectEntity(status, positionals[0]);
+  if (!entity.localPath) {
+    throw new Error(`Cloud entity ${entity.cloudPath || entity.uuid} is not materialized on this machine. Run \`amalgm add ${entity.uuid} <directory>\` first.`);
+  }
+  let stat;
+  try { stat = fs.statSync(entity.localPath); } catch {
+    throw new Error(`Local binding for ${entity.cloudPath || entity.uuid} is unavailable at ${entity.localPath}. Run \`amalgm status ${entity.uuid}\` for details.`);
+  }
+  if (!stat.isDirectory()) {
+    throw new Error(`${entity.cloudPath || entity.uuid} is a ${entity.type}, not a directory.`);
+  }
+  return entity.localPath;
+}
+
+/** A standalone process cannot change the invoking shell.  This direct form
+ * resolves a directory honestly and points to the opt-in shell integration;
+ * the shell function below intercepts the same spelling and performs cd. */
+async function entityCd(positionals) {
+  try {
+    const target = await resolveEntityDirectory(positionals);
+    if (!target) return;
+    console.log(target);
+    console.log('Run `eval "$(amalgm shell init zsh)"` once to make `amalgm cd <entity>` change this shell.');
+  } catch (error) {
+    console.error(error.message);
+    process.exitCode = 1;
+  }
+}
+
+async function resolveEntityDirectoryMachine(positionals) {
+  try {
+    const target = await resolveEntityDirectory(positionals);
+    if (target) console.log(target);
+  } catch (error) {
+    console.error(error.message);
+    process.exitCode = 1;
+  }
+}
+
+function shellCommand(positionals) {
+  if (positionals[0] !== 'init' || !['zsh', 'bash'].includes(positionals[1] || 'zsh') || positionals.length > 2) {
+    throw new Error('Usage: amalgm shell init [zsh|bash]');
+  }
+  console.log(`amalgm() {
+  if [ "$1" = cd ]; then
+    shift
+    local _amalgm_destination
+    _amalgm_destination="$(command amalgm __resolve-directory "$@")" || return $?
+    builtin cd "$_amalgm_destination"
+    return $?
+  fi
+  command amalgm "$@"
+}`);
+}
+
 async function doctor() {
   ensureBaseDirs();
 
@@ -1649,7 +1849,11 @@ 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 === 'ls') return entityList(positionals);
+  if (command === 'cd') return entityCd(positionals);
+  if (command === 'status') return entityStatus(positionals);
+  if (command === 'shell') return shellCommand(positionals);
+  if (command === '__resolve-directory') return resolveEntityDirectoryMachine(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.259",
   "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/observer/index.js

@@ -40,7 +40,7 @@ const path = require('path');
 const { createApply } = require('./apply');
 const { createContinuity } = require('./continuity');
 const { createStore } = require('./store');
-const { censusBoundaries, censusLinks, diffDirState, diffLinkState, diffRootState, gitDirTruth, walkRoot } = require('./scan');
+const { censusBoundaries, censusLinks, diffDirState, diffLinkState, diffRootState, gitDirTruth, listDir, walkRoot } = require('./scan');
 const { createVerify } = require('./verify');
 const { watchDir, watchRecursive } = require('./watch');
 const { adapterFor } = require('../adapters');
@@ -343,18 +343,75 @@ function createObserver(options) {
     }
     if (parent) {
       // Born from a files root, returned to it: the parent's next scan
-      // reclaims the files as creates.
+      // reclaims the files as creates. No doorbell will ever name the
+      // reclaimed ground, so every file is suspect — the scan must walk.
       detach(root.rootId);
       store.removeRoot(root.rootId);
-      live.get(parent.rootId)?.territories.delete(root.path.slice(parent.path.length + 1));
+      const parentState = live.get(parent.rootId);
+      parentState?.territories.delete(root.path.slice(parent.path.length + 1));
+      if (parentState) parentState.checkAll = true;
       scanFilesRoot(parent);
       return;
     }
     store.setRootKind(root.rootId, 'files');
-    if (state) state.kind = 'files';
+    if (state) {
+      state.kind = 'files';
+      state.checkAll = true; // conversion ground has no doorbells: walk it
+    }
     scanFilesRoot({ ...root, kind: 'files' });
   }
 
+  /**
+   * The scoped scan a NAMED doorbell earns: read only the directories
+   * the rung paths live in, compare only those directories' rows, and
+   * conclude only what is channel-local — an existing file's bytes
+   * changed, an existing link's written target changed. Anything
+   * structural (a create, a delete, a rename, a retag, a `.git`, an
+   * unreadable or absent directory) may be half of a story another
+   * directory holds, so it concludes nothing here and escalates to the
+   * full walk, which owns those laws unchanged. Returns true when the
+   * scoped conclusion was complete; false means walk.
+   */
+  function scanRungDirs(root, state, rung) {
+    const scopeDirs = new Set();
+    for (const relPath of rung) {
+      scopeDirs.add(relPath.includes('/') ? relPath.slice(0, relPath.lastIndexOf('/')) : '');
+      // A rung directory is also looked at directly: its own children
+      // may be what actually changed (the OS may name only the folder).
+      if (isDirectory(path.join(root.path, relPath))) scopeDirs.add(relPath);
+    }
+    const entries = { files: [], dirs: [], links: [] };
+    for (const relDir of scopeDirs) {
+      if (relDir !== '' && underTerritory(state, relDir)) return false; // territory ground answers to its own root
+      const look = listDir(root.path, relDir, shouldEnroll);
+      if (look.absent || look.unsettled || look.hasGit) return false;
+      for (const dir of look.dirs) {
+        // A nested repo is territory, never a dir channel — walkRoot
+        // reports it to repoDirs; the scoped look just leaves it alone.
+        if (state.territories.has(dir.relPath)) continue;
+        entries.dirs.push(dir);
+      }
+      entries.files.push(...look.files);
+      entries.links.push(...look.links);
+    }
+    const dirs = [...scopeDirs];
+    const rows = {
+      files: dirs.flatMap((relDir) => store.filesInDir(root.rootId, relDir)),
+      dirs: dirs.flatMap((relDir) => store.dirsInDir(root.rootId, relDir)),
+      links: dirs.flatMap((relDir) => store.linksInDir(root.rootId, relDir)),
+    };
+    const dirDiff = diffDirState(rows.dirs, entries.dirs);
+    const linkDiff = diffLinkState(rows.links, entries.links);
+    const fileDiff = diffRootState(rows.files, entries.files, rung);
+    const structural = dirDiff.renames.length || dirDiff.retags.length || dirDiff.creates.length || dirDiff.deletes.length
+      || linkDiff.renames.length || linkDiff.creates.length || linkDiff.deletes.length
+      || fileDiff.renames.length || fileDiff.creates.length || fileDiff.deletes.length;
+    if (structural) return false;
+    applyLinkDiff(root, linkDiff); // changes and retags: payload-local facts
+    applyDiff(root, fileDiff); // checks only: content truth on existing channels
+    return true;
+  }
+
   function scanFilesRoot(root, { allowRootRepository = false } = {}) {
     // Drain the doorbell's named hints first: anything that rings during the
     // walk below belongs to the next scan, not this one.
@@ -366,6 +423,10 @@ function createObserver(options) {
       state.checkAll = false;
     }
 
+    // A named doorbell earns a scoped look; only a nameless one (or a
+    // scoped look that met structural news) pays for the whole walk.
+    if (!checkAll && rung.size > 0 && state && scanRungDirs(root, state, rung)) return;
+
     const { files: entries, dirs, links, repoDirs, unsettled } = walkRoot(
       root.path,
       shouldEnroll,

package/runtime/scripts/amalgm-mcp/observer/scan.js

@@ -126,6 +126,65 @@ function walkRoot(rootPath, shouldEnroll, { allowRootRepository = false } = {})
   return { files, dirs, links, repoDirs, unsettled };
 }
 
+/**
+ * One directory's immediate truth — the scoped look a NAMED doorbell
+ * earns (walkRoot is the nameless doorbell's). Same laws, one level
+ * deep: entries classified exactly as walkRoot classifies them,
+ * symlinks read but never followed. The caller decides what a scoped
+ * look may conclude; this function only refuses to pretend it saw more
+ * than one directory: a `.git` here is territory news (`hasGit`), a
+ * listing that failed is `unsettled`, a directory that is gone is
+ * `absent` — all three send the caller to the full walk, which owns
+ * those conclusions.
+ */
+function listDir(rootPath, relDir, shouldEnroll) {
+  const absDir = relDir ? path.join(rootPath, relDir) : rootPath;
+  const out = { files: [], dirs: [], links: [], hasGit: false, absent: false, unsettled: false };
+  let entries;
+  try {
+    entries = fs.readdirSync(absDir, { withFileTypes: true });
+  } catch (error) {
+    if (lookFailed(error).truth === 'absent') out.absent = true;
+    else out.unsettled = true;
+    return out;
+  }
+  if (entries.some((entry) => entry.name === '.git')) {
+    out.hasGit = true;
+    return out;
+  }
+  for (const entry of entries) {
+    const relPath = relDir ? `${relDir}/${entry.name}` : entry.name;
+    if (!shouldEnroll(relPath)) continue;
+    let stat;
+    try {
+      stat = fs.lstatSync(path.join(rootPath, relPath));
+    } catch (error) {
+      // Vanished mid-look is honest absence (simply not listed); a
+      // failed look concludes nothing — the full walk reads again.
+      if (lookFailed(error).truth === 'unsettled') out.unsettled = true;
+      continue;
+    }
+    if (stat.isDirectory()) {
+      out.dirs.push({ relPath, device: stat.dev, inode: stat.ino });
+    } else if (stat.isSymbolicLink()) {
+      try {
+        out.links.push({ relPath, device: stat.dev, inode: stat.ino, target: fs.readlinkSync(path.join(rootPath, relPath)) });
+      } catch (error) {
+        if (lookFailed(error).truth === 'unsettled') out.unsettled = true;
+      }
+    } else if (stat.isFile()) {
+      out.files.push({
+        relPath,
+        device: stat.dev,
+        inode: stat.ino,
+        size: stat.size,
+        mtimeMs: Math.floor(stat.mtimeMs),
+      });
+    }
+  }
+  return out;
+}
+
 function defaultShouldEnroll(relPath) {
   return require('../workspace/tree/inclusion').shouldEnroll(relPath);
 }
@@ -384,4 +443,4 @@ function diffRootState(rows, entries, mustCheck = null) {
   return actions;
 }
 
-module.exports = { censusBoundaries, censusLinks, diffDirState, diffLinkState, diffRootState, gitDirTruth, walkRoot };
+module.exports = { censusBoundaries, censusLinks, diffDirState, diffLinkState, diffRootState, gitDirTruth, listDir, walkRoot };