@1agh/maude 0.60.2 → 0.60.4

package/apps/studio/sync/index.ts

@@ -29,6 +29,8 @@ import type { Context, LinkedHub } from '../context.ts';
 import { createHistory } from '../history.ts';
 import { SYNTHETIC_FS_DELAY_MS } from '../hmr-broadcast.ts';
 import { type CanvasSyncAgent, createCanvasSyncAgent } from './agent.ts';
+import { pullAssets } from './asset-pull.ts';
+import { isPushableAssetRel } from './asset-push.ts';
 import { type AssetSweepHandle, runAssetSweep } from './asset-sweep.ts';
 import { atomicWrite } from './atomic-write.ts';
 import { createAutoCommit } from './autocommit.ts';
@@ -39,8 +41,10 @@ import {
   createConnectionMonitor,
   type ProviderStatus,
 } from './connection-state.ts';
+import { createRescanScheduler, diffCanvasSet, type RescanScheduler } from './discovery.ts';
 import { createDocNameResolver } from './doc-name.ts';
 import { createEchoGuard } from './echo-guard.ts';
+import { type FilePullResult, pullFiles } from './file-pull.ts';
 import { createFsReader, type FsReader } from './fs-mirror.ts';
 import { getHubRecord } from './hubs-config.ts';
 import { loadJournal, type SyncJournal } from './journal.ts';
@@ -52,11 +56,16 @@ import { createDocProjection, type DocProjection } from './projection.ts';
 import {
   describeRemoteDiff,
   diffRemoteDocs,
-  fetchRemoteDocs,
+  fetchRemoteListing,
   pullTargets,
+  type RemoteTombstone,
   resolvePulledTarget,
+  slugFromDocName,
+  stateDocumentGone,
+  tombstonedSlugs,
 } from './remote-docs.ts';
 import { createSyncStatusStore, type SyncStatusStore } from './status.ts';
+import { quarantineCanvas } from './tombstone-apply.ts';
 import { writeUntrustedMarkers } from './untrusted.ts';
 
 /** A minimum-surface stand-in for the HocuspocusProvider's runtime API. */
@@ -122,6 +131,46 @@ export const RENEW_MIN_INTERVAL_MS = 60_000;
 export const RENEW_MAX_WITHOUT_PROGRESS = 3;
 /** F2 — setTimeout clamps delays above this (2^31-1) to 1 ms, turning a
  *  far-future expiry into a tight renewal loop. Clamp before we hand it over. */
+/**
+ * Quiet window before a canvas-set change triggers a rescan.
+ *
+ * Slightly longer than `canvas-list-watch.ts`'s own 150 ms, on purpose: a create
+ * writes the `.tsx` and then the `.meta.json`, and attaching in the gap would
+ * sync a canvas whose sidecar is about to say `syncable: false`. Letting the
+ * cheaper watcher settle first means the rescan sees a finished canvas.
+ */
+export const DISCOVERY_DEBOUNCE_MS = 400;
+
+/**
+ * How often a peer re-asks the hub what the project contains.
+ *
+ * The floor is set by what a person would call "immediately" for a canvas
+ * somebody else just made, and the ceiling by the fact that this runs per peer,
+ * per project, forever. 20 s is a name-and-size listing — a few hundred bytes —
+ * and it is the ONLY discovery lane a hub of any version can serve.
+ */
+export const REMOTE_POLL_MS = 20_000;
+
+/**
+ * Settling delay for an OFF-SCHEDULE poll (reconnect).
+ *
+ * Not zero: a reconnect is a burst — every provider re-handshakes — and asking
+ * the hub for the listing in the middle of that buys a slower answer and a
+ * needless second one. Short enough that a person does not experience it.
+ */
+export const REMOTE_POLL_SOON_MS = 1_500;
+
+/**
+ * How many previously-unknown canvases one listing may land.
+ *
+ * A ceiling on the TOTAL is not enough on its own: a hub that answers with
+ * thousands of names would still create thousands of files, providers and
+ * `_untrusted` entries inside a single tick before anything else got to run.
+ * A real project gains canvases a few at a time; a burst larger than this is a
+ * hub behaving unlike any project, and the rest simply arrive on later polls.
+ */
+export const MAX_PULLS_PER_POLL = 25;
+
 export const MAX_TIMER_DELAY_MS = 2_147_483_647;
 /** F2 — a hub-reported `expiresAt` further out than this is not believed for
  *  scheduling (cloud cells issue ≤ 12 h; a month is already implausible). */
