@1agh/maude 0.60.3 → 0.60.5

package/apps/studio/sync/index.ts

@@ -29,6 +29,7 @@ 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';
@@ -43,6 +44,7 @@ import {
 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';
@@ -54,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. */
@@ -250,7 +257,15 @@ export interface SyncRuntime {
    * discovery without the user authorising anything.
    */
   adopt(canvases: readonly CanvasDescriptor[]): Promise<number>;
-  /** Give up canvases that left the project. Returns how many were released. */
+  /**
+   * 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.
@@ -502,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.
@@ -697,6 +722,9 @@ export function createSyncRuntime(
    *  `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. */
@@ -724,6 +752,16 @@ export function createSyncRuntime(
    *  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.
    *
@@ -889,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
@@ -1002,6 +1050,8 @@ export function createSyncRuntime(
     // 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));
@@ -1172,7 +1222,7 @@ export function createSyncRuntime(
       // 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)) scheduleAssetSweep(linkedHub.url);
+      if (isPushableAssetRel(rel, ctx.cfg.canvasGroups)) scheduleAssetSweep(linkedHub.url);
     });
 
     /**
@@ -2083,6 +2133,74 @@ export function createSyncRuntime(
     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
@@ -2102,13 +2220,19 @@ export function createSyncRuntime(
     const pullRemoteOnce = async (): Promise<void> => {
       if (stopped) return;
       // Read `token` at call time: a silent renewal swaps it in place.
-      const docs = await fetchRemoteDocs(linkedHub.url, token);
+      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 (docs === null) return;
+      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)),
-        docs
+        listing.documents
       );
       if (diff.hubOnly.length === 0) return;
       const targets = pullTargets(
@@ -2125,6 +2249,9 @@ export function createSyncRuntime(
         }
       );
       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(
@@ -2169,10 +2296,67 @@ export function createSyncRuntime(
       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().catch((err) => console.error('[sync] remote poll failed:', err));
+      void pullRemoteOnce()
+        .then(() => pullAssetsOnce())
+        .then(() => pullFilesOnce())
+        .catch((err) => console.error('[sync] remote poll failed:', err));
+    };
+    remotePull = async () => {
+      await pullRemoteOnce();
+      await pullAssetsOnce();
+      await pullFilesOnce();
     };
-    remotePull = pullRemoteOnce;
     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.
@@ -2192,6 +2376,10 @@ export function createSyncRuntime(
     attachOne = null;
     discoveryUnsub?.();
     discoveryUnsub = null;
+    deletedUnsub?.();
+    deletedUnsub = null;
+    createdUnsub?.();
+    createdUnsub = null;
     discoveryRescan?.stop();
     discoveryRescan = null;
     if (remotePollTimer !== null) clearInterval(remotePollTimer);

package/apps/studio/sync/migrate-seed.ts

@@ -36,16 +36,19 @@ import type * as Y from 'yjs';
 
 import { Y_TYPES } from '../collab/persistence.ts';
 import {
+  annotationsEditAtFromDoc,
   applyAnnotationsToDoc,
   applyCommentsToDoc,
   applyCssToDoc,
   applyHtmlToDoc,
   applyMetaToDoc,
   bodyEditAtFromDoc,
+  isEmptyAnnotationsSvg,
+  stampAnnotationsEdit,
   stampBodyEdit,
   Y_SYNC_TYPES,
 } from './codec.ts';
-import { decideColdStart, unionCommentsById } from './cold-start.ts';
+import { decideAnnotationsColdStart, decideColdStart, unionCommentsById } from './cold-start.ts';
 import { hashBytes } from './echo-guard.ts';
 import type { SyncJournal } from './journal.ts';
 import { ORIGINS } from './origins.ts';
@@ -133,7 +136,17 @@ export async function migrateSeed(opts: MigrateSeedOptions): Promise<MigrateSeed
         const parsed = tryParseJsonArray(localComments);
         if (parsed) applyCommentsToDoc(doc, parsed, ORIGINS.MIGRATION);
       }
-      if (localAnnotations) applyAnnotationsToDoc(doc, localAnnotations, ORIGINS.MIGRATION);
+      if (localAnnotations) {
+        if (applyAnnotationsToDoc(doc, localAnnotations, ORIGINS.MIGRATION)) {
+          // Stamp with the FILE's mtime — adopt seeds pre-existing content,
+          // which must not claim apply-time freshness over a newer peer.
+          stampAnnotationsEdit(
+            doc,
+            ORIGINS.MIGRATION,
+            localMtimeMs(paths.annotations) ?? undefined
+          );
+        }
+      }
       if (paths.meta && localMeta) applyMetaToDoc(doc, localMeta, ORIGINS.MIGRATION);
       if (paths.css && localCss) applyCssToDoc(doc, localCss, ORIGINS.MIGRATION);
     }, ORIGINS.MIGRATION);
@@ -164,17 +177,16 @@ export async function migrateSeed(opts: MigrateSeedOptions): Promise<MigrateSeed
 
   let result: MigrateSeedResult = 'hub-wins';
 
-  /** Rebuild body (+ visually-coupled css/annotations) from local, in ONE
-   *  MIGRATION transaction — one source per type, never a two-history merge. */
+  /** Rebuild body (+ visually-coupled css) from local, in ONE MIGRATION
+   *  transaction — one source per type, never a two-history merge.
+   *  Annotations are deliberately NOT here any more: they resolve per-lane
+   *  below (decideAnnotationsColdStart), independent of the body winner. */
   const rebuildBodyFromLocal = (): void => {
     doc.transact(() => {
       if (applyHtmlToDoc(doc, localHtml as string, ORIGINS.MIGRATION)) {
         stampBodyEdit(doc, ORIGINS.MIGRATION);
       }
       if (paths.css && localCss !== null) applyCssToDoc(doc, localCss, ORIGINS.MIGRATION);
-      if (localAnnotations !== null) {
-        applyAnnotationsToDoc(doc, localAnnotations, ORIGINS.MIGRATION);
-      }
     }, ORIGINS.MIGRATION);
     opts.journal?.record(slug, {
       bodyHash: hashBytes(localHtml as string),
@@ -246,6 +258,39 @@ export async function migrateSeed(opts: MigrateSeedOptions): Promise<MigrateSeed
     }
   }
 
+  // ---- annotations: PER-LANE newest-wins (the 2026-08-14 eraser fix; the
+  // same table as agent.ts reconcile). Under sharedDoc the collab room's
+  // persistJson materializes the doc's annotations to disk, so a stale hub
+  // EMPTY WRAPPER (non-'' but zero strokes) in the doc erased local strokes
+  // right after this seed ran. Resolve the lane here, before the room
+  // materializes: unstamped emptiness never beats content.
+  {
+    const docSvg = doc.getMap<unknown>(Y_TYPES.annotations).get('svg');
+    const docAnnotations = typeof docSvg === 'string' ? docSvg : '';
+    const annDecision = decideAnnotationsColdStart({
+      local: localAnnotations,
+      doc: docAnnotations,
+      isEmpty: isEmptyAnnotationsSvg,
+      localMtimeMs: localMtimeMs(paths.annotations),
+      docEditAtMs: annotationsEditAtFromDoc(doc),
+      bodyWinner: result === 'body-seed-up' || result === 'conflict-local-wins' ? 'local' : 'hub',
+    });
+    if (annDecision.winner === 'local' && localAnnotations !== null) {
+      console.warn(`[sync/${slug}] shared-doc cold-start annotations: ${annDecision.reason}`);
+      doc.transact(() => {
+        if (applyAnnotationsToDoc(doc, localAnnotations, ORIGINS.MIGRATION)) {
+          stampAnnotationsEdit(
+            doc,
+            ORIGINS.MIGRATION,
+            localMtimeMs(paths.annotations) ?? undefined
+          );
+        }
+      }, ORIGINS.MIGRATION);
+    }
+    // winner 'hub' → nothing to write here: the collab room owns the
+    // annotations doc→file half and materializes it (persistJson).
+  }
+
   // Comments id-union (DDR-102): rebuild from merged JSON via the
   // delete-then-insert codec — same-id entries keep the doc's version, so the
   // duplication trap stays closed; local-only comments survive.

package/apps/studio/sync/projection.ts

@@ -39,6 +39,7 @@ import {
   htmlFromDoc,
   mergeSharedMetaIntoLocal,
   metaFromDoc,
+  stampAnnotationsEdit,
   stampBodyEdit,
 } from './codec.ts';
 import { type EchoGuard, hashBytes } from './echo-guard.ts';
@@ -354,7 +355,15 @@ export function createDocProjection(opts: DocProjectionOptions): DocProjection {
     }
     if (evt.path === paths.annotations) {
       clearStrike(evt.path);
-      return applyAnnotationsToDoc(doc, str, importOrigin);
+      // Apply + per-lane stamp in ONE transaction (mirrors agent.applyFromFs)
+      // so a deliberate delete-all (empty wrapper) carries its freshness and
+      // survives cold start on other peers (the 2026-08-14 eraser fix).
+      let changed = false;
+      doc.transact(() => {
+        changed = applyAnnotationsToDoc(doc, str, importOrigin);
+        if (changed) stampAnnotationsEdit(doc, importOrigin);
+      }, importOrigin);
+      return changed;
     }
     return false;
   }

package/apps/studio/sync/remote-docs.ts

@@ -32,6 +32,29 @@ export interface RemoteDoc {
   bytes: number;
 }
 
+/** One deletion the project has stated — see the hub's `tombstones.mjs`. */
+export interface RemoteTombstone {
+  name: string;
+  deletedAt: number;
+}
+
+/**
+ * The whole listing: what the project HAS, and what it has DELETED.
+ *
+ * Both halves are needed, and for symmetric reasons. Presence alone made a
+ * hub-only document authority to create a local file — correct, and the reason
+ * a project arrives in full. Absence alone was un-representable, so a delete was
+ * indistinguishable from "this peer has not discovered it yet" and got refilled
+ * on the next tick. One request carries both.
+ */
+export interface RemoteListing {
+  documents: RemoteDoc[];
+  /** Empty against a hub older than the tombstone route — never null, because
+   *  "this hub cannot say" and "nothing was deleted" call for the same
+   *  behaviour: change nothing on disk. */
+  tombstones: RemoteTombstone[];
+}
+
 export interface RemoteDocDiff {
   /** Documents on both sides — the ones actually syncing. */
   shared: string[];
@@ -54,11 +77,11 @@ const LIST_TIMEOUT_MS = 6000;
  * reporting improvement, and making it load-bearing would trade a real feature
  * for a nicer message.
  */
-export async function fetchRemoteDocs(
+export async function fetchRemoteListing(
   hubUrl: string,
   token: string,
   fetchImpl: typeof fetch = fetch
-): Promise<RemoteDoc[] | null> {
+): Promise<RemoteListing | null> {
   try {
     const base = hubUrl.replace(/\/+$/, '');
     const res = await fetchImpl(`${base}/api/documents`, {
@@ -66,19 +89,64 @@ export async function fetchRemoteDocs(
       signal: AbortSignal.timeout(LIST_TIMEOUT_MS),
     });
     if (!res.ok) return null;
-    const body = (await res.json()) as { documents?: unknown };
+    const body = (await res.json()) as { documents?: unknown; tombstones?: unknown };
     if (!Array.isArray(body?.documents)) return null;
-    return body.documents
+    const documents = body.documents
       .filter(
         (d): d is RemoteDoc =>
           !!d && typeof (d as RemoteDoc).name === 'string' && (d as RemoteDoc).name.length > 0
       )
       .map((d) => ({ name: d.name, bytes: Number(d.bytes) || 0 }));
+    // A hub without the route omits the field entirely; a hostile one could send
+    // anything. Both land on "no deletions", which changes nothing on disk — the
+    // safe direction for a signal whose only effect is to REMOVE local files.
+    const tombstones = Array.isArray(body?.tombstones)
+      ? (body.tombstones as unknown[])
+          .filter(
+            (t): t is RemoteTombstone =>
+              !!t &&
+              typeof (t as RemoteTombstone).name === 'string' &&
+              (t as RemoteTombstone).name.length > 0
+          )
+          .map((t) => ({ name: t.name, deletedAt: Number(t.deletedAt) || 0 }))
+      : [];
+    return { documents, tombstones };
   } catch {
     return null;
   }
 }
 
+/**
+ * Tell the hub a document is gone (`DELETE`) or exists again (`POST`).
+ *
+ * BEST-EFFORT, LIKE EVERY OTHER HUB CALL HERE. A hub that is old, offline or
+ * refusing means the local delete still happened — the canvas is in `_trash/`
+ * and this peer has released it. What is lost is only the PROPAGATION, and the
+ * peer retries the statement on its next poll for anything it still sees on the
+ * hub but no longer has on disk. Returning false rather than throwing keeps a
+ * failed network call from turning a successful local delete into an error the
+ * user has to interpret.
+ */
+export async function stateDocumentGone(
+  hubUrl: string,
+  token: string,
+  docName: string,
+  opts: { revive?: boolean; fetchImpl?: typeof fetch } = {}
+): Promise<boolean> {
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  try {
+    const base = hubUrl.replace(/\/+$/, '');
+    const res = await fetchImpl(`${base}/api/documents/${encodeURIComponent(docName)}`, {
+      method: opts.revive ? 'POST' : 'DELETE',
+      headers: { authorization: `Bearer ${token}` },
+      signal: AbortSignal.timeout(LIST_TIMEOUT_MS),
+    });
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Diff the hub's documents against the ones this peer syncs.
  *
@@ -146,6 +214,32 @@ export function slugFromDocName(docName: string): string | null {
   return ns ? ns[1].toLowerCase() : null;
 }
 
+/**
+ * The local slugs a tombstone set names — validated, deduplicated, safe.
+ *
+ * A tombstone is the one hub-supplied signal whose effect is to REMOVE work from
+ * a person's disk, so it runs through exactly the same name gate a pull does
+ * (`slugFromDocName`: whole-name match, no dots, no traversal, no extension
+ * smuggling) and anything that does not survive is dropped silently. A hub
+ * cannot name a file this way that it could not already have created.
+ *
+ * `known` is the set of slugs this peer actually holds; a tombstone for anything
+ * else is not an error, just nothing to do — that is the normal steady state
+ * once both sides have converged.
+ */
+export function tombstonedSlugs(
+  tombstones: readonly RemoteTombstone[],
+  known: Iterable<string>
+): string[] {
+  const have = new Set(known);
+  const out = new Set<string>();
+  for (const t of tombstones) {
+    const slug = slugFromDocName(t.name);
+    if (slug && have.has(slug)) out.add(slug);
+  }
+  return [...out].sort();
+}
+
 export interface PullTarget {
   slug: string;
   docName: string;

package/apps/studio/sync/status.ts

@@ -53,6 +53,22 @@ export interface SyncStatusPayload extends SyncStatusSnapshot {
    * payload as the doc counts so the Sync panel has one source, not two.
    */
   assets?: AssetPushProgress;
+  /**
+   * feature-sync-file-plane — Plane B's counts (additive; absent until the
+   * first flag-on file pull of a boot). `conflicts` names losers parked in
+   * `_trash/<rel>-conflict-<ts>` — the panel line points there, because a
+   * conflict a person cannot find is silent loss with extra steps.
+   */
+  files?: FilePlaneStatus;
+}
+
+export interface FilePlaneStatus {
+  /** Plane files present and equal after the last pass — the steady state. */
+  synced: number;
+  /** Cumulative files landed this boot. */
+  pulled: number;
+  /** Cumulative conflicts this boot (either winner); losers are in _trash/. */
+  conflicts: number;
 }
 
 export interface SyncStatusStoreOptions {
@@ -78,6 +94,9 @@ export interface SyncStatusStore {
    *  broadcast. Kept in the store (not the monitor): assets are a push lane,
    *  not a connection, and the monitor's state machine must not learn them. */
   updateAssets(progress: AssetPushProgress): void;
+  /** feature-sync-file-plane — merge Plane B counts + persist + broadcast.
+   *  Same reasoning as `updateAssets`: a lane, not a connection. */
+  updateFiles(files: FilePlaneStatus): void;
   /** Current payload (defensive copy). */
   get(): SyncStatusPayload;
 }
@@ -102,6 +121,7 @@ export function createSyncStatusStore(opts: SyncStatusStoreOptions): SyncStatusS
   };
 
   let assets: AssetPushProgress | undefined;
+  let files: FilePlaneStatus | undefined;
 
   function payload(): SyncStatusPayload {
     return {
@@ -111,6 +131,7 @@ export function createSyncStatusStore(opts: SyncStatusStoreOptions): SyncStatusS
       conflicts: conflicts.slice(),
       ...(opts.sharedDoc ? { sharedDoc: true } : {}),
       ...(assets ? { assets } : {}),
+      ...(files ? { files } : {}),
     };
   }
 
@@ -142,6 +163,10 @@ export function createSyncStatusStore(opts: SyncStatusStoreOptions): SyncStatusS
       assets = progress;
       flush();
     },
+    updateFiles(next) {
+      files = next;
+      flush();
+    },
     get: payload,
   };
 }