amalgm 0.1.261 → 0.1.263

package/lib/cli.js

@@ -1215,10 +1215,16 @@ function selectEntity(status, selector) {
   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;
+  // A UUID is an entity's globally unique address. Do not let rows without
+  // an optional display path turn that exact address into a fuzzy selector.
+  if (uuid) {
+    const match = entities.find((entity) => entity.uuid === uuid);
+    if (!match) throw new Error(`No cloud-backed entity matches ${selector}.`);
+    return match;
+  }
   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
+  const cloudPath = String(selector).replace(/^\/+|\/+$/g, '');
+  const matches = entities.filter((entity) => entity.localPath === localPath
     || entity.cloudPath === cloudPath
     || entity.name === selector);
   if (matches.length === 0) throw new Error(`No cloud-backed entity matches ${selector}.`);

package/package.json

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

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

@@ -0,0 +1,27 @@
+'use strict';
+
+/**
+ * Memoized statement preparation for one database handle.
+ *
+ * better-sqlite3 compiles the SQL text on EVERY `db.prepare()` call — it
+ * keeps no statement cache of its own. The stores' row-level verbs run
+ * thousands of times per scan (a first census inserts one row per file),
+ * so recompiling identical SQL each call was a measured double-digit
+ * share of a large registration. Each store builds one preparer over its
+ * injected handle and asks it instead; the SQL string is the whole key,
+ * so a handful of table-templated queries memoize to a handful of
+ * statements, never an unbounded set.
+ */
+function preparer(db) {
+  const statements = new Map();
+  return (sql) => {
+    let statement = statements.get(sql);
+    if (!statement) {
+      statement = db.prepare(sql);
+      statements.set(sql, statement);
+    }
+    return statement;
+  };
+}
+
+module.exports = { preparer };

package/runtime/scripts/amalgm-mcp/observer/README.md

@@ -80,7 +80,10 @@ never merges, never decides truth — it emits facts for the layers above.
    never traversed — an explicitly enrolled symlink enrolls as the
    pointer itself.
 2. **The doorbell is a hint, never a fact — but a hint only ever raises
-   scrutiny.** OS watchers are lossy by contract. Truth is always:
+   scrutiny.** One OS watcher per outermost tree (coverage.js — see
+   docs/watchers.md): enclosed roots hold no handles; the encloser
+   forwards their dings, rebased, synchronously. OS watchers are lossy
+   by contract. Truth is always:
    settle → walk → compare → hash. Stats may excuse a file from hashing
    only when all three hold: nothing named it, its stats are identical,
    and its mtime is strictly older than the moment we last read its bytes

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

@@ -0,0 +1,52 @@
+'use strict';
+
+/**
+ * The coverage law: one OS watcher per outermost tree.
+ *
+ * A recursive watcher on a directory hears every event beneath it, at any
+ * depth — so a root enclosed by watched ground already has its content
+ * observed, exactly as its ADDRESS is already observed (the enclosed()
+ * rule that predates this module). Opening a second watcher over enclosed
+ * ground buys nothing on any platform and, on Linux — where a recursive
+ * watch is silently one inotify slot PER DIRECTORY against a small kernel
+ * budget — it is what exhausted the T3 machine. Doorbells are shared;
+ * what a root DOES with its dings (files channels, repo Card+Checkpoint)
+ * stays its own type's business, routed by ring().
+ *
+ * Pure functions over root rows — no handles, no state. index.js owns
+ * opening and closing; this module only answers "who guards whom".
+ */
+
+const path = require('path');
+
+/** The ground a root's doorbell must cover: a directory root guards
+ * itself; a single-file root's bell lives on its parent directory (the
+ * file's own inode goes deaf on atomic saves). */
+function doorbellGround(root) {
+  return root.kind === 'file' ? path.dirname(root.path) : root.path;
+}
+
+/**
+ * The root whose OS watcher covers `root`'s doorbell ground, or null when
+ * `root` guards itself. The OUTERMOST enclosing directory root wins: with
+ * A ⊃ B ⊃ C only A holds a handle, and every deeper root — B, C, nested
+ * repos, single files — rides it. A file root can never cover anything.
+ */
+function watchOwnerOf(root, roots) {
+  const ground = doorbellGround(root);
+  let owner = null;
+  for (const other of roots) {
+    if (other.rootId === root.rootId || other.kind === 'file') continue;
+    if (ground !== other.path && !ground.startsWith(`${other.path}/`)) continue;
+    if (!owner || other.path.length < owner.path.length) owner = other;
+  }
+  return owner;
+}
+
+/** Every live root covered by `owner` (owner excluded). */
+function coveredRoots(owner, roots) {
+  return roots.filter((root) => root.rootId !== owner.rootId
+    && watchOwnerOf(root, roots)?.rootId === owner.rootId);
+}
+
+module.exports = { coveredRoots, doorbellGround, watchOwnerOf };

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

@@ -21,10 +21,12 @@
  * Nested repositories are territories too: a repo inside a repo is simply
  * another repo. A census at lifecycle moments (enrollment, conversion,
  * catch-up scans) plus doorbells live make each nested boundary its own
- * root with its own watcher; the parent stays silent for a child's ground.
- * A doorbell's filename never proves anything — it only says where to
- * look, and disk decides what it means (a repo moved in whole rings only
- * the directory that landed, never a path spelling ".git").
+ * root — but never its own OS watcher: one watcher per outermost tree
+ * (coverage.js), and the encloser FORWARDS a child territory's dings,
+ * rebased, synchronous, still raw. A doorbell's filename never proves
+ * anything — it only says where to look, and disk decides what it means
+ * (a repo moved in whole rings only the directory that landed, never a
+ * path spelling ".git").
  *
  * Enrollment is amalgm's OWN policy (`shouldEnroll`), applied uniformly to
  * files territory and repo boundaries alike. Git's ignore rules never
@@ -42,6 +44,7 @@ const { createContinuity } = require('./continuity');
 const { createStore } = require('./store');
 const { censusBoundaries, censusLinks, diffDirState, diffLinkState, diffRootState, gitDirTruth, listDir, walkRoot } = require('./scan');
 const { createVerify } = require('./verify');
+const { coveredRoots, watchOwnerOf } = require('./coverage');
 const { watchDir, watchRecursive } = require('./watch');
 const { adapterFor } = require('../adapters');
 const { lookFailed } = require('../adapters/truth');
@@ -80,7 +83,8 @@ function createObserver(options) {
   if (typeof emit !== 'function') throw new Error('createObserver requires { emit }');
 
   const store = createStore(db);
-  // rootId -> { kind, watcher, settleTimer, dirtyPaths, checkAll, territories }
+  // rootId -> { kind, watcher, addressWatcher, settleTimer, dirtyPaths,
+  //   checkAll, territories, watchEnabled, coveredBy, held }
   const live = new Map();
   let started = false;
 
@@ -338,7 +342,7 @@ function createObserver(options) {
       detach(root.rootId);
       store.removeRoot(root.rootId);
       live.get(parent.rootId)?.territories.delete(root.path.slice(parent.path.length + 1));
-      publish({ type: 'repo.changed', rootId: parent.rootId, areas: ['worktree'] });
+      publish({ type: 'repo.changed', rootId: parent.rootId, areas: ['worktree'], hint: null });
       return;
     }
     if (parent) {
@@ -407,8 +411,10 @@ function createObserver(options) {
       || 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
+    store.transaction(() => {
+      applyLinkDiff(root, linkDiff); // changes and retags: payload-local facts
+      applyDiff(root, fileDiff); // checks only: content truth on existing channels
+    });
     return true;
   }
 
@@ -448,11 +454,17 @@ function createObserver(options) {
       : { ...diff, deletes: diff.deletes.filter((row) => !underUnsettled(row.relPath)) });
     if (unsettled.length > 0 && state) armRetry(root, state);
 
-    applyDirDiff(root, concluded(diffDirState(store.dirsForRoot(root.rootId), dirs)));
-    applyLinkDiff(root, concluded(diffLinkState(store.linksForRoot(root.rootId), links)));
-    const rows = store.filesForRoot(root.rootId);
-    const mustCheck = checkAll ? new Set(entries.map((entry) => entry.relPath)) : rung;
-    applyDiff(root, concluded(diffRootState(rows, entries, mustCheck)));
+    // One walk's conclusions are one durable transition: a census over
+    // thousands of channels commits once, not once per row. Events stay
+    // hints — a consumer told early about a rolled-back row re-reads
+    // store truth and finds the old state, which concludes nothing.
+    store.transaction(() => {
+      applyDirDiff(root, concluded(diffDirState(store.dirsForRoot(root.rootId), dirs)));
+      applyLinkDiff(root, concluded(diffLinkState(store.linksForRoot(root.rootId), links)));
+      const rows = store.filesForRoot(root.rootId);
+      const mustCheck = checkAll ? new Set(entries.map((entry) => entry.relPath)) : rung;
+      applyDiff(root, concluded(diffRootState(rows, entries, mustCheck)));
+    });
   }
 
   /**
@@ -580,8 +592,9 @@ function createObserver(options) {
           censusRepoRoot(root);
           // Catch-up semantics: the observer cannot know what happened to a
           // repo while nobody watched; the follower's ids turn "maybe" into
-          // silence, so an unconditional doorbell is the honest answer.
-          publish({ type: 'repo.changed', rootId: root.rootId, areas: ['git', 'worktree'] });
+          // silence, so an unconditional doorbell is the honest answer —
+          // and a null path, because anything could have changed.
+          publish({ type: 'repo.changed', rootId: root.rootId, areas: ['git', 'worktree'], hint: null });
         }
       }
       // A scan that leaves no look pending resets the backoff: the
@@ -605,6 +618,10 @@ function createObserver(options) {
   function ring(root, relPath) {
     const state = live.get(root.rootId);
     if (!state) return;
+    // Held doorbells: the watcher is proven alive but registration has not
+    // committed. Dings conclude nothing — start(rootId)'s initial scan and
+    // census are the catch-up for everything heard during the hold.
+    if (state.held) return;
     state.retryMs = settleMs; // new evidence resets a backoff
 
     if (state.kind === 'file') {
@@ -653,6 +670,7 @@ function createObserver(options) {
             // Only absence buries — and an unsettled look keeps the news
             // pending: the retry looks again, no second doorbell needed.
             if (childTruth === 'unsettled') armRetry(root, state);
+            else forwardToTerritory(root, territory, relPath);
             return;
           }
           const known = store.rootByPath(childPath);
@@ -736,17 +754,22 @@ function createObserver(options) {
         }
       }
       // Forwarded raw and instantly: quieting is the follower's job, and a
-      // delayed doorbell would blind its torn-read guard.
+      // delayed doorbell would blind its torn-read guard. The named path
+      // travels as a HINT — scope for the checkpoint to patch one file
+      // instead of re-reading the world; null means "anywhere". A hint is
+      // never a conviction: the grammar's voice (path/from/to) stays
+      // wording-independent, exactly as the wording grid ratifies.
       const areas = relPath === null
         ? ['git', 'worktree']
         : relPath === '.git' || relPath.startsWith('.git/') ? ['git'] : ['worktree'];
-      publish({ type: 'repo.changed', rootId: root.rootId, areas });
+      publish({ type: 'repo.changed', rootId: root.rootId, areas, hint: relPath });
       return;
     }
 
-    // A child repo's own doorbell covers its territory — while the boundary
-    // is alive on disk. A dead one is territory news: fall through and let
-    // the scan's reconcile bury it and reclaim the ground.
+    // A child territory's dings arrive on THIS root's watcher (one watcher
+    // per outermost tree) and are forwarded to the child — while the
+    // boundary is alive on disk. A dead one is territory news: fall through
+    // and let the scan's reconcile bury it and reclaim the ground.
     const filesTerritory = relPath === null ? null : coveringTerritory(state, relPath);
     if (filesTerritory !== null) {
       const territoryTruth = gitDirTruth(path.join(root.path, filesTerritory));
@@ -754,7 +777,10 @@ function createObserver(options) {
         armRetry(root, state); // no conclusion from a failed look — the retry decides
         return;
       }
-      if (territoryTruth === 'present') return;
+      if (territoryTruth === 'present') {
+        forwardToTerritory(root, filesTerritory, relPath);
+        return;
+      }
     }
     // Enrollment policy applies to doorbells too — except .git itself: it is
     // never enrollable, but its appearance is territory news and must scan.
@@ -771,6 +797,19 @@ function createObserver(options) {
     armSettle(root, state);
   }
 
+  /**
+   * A covered child's dings arrive on its encloser's watcher; the encloser
+   * forwards them — synchronously, so repo doorbells stay raw and instant —
+   * rebased to the child's own ground. A ding naming the territory itself
+   * forwards as null (anything in there could have changed). Ringing the
+   * child recurses naturally through deeper territories.
+   */
+  function forwardToTerritory(root, territory, relPath) {
+    const child = store.rootByPath(path.join(root.path, territory));
+    if (!child) return; // racing a burial: the next reconcile owns it
+    ring(child, relPath === territory ? null : relPath.slice(territory.length + 1));
+  }
+
   function openWatcher(root) {
     // A single-file root's doorbell lives on its parent directory: a
     // watcher on the file itself would follow the inode and go deaf on
@@ -801,6 +840,34 @@ function createObserver(options) {
     );
   }
 
+  /**
+   * One root's watch health, coverage-aware: a covered root is watching
+   * exactly when its OWNER's watcher is live — it holds no handle of its
+   * own, by law, and pretending otherwise would hide a dead doorbell.
+   * Self-owned roots report their own handle, as always.
+   */
+  function statusOf(root) {
+    const state = live.get(root.rootId);
+    const ownerState = state?.coveredBy ? live.get(state.coveredBy) : null;
+    const watching = state?.coveredBy
+      ? Boolean(ownerState?.watcher) && !ownerState.watcher.degraded
+      : Boolean(state?.watcher) && !state.watcher.degraded;
+    const degraded = state?.coveredBy
+      ? Boolean(ownerState?.watcher?.degraded)
+      : Boolean(state?.watcher?.degraded);
+    return {
+      ...root,
+      watching,
+      degraded,
+      degradedReason: (state?.coveredBy ? ownerState : state)?.watcher?.reason ?? null,
+      coveredBy: state?.coveredBy ?? null,
+      addressRequired: root.kind !== 'file' && !enclosed(root),
+      addressWatching: Boolean(state?.addressWatcher) && !state.addressWatcher.degraded,
+      addressDegraded: Boolean(state?.addressWatcher?.degraded),
+      files: root.kind === 'repo' ? null : store.filesForRoot(root.rootId).length,
+    };
+  }
+
   /** A root enclosed by watched ground has its address observed already. */
   function enclosed(root) {
     return store.listRoots().some((other) =>
@@ -917,29 +984,81 @@ function createObserver(options) {
     const state = live.get(root.rootId);
     if (!state || !started) return;
     state.watcher = openWatcher(root);
-    try {
-      scanNow(root.rootId);
-    } catch (error) {
-      console.warn(`[Observer] post-revive scan failed for "${root.path}":`, error?.message || error);
+    // Only owners hold watchers, so this death silenced every covered
+    // root too: the gap reconcile belongs to the whole family.
+    const family = [root, ...coveredRoots(root, watchCandidates())];
+    for (const member of family) {
+      try {
+        scanNow(member.rootId);
+      } catch (error) {
+        console.warn(`[Observer] post-revive scan failed for "${member.path}":`, error?.message || error);
+      }
     }
   }
 
-  function startWatching(root, state) {
+  /** The roots that participate in watch coverage: attached, and asked to
+   * watch (a registration-phase address-only root is neither an owner nor
+   * covered — it is invisible to coverage until its watch begins). */
+  function watchCandidates() {
+    return store.listRoots().filter((root) => live.get(root.rootId)?.watchEnabled);
+  }
+
+  function ensureOwnWatcher(root, state) {
     if (!state.watcher || state.watcher.degraded) {
       state.watcher?.close();
       state.watcher = openWatcher(root);
     }
-    if ((!state.addressWatcher || state.addressWatcher.degraded)
-      && root.kind !== 'file' && !enclosed(root)) {
+  }
+
+  function ensureAddressWatcher(root, state) {
+    if (root.kind === 'file') return; // its main doorbell IS the parent
+    if (enclosed(root)) {
+      // The encloser's walk is its address evidence — and adoption can
+      // make this true of a root that once held one: close it.
+      state.addressWatcher?.close();
+      state.addressWatcher = null;
+      return;
+    }
+    if (!state.addressWatcher || state.addressWatcher.degraded) {
       state.addressWatcher?.close();
       state.addressWatcher = openAddressWatcher(root);
     }
   }
 
+  /**
+   * THE one decision about who holds OS handles, re-made whenever a root
+   * joins, leaves, or moves: each watch-enabled root is either self-owned
+   * (outermost — opens its own recursive doorbell) or covered (rides its
+   * owner's; ring() forwards). Owners open FIRST, covered close after, so
+   * an adoption never leaves a gap with no watcher over the ground.
+   * Idempotent — settled roots are untouched.
+   */
+  function resolveCoverage() {
+    if (!started) return;
+    const candidates = watchCandidates();
+    const owned = [];
+    const covered = [];
+    for (const root of candidates) {
+      const state = live.get(root.rootId);
+      const owner = watchOwnerOf(root, candidates);
+      state.coveredBy = owner?.rootId ?? null;
+      (owner ? covered : owned).push([root, state]);
+    }
+    for (const [root, state] of owned) ensureOwnWatcher(root, state);
+    for (const [, state] of covered) {
+      state.watcher?.close();
+      state.watcher = null;
+    }
+    for (const [root, state] of [...owned, ...covered]) ensureAddressWatcher(root, state);
+  }
+
   function attach(root, { watch = true } = {}) {
     const existing = live.get(root.rootId);
     if (existing) {
-      if (started && watch) startWatching(root, existing);
+      if (started && watch) {
+        existing.watchEnabled = true;
+        resolveCoverage();
+      }
       return existing;
     }
     const state = {
@@ -952,12 +1071,18 @@ function createObserver(options) {
       dirtyPaths: new Set(),
       checkAll: false,
       territories: new Set(),
+      watchEnabled: false,
+      coveredBy: null,
+      held: false,
     };
     for (const child of childRepoRoots(root)) {
       state.territories.add(child.path.slice(root.path.length + 1));
     }
     live.set(root.rootId, state);
-    if (started && watch) startWatching(root, state);
+    if (started && watch) {
+      state.watchEnabled = true;
+      resolveCoverage();
+    }
     return state;
   }
 
@@ -968,6 +1093,9 @@ function createObserver(options) {
     state.addressWatcher?.close();
     if (state.settleTimer) clearTimeout(state.settleTimer);
     live.delete(rootId);
+    // A departed owner promotes whoever it covered (stop() sets
+    // started=false first, so teardown never reopens handles).
+    resolveCoverage();
   }
 
   return {
@@ -1164,6 +1292,27 @@ function createObserver(options) {
       }
     },
 
+    /**
+     * Open and prove a root's doorbells WITHOUT scanning — the
+     * registration boundary's "watcher first" step. The watcher is born
+     * (or refuses to be, visibly), coverage is resolved, and its dings
+     * are HELD: nothing is scanned, published, or recorded until
+     * start(rootId) releases the hold — whose initial scan and census
+     * are the catch-up for anything heard meanwhile. Returns the root's
+     * coverage-aware status row so the caller can refuse BEFORE any
+     * identity commits.
+     */
+    watchNow(rootId) {
+      started = true; // watching has begun for this runtime
+      const root = store.listRoots().find((row) => row.rootId === rootId);
+      if (!root) throw new Error(`watchNow requires a live root: ${rootId}`);
+      const state = attach(root, { watch: false });
+      state.held = true;
+      state.watchEnabled = true;
+      resolveCoverage();
+      return statusOf(root);
+    },
+
     start(rootId = null) {
       const firstStart = !started;
       if (firstStart) started = true;
@@ -1173,8 +1322,12 @@ function createObserver(options) {
         : store.listRoots().filter((root) => root.rootId === rootId);
       // Watch begins after registration. The initial scan makes the fresh
       // structural tree concrete; changes during registration are outside
-      // this operation's contract and are not reconstructed here.
-      for (const root of roots) attach(root, { watch: true });
+      // this operation's contract and are not reconstructed here — held
+      // doorbells (watchNow) release into that same catch-up.
+      for (const root of roots) {
+        const state = attach(root, { watch: true });
+        state.held = false;
+      }
       try {
         for (const root of roots) scanNow(root.rootId);
       } catch (error) {
@@ -1188,18 +1341,7 @@ function createObserver(options) {
     },
 
     status() {
-      return store.listRoots().map((root) => {
-        const state = live.get(root.rootId);
-        return {
-          ...root,
-          watching: Boolean(state?.watcher) && !state.watcher.degraded,
-          degraded: Boolean(state?.watcher?.degraded),
-          addressRequired: root.kind !== 'file' && !enclosed(root),
-          addressWatching: Boolean(state?.addressWatcher) && !state.addressWatcher.degraded,
-          addressDegraded: Boolean(state?.addressWatcher?.degraded),
-          files: root.kind === 'repo' ? null : store.filesForRoot(root.rootId).length,
-        };
-      });
+      return store.listRoots().map((root) => statusOf(root));
     },
   };
 }