@matatbread/matbot-plugin-api 0.4.4 → 0.4.5

package/package.json

@@ -4,7 +4,7 @@
     "node",
     "browser"
   ],
-  "version": "0.4.4",
+  "version": "0.4.5",
   "engines": {
     "node": ">=24.0.0"
   },

package/src/context-switch.ts

@@ -45,6 +45,12 @@ interface ContextSwitchState {
   /** The flush currently settling, when a flusher went async. Held so a second caller joins the one
    *  in flight rather than starting a second, and so {@link quiesced} has something to wait on. */
   inflight?: Promise<void> | undefined;
+  /** Deferred work was staged while the machine was held, so the edge it needs was out of reach. Raised
+   *  by {@link flushIfQuiescent} — which is only ever called by a stager — and lowered when a flush
+   *  actually runs. While it is up, {@link machineBusy} bars new entrants so `depth` can reach 0. */
+  wanted?:   boolean;
+  /** Entrants parked at the barrier, woken on every release and at the end of every flush. */
+  waiters?:  Array<() => void>;
 }
 const cs = globalSlot<ContextSwitchState>('context-switch', () => ({
   quiescers: new Set<Quiescer>(),
@@ -52,6 +58,27 @@ const cs = globalSlot<ContextSwitchState>('context-switch', () => ({
   flushing:  false,
 }));
 
+// The slot is shared by every loaded copy of this module, INCLUDING published copies older than the
+// barrier — one of those may have created it, so the two fields above can be absent rather than merely
+// false. Read them through here. A stager living in an old copy raises no `wanted`, so entry is not
+// barred on its behalf: that is the pre-barrier behaviour (its work lands at the next natural release),
+// not a broken one.
+function waiters(): Array<() => void> {
+  return (cs.waiters ??= []);
+}
+
+/** Nothing staged and nothing settling — the barrier is down and an entrant walks straight in. */
+function clear(): boolean {
+  return cs.wanted !== true && !cs.flushing;
+}
+
+function wake(): void {
+  const parked = waiters();
+  if (parked.length === 0) return;
+  cs.waiters = [];
+  for (const w of parked) w();
+}
+
 /**
  * A machine-update flush. Returning a promise makes the edge *wait*: the deferred work is no longer
  * merely started at the edge but finished before the machine is handed to whoever asked to be
@@ -59,12 +86,40 @@ const cs = globalSlot<ContextSwitchState>('context-switch', () => ({
  * next operation is about to read — a store edge deferred out of a turn lands in the window before
  * the next turn takes its copy, or not at all.
  */
-export type Quiescer = () => void | Promise<void>;
+export type Quiescer = (unregister: () => void) => void | Promise<void>;
 
 /**
- * Register a machine-update flush, run at every quiescent edge (nothing holding the machine).
- * Flushers MUST be idempotent: a no-op when nothing is pending, since the edge is reached after every
- * operation. Returns an unregister fn.
+ * Register work to run at a quiescent edge — the next moment nothing holds the machine. Returns an
+ * unregister fn, and passes the same fn to the flusher.
+ *
+ * **Registering is all a stager does.** It announces the work, so the barrier engages and the edge is
+ * guaranteed to arrive; there is no second call to remember. Two idioms, and between them they cover
+ * everything in-tree:
+ *
+ * ```ts
+ * // ONE-SHOT — "do this at the next edge". The closure holds the work, so there is no pending flag.
+ * onContextQuiesce(un => { un(); applyTheThing(); });
+ *
+ * // REPEATED — "do this at every edge". Same thing without the un(), and then it MUST be idempotent:
+ * onContextQuiesce(() => { if (nothingToDo) return; … });
+ * ```
+ *
+ * **This or {@link scheduleAtEdge}?** They answer different questions, and the difference is what happens
+ * when you ask twice.
+ *
+ * This is a *subscription*: each call adds a callback, and every callback added runs. Ask twice and the work
+ * happens twice — correct when each call carries its own work (two deferred session edits are two edits, and
+ * both must land). `scheduleAtEdge` is a *dirty flag*: you create one scheduler up front, and however many
+ * times you poke it before an edge, the work runs once. Correct when the calls describe a **slot** rather
+ * than a queue — three `register('StorageBackend')` calls mean one backend to install, not three to install
+ * in turn, and the work reads the slot at fire time so the last writer wins.
+ *
+ * Picking wrongly is not subtle in either direction: a subscription where you wanted a flag re-applies stale
+ * intermediate values, and a flag where you wanted a subscription silently drops work.
+ *
+ * Continuous delivery is a *standing registration* — this, without calling `unregister` — and never a
+ * callback re-registering itself: see {@link scheduleAtEdge} for why re-registration re-enters the edge
+ * immediately and forever.
  *
  * What the edge guarantees a flusher:
  *
@@ -78,27 +133,28 @@ export type Quiescer = () => void | Promise<void>;
  * - A throwing flusher is isolated, and so is a rejecting one — neither may deny the others their
  *   completion, nor escape into the operation whose release happened to reach the edge.
  *
- * **It does not give exclusivity, and could not.** A synchronous flusher has it for free — the runtime
- * is single-threaded — and that is the argument for keeping a flusher synchronous whenever the work
- * allows. The moment one awaits, the window is open: `depth` is 0 while a flush settles, so an HTTP
- * endpoint can accept a request and run a tool call to completion inside a single `await`, and only an
- * operation that asked to be {@link quiesced} first (the pump) is held back. Flushers may therefore
- * overlap each other too, and sequencing them would buy nothing — it would remove one source of
- * concurrent mutation while leaving every other in place, at the price of every flusher waiting on the
- * slowest.
- *
- * So contention over a service is the *service's* to resolve, not the sweep's: a `Store` answers it
- * with compare-and-swap, and a subsystem with a stronger requirement owns a stronger answer. The
- * sweep's job is to make contention rare, not to pretend the machine stops.
- *
- * **Known gap, not caused here.** Compare-and-swap answers "did this document change?", not "did the
- * medium change?" — a read from one `StorageBackend` and a write to another compares a version from
- * the first against the second, and a session migrates with nothing in a position to notice. Staging
- * a swap rather than applying it while a flush settles narrows that window, but it is a mitigation
- * in the wrong place: an HTTP tool call has always been able to straddle a swap the same way, so the
- * exposure predates asynchronous flushers and is merely easier to reach with them. The fix belongs
- * where the consequence lands — a `cas` that checks the backend it is writing to is the one it read
- * from, and fails when it is not.
+ * - **Exclusivity, for a flusher's whole extent.** A synchronous flusher has always had it for free —
+ *   the runtime is single-threaded — and that remains the argument for keeping one synchronous whenever
+ *   the work allows. An asynchronous one now has it too, because {@link machineBusy} bars entry while a
+ *   flush is settling. Flushers still overlap *each other*, deliberately: sequencing them would remove
+ *   one source of concurrent mutation while leaving every other in place, at the price of every flusher
+ *   waiting on the slowest.
+ *
+ * Exclusivity is a recent acquisition and the reasoning that preceded it is worth keeping, because it
+ * says what the barrier is really for. This edge used to be a counter, not a gate: `depth` was 0 while
+ * a flush settled, so an HTTP endpoint could accept a request and run a whole tool call inside a single
+ * `await`, and the conclusion drawn was that contention over a service is the *service's* to resolve —
+ * a `Store` answers it with compare-and-swap — and that the sweep's job was only to make contention
+ * rare rather than to pretend the machine stops.
+ *
+ * That is still true, and `mediumGuard` is the shipped form of it: a write whose read came from another
+ * `StorageBackend` fails on the version stamp, so coherence does not depend on this module at all.
+ * Which is precisely what makes the barrier safe to add. It is not the correctness mechanism; it is the
+ * **liveness** one. A counter cannot force `depth` to reach 0, so under continuously overlapping holds —
+ * several sessions on a busy server, each pump holding across its own queue — the edge simply never
+ * arrives and staged work waits for an idle moment that never comes. A deferred session edit that never
+ * lands, and a staged backend swap that never applies, are both failures with no symptom. Barring entry
+ * is the only way to make the drain reachable, and exclusivity falls out of it for free.
  *
  * The keys that repoint *immediately* — `Vault`, `KnowledgeIndex`, `Notifier`, anything a plugin
  * registers — carry no protection here or anywhere: they change under a running turn too, by the
@@ -106,24 +162,64 @@ export type Quiescer = () => void | Promise<void>;
  * should resolve it once rather than either side of an await, exactly as a turn should.
  */
 export function onContextQuiesce(flush: Quiescer): () => void {
+  const unregister = (): void => { cs.quiescers.delete(flush); };
   cs.quiescers.add(flush);
-  return () => { cs.quiescers.delete(flush); };
+
+  // **Registering IS announcing.** A stager should not have to also remember to ask for an edge: the one
+  // plugin doing this in-tree registered a one-shot and never called `flushIfQuiescent`, so the barrier
+  // never engaged on its behalf and its work depended on someone else happening to release. Two calls that
+  // must be paired, where omitting the second is silent, is the shape this module exists to avoid.
+  //
+  // The barrier is raised synchronously (it invokes nothing) so it engages at once, while the edge ATTEMPT
+  // waits for a microtask — a callback must not run before the statement registering it has finished, or a
+  // one-shot reading anything initialised on that same line, `unregister` included, would see it missing.
+  // Nothing depends on registration landing synchronously; the host's inline-landing guarantee is attached
+  // to an explicit `flushIfQuiescent()`, which still has it.
+  if (cs.depth !== 0 || cs.flushing) cs.wanted = true;
+  void Promise.resolve().then(() => { if (cs.quiescers.has(flush)) flushIfQuiescent(); });
+
+  return unregister;
 }
 
 /**
- * Run the registered flushers iff nothing holds the machine — the quiescent edge. Called by
- * {@link machineBusy} at both edges, and by the host right after it *queues* a deferred mutation:
- * queued while busy (depth > 0) this no-ops and the release edge lands it; queued while idle (depth 0)
- * it applies immediately, so an idle-time swap doesn't wait for the next request to take effect.
+ * Announce registered work and land it if the edge is already here — **private**, and the second half of
+ * {@link onContextQuiesce}.
+ *
+ * It was public, and announcing was then a call a stager had to remember to pair with its registration. The
+ * one plugin registering a one-shot never made it, so the barrier never engaged for the very work whose
+ * starvation motivated it. Registering announces now, which is the same guarantee with nothing to forget —
+ * and once that was true, nothing outside this module had any reason to call this. Exposing "force an edge"
+ * only offered a way to reason about firing that a caller should not have to have.
+ *
+ * It stays separate from the opportunistic sweep {@link machineBusy} performs at its own edges: only a
+ * registration knows work exists, and a sweep that raised `wanted` merely because it found the machine busy
+ * would bar every overlapping operation on behalf of nothing.
  *
  * Returns the settling promise when some flusher went async, and `undefined` when the edge is already
  * complete — the caller decides whether it can afford to wait ({@link quiesced} does; a synchronous
  * caller cannot). Re-entering while one is settling joins it rather than starting a second: `flushing`
  * stays raised for the whole asynchronous extent, not just the synchronous sweep.
  */
-export function flushIfQuiescent(): Promise<void> | undefined {
+function flushIfQuiescent(): Promise<void> | undefined {
+  // Raised whenever this could not land the work — held, or a flush already settling. The settling case
+  // matters as much as the held one: `depth` is 0 there, so nothing is coming to force another edge, and
+  // an idle process would leave the work staged indefinitely.
+  if (cs.depth !== 0 || cs.flushing) { cs.wanted = true; return cs.inflight; }
+  return sweep();
+}
+
+/**
+ * The sweep itself, without the announcement — {@link machineBusy}'s own edges, which are offering the
+ * machine rather than asking for it.
+ */
+function sweep(): Promise<void> | undefined {
   if (cs.depth !== 0 || cs.flushing) return cs.inflight;
   cs.flushing = true;
+  // Lowered here rather than on completion: every flusher has now been *offered* this edge, so anything
+  // staged before it is accounted for. Work staged DURING the sweep re-raises it through the public
+  // entry point above and is answered by the next edge — which is what the sweep already promised
+  // ("a mutation staged meanwhile is turned away rather than applied").
+  cs.wanted = false;
 
   // Snapshot: a one-shot flusher unregisters itself as it fires, and a flusher may register another.
   // Iterating a copy makes both safe and settles what a mid-sweep registration means — it was not
@@ -132,7 +228,7 @@ export function flushIfQuiescent(): Promise<void> | undefined {
     .map(q => {
       // A synchronous throw is the flusher's own business, never that of the operation whose release
       // happened to reach the edge. A rejection is handled below, by allSettled.
-      try { return q() ?? undefined; }
+      try { return q(() => { cs.quiescers.delete(q); }) ?? undefined; }
       catch (e) { console.error('[matbot] context-quiesce flush threw:', e instanceof Error ? e.message : e); return undefined; }
     })
     .filter((p): p is Promise<void> => p !== undefined);
@@ -142,6 +238,7 @@ export function flushIfQuiescent(): Promise<void> | undefined {
     // stage a mutation and land it with a bare `flushIfQuiescent()`, in effect before the call returns.
     cs.flushing = false;
     cs.inflight = undefined;
+    wake();
     return undefined;
   }
 
@@ -153,6 +250,13 @@ export function flushIfQuiescent(): Promise<void> | undefined {
     }
     cs.flushing = false;
     cs.inflight = undefined;
+    // A stager that announced DURING this settle got `wanted` raised and no edge, and if the machine is
+    // idle nothing else is coming to give it one. So answer it here — guarded, and therefore terminating:
+    // only `flushIfQuiescent` raises `wanted`, and the sweep lowers it on entry, so an idempotent async
+    // flusher (which returns a promise whether or not it had work) cannot manufacture the next round. That
+    // is the distinction the "one pass, deliberately not a loop" note on `quiesced` turns on.
+    if (cs.wanted === true && cs.depth === 0) sweep();
+    wake();
   });
   cs.inflight = all;
   return all;
@@ -172,42 +276,145 @@ export function flushIfQuiescent(): Promise<void> | undefined {
  * staged *during* a flush lands at the following edge — the next `machineBusy` release, or the next
  * caller through here — which is all the mount contract has ever promised: eventual and ordered,
  * never timed.
+ *
+ * **Largely redundant since the barrier.** {@link machineBusy} now waits for staged work before it takes
+ * the hold, which is this guarantee delivered where it cannot be forgotten — so the pump, the caller this
+ * was written for, no longer calls it. It remains for an operation that needs deferred work complete and
+ * does *not* want to hold the machine.
  */
 export async function quiesced(): Promise<void> {
-  await flushIfQuiescent();
+  await sweep();
+}
+
+/**
+ * Run `work` at the next quiescent edge, **coalescing** repeated calls onto one edge. Returns the scheduler;
+ * call it every time you stage something.
+ *
+ * The guarded one-shot, named — because the announcements a host makes are usually about a *slot* rather than
+ * a queue: three `register('StorageBackend')` calls before an edge mean one backend to install, not three to
+ * install in turn. Read the slot inside `work` and repeated stagings collapse for free, while one callback
+ * keeps whatever `work` does in a fixed order.
+ *
+ * **Why continuous delivery is a standing registration and not this.** Registering means "I have work now",
+ * which is what forces the edge — so a callback that re-registered itself would announce fresh work from
+ * inside the sweep answering the last lot, and the edge would re-enter immediately and forever. A `setInterval`
+ * cannot be built out of `setTimeout` here, because there is no independent clock to wait for: the edge is
+ * driven by demand, and re-registration is unbounded demand. Want every edge? Register once and don't
+ * unregister — and then be idempotent, since you will be called after every operation.
+ */
+export function scheduleAtEdge(work: () => void | Promise<void>): () => void {
+  let scheduled = false;
+  return () => {
+    if (scheduled) return;
+    scheduled = true;
+    // Lowered before `work`, so work that itself stages more (a mount handler registering a service)
+    // schedules a fresh edge rather than finding this one still claiming to be pending.
+    onContextQuiesce(un => {
+      un();
+      scheduled = false;
+      return work();
+    });
+  };
 }
 
+/** How long an entrant waits at the barrier before proceeding anyway. See {@link admit}. */
+const ADMIT_TIMEOUT_MS = 2_000;
+
 /**
- * Hold the machine for the extent of `fn`: land any pending mutation first (only safe while idle),
- * then keep the machine off-limits to further ones until `fn` is done. Mirrors {@link runAs}'s
- * sync/async return — when `fn` is async the hold stays up until its promise settles, so the count
- * tracks the real operation rather than the synchronous call.
- *
- * The hold is released on **every** exit — a synchronous throw, a rejected promise, a bare `return`
- * from anywhere inside — because the release is bound to the call, not written at the exits. That is
- * the whole reason this is a wrapper and not a `begin()`/`end()` pair: a caller with a dozen early
- * returns (the pump has several per queue item) cannot leave the counter stuck, and a stuck counter
- * is unrecoverable — every later flush would silently no-op forever, and the symptom would be a
- * deferred mutation that simply never happens.
+ * The barrier: wait for staged work to land, then let the caller in.
+ *
+ * This is what makes the drain reachable. Without it `depth` is a counter that overlapping operations can
+ * hold above zero indefinitely, and staged work waits for an idle moment that never arrives.
+ *
+ * **Bounded, because a counter cannot tell a nested entrant from a concurrent one.** An operation already
+ * holding the machine that enters again — an LLM reaching a matbot HTTP endpoint through its own `http` or
+ * `bash` tool, in-process, inside its own turn — would be waiting for a drain that includes its own outer
+ * hold, and if the outer holder awaits the inner one that is a deadlock. Distinguishing the two needs a
+ * hold-identity carrier (`AsyncLocalStorage` on node, something else in the browser) and the platform
+ * split that implies; a bounded wait costs one constant and degrades to exactly the pre-barrier behaviour
+ * instead of hanging. The warning is the diagnosis, since this is otherwise invisible.
+ *
+ * Giving up lowers `wanted`. Leaving it raised would make every subsequent entrant pay the full timeout
+ * for one stuck round — a liveness aid turned into a throughput collapse — and the work is not lost: its
+ * stager still holds it, and the next real edge lands it.
  */
-export function machineBusy<T>(fn: () => T): T {
-  flushIfQuiescent();
+async function admit(): Promise<void> {
+  if (clear()) { sweep(); return; }        // the common path — and still an edge, as it always was
+  const started = Date.now();
+  for (;;) {
+    if (cs.depth === 0) await sweep();     // the drain we were waiting for; land it here and now
+    if (clear()) return;
+    const waited = Date.now() - started;
+    if (waited >= ADMIT_TIMEOUT_MS) {
+      console.warn(
+        `[matbot] entering the machine after waiting ${waited}ms for deferred work to land — it is still ` +
+        `pending (${cs.quiescers.size} flusher(s), depth ${cs.depth}). If this repeats, an operation is ` +
+        `holding the machine while waiting on something that needs it.`,
+      );
+      cs.wanted = false;
+      return;
+    }
+    // The timer doubles as a poll: a missed wake-up would otherwise park an entrant until the next
+    // unrelated release, and the whole point of this function is that progress does not depend on one.
+    await new Promise<void>(resolve => {
+      const done = (): void => { clearTimeout(timer); resolve(); };
+      const timer = setTimeout(done, Math.min(25, ADMIT_TIMEOUT_MS - waited));
+      waiters().push(done);
+    });
+  }
+}
+
+/**
+ * Hold the machine for the extent of `fn`: wait for any staged mutation to land, then keep the machine
+ * off-limits to further ones until `fn` is done. When `fn` is async the hold stays up until its promise
+ * settles, so the count tracks the real operation rather than the synchronous call.
+ *
+ * **Always a promise, because entry can wait** ({@link admit}) — that is the barrier, and it is in here
+ * rather than at the call site on purpose. An explicit "wait, then hold" pair reads better and puts the
+ * cost in view, but it makes the waiting *optional*, and a second caller who omits it gets no error and
+ * no symptom: staged work simply stops landing. That is the failure this whole module exists to prevent,
+ * so it is not one to leave to a caller's memory — the same reasoning that makes the principal ambient
+ * rather than threaded, and binds a mount interest to its plugin's load extent.
+ *
+ * When nothing is staged, `fn` still runs **synchronously** within the call, before the returned promise
+ * is handed back: the barrier adds a hold, never a scheduling gap, so nothing can slip between the check
+ * and the hold. A synchronous throw becomes a rejection, so the two paths report failure identically.
+ *
+ * The hold is released on **every** exit — a throw, a rejected promise, a bare `return` from anywhere
+ * inside — because the release is bound to the call, not written at the exits. That is the whole reason
+ * this is a wrapper and not a `begin()`/`end()` pair: a caller with a dozen early returns (the pump has
+ * several per queue item) cannot leave the counter stuck, and a stuck counter is unrecoverable — every
+ * later flush would silently no-op forever, and the symptom would be a deferred mutation that simply
+ * never happens.
+ */
+export function machineBusy<T>(fn: () => T | Promise<T>): Promise<T> {
+  if (!clear()) return admit().then(() => held(fn));
+  // Nothing staged, so this entry is itself an edge — as it always was. If the sweep settles inline the
+  // hold goes up within this call; if a flusher went async we wait for it, which is the guarantee the
+  // pump used to spell as `quiesced()`: deferred work that rewrites a document must finish before the
+  // next operation reads it, not merely have been started.
+  const settling = sweep();
+  return settling === undefined ? held(fn) : settling.then(() => held(fn));
+}
+
+function held<T>(fn: () => T | Promise<T>): Promise<T> {
   cs.depth++;
   let settled = false;
   const settle = (): void => {
-    if (settled) return;   // the sync-throw path settles before rethrowing; never settle twice
+    if (settled) return;   // the throw path settles before rejecting; never settle twice
     settled = true;
     cs.depth--;
-    flushIfQuiescent();
+    sweep();
+    wake();                // a release is a chance for anyone parked at the barrier to get in
   };
-  let result: T;
+  let result: T | Promise<T>;
   try {
     result = fn();
   } catch (e) {
     settle();
-    throw e;
+    return Promise.reject(e instanceof Error ? e : new Error(String(e)));
   }
-  return result instanceof Promise ? (result.finally(settle) as T) : (settle(), result);
+  return result instanceof Promise ? result.finally(settle) : (settle(), Promise.resolve(result));
 }
 
 /**
@@ -217,6 +424,6 @@ export function machineBusy<T>(fn: () => T): T {
  * into differently-owned units (the pump: one queue, a principal per item) holds the machine once
  * around the whole of it and calls `runAs` per unit instead.
  */
-export function contextSwitch<T>(principal: Principal, fn: () => T): T {
+export function contextSwitch<T>(principal: Principal, fn: () => T | Promise<T>): Promise<T> {
   return machineBusy(() => runAs(principal, fn));
 }

package/src/host-machine.ts

@@ -1,6 +1,7 @@
 import type {
   CompletionRequest, MatbotMachine, MatbotServices, Mounted, MountConsumeOptions, SingleTurnRequest,
 } from './plugin.js';
+import { RegistryChangeKind } from './notify.js';
 
 /*
  * Host-side machine assembly — the wiring an *embedder* does once at boot, not API a plugin author
@@ -111,6 +112,20 @@ function reportMountHandlerError(e: unknown): void {
  * the last-committed presence per key, so a reload collapses to one remount and a committed unload is
  * well-defined. Presence is read by member access on the unified machine, which resolves both the core
  * getters (StorageBackend/Vault/KnowledgeIndex) and the registry-backed augmented keys.
+ *
+ * Each transition is ALSO published onto the bus as a `RegistryChange` on the `services` registry — the
+ * mount table reaches in-process subscribers only, and a service being replaced is exactly the kind of
+ * fact a reader outside this process has no other way to learn. It matters most for `StorageBackend`:
+ * `notifyingStore` announces writes made THROUGH it, so replacing the medium wholesale — every document
+ * in every namespace now coming from somewhere else — passes it silently, and a browser listing sessions,
+ * skills and files went on showing the displaced backend's contents until something unrelated happened
+ * to make it re-query.
+ *
+ * Published AFTER that key's handlers settle, and independently of whether any exist. The handlers are
+ * how the in-process caches a remote reader queries THROUGH (a SkillManager's documents, function-tools'
+ * compiled set) get rebuilt, so announcing first would invite exactly the stale read this exists to fix.
+ * A subscriber-less key still announces: the interests map holds this process's plugins, and says nothing
+ * about who is listening on the bus.
  */
 export function createMountTable(getMachine: () => MatbotMachine): MountTable {
   const interests = new Map<string, Set<MountInterest>>();
@@ -119,11 +134,13 @@ export function createMountTable(getMachine: () => MatbotMachine): MountTable {
 
   const present = (key: string): boolean => (getMachine() as unknown as Record<string, unknown>)[key] !== undefined;
 
-  const run = (fn: (machine: MatbotMachine) => void | Promise<void>, machine: MatbotMachine): void => {
+  // Returns when the handler has settled, so flush can hold the bus announcement until the in-process
+  // caches are rebuilt. Still isolates a throw: an announcement must not be lost to a bad subscriber.
+  const run = (fn: (machine: MatbotMachine) => void | Promise<void>, machine: MatbotMachine): Promise<void> => {
     try {
       const r = fn(machine);
-      if (r instanceof Promise) r.catch(reportMountHandlerError);
-    } catch (e) { reportMountHandlerError(e); }
+      return r instanceof Promise ? r.catch(reportMountHandlerError) : Promise.resolve();
+    } catch (e) { reportMountHandlerError(e); return Promise.resolve(); }
   };
 
   const mounted: Mounted = {
@@ -161,13 +178,19 @@ export function createMountTable(getMachine: () => MatbotMachine): MountTable {
         const before = committed.get(key) ?? false;
         const after  = present(key);
         committed.set(key, after);
-        const subs = interests.get(key);
-        if (subs === undefined) continue;
+        if (!after && !before) continue;                    // marked dirty, but never present: nothing happened
+        const subs    = interests.get(key) ?? [];
+        const settled: Promise<void>[] = [];
         if (after) {
-          for (const i of subs) run(i.handler, machine);                                  // mount / remount
-        } else if (before) {
-          for (const i of subs) if (i.onUnmount !== undefined) run(i.onUnmount, machine);  // committed unload
+          for (const i of subs) settled.push(run(i.handler, machine));                                  // mount / remount
+        } else {
+          for (const i of subs) if (i.onUnmount !== undefined) settled.push(run(i.onUnmount, machine));  // committed unload
         }
+        // Detached: the edge does not wait on fan-out, only on the flushers that asked to suspend it.
+        void Promise.allSettled(settled).then(() => machine.Notifier.notify({
+          kind: RegistryChangeKind, source: 'services', registry: 'services',
+          name: key, operation: after ? 'added' : 'removed',
+        }));
       }
     },
   };

package/src/index.ts

@@ -30,3 +30,11 @@ export { currentPrincipal, tryCurrentPrincipal, runAs } from './principal-contex
 // notifier is the host's job (`/host`).
 export type * from './notify.js';
 export { ItemChangeKind, RegistryChangeKind, notifyingStore } from './notify.js';
+
+// The quiescent edge: defer work to the next moment it is safe to touch machine state. A plugin that has
+// something to do after the current operation — a store edit the running turn would otherwise write over —
+// wants exactly this and nothing else in the file. HOLDING the machine (`machineBusy`, `contextSwitch`),
+// waiting on it (`quiesced`) and coalescing repeated stagings (`scheduleAtEdge`) are the host's side, so
+// they stay behind `/host`.
+export type * from './context-switch.js';
+export { onContextQuiesce } from './context-switch.js';

package/src/notify.ts

@@ -58,7 +58,15 @@ export interface ItemChange extends NotificationBase {
   readonly detail?:   unknown;
 }
 
-/** A process-global registry gained or lost a member (tools, plugins). No owner, no item identity. */
+/**
+ * A process-global registry gained or lost a member. No owner, no item identity.
+ *
+ * `registry` is `tools`, `plugins`, or `services` — the last published by the mount table at the
+ * quiescent edge, where `name` is the `MatbotServices` key and a remount reads as `added` (the key
+ * has a member; it is not the one it had). It is how "the medium under everything was replaced" reaches
+ * a reader outside this process, which no {@link ItemChange} can say: that addresses one item, and a
+ * `StorageBackend` swap invalidates every item in every namespace at once without writing any of them.
+ */
 export interface RegistryChange extends NotificationBase {
   readonly registry:  string;
   readonly name:      string;

package/src/types/builtin-tools.ts

@@ -77,6 +77,29 @@ export interface PluginListResult {
   failed?:       FailedPlugin[] | undefined;
   /** Tools registered by the host rather than by any plugin. */
   builtinTools?: ToolSummary[] | undefined;
+  /** Second copies of a host singleton that something would resolve to. Absent ⇒ none, or a host that
+   *  cannot tell (the browser resolves every specifier through one import map, so it cannot have two). */
+  duplicateSingletons?: DuplicateSingleton[] | undefined;
+}
+
+/**
+ * A second physical copy of `plugin-api` or `core`, found where something would actually resolve it.
+ *
+ * Reported rather than repaired: duplication is survivable by design (singleton state lives on
+ * `globalThis`, errors are brand-checked rather than `instanceof`'d — see docs/duplicate-singletons.md),
+ * and replacing a package-manager-installed directory with a symlink invites the next `install` to undo it.
+ */
+export interface DuplicateSingleton {
+  /** The singleton's package name. */
+  package:     string;
+  /** The version this host is running. */
+  hostVersion: string;
+  /** The version the other copy declares. */
+  version:     string;
+  /** The other copy's real directory — symlinks resolved, which is how a link to the host is excluded. */
+  dir:         string;
+  /** What resolves to it: plugin names, and/or the config directory. */
+  reachedFrom: string[];
 }
 
 /** One installable plugin found by `plugin discover_local`. */