amalgm 0.1.258 → 0.1.260

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 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]',
@@ -1177,12 +1180,10 @@ async function runtimeStatus() {
   }
 }
 
-/** `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]');
+/** 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) {
@@ -1195,26 +1196,71 @@ async function entityStatus(positionals) {
   if (!answer) {
     console.error('Amalgm runtime is not running. Start it with `amalgm start`.');
     process.exitCode = 1;
-    return;
+    return null;
   }
   if (answer.status !== 200 || !answer.payload) {
     console.error(`Error: ${answer.payload?.error || `runtime responded ${answer.status}`}`);
     process.exitCode = 1;
-    return;
+    return null;
   }
+  return answer.payload;
+}
 
-  const status = answer.payload;
-  const selector = positionals[0] || null;
+/** 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 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 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 || {};
@@ -1246,6 +1292,91 @@ async function entityStatus(positionals) {
   }
 }
 
+/** `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();
 
@@ -1718,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 === '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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "amalgm",
-  "version": "0.1.258",
+  "version": "0.1.260",
   "description": "Amalgm local computer runtime: login, MCP, chat, events, previews, and tunnels.",
   "license": "UNLICENSED",
   "private": false,

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

@@ -14,15 +14,31 @@ const { lookFailed } = require('../adapters/truth');
 /**
  * Does a .git hold this ground? Three answers, like every look — and
  * only present or absent may conclude: territory is never born,
- * buried, or converted on a look that failed.
+ * buried, or converted on a look that failed. A directory is Git's own
+ * repository marker. A file is a linked-worktree/submodule pointer, so it
+ * claims territory only when the referenced gitdir still exists: a stale
+ * pointer is ordinary folder ground, never a broken repo boundary.
  */
 function gitDirTruth(absDir) {
+  let marker;
   try {
-    fs.lstatSync(path.join(absDir, '.git'));
-    return 'present';
+    marker = fs.lstatSync(path.join(absDir, '.git'));
   } catch (error) {
     return lookFailed(error).truth;
   }
+  if (marker.isDirectory()) return 'present';
+  if (!marker.isFile()) return 'absent';
+  try {
+    const source = fs.readFileSync(path.join(absDir, '.git'), 'utf8');
+    const match = /^gitdir:\s*(.+?)\s*$/im.exec(source);
+    if (!match) return 'absent';
+    const gitDir = path.resolve(absDir, match[1]);
+    if (!fs.lstatSync(gitDir).isDirectory()) return 'absent';
+    if (!fs.lstatSync(path.join(gitDir, 'HEAD')).isFile()) return 'absent';
+    return 'present';
+  } catch (error) {
+    return lookFailed(error).truth === 'unsettled' ? 'unsettled' : 'absent';
+  }
 }
 
 /**
@@ -72,9 +88,15 @@ function walkRoot(rootPath, shouldEnroll, { allowRootRepository = false } = {})
       vanished(error, relDir);
       continue;
     }
-    // A .git claims its subtree: an embedded repository is repo territory,
-    // never files territory. Its changes travel as one card, not as files.
-    if (entries.some((entry) => entry.name === '.git') && !(allowRootRepository && relDir === '')) {
+    // A valid .git claims its subtree: an embedded repository is repo
+    // territory, never files territory. Its changes travel as one card, not
+    // as files. A stale linked-worktree pointer is plain folder ground.
+    const territory = gitDirTruth(absDir);
+    if (territory === 'unsettled') {
+      unsettled.push(relDir);
+      continue;
+    }
+    if (territory === 'present' && !(allowRootRepository && relDir === '')) {
       repoDirs.push(relDir);
       if (!relDir) return { files: [], dirs: [], links: [], repoDirs, unsettled }; // the whole root is repo territory
       continue;
@@ -126,6 +148,70 @@ 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;
+  }
+  const territory = gitDirTruth(absDir);
+  if (territory === 'unsettled') {
+    out.unsettled = true;
+    return out;
+  }
+  if (territory === 'present') {
+    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);
 }
@@ -159,7 +245,12 @@ function censusBoundaries(rootPath, shouldEnroll = defaultShouldEnroll) {
       if (lookFailed(error).truth === 'unsettled') unsettled.push(relDir);
       continue;
     }
-    if (relDir && entries.some((entry) => entry.name === '.git')) {
+    const territory = gitDirTruth(absDir);
+    if (territory === 'unsettled') {
+      unsettled.push(relDir);
+      continue;
+    }
+    if (relDir && territory === 'present') {
       boundaries.push(relDir);
       continue;
     }
@@ -200,7 +291,12 @@ function censusLinks(rootPath, shouldEnroll = defaultShouldEnroll) {
       if (lookFailed(error).truth === 'unsettled') unsettled.push(relDir);
       continue;
     }
-    if (relDir && entries.some((entry) => entry.name === '.git')) continue;
+    const territory = gitDirTruth(absDir);
+    if (territory === 'unsettled') {
+      unsettled.push(relDir);
+      continue;
+    }
+    if (relDir && territory === 'present') continue;
     for (const entry of entries) {
       if (entry.name === '.git') continue;
       const rel = relDir ? `${relDir}/${entry.name}` : entry.name;
@@ -384,4 +480,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 };

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

@@ -78,6 +78,20 @@ function rowToFile(row) {
   };
 }
 
+function rowToDir(row) {
+  return {
+    dirId: row.dir_id, rootId: row.root_id, relPath: row.rel_path,
+    device: row.device, inode: row.inode,
+  };
+}
+
+function rowToLink(row) {
+  return {
+    linkId: row.link_id, rootId: row.root_id, relPath: row.rel_path,
+    device: row.device, inode: row.inode, target: row.target,
+  };
+}
+
 const TABLES = ['observer_roots', 'observer_files', 'observer_dirs', 'observer_links'];
 
 function rowToRoot(row) {
@@ -127,6 +141,24 @@ function createStore(db) {
   db.exec(SCHEMA);
   db.pragma(`user_version = ${GENERATION}`);
 
+  /**
+   * One directory's immediate child rows — the scoped scan's slice of
+   * memory, served by the (root_id, rel_path) unique index. '0' is the
+   * character after '/', so [`dir/`, `dir0`) is exactly the rel_path
+   * range under the directory; depth filters to immediate children
+   * because rel_path is flat text.
+   */
+  function immediateRows(table, rootId, relDir) {
+    if (relDir === '') {
+      return db.prepare(`SELECT * FROM ${table} WHERE root_id = ? AND instr(rel_path, '/') = 0 ORDER BY rel_path`)
+        .all(rootId);
+    }
+    const prefix = `${relDir}/`;
+    return db.prepare(`SELECT * FROM ${table} WHERE root_id = ? AND rel_path >= ? AND rel_path < ? ORDER BY rel_path`)
+      .all(rootId, prefix, `${relDir}0`)
+      .filter((row) => !row.rel_path.slice(prefix.length).includes('/'));
+  }
+
   return {
     addRoot({ rootId, path, kind, device = null, inode = null }) {
       db.prepare('INSERT INTO observer_roots (root_id, path, kind, device, inode) VALUES (?, ?, ?, ?, ?)')
@@ -177,6 +209,15 @@ function createStore(db) {
       return db.prepare('SELECT * FROM observer_files WHERE root_id = ? ORDER BY rel_path').all(rootId)
         .map(rowToFile);
     },
+    filesInDir(rootId, relDir) {
+      return immediateRows('observer_files', rootId, relDir).map(rowToFile);
+    },
+    dirsInDir(rootId, relDir) {
+      return immediateRows('observer_dirs', rootId, relDir).map(rowToDir);
+    },
+    linksInDir(rootId, relDir) {
+      return immediateRows('observer_links', rootId, relDir).map(rowToLink);
+    },
     fileByPath(rootId, relPath) {
       return rowToFile(
         db.prepare('SELECT * FROM observer_files WHERE root_id = ? AND rel_path = ?').get(rootId, relPath),
@@ -204,10 +245,7 @@ function createStore(db) {
 
     dirsForRoot(rootId) {
       return db.prepare('SELECT * FROM observer_dirs WHERE root_id = ? ORDER BY rel_path').all(rootId)
-        .map((row) => ({
-          dirId: row.dir_id, rootId: row.root_id, relPath: row.rel_path,
-          device: row.device, inode: row.inode,
-        }));
+        .map(rowToDir);
     },
     /**
      * One compare result is ONE truth transition. Movers may exchange
@@ -240,10 +278,7 @@ function createStore(db) {
     // per-row like files — every commit is a valid last-known truth.
     linksForRoot(rootId) {
       return db.prepare('SELECT * FROM observer_links WHERE root_id = ? ORDER BY rel_path').all(rootId)
-        .map((row) => ({
-          linkId: row.link_id, rootId: row.root_id, relPath: row.rel_path,
-          device: row.device, inode: row.inode, target: row.target,
-        }));
+        .map(rowToLink);
     },
     insertLink({ linkId, rootId, relPath, device, inode, target }) {
       db.prepare('INSERT INTO observer_links (link_id, root_id, rel_path, device, inode, target) VALUES (?, ?, ?, ?, ?, ?)')

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

@@ -818,6 +818,20 @@ function createRegistrationService({
     const localRecords = boundary.current.registry.syncRecords();
     const localByUuid = new Map(localRecords.map((record) => [record.uuid, record]));
     const cloudByUuid = new Map(cloud.catalog.records.map((record) => [record.uuid, record]));
+    function cloudPathOf(uuid) {
+      const names = [];
+      const seen = new Set();
+      let record = cloudByUuid.get(uuid) || null;
+      while (record) {
+        if (seen.has(record.uuid)) return null;
+        seen.add(record.uuid);
+        names.unshift(record.name);
+        if (record.parentUUID === null) break;
+        record = cloudByUuid.get(record.parentUUID) || null;
+        if (!record) return null;
+      }
+      return names.length > 0 ? names.join('/') : null;
+    }
     const roots = observer.status().map((root) => {
       const tree = boundary.current.tree(root.path);
       const record = tree ? tree.root() : null;
@@ -847,6 +861,7 @@ function createRegistrationService({
         // `cloudBacked`: the enclosing cloud summary says whether the
         // catalog is actually pinned to an authoritative current head.
         catalogued: cloudByUuid.has(uuid),
+        cloudPath: cloudByUuid.has(uuid) ? cloudPathOf(uuid) : null,
         localPath,
         root: rootByUuid.get(uuid) || null,
       };

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

@@ -29,6 +29,7 @@
 const fs = require('fs');
 const path = require('path');
 const crypto = require('crypto');
+const { gitDirTruth } = require('../observer/scan');
 
 function rootType(rootPath, kind) {
   if (kind === 'repo') return 'repo.git';
@@ -37,18 +38,10 @@ function rootType(rootPath, kind) {
 }
 
 function isRepository(dirPath) {
-  try {
-    fs.lstatSync(path.join(dirPath, '.git'));
-    return true;
-  } catch (error) {
-    // A failed look cannot prove a repo boundary. Register the readable
-    // shape below it; observer territory detection retries the boundary
-    // look and performs the UUID-preserving folder → repo.git transition
-    // once Git becomes knowable.
-    if (error.code === 'ENOENT' || error.code === 'ENOTDIR'
-      || error.code === 'EACCES' || error.code === 'EPERM') return false;
-    throw error;
-  }
+  // This is the observer's exact territory primitive. In particular, a
+  // stale linked-worktree pointer must be ordinary folder ground for both
+  // structural registration and later Watch/Detect reconciliation.
+  return gitDirTruth(dirPath) === 'present';
 }
 
 /**

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

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

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

@@ -63,6 +63,21 @@ test('a .git claims its subtree: embedded repos are never files territory', () =
   ));
 });
 
+test('a stale linked-worktree pointer is ordinary folder ground, not a broken repository', () => {
+  const dir = makeDir('stale-gitfile');
+  const child = path.join(dir, 'former-submodule');
+  fs.mkdirSync(child);
+  fs.writeFileSync(path.join(child, '.git'), 'gitdir: ../.git/modules/missing\n');
+  fs.writeFileSync(path.join(child, 'readme.md'), 'still ordinary files');
+
+  const { observer, events } = makeObserver();
+  observer.enrollRoot(dir);
+
+  assert.deepEqual(eventsOf(events, 'repo.discovered'), []);
+  assert.deepEqual(eventsOf(events, 'file.created').map((event) => event.path), ['former-submodule/readme.md']);
+  assert.equal(observer.listRoots().some((root) => root.path === child && root.kind === 'repo'), false);
+});
+
 test('a .git vanishing returns its territory to files: channels are reborn', () => {
   const dir = makeDir('territory-back');
   fs.mkdirSync(path.join(dir, 'vendor', '.git'), { recursive: true });

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

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

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

@@ -435,6 +435,56 @@ test('a signed-in register call writes every entity delivery intent in identity.
   }
 });
 
+test('service status exposes only a verified cloud path as a navigable workspace', async () => {
+  const service = createRegistrationService({
+    dir: path.join(tempRoot, 'state-cloud-status'),
+    homeDir: path.join(tempRoot, 'cloud-status-home'),
+    cloudUserId: 'user-cloud-status',
+    cloudDeviceId: 'computer-cloud-status',
+  });
+  const bootstrap = service.entityCloud.bootstrap(service.registration.registry.syncRecords());
+  service.entityCloud.install({
+    registry: service.registration.registry,
+    resourceId: bootstrap.resourceId,
+    authorityEpoch: 1,
+    headVersion: 0,
+    snapshotBase64: bootstrap.snapshotBase64,
+    snapshotChecksum: bootstrap.snapshotChecksum,
+  });
+  const ground = makeGround('cloud-status');
+  fs.mkdirSync(path.join(ground, 'src'));
+
+  try {
+    const registered = await service.register(ground);
+    const beforeAcknowledgement = service.status();
+    assert.equal(beforeAcknowledgement.cloud.catalog.current, false,
+      'a pending local registration is visible to status but not a navigable verified cloud workspace');
+
+    let version = 0;
+    for (;;) {
+      const [claim] = service.entityCloud.claim();
+      if (!claim) break;
+      version += 1;
+      service.entityCloud.acknowledge({
+        resourceId: claim.resourceId,
+        mutationId: claim.mutationId,
+        version,
+        committedAt: '2026-08-05T00:00:00.000Z',
+      });
+    }
+
+    const status = service.status();
+    assert.equal(status.cloud.catalog.current, true);
+    const root = status.entities.find((entity) => entity.uuid === registered.record.uuid);
+    assert.equal(root.cloudPath, path.basename(ground));
+    const child = status.entities.find((entity) => entity.cloudPath === `${path.basename(ground)}/src`);
+    assert.ok(child, 'the cloud path is derived from canonical parentage, never a local absolute path');
+    assert.equal(child.localPath, path.join(ground, 'src'));
+  } finally {
+    service.close();
+  }
+});
+
 test('a large signed-in register call publishes one complete cloud graph before Watch begins', async () => {
   const service = createRegistrationService({
     dir: path.join(tempRoot, 'state-cloud-register-large'),

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

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