@@ -197,6 +246,41 @@ export type ProviderFactory = (args: {
 export interface SyncRuntime {
   start(): Promise<void>;
   stop(): Promise<void>;
+  /**
+   * Take ownership of canvases discovered AFTER `start()` — the incremental
+   * half of `start()`'s boot set. Returns how many were newly attached
+   * (already-attached slugs are skipped, not re-opened).
+   *
+   * Deliberately NOT a restart: a restart re-links every canvas in the project
+   * and costs a full handshake fan-out, which is why the Resync button is
+   * rate-limited. Adoption is per-canvas and cheap, so it can run on every
+   * discovery without the user authorising anything.
+   */
+  adopt(canvases: readonly CanvasDescriptor[]): Promise<number>;
+  /**
+   * Give up canvases that left the project. Returns how many were released.
+   *
+   * NOT A DELETION, and the distinction is the whole delete lane: this says
+   * "this machine stopped carrying it", which the project is right to ignore.
+   * Stating that a canvas is GONE travels on the `canvas-deleted` bus event that
+   * `api.ts` emits from its privileged delete route — the one signal that
+   * carries intent rather than a filesystem observation.
+   */
+  release(slugs: readonly string[]): Promise<number>;
+  /**
+   * Run the local canvas rescan immediately instead of waiting for the debounce.
+   *
+   * The discovery loop is event-driven (`canvas-list-update`); this is the seam
+   * tests use to make it deterministic, and the hook a caller can use to force a
+   * check without paying for a full runtime cycle the way Resync does.
+   */
+  rescanNow(): Promise<void>;
+  /**
+   * Ask the hub what the project contains right now, and pull down anything
+   * this peer does not have — the remote half of `rescanNow`, off the poll's
+   * schedule. Test seam, and the hook behind a manual "check now".
+   */
+  pullRemoteNow(): Promise<void>;
   /** Number of active per-canvas agents. */
   size(): number;
   /** Test inspection — get the agent for a slug if one was created. */
@@ -233,6 +317,8 @@ export interface CreateSyncRuntimeOptions {
   connectionMonitor?: ConnectionMonitor;
   /** Override the status store (Task 8 test injection). */
   statusStore?: SyncStatusStore;
+  /** Override the asset-sweep runner (test injection — no child process). */
+  assetSweepRunner?: typeof runAssetSweep;
   /**
    * DDR-102 — auth-failure + boot-settle knobs (test injection, mirrors the
    * connection-state injectable-timer pattern).
@@ -431,6 +517,16 @@ export function createSyncRuntime(
   // hub body, so a bogus/far-future stamp must not schedule a renewal at boot.
   let tokenExpiresAt: number | null = validExpiry(storedRecord?.expiresAt);
 
+  // feature-sync-file-plane — Plane B, behind its flag. The flag gates ONLY
+  // the new plane (the downward file pull here + the widened sweep inside
+  // `listPushableAssets`); with it off, behavior is today's, byte-for-byte.
+  const syncFilesOn = linkedHub.syncFiles === true || process.env.MAUDE_SYNC_FILES === '1';
+  // The owner-hub gate for `code-module` entries, decided from LOCAL state
+  // only: the role this machine's credential store vouched for at sign-in
+  // (never a hub-supplied claim), or the hub being this cell's own loopback
+  // pairing — where the hub and the checkout are the same trust domain.
+  const allowCodeModules = cellPairing !== null || storedRecord?.role === 'owner';
+
   // DDR-102 — the default factory multiplexes every provider over ONE shared
   // WebSocket per hub URL; the runtime owns its disposal (stop(), after the
   // providers detach). An injected test factory has no shared socket.
@@ -444,8 +540,31 @@ export function createSyncRuntime(
   // per run (chosen by useSharedDoc).
   const projections = new Map<string, DocProjection>();
   const providers = new Map<string, SyncProvider>();
-  const awarenessDetaches: Array<() => void> = [];
-  const statusDetaches: Array<() => void> = [];
+  // KEYED BY SLUG, not flat arrays.
+  //
+  // These used to be two bare lists drained only by `stop()`, which was right
+  // while the canvas set was fixed at boot. Continuous discovery makes a canvas
+  // leave the runtime on its own (deleted on disk, moved out of a synced group),
+  // and releasing one means running exactly ITS closures — a flat list cannot
+  // say which those are. `stop()` still drains everything, in the same two
+  // phases and the same order as before.
+  const awarenessDetaches = new Map<string, Array<() => void>>();
+  const statusDetaches = new Map<string, Array<() => void>>();
+  const noteDetach = (map: Map<string, Array<() => void>>, slug: string, fn: () => void): void => {
+    const list = map.get(slug);
+    if (list) list.push(fn);
+    else map.set(slug, [fn]);
+  };
+  const runDetaches = (map: Map<string, Array<() => void>>, slug: string): void => {
+    for (const detach of map.get(slug) ?? []) {
+      try {
+        detach();
+      } catch {
+        /* best-effort — registry teardown also clears bridges on destroyAll */
+      }
+    }
+    map.delete(slug);
+  };
   // Phase 9.2 (DDR-064) — slugs pinned in the registry because a provider is
   // attached to their shared doc; released on stop(). Empty unless sharedDoc.
   const pinnedSlugs = new Set<string>();
@@ -459,6 +578,72 @@ export function createSyncRuntime(
   let stopped = false;
   /** The live asset sweep, so `stop()` can end it and the panel can cancel it. */
   let assetSweep: AssetSweepHandle | null = null;
+  /** Debounce for the on-change sweep — see `scheduleAssetSweep`. */
+  let assetSweepTimer: ReturnType<typeof setTimeout> | null = null;
+  /** A change that arrived while a sweep was running: sweep once more after. */
+  let assetSweepAgain = false;
+
+  /**
+   * Run the asset sweep now, unless one is already running.
+   *
+   * OUT OF PROCESS since feature-sync-resync-and-out-of-process-sweep: the
+   * sweep segfaults Bun when it runs alongside the dev server (proven by
+   * isolation — the identical sweep against the same hub completes standalone).
+   * A dead child is a reported failed sweep, not a dead editor.
+   */
+  function startAssetSweep(hubUrl: string): void {
+    if (stopped || assetSweep) return;
+    const handle = (opts.assetSweepRunner ?? runAssetSweep)({
+      designRoot: ctx.paths.designRoot,
+      hubUrl,
+      // Read at call time — a silent renewal mid-sweep must reach the child
+      // (the parent re-writes its credential file when this changes).
+      token: () => token,
+      // feature-sync-progress-modal — ride the same `sync:status` payload the
+      // doc counts use, so the Sync panel has one source. `statusStore`, not
+      // start()'s local `store` alias: this helper is runtime-scoped so it can
+      // also be called from the fs watcher, and the alias does not exist here.
+      // Guarded on `stopped`: a late emit must not write `_sync.json`
+      // post-teardown.
+      onProgress: (p) => {
+        if (!stopped) statusStore?.updateAssets?.(p);
+      },
+    });
+    assetSweep = handle;
+    handle.done.finally(() => {
+      if (assetSweep === handle) assetSweep = null;
+      // A file that changed WHILE this sweep ran was not in its list — the
+      // trailing re-run is what keeps "I pasted two images quickly" from
+      // uploading only the first. Same single-flight-with-trailing-run shape
+      // the hub's own sweeper uses.
+      if (assetSweepAgain && !stopped) {
+        assetSweepAgain = false;
+        scheduleAssetSweep(hubUrl);
+      }
+    });
+  }
+
+  /**
+   * Coalesce a burst of asset writes into one sweep.
+   *
+   * Dragging six images onto a canvas is six `fs:any` events inside a second,
+   * and each sweep costs one presence probe over the wire. The debounce makes
+   * that one probe; `assetSweepAgain` makes a change during a sweep a second
+   * pass rather than a lost upload.
+   */
+  function scheduleAssetSweep(hubUrl: string): void {
+    if (stopped || cellPairing) return;
+    if (assetSweep) {
+      assetSweepAgain = true;
+      return;
+    }
+    if (assetSweepTimer !== null) clearTimeout(assetSweepTimer);
+    assetSweepTimer = setTimeout(() => {
+      assetSweepTimer = null;
+      startAssetSweep(hubUrl);
+    }, ASSET_SWEEP_DEBOUNCE_MS);
+    assetSweepTimer.unref?.();
+  }
 
   // Task 8 — offline-mode status surface, initialized in start() once the
   // canvas count is known. The store writes `_sync.json` + broadcasts
@@ -525,6 +710,173 @@ export function createSyncRuntime(
    *  that no longer exists. */
   const announceTimers = new Map<string, ReturnType<typeof setTimeout>>();
 
+  /**
+   * Assigned by `start()`. Adopting a canvas needs the boot closure (the
+   * journal, the history, the status store, `connectCanvas`), so the function
+   * is built there and published here for `adopt()` to reach. Null in solo mode
+   * and after `stop()`.
+   */
+  let attachOne: ((canvas: CanvasDescriptor, boot: boolean) => Promise<void>) | null = null;
+
+  /** Continuous local discovery — armed at the end of `start()`, torn down in
+   *  `stop()`. See the block that creates it and `discovery.ts`. */
+  let discoveryRescan: RescanScheduler | null = null;
+  let discoveryUnsub: (() => void) | null = null;
+  /** The outbound delete-lane subscriptions — see `noteToHub`. */
+  let deletedUnsub: (() => void) | null = null;
+  let createdUnsub: (() => void) | null = null;
+  /** Periodic remote-document poll — the hub-side half of discovery. */
+  let remotePollTimer: ReturnType<typeof setInterval> | null = null;
+  /** Assigned by `start()`; the seam `pullRemoteNow()` and tests reach. */
+  let remotePull: (() => Promise<void>) | null = null;
+  /**
+   * Ask for an off-schedule remote poll, coalesced.
+   *
+   * Reachable before `start()` finishes wiring `remotePull` (the monitor is
+   * built first and can emit during boot), so it is a no-op until there is
+   * something to call — the boot pull has just run at that point anyway.
+   */
+  let remotePollSoonTimer: ReturnType<typeof setTimeout> | null = null;
+  function pollRemoteSoon(): void {
+    if (stopped || remotePollSoonTimer !== null) return;
+    remotePollSoonTimer = setTimeout(() => {
+      remotePollSoonTimer = null;
+      if (stopped) return;
+      void remotePull?.().catch(() => {
+        /* the scheduled poll retries — a missed opportunistic one is not news */
+      });
+    }, REMOTE_POLL_SOON_MS);
+    remotePollSoonTimer.unref?.();
+  }
+  /** Every slug this run brought down, so the panel's "came down from the
+   *  project" list accumulates instead of being replaced by the latest batch. */
+  const everPulled = new Set<string>();
+
+  /**
+   * Every slug the PROJECT has deleted, as this run has learned it.
+   *
+   * The hub drops its `documents` row best-effort while the tombstone is the
+   * durable part, so a deleted canvas can still appear in one more listing. This
+   * set is what stops the pull lane from treating that listing as an invitation
+   * to write the canvas back — the resurrection, arrived at from the other side.
+   */
+  const tombstoned = new Set<string>();
+
+  /**
+   * The LIVE descriptor set, by slug.
+   *
+   * `start()`'s `canvases` array is the BOOT set and stops being the truth the
+   * moment a canvas is adopted or released. The DDR-054 §3 F3 untrusted markers
+   * must describe what is actually attached — a marker naming a canvas that
+   * left, or silently omitting one that arrived, is the control pointing at a
+   * phantom. Descriptors are held BY REFERENCE: `relocatePulled` mutates them in
+   * place, and the map must see that.
+   */
+  const descriptors = new Map<string, CanvasDescriptor>();
+
+  /** Warnings already emitted, so a per-poll refusal is said once, not forever. */
+  const warnedOnce = new Set<string>();
+  function warnOnce(key: string, message: string): void {
+    if (warnedOnce.has(key)) return;
+    warnedOnce.add(key);
+    console.warn(message);
+  }
+
+  /**
+   * May a HUB-AUTHORED body of this shape be written to this disk at all?
+   *
+   * The local lane has asked this since 9.1-B: `scanCanvases` admits a `.tsx`
+   * only when the cross-origin sandbox is active AND the project has not opted
+   * out (`walk` → `resolveSyncable`; DDR-060 couples the two, DDR-079 sets the
+   * default). The PULL lane never asked it — so a peer running with the sandbox
+   * off, or with `linkedHub.syncTsx: false` set precisely to keep hub `.tsx` off
+   * this machine, still received hub-authored `.tsx` bodies and rendered them.
+   * With the sandbox off that render is on the MAIN origin, which is the exact
+   * execution the coupling exists to prevent.
+   *
+   * The gap predates continuous discovery — it was reachable once per connect —
+   * but a lane that re-asks every 20 s makes "the opt-out holds for a moment"
+   * indistinguishable from "the opt-out does nothing".
+   */
+  function admitPulledBody(slug: string, bodyAbs: string): boolean {
+    if (!bodyAbs.toLowerCase().endsWith('.tsx')) return true;
+    const splitActive = !!ctx.canvasOrigin;
+    const projectSyncTsx = linkedHub.syncTsx !== false;
+    if (splitActive && projectSyncTsx) return true;
+    warnOnce(
+      `pull-tsx-refused:${splitActive ? 'opt-out' : 'sandbox-off'}`,
+      `[sync] refusing hub-authored .tsx canvases (first: ${slug}) — ` +
+        (splitActive
+          ? 'this project set linkedHub.syncTsx: false.'
+          : 'the cross-origin sandbox is off (MAUDE_CANVAS_ORIGIN_SPLIT=0), and TSX sync with it — DDR-060.') +
+        ' The same gate the local scan applies, now applied to what the hub sends.'
+    );
+    return false;
+  }
+
+  /**
+   * Give up ONE canvas — the inverse of `attachOne`.
+   *
+   * Order is deliberate and is NOT `stop()`'s order. `stop()` unpins before it
+   * flushes because the whole process is going away and the rooms are being
+   * torn down anyway; here the room OUTLIVES the release, so the doc→file
+   * projection must flush FIRST and the pin is dropped last. Unpinning early
+   * would hand the room to the last-browser-leaves drop while the projector was
+   * still writing through it.
+   *
+   * The shared WebSocket is deliberately untouched: it belongs to the runtime,
+   * not to a canvas, and the next adopt will need it. Only `stop()` disposes it.
+   */
+  async function releaseOne(slug: string): Promise<boolean> {
+    const known = agents.has(slug) || projections.has(slug) || providers.has(slug);
+    if (!known) return false;
+    runDetaches(awarenessDetaches, slug);
+    runDetaches(statusDetaches, slug);
+    const agent = agents.get(slug);
+    if (agent) {
+      try {
+        await agent.flush();
+        agent.stop();
+      } catch {
+        /* best-effort */
+      }
+      agents.delete(slug);
+    }
+    const projection = projections.get(slug);
+    if (projection) {
+      try {
+        await projection.flush();
+        projection.stop();
+      } catch {
+        /* best-effort */
+      }
+      projections.delete(slug);
+    }
+    const provider = providers.get(slug);
+    if (provider) {
+      try {
+        provider.destroy();
+      } catch {
+        /* best-effort */
+      }
+      providers.delete(slug);
+    }
+    if (pinnedSlugs.delete(slug)) {
+      try {
+        opts.registry?.unpin?.(slug);
+      } catch {
+        /* best-effort */
+      }
+    }
+    descriptors.delete(slug);
+    // Drop the row too — a released canvas that stayed `pending` in the status
+    // payload would be a permanent "still syncing" the user can never clear.
+    monitor?.forgetDoc(slug);
+    rejectedPermanent.delete(slug);
+    rejectedReasons.delete(slug);
+    return true;
+  }
+
   async function start(): Promise<void> {
     if (started || stopped) return;
     started = true;
@@ -575,10 +927,20 @@ export function createSyncRuntime(
     // design root — see `pullTargets` for why flat); local-only canvases go up
     // as they always did. Best-effort: an older hub without the listing route,
     // or an unreachable one, syncs exactly as before.
-    const remoteDocs = await fetchRemoteDocs(linkedHub.url, resolvedToken);
+    const remoteListing = await fetchRemoteListing(linkedHub.url, resolvedToken);
+    // BOOT LEARNS THE DELETIONS BEFORE IT PULLS ANYTHING. The peer-side apply
+    // lives further down (it needs the live descriptor map), so this boot pass
+    // only has to make sure the pull does not fetch a canvas the project has
+    // deleted — the first poll then quarantines whatever is still on disk. Doing
+    // it in the other order would materialise a deleted canvas on every launch
+    // and delete it again seconds later, which is worse than the bug.
+    for (const stone of remoteListing?.tombstones ?? []) {
+      const slug = slugFromDocName(stone.name);
+      if (slug) tombstoned.add(slug);
+    }
     const remoteDiff = diffRemoteDocs(
       localCanvases.map((c) => docNameFor(c.slug)),
-      remoteDocs
+      remoteListing?.documents ?? null
     );
     // PROVISIONAL targets. The listing carries names and byte counts only — a
     // document's own `syncMeta.path` lives INSIDE it, so every target here is
@@ -683,12 +1045,48 @@ export function createSyncRuntime(
     // in the same place: `system-colors_and_type` falls back to
     // `system/colors_and_type.tsx` whether or not a path arrives. Checking only
     // the carried path leaves every one of these reachable with no path at all.
-    const admittedPulls = pulled.filter((t) => admitPullTarget(ctx, t.slug, t.bodyAbs));
+    // The boot pull asks the SAME two questions the incremental one does — the
+    // sandbox/opt-out gate on a hub-authored body, and the pinned-room ceiling.
+    // Both were missing here too; the incremental lane just made their absence
+    // permanent instead of momentary. See `admitPulledBody` and MAX_PULLS_PER_POLL.
+    const admittedPulls = pulled
+      // A canvas the project deleted is never pulled, however it is still listed.
+      .filter((t) => !tombstoned.has(t.slug))
+      .filter((t) => admitPullTarget(ctx, t.slug, t.bodyAbs))
+      .filter((t) => admitPulledBody(t.slug, t.bodyAbs))
+      .slice(0, Math.max(0, maxPinnedRooms() - localCanvases.length));
     const pulledSlugs = new Set(admittedPulls.map((t) => t.slug));
+    for (const t of admittedPulls) everPulled.add(t.slug);
+    /**
+     * Tell the panel EVERYTHING that came down this run, boot included.
+     *
+     * `notePulled` REPLACES the list, and the boot pull used to pass its own
+     * slugs directly — so the first mid-session pull erased every boot-pulled
+     * canvas from the surface, which is precisely what `everPulled` exists to
+     * stop. One accumulating set, one caller.
+     */
+    const notePulledAll = (): void => mon.notePulled([...everPulled]);
+    /**
+     * Slugs pulled AFTER boot, which never get the fresh-link relaxation.
+     *
+     * `allowUndeclaredGroup` exists for exactly one moment: the first connect of
+     * a bare folder somebody just pointed at a project, which has declared no
+     * canvas groups and would otherwise refuse every incoming path. It closes as
+     * soon as one group is learned. A mid-session pull is not that moment — and
+     * because `relocatePulled` reads `pathOpts` at call time, a project that
+     * never learned a group would otherwise leave the relaxation open for every
+     * later arrival, which is an unbounded directory-creation primitive for the
+     * hub. Membership in this set overrides the flag, per canvas.
+     */
+    const strictPullSlugs = new Set<string>();
     const canvases = [
       ...localCanvases,
       ...admittedPulls.map((t) => descriptorFor(t.slug, t.bodyAbs)),
     ];
+    /**
+     * Seed the live descriptor set from the boot set — see `descriptors`.
+     */
+    for (const c of canvases) descriptors.set(c.slug, c);
     // T4.5 (DDR-054 §3 F3) — every syncable canvas can receive hub-pushed
     // content, so the whole set is untrusted Claude-context. Mark it (writes
     // `_untrusted/INDEX.json` + a managed `.claudeignore` block; clears both
@@ -712,8 +1110,9 @@ export function createSyncRuntime(
     //
     // So it is written twice: once now (so the markers exist before any provider
     // is built) and once after the pulls settle, from the final descriptors.
+    // Reads the LIVE set, not the boot array — see `descriptors`.
     const markUntrusted = (): void => {
-      if (!cellPairing) writeUntrustedMarkers(ctx, canvases, linkedHub.url);
+      if (!cellPairing) writeUntrustedMarkers(ctx, [...descriptors.values()], linkedHub.url);
     };
     markUntrusted();
     if (canvases.length === 0) {
@@ -723,6 +1122,31 @@ export function createSyncRuntime(
       // loudly: a warn, a `_sync.json` the CLI + browser banner read, and a bus
       // broadcast so open tabs render it immediately.
       surfaceNoSyncable(ctx, linkedHub.url, scan.tsxCount);
+      // A PROJECT WITH NOTHING IN IT YET IS STILL A PROJECT.
+      //
+      // This return happens before the status store, the monitor and the fs
+      // reader exist, so the continuous-discovery machinery at the bottom of
+      // start() is never reached — and a person who links an empty project and
+      // then makes their first canvas would be back to "nothing syncs until you
+      // restart", which is the whole bug, reached from its emptiest corner.
+      //
+      // A full cycle IS the right answer here and only here: there is no runtime
+      // state to preserve, and one is exactly what a first canvas needs. The
+      // supervisor owns cycling (it holds the serialization), so this asks
+      // rather than acts — see `server.ts`.
+      const watchForFirst = createRescanScheduler({
+        debounceMs: DISCOVERY_DEBOUNCE_MS,
+        onError: (err) => console.error('[sync] first-canvas watch failed:', err),
+        run: async () => {
+          if (stopped || opts.canvases) return;
+          const again = await scanCanvases(ctx);
+          if (admitCanvases(again.canvases, useSharedDoc).length === 0) return;
+          console.log('[sync] the project has its first syncable canvas — starting sync.');
+          ctx.bus.emit('sync:needs-restart');
+        },
+      });
+      discoveryRescan = watchForFirst;
+      discoveryUnsub = ctx.bus.on('canvas-list-update', () => watchForFirst.schedule());
       return;
     }
 
@@ -789,6 +1213,16 @@ export function createSyncRuntime(
 
     busUnsub = ctx.bus.on('fs:any', (rel: string) => {
       reader.notify(rel);
+      // AN ASSET THAT APPEARS AFTER BOOT HAS TO GO UP NOW, NOT NEXT LAUNCH.
+      //
+      // The sweep used to fire from exactly one place — `start()` — so a picture
+      // pasted into an annotation reached the cloud only on the next boot or
+      // Resync. Meanwhile the annotation itself syncs through the doc in
+      // milliseconds, so the other side rendered an `<image>` pointing at bytes
+      // nobody had sent: a permanent empty frame that looked like a broken path.
+      // Reported three times in one day on alligators, each time with a
+      // different asset, which is what finally named it.
+      if (isPushableAssetRel(rel, ctx.cfg.canvasGroups)) scheduleAssetSweep(linkedHub.url);
     });
 
     /**
@@ -1235,7 +1669,9 @@ export function createSyncRuntime(
         resolve: path.resolve,
         sep: path.sep,
         realpath: realpathOfDeepestExisting,
-        allowUndeclaredGroup: pathOpts.allowUndeclaredGroup,
+        // The fresh-link relaxation is boot-only, per canvas — see
+        // `strictPullSlugs` for why reading `pathOpts` alone is not enough.
+        allowUndeclaredGroup: pathOpts.allowUndeclaredGroup && !strictPullSlugs.has(canvas.slug),
         onRefused: (reason) => pathOpts.onRefused(canvas.slug, reason),
       });
       if (!resolved) return;
@@ -1288,7 +1724,19 @@ export function createSyncRuntime(
       canvas: CanvasDescriptor,
       canvasPaths: import('./agent.ts').CanvasSyncPaths,
       document?: Y.Doc,
-      setup?: (provider: SyncProvider) => void
+      setup?: (provider: SyncProvider) => void,
+      /**
+       * Does this connect belong to the BOOT set?
+       *
+       * Only a boot connect may enqueue a `bootWaits` entry. The boot summary
+       * (`Promise.allSettled(bootWaits)`) is a one-shot report about the set the
+       * runtime opened at start; a canvas adopted later must never be able to
+       * join a list that has already been awaited — and, once discovery is
+       * continuous, an unbounded stream of them would grow that array for the
+       * life of the process. Defaults true so the re-probe path (which has
+       * always pushed) is byte-for-byte unchanged.
+       */
+      boot = true
     ): Promise<SyncProvider> => {
       const provider = await providerFactory({
         url: linkedHub.url,
@@ -1321,8 +1769,30 @@ export function createSyncRuntime(
       if (!deferSetup) setup?.(provider);
 
       // Task 8 — feed this provider's WS status into the offline monitor.
+      // Per-provider, so a socket that never dropped never triggers a poll.
+      let wasDisconnected = false;
       if (provider.onStatus) {
-        statusDetaches.push(provider.onStatus((s) => mon.noteProviderStatus(canvas.slug, s)));
+        noteDetach(
+          statusDetaches,
+          canvas.slug,
+          provider.onStatus((s) => {
+            mon.noteProviderStatus(canvas.slug, s);
+            // COMING BACK IS THE MOMENT MOST LIKELY TO HAVE MISSED SOMETHING.
+            //
+            // A peer that was away for an hour has an hour of other people's
+            // canvases to learn about, and making it sit out the poll interval
+            // ON TOP of the outage is the one wait that is both longest and
+            // least excusable. The signal is the socket returning, taken from
+            // the provider rather than from the monitor's snapshot: a caller
+            // that injects its own monitor (every test, and anything later)
+            // would otherwise silently lose this.
+            //
+            // A reconnect storm is N providers reporting at once —
+            // `pollRemoteSoon` coalesces them into one request.
+            if (s === 'connected' && wasDisconnected) pollRemoteSoon();
+            wasDisconnected = s !== 'connected';
+          })
+        );
       } else {
         // No status events (test stub) — treat as connected so the monitor
         // doesn't sit in the boot 'connecting' state forever.
@@ -1330,7 +1800,9 @@ export function createSyncRuntime(
       }
       // DDR-102 — classify + aggregate hub auth rejections.
       if (provider.onAuthFailed) {
-        statusDetaches.push(
+        noteDetach(
+          statusDetaches,
+          canvas.slug,
           provider.onAuthFailed(({ reason }) =>
             handleAuthFailure(canvas, canvasPaths, provider, reason)
           )
@@ -1340,7 +1812,11 @@ export function createSyncRuntime(
       // browser cursors relay cross-machine. No-op when the provider exposes
       // no awareness or no registry was passed (file-sync-only tests).
       if (opts.registry && provider.awareness) {
-        awarenessDetaches.push(opts.registry.attachHubAwareness(canvas.slug, provider.awareness));
+        noteDetach(
+          awarenessDetaches,
+          canvas.slug,
+          opts.registry.attachHubAwareness(canvas.slug, provider.awareness)
+        );
       }
       // Cold-start reconcile fires once the provider has hub state.
       const synced = provider.onceSynced().then(() => {
@@ -1350,12 +1826,25 @@ export function createSyncRuntime(
         }
         return runHandleSynced(canvas, canvasPaths, provider);
       });
-      bootWaits.push(settleWait(synced));
+      if (boot) bootWaits.push(settleWait(synced));
       return provider;
     };
 
-    for (const canvas of canvases) {
+    /**
+     * Take ownership of ONE canvas: pin its shared doc if there is one, open a
+     * provider, and build the disk handler behind it.
+     *
+     * Extracted from the boot loop so the SAME path can be reached after boot —
+     * document discovery is continuous, not a snapshot taken at `start()`, and a
+     * canvas that appears later must be adopted by exactly this code rather than
+     * by a second, drifting copy of it. Every branch below is the boot
+     * behaviour, unchanged; `boot` only decides whether the connect joins the
+     * one-shot boot summary.
+     */
+    const attachCanvas = async (canvas: CanvasDescriptor, boot: boolean): Promise<void> => {
       try {
+        // By reference — `relocatePulled` mutates this object in place.
+        descriptors.set(canvas.slug, canvas);
         // Phase 9.2 (DDR-064) — when sharedDoc is on, the provider attaches to
         // the collab room's single Y.Doc (registry.getDoc) instead of a fresh
         // one, so browser edits flow straight into the doc that syncs to the
@@ -1377,129 +1866,143 @@ export function createSyncRuntime(
           css: canvas.css,
         };
         mon.noteDocState(canvas.slug, 'pending');
-        await connectCanvas(canvas, canvasPaths, sharedYDoc, (provider) => {
-          // Phase 9.2 (DDR-064) — the disk handler. Under sharedDoc it's a
-          // loop-free projection (html/css/meta doc→file + all-types file→doc;
-          // the collab room keeps comments/annotations doc→file, so no
-          // double-write). Flag-OFF keeps the proven two-doc agent. Created
-          // ONCE here (first connect) — a DDR-102 re-probe swaps only the
-          // provider; everything below is doc-scoped and survives.
-          let agent: CanvasSyncAgent | undefined;
-          if (useSharedDoc && sharedYDoc) {
-            const projection = createDocProjection({
-              slug: canvas.slug,
-              doc: provider.document,
-              paths: canvasPaths,
-              echoGuard,
-              journal: journal ?? undefined,
-              // Cell pairing only — see the DocProjectionOptions.onWrote doc.
-              // The synthetic event is delayed by the same margin the container
-              // write bridge uses, so a watcher that DOES fire wins the race and
-              // the HMR broadcaster's per-file coalescing collapses the pair
-              // into one `canvas-hmr`. The projector's own echo guard drops the
-              // resulting file→doc read, so this cannot loop.
-              ...(cellPairing ? { onWrote: announceWrite } : {}),
-            });
-            projection.start();
-            projections.set(canvas.slug, projection);
-          } else {
-            const relBody = path.relative(ctx.paths.repoRoot, canvas.html);
-            agent = createCanvasSyncAgent({
-              slug: canvas.slug,
-              doc: provider.document,
-              paths: canvasPaths,
-              echoGuard,
-              adopt: adoptOnce,
-              journal: journal ?? undefined,
-              // Wrap the writer rather than adding a new hook: every path the
-              // agent materializes to disk goes through it, so a future write
-              // surface is committed automatically instead of being forgotten.
-              ...(autoCommit
-                ? {
-                    writer: (file: string, bytes: string | Uint8Array) => {
-                      atomicWrite(file, bytes);
-                      autoCommit.note(
-                        path.relative(ctx.paths.repoRoot, file),
-                        editorOf(canvas.slug)
-                      );
-                    },
+        await connectCanvas(
+          canvas,
+          canvasPaths,
+          sharedYDoc,
+          (provider) => {
+            // Phase 9.2 (DDR-064) — the disk handler. Under sharedDoc it's a
+            // loop-free projection (html/css/meta doc→file + all-types file→doc;
+            // the collab room keeps comments/annotations doc→file, so no
+            // double-write). Flag-OFF keeps the proven two-doc agent. Created
+            // ONCE here (first connect) — a DDR-102 re-probe swaps only the
+            // provider; everything below is doc-scoped and survives.
+            let agent: CanvasSyncAgent | undefined;
+            if (useSharedDoc && sharedYDoc) {
+              const projection = createDocProjection({
+                slug: canvas.slug,
+                doc: provider.document,
+                paths: canvasPaths,
+                echoGuard,
+                journal: journal ?? undefined,
+                // Cell pairing only — see the DocProjectionOptions.onWrote doc.
+                // The synthetic event is delayed by the same margin the container
+                // write bridge uses, so a watcher that DOES fire wins the race and
+                // the HMR broadcaster's per-file coalescing collapses the pair
+                // into one `canvas-hmr`. The projector's own echo guard drops the
+                // resulting file→doc read, so this cannot loop.
+                ...(cellPairing ? { onWrote: announceWrite } : {}),
+              });
+              projection.start();
+              projections.set(canvas.slug, projection);
+            } else {
+              const relBody = path.relative(ctx.paths.repoRoot, canvas.html);
+              agent = createCanvasSyncAgent({
+                slug: canvas.slug,
+                doc: provider.document,
+                paths: canvasPaths,
+                echoGuard,
+                adopt: adoptOnce,
+                journal: journal ?? undefined,
+                // Wrap the writer rather than adding a new hook: every path the
+                // agent materializes to disk goes through it, so a future write
+                // surface is committed automatically instead of being forgotten.
+                ...(autoCommit
+                  ? {
+                      writer: (file: string, bytes: string | Uint8Array) => {
+                        atomicWrite(file, bytes);
+                        autoCommit.note(
+                          path.relative(ctx.paths.repoRoot, file),
+                          editorOf(canvas.slug)
+                        );
+                      },
+                    }
+                  : {}),
+                snapshot: async (content, reason) => {
+                  try {
+                    const snap = await history.writeSnapshot(relBody, content, reason);
+                    return snap.ts;
+                  } catch {
+                    return null; // best-effort — resolution proceeds without refs
                   }
-                : {}),
-              snapshot: async (content, reason) => {
-                try {
-                  const snap = await history.writeSnapshot(relBody, content, reason);
-                  return snap.ts;
-                } catch {
-                  return null; // best-effort — resolution proceeds without refs
-                }
-              },
-              onConflict: (info) => store.addConflict(info),
-            });
-            agent.start();
-            agents.set(canvas.slug, agent);
-          }
+                },
+                onConflict: (info) => store.addConflict(info),
+              });
+              agent.start();
+              agents.set(canvas.slug, agent);
+            }
 
-          // Count local edits (agent-origin doc updates) toward queuedOps while
-          // the hub is unreachable — the banner's "N edits queued" figure. Under
-          // sharedDoc there is no agent origin to key off (browser edits carry a
-          // RoomConn origin); queued-edit counting in that mode is a known gap
-          // (offline-banner accuracy only, not data) deferred past Phase C.
-          if (agent) {
-            const agentOrigin = agent.origin;
-            const onLocalUpdate = (_u: Uint8Array, origin: unknown) => {
-              if (origin === agentOrigin) mon.noteLocalEdit();
-            };
-            provider.document.on('update', onLocalUpdate);
-            statusDetaches.push(() => provider.document.off('update', onLocalUpdate));
-          }
+            // Count local edits (agent-origin doc updates) toward queuedOps while
+            // the hub is unreachable — the banner's "N edits queued" figure. Under
+            // sharedDoc there is no agent origin to key off (browser edits carry a
+            // RoomConn origin); queued-edit counting in that mode is a known gap
+            // (offline-banner accuracy only, not data) deferred past Phase C.
+            if (agent) {
+              const agentOrigin = agent.origin;
+              const onLocalUpdate = (_u: Uint8Array, origin: unknown) => {
+                if (origin === agentOrigin) mon.noteLocalEdit();
+              };
+              provider.document.on('update', onLocalUpdate);
+              noteDetach(statusDetaches, canvas.slug, () =>
+                provider.document.off('update', onLocalUpdate)
+              );
+            }
 
-          // Relay hub-pushed comment/annotation changes straight into the live
-          // room — IN-PROCESS + synchronous, so the room's in-memory doc is
-          // updated BEFORE its 800ms persist timer can flush stale pre-sync state
-          // back over the file (the disk-mediated re-seed in createCollab loses
-          // that race under an actively-edited peer; this is the tight path that
-          // actually closes the "comment reverts" clobber). Wholesale-replace via
-          // syncRoomFrom* → no duplication. Skip agent-origin updates (our own
-          // disk→doc apply — the file is authoritative there; a local design:edit
-          // reaches the room via createCollab's fs hook instead).
-          //
-          // CRITICAL: observe the comment + annotation Y-types SEPARATELY, not the
-          // whole-doc update. A whole-doc relay re-applies BOTH types on every
-          // change, so a comment sync would re-push the (stale) annotation and
-          // clobber an annotation the peer just drew but hasn't synced yet — and
-          // vice versa. Per-type observers keep the two lanes independent.
-          //
-          // Phase 9.2 (DDR-064): under sharedDoc the provider IS attached to the
-          // room's doc, so there is no second doc to relay into — the room already
-          // has every change. Skipping the relay is what RETIRES the
-          // wholesale-replace clobber path (the Phase 9.1 ceiling): with one doc,
-          // CRDT merge handles concurrency, no last-writer-wins blob copy.
-          const reg = opts.registry;
-          if (!useSharedDoc && agent && reg?.syncRoomFromComments) {
-            const agentOrigin = agent.origin;
-            const slug = canvas.slug;
-            const provComments = provider.document.getArray(Y_TYPES.comments);
-            const provAnn = provider.document.getMap(Y_TYPES.annotations);
-            const onComments = (_e: unknown, tx: { origin: unknown }) => {
-              if (tx.origin === agentOrigin) return;
-              reg.syncRoomFromComments?.(slug, provComments.toArray());
-            };
-            const onAnn = (_e: unknown, tx: { origin: unknown }) => {
-              if (tx.origin === agentOrigin) return;
-              const svg = provAnn.get('svg');
-              if (typeof svg === 'string') reg.syncRoomFromAnnotations?.(slug, svg);
-            };
-            provComments.observe(onComments);
-            provAnn.observe(onAnn);
-            statusDetaches.push(() => {
-              provComments.unobserve(onComments);
-              provAnn.unobserve(onAnn);
-            });
-          }
-        });
+            // Relay hub-pushed comment/annotation changes straight into the live
+            // room — IN-PROCESS + synchronous, so the room's in-memory doc is
+            // updated BEFORE its 800ms persist timer can flush stale pre-sync state
+            // back over the file (the disk-mediated re-seed in createCollab loses
+            // that race under an actively-edited peer; this is the tight path that
+            // actually closes the "comment reverts" clobber). Wholesale-replace via
+            // syncRoomFrom* → no duplication. Skip agent-origin updates (our own
+            // disk→doc apply — the file is authoritative there; a local design:edit
+            // reaches the room via createCollab's fs hook instead).
+            //
+            // CRITICAL: observe the comment + annotation Y-types SEPARATELY, not the
+            // whole-doc update. A whole-doc relay re-applies BOTH types on every
+            // change, so a comment sync would re-push the (stale) annotation and
+            // clobber an annotation the peer just drew but hasn't synced yet — and
+            // vice versa. Per-type observers keep the two lanes independent.
+            //
+            // Phase 9.2 (DDR-064): under sharedDoc the provider IS attached to the
+            // room's doc, so there is no second doc to relay into — the room already
+            // has every change. Skipping the relay is what RETIRES the
+            // wholesale-replace clobber path (the Phase 9.1 ceiling): with one doc,
+            // CRDT merge handles concurrency, no last-writer-wins blob copy.
+            const reg = opts.registry;
+            if (!useSharedDoc && agent && reg?.syncRoomFromComments) {
+              const agentOrigin = agent.origin;
+              const slug = canvas.slug;
+              const provComments = provider.document.getArray(Y_TYPES.comments);
+              const provAnn = provider.document.getMap(Y_TYPES.annotations);
+              const onComments = (_e: unknown, tx: { origin: unknown }) => {
+                if (tx.origin === agentOrigin) return;
+                reg.syncRoomFromComments?.(slug, provComments.toArray());
+              };
+              const onAnn = (_e: unknown, tx: { origin: unknown }) => {
+                if (tx.origin === agentOrigin) return;
+                const svg = provAnn.get('svg');
+                if (typeof svg === 'string') reg.syncRoomFromAnnotations?.(slug, svg);
+              };
+              provComments.observe(onComments);
+              provAnn.observe(onAnn);
+              noteDetach(statusDetaches, canvas.slug, () => {
+                provComments.unobserve(onComments);
+                provAnn.unobserve(onAnn);
+              });
+            }
+          },
+          boot
+        );
       } catch (err) {
         console.error(`[sync/${canvas.slug}] failed to start:`, err);
       }
+    };
+
+    attachOne = attachCanvas;
+
+    for (const canvas of canvases) {
+      await attachCanvas(canvas, true);
     }
 
     // Persist an initial status snapshot so `_sync.json` exists — and `maude
@@ -1544,7 +2047,7 @@ export function createSyncRuntime(
       // the pull, so it named exactly the canvases that had just arrived and
       // were sitting on disk. `pulled` is the same list under the name that is
       // true, and it is the fact the user is told to act on.
-      mon.notePulled(admittedPulls.map((t) => t.slug));
+      notePulledAll();
       // Re-mark from the FINAL descriptors — `relocatePulled` mutates them in
       // place after each handshake, and the markers are the one consumer that
       // read them before that and would otherwise never read them again.
@@ -1555,27 +2058,310 @@ export function createSyncRuntime(
       // under pairing: a cell's assets are already on the cell. Fire-and-forget
       // — a miss is retried on the next boot for free.
       if (!cellPairing && !stopped) {
-        // OUT OF PROCESS since feature-sync-resync-and-out-of-process-sweep:
-        // the sweep segfaults Bun when it runs alongside the dev server (proven
-        // by isolation — identical sweep, same hub, completes standalone). The
-        // child dying is now a failed sweep the panel reports, not a dead
-        // editor. See `asset-sweep.ts`.
-        assetSweep = runAssetSweep({
-          designRoot: ctx.paths.designRoot,
-          hubUrl: linkedHub.url,
-          // Read at call time — a silent renewal mid-sweep must reach the child
-          // (the parent re-writes its credential file when this changes).
-          token: () => token,
-          // feature-sync-progress-modal — ride the same `sync:status` payload
-          // the doc counts use, so the Sync panel has one source. Guarded on
-          // `stopped`: a late emit must not write `_sync.json` post-teardown.
-          onProgress: (p) => {
-            if (!stopped) store.updateAssets?.(p);
-          },
-        });
+        startAssetSweep(linkedHub.url);
       }
     });
 
+    // ─── DISCOVERY IS CONTINUOUS FROM HERE ────────────────────────────────
+    //
+    // Everything above is the BOOT set. `canvas-list-watch.ts` already notices
+    // when the openable-canvas set changes on disk from ANY source (the API, the
+    // ACP agent, a terminal `cp`, `git checkout`, or the hub's own workspace
+    // agent writing a peer's new canvas into a cell's checkout) and emits
+    // `canvas-list-update`. Nothing was listening on behalf of sync. This is
+    // that listener.
+    //
+    // The payload is used ONLY as a nudge — never as data. See `discovery.ts`
+    // for why the authoritative answer is a full rescan through the same
+    // `scanCanvases` boot used.
+    const rescan = createRescanScheduler({
+      debounceMs: DISCOVERY_DEBOUNCE_MS,
+      onError: (err) => console.error('[sync] canvas rescan failed:', err),
+      run: async () => {
+        if (stopped) return;
+        // An explicit canvas list (test injection) means the caller owns
+        // membership; rescanning would silently overrule them.
+        if (opts.canvases) return;
+        const fresh = await scanCanvases(ctx);
+        const admitted = admitCanvases(fresh.canvases, useSharedDoc);
+        const bySlug = new Map(admitted.map((c) => [c.slug, c]));
+        // THE PULL PIN IS A RACE GUARD, NOT A PERMANENT EXEMPTION.
+        //
+        // A pulled canvas is kept out of `removed` because its body is written
+        // AFTER the handshake, so a scan taken in that window is not evidence
+        // it left the project. That window closes the moment the file exists —
+        // and the pin was never released, so it did not close at all. The cost
+        // is exactly the control this file calls "a security opt-out a hub must
+        // not be able to flip": a pulled canvas whose `.meta.json` says
+        // `syncable: false` was dropped by the scan, held by the pin, and kept
+        // receiving hub writes for the life of the process. On a cell that is
+        // days. Once the body is on disk the ordinary rules apply to it.
+        for (const slug of [...pulledSlugs]) {
+          const body = descriptors.get(slug)?.html;
+          if (body && existsSync(body)) pulledSlugs.delete(slug);
+        }
+        const { added, removed } = diffCanvasSet(
+          [...agents.keys(), ...projections.keys()],
+          bySlug.keys(),
+          pulledSlugs
+        );
+        if (added.length === 0 && removed.length === 0) return;
+        if (removed.length > 0) {
+          for (const slug of removed) await releaseOne(slug);
+          console.log(`[sync] released ${removed.length} canvas(es): ${removed.join(', ')}`);
+          // The marker set shrank. It describes what a peer can WRITE to, so a
+          // stale entry over-lists — the safe direction, and still wrong: it is
+          // the one mitigation standing between an untrusted pull and what the
+          // agent reads.
+          markUntrusted();
+        }
+        const incoming = added.map((slug) => bySlug.get(slug)).filter((c) => !!c);
+        for (const canvas of incoming) {
+          if (agents.has(canvas.slug) || projections.has(canvas.slug)) continue;
+          if (providers.has(canvas.slug)) continue;
+          await attachCanvas(canvas, false);
+        }
+        if (incoming.length > 0) {
+          console.log(
+            `[sync] adopted ${incoming.length} new canvas(es): ${incoming.map((c) => c.slug).join(', ')}`
+          );
+          // The set the DDR-054 §3 F3 markers describe just grew.
+          markUntrusted();
+        }
+      },
+    });
+    discoveryRescan = rescan;
+    discoveryUnsub = ctx.bus.on('canvas-list-update', () => rescan.schedule());
+
+    // The OUTBOUND half of the delete lane. `api.ts` emits these two only from
+    // its privileged create/delete routes, never from the filesystem watcher —
+    // see the comment at the emit site for why that distinction is what makes
+    // them safe to act on.
+    const noteToHub = (slug: unknown, revive: boolean): void => {
+      if (typeof slug !== 'string' || !slug) return;
+      if (revive) tombstoned.delete(slug);
+      else tombstoned.add(slug);
+      void stateDocumentGone(linkedHub.url, token, docNameFor(slug), { revive }).then((ok) => {
+        if (!ok) {
+          console.warn(
+            `[sync] could not tell the project that ${slug} was ${revive ? 're-created' : 'deleted'} — it stays ${revive ? 'buried' : 'in the project'} for other peers until this succeeds.`
+          );
+        }
+      });
+    };
+    deletedUnsub = ctx.bus.on('canvas-deleted', (p: { slug?: unknown }) =>
+      noteToHub(p?.slug, false)
+    );
+    createdUnsub = ctx.bus.on('canvas-created', (p: { slug?: unknown }) =>
+      noteToHub(p?.slug, true)
+    );
+
+    /**
+     * Apply the project's deletions to this machine.
+     *
+     * The runtime releases the canvas first and moves the bytes second: a live
+     * agent flushing its Y.Doc onto a path we are about to rename is how a
+     * "deleted" canvas comes back as a half-written file.
+     *
+     * `tombstoned` outlives the individual poll. The hub drops the `documents`
+     * row on a best-effort basis, so a tombstone and a still-listed document can
+     * coexist for a tick; without a local memory of what was deleted, that
+     * window is enough for the pull lane to fetch the canvas straight back.
+     */
+    const applyTombstones = async (stones: readonly RemoteTombstone[]): Promise<void> => {
+      if (stones.length === 0) return;
+      // Remember EVERY deletion, including names this peer never had — that is
+      // what makes the pull lane below refuse a document the project deleted but
+      // whose row has not gone yet.
+      for (const stone of stones) {
+        const slug = slugFromDocName(stone.name);
+        if (slug) tombstoned.add(slug);
+      }
+      const gone = tombstonedSlugs(stones, descriptors.keys());
+      if (gone.length === 0) return;
+      for (const slug of gone) {
+        const canvas = descriptors.get(slug);
+        await releaseOne(slug);
+        if (canvas) {
+          quarantineCanvas({
+            designRoot: ctx.paths.designRoot,
+            slug,
+            lanes: {
+              html: canvas.html,
+              meta: canvas.meta,
+              css: canvas.css,
+              annotations: canvas.annotations,
+            },
+          });
+        }
+        descriptors.delete(slug);
+      }
+      console.log(`[sync] the project deleted ${gone.length} canvas(es): ${gone.join(', ')}`);
+      // The set the DDR-054 §3 F3 markers describe just shrank.
+      markUntrusted();
+    };
+
+    // ─── THE HUB HALF OF DISCOVERY ────────────────────────────────────────
+    //
+    // The rescan above sees this DISK. A document that exists only on the hub
+    // is invisible to it — Yjs has no enumeration, so a peer learns of a
+    // document only by being told its name. Boot asks once
+    // (`GET /api/documents`), which is why a canvas created in the cloud after
+    // this peer connected could never arrive: the desktop had already asked.
+    //
+    // So keep asking. This is deliberately a POLL and not a push: the listing
+    // route is the ONLY document-enumeration surface every hub version exposes,
+    // including self-hosted ones nobody is going to upgrade, and a fix that
+    // required a new hub would leave exactly the installations that reported the
+    // bug still broken. It is cheap (names + byte counts, one request), it
+    // inherits `fetchRemoteDocs`'s never-fatal posture, and it rides the same
+    // scope gate the sync itself does — a token that may not open a document is
+    // not told the document exists.
+    const pullRemoteOnce = async (): Promise<void> => {
+      if (stopped) return;
+      // Read `token` at call time: a silent renewal swaps it in place.
+      const listing = await fetchRemoteListing(linkedHub.url, token);
+      // null = unreachable, refused, or a hub without the route. Not an error
+      // here any more than it is at boot — sync continues, we ask again later.
+      if (listing === null) return;
+      // ABSENCE BEFORE PRESENCE. A canvas the project deleted must leave before
+      // the pull runs, or a slug that is tombstoned AND still listed (the window
+      // between the tombstone and the row actually going) would be trashed and
+      // immediately pulled back — the resurrection this lane exists to end,
+      // reintroduced inside one tick.
+      await applyTombstones(listing.tombstones);
+      const diff = diffRemoteDocs(
+        [...descriptors.keys()].map((slug) => docNameFor(slug)),
+        listing.documents
+      );
+      if (diff.hubOnly.length === 0) return;
+      const targets = pullTargets(
+        diff.hubOnly,
+        ctx.paths.designRoot,
+        path.join,
+        path.resolve,
+        path.sep,
+        {
+          ...pathOpts,
+          // NEVER the fresh-link relaxation after boot. See `strictPullSlugs`.
+          allowUndeclaredGroup: false,
+          realpath: realpathOfDeepestExisting,
+        }
+      );
+      const admitted = targets
+        // A canvas the project deleted is not a canvas to fetch, even while the
+        // hub is still listing it — see `tombstoned`.
+        .filter((t) => !tombstoned.has(t.slug))
+        .filter((t) => admitPullTarget(ctx, t.slug, t.bodyAbs))
+        .filter((t) => admitPulledBody(t.slug, t.bodyAbs));
+      const fresh = admitted.filter(
+        (t) => !agents.has(t.slug) && !projections.has(t.slug) && !providers.has(t.slug)
+      );
+      if (fresh.length === 0) return;
+      // VOLUME IS A SECURITY PROPERTY HERE, NOT A PERFORMANCE ONE.
+      //
+      // Every accepted name becomes a real file in the design root, a provider,
+      // a pinned Y.Doc, and (on a desktop) something autocommit puts into the
+      // person's git history and `_untrusted/INDEX.json` offers to Claude. The
+      // hub is untrusted to peers (DDR-054), and before continuous discovery
+      // the damage was bounded by there being exactly ONE listing, at connect.
+      // Asking every 20 s for the life of the process removes that bound: a
+      // hostile hub can drip distinct names forever. So the pull lane gets the
+      // ceiling the LOCAL lane has always had (`admitCanvases` → DDR-064 A6),
+      // plus a per-poll cap so one answer cannot land thousands at once.
+      const room = Math.max(0, maxPinnedRooms() - (agents.size + projections.size));
+      const budget = Math.min(room, MAX_PULLS_PER_POLL);
+      const accepted = fresh.slice(0, budget);
+      if (accepted.length < fresh.length) {
+        // Named loudly. A silent cap reads as "sync is broken" with no cause —
+        // the same reason `admitCanvases` shouts about its own ceiling.
+        warnOnce(
+          `pull-cap:${room === 0 ? 'ceiling' : 'batch'}`,
+          `[sync] the project offers ${fresh.length} more canvas(es) than this peer will take in one pass (${accepted.length} accepted; ceiling ${maxPinnedRooms()}, per-pass cap ${MAX_PULLS_PER_POLL}). Raise MAUDE_MAX_PINNED_ROOMS if this project is genuinely this large.`
+        );
+      }
+      if (accepted.length === 0) return;
+      for (const target of accepted) {
+        pulledSlugs.add(target.slug);
+        strictPullSlugs.add(target.slug);
+        everPulled.add(target.slug);
+        await attachCanvas(descriptorFor(target.slug, target.bodyAbs), false);
+      }
+      console.log(
+        `[sync] pulled ${accepted.length} canvas(es) down from the project: ${accepted
+          .map((t) => t.slug)
+          .join(', ')}`
+      );
+      // Both controls describe the set, and the set just grew.
+      notePulledAll();
+      markUntrusted();
+    };
+    /**
+     * Fetch the referenced assets this machine is missing.
+     *
+     * RUNS ON EVERY PEER, cell included — unlike the PUSH sweep, which is a
+     * desktop job because the desktop is the side that has the bytes. Wanting an
+     * asset you can see referenced and do not hold is symmetric, and so is the
+     * fix; making this desktop-only would rebuild the same one-way street facing
+     * the other way.
+     *
+     * After the document poll, deliberately: a canvas that arrives in this tick
+     * brings its references with it, and this is the pass that resolves them.
+     */
+    const pullAssetsOnce = async (): Promise<void> => {
+      if (stopped) return;
+      await pullAssets({
+        designRoot: ctx.paths.designRoot,
+        hubUrl: linkedHub.url,
+        token: () => token,
+      });
+    };
+    // Cumulative per boot — the Sync panel's one line. `synced` is the last
+    // pass's converged count; `pulled`/`conflicts` accumulate.
+    const fileTotals = { synced: 0, pulled: 0, conflicts: 0 };
+    const noteFilePull = (result: FilePullResult): void => {
+      fileTotals.synced = result.skipped + result.pulled.length;
+      fileTotals.pulled += result.pulled.length;
+      fileTotals.conflicts += result.conflicts.length;
+      statusStore?.updateFiles?.({ ...fileTotals });
+    };
+    /**
+     * Plane B's downward pass — after the doc poll and the asset pull, so a
+     * canvas that arrived this tick has its design system resolved in the
+     * same tick. Flag-gated; a no-op when off.
+     *
+     * On a cell the hub shares the checkout, so every manifest entry is
+     * hash-equal by construction and the pass skips itself — deliberately
+     * NOT special-cased: the invariant covers it, and a special case would
+     * be one more branch that can drift.
+     */
+    const pullFilesOnce = async (): Promise<void> => {
+      if (stopped || !syncFilesOn) return;
+      const result = await pullFiles({
+        designRoot: ctx.paths.designRoot,
+        hubUrl: linkedHub.url,
+        token: () => token,
+        canvasGroups: ctx.cfg.canvasGroups,
+        allowCodeModules,
+      });
+      noteFilePull(result);
+    };
+    const pollRemote = (): void => {
+      void pullRemoteOnce()
+        .then(() => pullAssetsOnce())
+        .then(() => pullFilesOnce())
+        .catch((err) => console.error('[sync] remote poll failed:', err));
+    };
+    remotePull = async () => {
+      await pullRemoteOnce();
+      await pullAssetsOnce();
+      await pullFilesOnce();
+    };
+    remotePollTimer = setInterval(pollRemote, REMOTE_POLL_MS);
+    // `setInterval` keeps a Bun process alive; a poll is not a reason for the
+    // dev server to refuse to exit.
+    remotePollTimer.unref?.();
+
     // Arm the pre-expiry renewal from the credential that just booted. Placed
     // last — the timer needs nothing from boot, and boot needs nothing from it
     // (a credential that dies mid-boot lands in the invalid-token path, which
@@ -1586,9 +2372,27 @@ export function createSyncRuntime(
   async function stop(): Promise<void> {
     if (stopped) return;
     stopped = true;
+    // Nothing may be adopted into a runtime that is going away.
+    attachOne = null;
+    discoveryUnsub?.();
+    discoveryUnsub = null;
+    deletedUnsub?.();
+    deletedUnsub = null;
+    createdUnsub?.();
+    createdUnsub = null;
+    discoveryRescan?.stop();
+    discoveryRescan = null;
+    if (remotePollTimer !== null) clearInterval(remotePollTimer);
+    remotePollTimer = null;
+    if (remotePollSoonTimer !== null) clearTimeout(remotePollSoonTimer);
+    remotePollSoonTimer = null;
+    remotePull = null;
     // A sweep that outlives its runtime keeps uploading a project the person
     // just closed — and `restart()` (the Resync button) calls stop() on every
     // press, so without this each press would leave another sweep running.
+    if (assetSweepTimer !== null) clearTimeout(assetSweepTimer);
+    assetSweepTimer = null;
+    assetSweepAgain = false;
     assetSweep?.cancel();
     assetSweep = null;
     // Commit whatever is still inside the quiescence window BEFORE tearing
@@ -1603,14 +2407,8 @@ export function createSyncRuntime(
       }
       autoCommit.stop();
     }
-    for (const detach of awarenessDetaches) {
-      try {
-        detach();
-      } catch {
-        /* best-effort — registry teardown also clears bridges on destroyAll */
-      }
-    }
-    awarenessDetaches.length = 0;
+    for (const slug of [...awarenessDetaches.keys()]) runDetaches(awarenessDetaches, slug);
+    awarenessDetaches.clear();
     // Phase 9.2 (DDR-064) — release shared-doc pins so the rooms can be dropped
     // / destroyed normally on shutdown. Empty unless sharedDoc was active.
     for (const slug of pinnedSlugs) {
@@ -1621,14 +2419,8 @@ export function createSyncRuntime(
       }
     }
     pinnedSlugs.clear();
-    for (const detach of statusDetaches) {
-      try {
-        detach();
-      } catch {
-        /* best-effort */
-      }
-    }
-    statusDetaches.length = 0;
+    for (const slug of [...statusDetaches.keys()]) runDetaches(statusDetaches, slug);
+    statusDetaches.clear();
     monitor?.stop();
     journal?.stop(); // flushes the pending debounce
     journal = null;
@@ -1688,9 +2480,43 @@ export function createSyncRuntime(
     ownedFactory?.dispose();
   }
 
+  // One chain for every membership change, so an adopt cannot interleave with a
+  // release of the same slug (rename arrives as remove+add) or with `stop()`
+  // tearing the maps down underneath it. This is the runtime's own ordering and
+  // is separate from the SUPERVISOR's chain, which serializes whole start/stop
+  // cycles — an adopt is not a cycle and must not make `busy()` true.
+  let membership: Promise<unknown> = Promise.resolve();
+  function serializeMembership<T>(work: () => Promise<T>): Promise<T> {
+    const next = membership.then(work, work);
+    membership = next.catch(() => {});
+    return next;
+  }
+
   return {
     start,
     stop,
+    adopt: (incoming) =>
+      serializeMembership(async () => {
+        if (stopped || !attachOne) return 0;
+        let attached = 0;
+        for (const canvas of incoming) {
+          // Already ours — adopting twice would open a second provider on the
+          // same document and give this peer two votes in every merge.
+          if (agents.has(canvas.slug) || projections.has(canvas.slug)) continue;
+          if (providers.has(canvas.slug)) continue;
+          await attachOne(canvas, false);
+          attached += 1;
+        }
+        return attached;
+      }),
+    release: (slugs) =>
+      serializeMembership(async () => {
+        let released = 0;
+        for (const slug of slugs) if (await releaseOne(slug)) released += 1;
+        return released;
+      }),
+    rescanNow: () => discoveryRescan?.flush() ?? Promise.resolve(),
+    pullRemoteNow: () => remotePull?.() ?? Promise.resolve(),
     // Under sharedDoc the per-canvas handler is a projection, not an agent;
     // count both so size() reflects the synced-canvas count in either mode.
     size: () => agents.size + projections.size,
@@ -1720,6 +2546,9 @@ export function createSyncRuntime(
  * `MAUDE_MAX_PINNED_ROOMS` if a real project ever meets it — and if one does,
  * that is a signal worth reading rather than a number worth bumping.
  */
+/** Coalesce a burst of asset writes (dragging six images on) into one sweep. */
+const ASSET_SWEEP_DEBOUNCE_MS = 1500;
+
 export const DEFAULT_MAX_PINNED_ROOMS = 500;
 
 function maxPinnedRooms(): number {