@1agh/maude 0.55.0 → 0.57.0

package/apps/studio/sync/presentation.ts

@@ -0,0 +1,273 @@
+// One rule for "what is the hub link doing", shared by every surface.
+//
+// There were two answers to that question and they disagreed. The status bar
+// keyed off `state` alone — it referenced `docs` zero times, so a link whose
+// every document the hub had refused still showed a green dot and the word
+// "synced". The connect note in the cloud rail keyed off the ATTACH RESPONSE,
+// a value that means "the runtime started", and never updated again. A user
+// who distrusted one was sent to the other, which was wrong in a different way.
+//
+// So the rule lives here, once, as a pure function over the payload both
+// surfaces already receive. Agreement between them is then structural rather
+// than a thing two files have to remember.
+//
+// DDR-054 — document names and project names originate at the hub. Counts come
+// first in every sentence so a hostile name cannot dominate it, names are
+// capped, and nothing here produces markup.
+
+import type { SyncStatusSnapshot } from './connection-state.ts';
+
+/** Where a link is, in the terms a person cares about. */
+export type SyncPhase =
+  | 'connecting'
+  | 'syncing'
+  | 'synced'
+  | 'refused'
+  | 'offline'
+  | 'nothing-syncable';
+
+export interface SyncPresentation {
+  phase: SyncPhase;
+  /** Green dot — reserved for a link that is genuinely carrying edits. */
+  online: boolean;
+  /** Status-bar slot text. Terse; never contains a hub-supplied name. */
+  label: string;
+  /** Full sentence — the rail note and the status-bar hover. */
+  title: string;
+  /**
+   * What the person should do now, or null when the honest answer is "nothing,
+   * it is working". Every non-null phase names one — being told a state without
+   * being told the move is the complaint this whole change exists for.
+   */
+  next: string | null;
+  /** Up to 3 hub-supplied names relevant to the phase (refused / pulled). */
+  names: string[];
+}
+
+/**
+ * The `/_sync-status` payload, in its three historical shapes:
+ *   - `{ linked: false }`                      — solo project, no link
+ *   - `{ notSyncable, tsxCount, reason }`      — DDR-060, linked but 0 syncable
+ *   - the connection-state snapshot + url/canvases (the common case)
+ *
+ * Every field is optional on purpose: pre-DDR-102 payloads have no `docs`, and
+ * the browser and the CLI read the same JSON.
+ */
+export interface SyncStatusLike extends Partial<SyncStatusSnapshot> {
+  linked?: boolean;
+  notSyncable?: boolean;
+  tsxCount?: number;
+  reason?: string;
+  canvases?: number;
+}
+
+/** Hub-supplied text that reaches a UI. Bounded, never markup. */
+const MAX_NAME_LEN = 60;
+const SHOWN_NAMES = 3;
+
+export function safeName(raw: unknown, fallback: string): string {
+  // Length alone was not enough. A name is hub-supplied (cell mode sets it from
+  // `MAUDE_PROJECT_NAME`; `.design/config.json` is a committed file anyone with
+  // repo access can author), and it lands in trusted app chrome — including a
+  // `title=` tooltip, where a newline RENDERS and can push the true clause out
+  // of view. `All 75 canvases synced.\n\n\n` fits inside 60 characters and
+  // reads as a reassuring sentence of ours.
+  //
+  // So: strip control and format characters (which covers the bidi overrides
+  // U+202A–U+202E / U+2066–U+2069 — a name that reverses the rest of the line
+  // is the same attack by a different mechanism), then collapse whitespace to
+  // single spaces so no name can ever contain a line break.
+  const s = String(raw ?? '')
+    .replace(/[\p{Cc}\p{Cf}]/gu, '')
+    .replace(/\s+/g, ' ')
+    .trim();
+  if (!s) return fallback;
+  return s.length > MAX_NAME_LEN ? `${s.slice(0, MAX_NAME_LEN)}…` : s;
+}
+
+function shownNames(list: readonly string[] | undefined): string[] {
+  return (list ?? []).slice(0, SHOWN_NAMES).map((n) => safeName(n, '(unnamed)'));
+}
+
+/**
+ * The per-document counts, or null if they cannot be trusted.
+ *
+ * FAIL CLOSED. `/_sync-status` returns `JSON.parse` of `_sync.json` with no
+ * schema, so this function's input is whatever is on disk — a partial write, an
+ * older producer, a newer one. `synced` was the FALL-THROUGH branch, which made
+ * the reassuring answer the only reachable one for any shape not recognised:
+ * `docs: {}` gave `total === NaN`, failed both `> 0` and `=== 0`, and rendered
+ * "Synced — all NaN canvases", green. For a module whose entire premise is that
+ * it does not overstate, the unreadable case must land in `connecting`, never
+ * in `synced`.
+ */
+function readCounts(
+  docs: SyncStatusLike['docs']
+): { synced: number; pending: number; rejected: number } | null {
+  if (!docs) return null;
+  const ok = (n: unknown): n is number => typeof n === 'number' && Number.isInteger(n) && n >= 0;
+  if (!ok(docs.synced) || !ok(docs.pending) || !ok(docs.rejected)) return null;
+  return { synced: docs.synced, pending: docs.pending, rejected: docs.rejected };
+}
+
+/**
+ * Read a sync payload the way a person would.
+ *
+ * Returns null when there is nothing to say — an unlinked project has no hub
+ * status, and inventing one would put a slot on screen that can only ever be
+ * empty.
+ */
+export function syncPresentation(
+  status: SyncStatusLike | null | undefined,
+  opts: { project?: string | null } = {}
+): SyncPresentation | null {
+  if (!status || status.linked === false) return null;
+  const project = safeName(opts.project, 'the workspace');
+
+  if (status.notSyncable) {
+    const tsx = status.tsxCount ?? 0;
+    return {
+      phase: 'nothing-syncable',
+      online: false,
+      label: `0 syncable${tsx > 0 ? ` · ${tsx} tsx` : ''}`,
+      title: status.reason
+        ? safeName(status.reason, 'No canvases in this project are syncable yet.')
+        : `Connected to ${project} — no canvases here are syncable yet.`,
+      next: 'Create a canvas — it will start syncing on its own.',
+      names: [],
+    };
+  }
+
+  const queued = status.queuedOps ?? 0;
+  const queueNote = queued > 0 ? ` ${queued} local edit${queued === 1 ? '' : 's'} are queued.` : '';
+  const unreachable = status.state === 'offline' || status.state === 'offline-long';
+  // Validated, not taken on trust — see `readCounts`. `null` means "unreadable",
+  // which is deliberately NOT the same as "absent" (an old payload, handled
+  // below) and must never reach the synced branch.
+  const docs = readCounts(status.docs);
+  const unreadable = status.docs !== undefined && docs === null;
+
+  // A REFUSAL OUTRANKS EVERYTHING, including an unreachable hub.
+  //
+  // The offline branch used to sit above this one, and that was the bug from
+  // one branch up: a hub can refuse auth on the documents it wants silenced and
+  // then drop the sockets, and the user would be told "your edits are safe and
+  // queued — nothing to do". For an auth-rejected document that is false and
+  // never self-heals. Rejections are deliberately sticky (a dropped socket does
+  // not launder them), so if one is on record it is still true while offline —
+  // and it is the only part of the picture that needs a person.
+  if (docs && docs.rejected > 0) {
+    const total = docs.synced + docs.pending + docs.rejected;
+    return {
+      phase: 'refused',
+      online: false,
+      label: `${docs.rejected} refused`,
+      title:
+        `${docs.rejected} of ${total} canvas${total === 1 ? '' : 'es'} were refused by ${project} — their edits are not syncing.` +
+        (unreachable ? ' The hub is also unreachable right now.' : ''),
+      next: 'Reconnect the workspace — the credential may have been rotated.',
+      names: shownNames(status.rejectedSlugs),
+    };
+  }
+
+  // Otherwise an unreachable hub outranks every count. Whatever the documents
+  // last said, nothing is moving — and "72 synced" over a dead socket is the
+  // exact shape of lie this module exists to stop.
+  //
+  // Count first, name second: `project` is hub-supplied, and a leading name is
+  // a name that gets to set the tone of our own sentence.
+  if (unreachable) {
+    return {
+      phase: 'offline',
+      online: false,
+      label: queued > 0 ? `offline · ${queued} ↑` : 'offline',
+      title: `Not reachable: ${project}. Your edits are safe on this machine and queued.${queueNote}`,
+      next: 'Nothing to do — syncing resumes by itself when the hub is back.',
+      names: [],
+    };
+  }
+
+  if (unreadable) {
+    // A payload we cannot read is not a payload that says everything is fine.
+    return {
+      phase: 'connecting',
+      online: false,
+      label: 'status unreadable',
+      title: `Cannot read the sync status for ${project} — the counts on disk are malformed.`,
+      next: 'Reconnect the workspace; if it persists, restart Maude.',
+      names: [],
+    };
+  }
+
+  if (!docs) {
+    // Pre-DDR-102 payload: `state` is all there is. Report it as the weaker
+    // evidence it is, rather than promoting it to a document-level claim.
+    const online = status.state === 'online' || status.flash === 'synced';
+    return {
+      phase: online ? 'synced' : 'connecting',
+      online,
+      label: online ? (queued > 0 ? `${queued} ↑` : 'synced') : 'connecting…',
+      title: online ? `Syncing with ${project}.${queueNote}` : `Connecting to ${project}…`,
+      next: online ? null : 'Nothing to do — this usually takes a moment.',
+      names: [],
+    };
+  }
+
+  // Refusals were already handled above — they outrank an unreachable hub, so
+  // that branch has to come first. Everything from here on has `rejected === 0`.
+  const total = docs.synced + docs.pending + docs.rejected;
+
+  if (total === 0) {
+    return {
+      phase: 'connecting',
+      online: false,
+      label: 'connecting…',
+      title: `Connecting to ${project}…`,
+      next: 'Nothing to do — this usually takes a moment.',
+      names: [],
+    };
+  }
+
+  if (docs.pending > 0) {
+    // Zero settled yet is a different fact from some settled: one is a
+    // handshake in flight, the other is visible progress.
+    const started = docs.synced > 0;
+    return {
+      phase: started ? 'syncing' : 'connecting',
+      online: false,
+      label: started ? `${docs.synced}/${total}` : 'connecting…',
+      title: started
+        ? `Syncing with ${project} — ${docs.synced} of ${total} canvas${total === 1 ? '' : 'es'} so far.`
+        : `Connecting to ${project}…`,
+      next: 'Nothing to do — this usually takes a moment.',
+      names: [],
+    };
+  }
+
+  // Clamped and validated for the same reason as the doc counts: `count` is
+  // read off disk, and "1000000000 came down from the project" is not a
+  // sentence this module should be capable of producing. The ceiling is `total`
+  // — a pulled document becomes one of the canvases being counted, so more
+  // pulled than exist is not a big number, it is a broken payload.
+  const rawPulled = status.pulled?.count;
+  const pulledCount =
+    typeof rawPulled === 'number' && Number.isInteger(rawPulled) && rawPulled >= 0
+      ? Math.min(rawPulled, total)
+      : 0;
+  return {
+    phase: 'synced',
+    online: true,
+    label: queued > 0 ? `${queued} ↑` : 'synced',
+    title:
+      `Synced with ${project} — all ${total} canvas${total === 1 ? '' : 'es'}.` +
+      (pulledCount > 0 ? ` ${pulledCount} came down from the project on this connect.` : '') +
+      queueNote,
+    // Deliberately NOT "open one of the canvases that just arrived". A pulled
+    // canvas is hub-authored TSX (DDR-054, and the DDR-079 residual it carries),
+    // and an imperative in our own green success sentence is the strongest
+    // possible endorsement of content we do not vouch for. State the fact; the
+    // decision to open stays the person's.
+    next: pulledCount > 0 ? 'They are new to this machine — look them over before editing.' : null,
+    names: pulledCount > 0 ? shownNames(status.pulled?.names) : [],
+  };
+}

package/apps/studio/sync/projection.ts

@@ -37,15 +37,13 @@ import {
   applyMetaToDoc,
   cssFromDoc,
   htmlFromDoc,
-  MAX_CSS_BYTES,
-  MAX_HTML_BYTES,
-  MAX_META_BYTES,
   mergeSharedMetaIntoLocal,
   metaFromDoc,
   stampBodyEdit,
 } from './codec.ts';
 import { type EchoGuard, hashBytes } from './echo-guard.ts';
 import type { SyncJournal } from './journal.ts';
+import { MAX_CSS_BYTES, MAX_HTML_BYTES, MAX_META_BYTES, withinByteCap } from './limits.ts';
 import { ORIGINS } from './origins.ts';
 
 export const PROJECT_FLUSH_MS = 800;
@@ -76,6 +74,20 @@ export interface DocProjectionOptions {
   echoGuard?: EchoGuard;
   /** Injected for tests — defaults to atomicWrite. */
   writer?: (path: string, bytes: string | Uint8Array) => void;
+  /**
+   * Called with the absolute path after a doc→file write LANDS.
+   *
+   * Exists for one environment: a cell, where the container's recursive
+   * `fs.watch` does not see our atomic tmp+rename writes. Locally the watcher
+   * fires and the runtime leaves this unset — the same "the watcher owes us this
+   * event" reasoning (and the same workspace-mode gate) as
+   * `createContainerWriteBridge`, which covers the API write path and cannot
+   * cover this one because the projector never arms `activity:suppress`.
+   *
+   * Without it a peer's edit reaches the doc, reaches disk, and the browser's
+   * canvas iframe still shows the old render until somebody reloads by hand.
+   */
+  onWrote?: (absPath: string) => void;
   /** Override the 800 ms debounce. Tests use 0 to flush on the next microtask. */
   flushMs?: number;
   /** Circuit-breaker threshold (consecutive parse failures per path). */
@@ -153,18 +165,41 @@ export function createDocProjection(opts: DocProjectionOptions): DocProjection {
     opts.echoGuard?.record(path, hashBytes(value));
   }
 
+  /**
+   * Write + announce. Every doc→file write goes through here rather than calling
+   * `writer` directly, so a future fourth projected type cannot silently skip
+   * the announcement — the bug class this whole hook exists to close.
+   *
+   * NO-OPS WHEN THE FILE ALREADY HOLDS THESE BYTES. The `last*` guards above
+   * compare against what THIS projector wrote, which is null on the first pass —
+   * so the cold-start `reconcile()` re-wrote every canvas with content identical
+   * to what was already there. Harmless while nobody was listening; once the
+   * write announces itself (below) it became a spurious reload of every open
+   * canvas at boot. A write that changes nothing should cost nothing, including
+   * downstream.
+   *
+   * `onWrote` is best-effort: it feeds a reload, and a reload that failed to
+   * fire must never cost the write that already succeeded.
+   */
+  function writeAndAnnounce(path: string, value: string): void {
+    if (readLocal(path) === value) return;
+    writer(path, value);
+    try {
+      opts.onWrote?.(path);
+    } catch (err) {
+      console.error(`[projection/${slug}] onWrote(${path}) failed:`, err);
+    }
+  }
+
   // Security re-audit (Phase D, finding A2 / DDR-054 §2d): the codec's
   // MAX_*_BYTES caps guard the file→doc *import* lane, but hub-pushed content
   // arrives as raw Yjs updates through the provider (NOT via applyXToDoc), so it
   // bypasses those caps. This doc→file lane is the consumer's guard on that
   // direction — refuse to materialize an oversized hub-pushed body to disk
-  // (disk-fill DoS). Returns true when the write is allowed.
+  // (disk-fill DoS). Returns true when the write is allowed. Shared with
+  // `collab/persistence.ts`'s equivalent guard via `limits.ts`.
   function withinCap(path: string, value: string, max: number): boolean {
-    if (Buffer.byteLength(value, 'utf8') <= max) return true;
-    console.warn(
-      `[projection/${slug}] refusing doc→file write of ${path} > ${max} bytes (hub-pushed oversize). DDR-054 §2d.`
-    );
-    return false;
+    return withinByteCap(`projection/${slug}`, path, Buffer.byteLength(value, 'utf8'), max);
   }
 
   // ----- doc → file (html / css / meta only; room owns comments/annotations)
@@ -180,7 +215,7 @@ export function createDocProjection(opts: DocProjectionOptions): DocProjection {
     }
     if (!withinCap(paths.html, next, MAX_HTML_BYTES)) return;
     recordEcho(paths.html, next);
-    writer(paths.html, next);
+    writeAndAnnounce(paths.html, next);
     lastHtml = next;
     opts.journal?.record(slug, { bodyHash: hashBytes(next) }); // DDR-102 checkpoint
   }
@@ -193,7 +228,7 @@ export function createDocProjection(opts: DocProjectionOptions): DocProjection {
     if (next === null) return; // doc carries no css yet — nothing to write
     if (!withinCap(paths.css, next, MAX_CSS_BYTES)) return;
     recordEcho(paths.css, next);
-    writer(paths.css, next);
+    writeAndAnnounce(paths.css, next);
     opts.journal?.record(slug, { cssHash: hashBytes(next) }); // DDR-102 checkpoint
   }
 
@@ -208,7 +243,7 @@ export function createDocProjection(opts: DocProjectionOptions): DocProjection {
     if (merged === null || merged === local) return; // unparseable / disk matches
     if (!withinCap(paths.meta, merged, MAX_META_BYTES)) return;
     recordEcho(paths.meta, merged);
-    writer(paths.meta, merged);
+    writeAndAnnounce(paths.meta, merged);
   }
 
   async function flush(): Promise<void> {

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

@@ -0,0 +1,191 @@
+// What the PROJECT holds, versus what this machine happens to carry.
+//
+// The sync runtime opens one provider per canvas found on LOCAL disk, and Yjs
+// has no enumeration — so a document that exists only on the hub is invisible
+// to a peer by construction. A desktop with 72 of a project's 75 canvases syncs
+// 72, reports "72/72 synced", and is accurate about the wrong universe. The
+// user-visible form of that was "I pressed Open in Maude and nothing happened":
+// three real canvases (welcome, how-to-use, how-to-make-video) lived only in
+// the cloud and could never arrive.
+//
+// This module asks the hub what it has (`GET /api/documents`, scope-bound to
+// the same token the sync uses) and diffs it against the local set, so the
+// runtime can say which side is missing what.
+//
+// SYNC IS BIDIRECTIONAL AND COMPLETE. A project you have been granted access to
+// is a project you get — all of it, both directions. Local canvases go up (they
+// always did); hub-only documents now come DOWN, materialised as real files.
+//
+// What that trades, stated plainly: a hub can create files in your design root,
+// where before it could only update canvases you already had (DDR-054 treats
+// hub-pushed content as untrusted). That is accepted deliberately — the hub is
+// the project, the caller is authenticated, and a partial project is not a
+// project. The one guard kept is containment: a document NAME can never place a
+// file outside the design root. That is not policy filtering, it is the
+// difference between writing your project and writing your filesystem.
+
+/** One document as the hub reports it. */
+export interface RemoteDoc {
+  name: string;
+  bytes: number;
+}
+
+export interface RemoteDocDiff {
+  /** Documents on both sides — the ones actually syncing. */
+  shared: string[];
+  /** On the hub, absent here. The project has them; this machine cannot get them. */
+  hubOnly: RemoteDoc[];
+  /** Here, not on the hub yet — normal for a canvas this peer just created. */
+  localOnly: string[];
+  /** Null when the hub could not be asked (old hub, offline, refused). */
+  reachable: boolean;
+}
+
+/** How long to wait for the listing. Never blocks a sync — see `fetchRemoteDocs`. */
+const LIST_TIMEOUT_MS = 6000;
+
+/**
+ * Ask the hub which documents this token may open.
+ *
+ * Returns null on ANY failure — an old hub without the route, a refused token,
+ * a network blip. A peer that cannot get the listing must still sync: this is a
+ * reporting improvement, and making it load-bearing would trade a real feature
+ * for a nicer message.
+ */
+export async function fetchRemoteDocs(
+  hubUrl: string,
+  token: string,
+  fetchImpl: typeof fetch = fetch
+): Promise<RemoteDoc[] | null> {
+  try {
+    const base = hubUrl.replace(/\/+$/, '');
+    const res = await fetchImpl(`${base}/api/documents`, {
+      headers: { authorization: `Bearer ${token}` },
+      signal: AbortSignal.timeout(LIST_TIMEOUT_MS),
+    });
+    if (!res.ok) return null;
+    const body = (await res.json()) as { documents?: unknown };
+    if (!Array.isArray(body?.documents)) return null;
+    return 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 }));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Diff the hub's documents against the ones this peer syncs.
+ *
+ * `localDocNames` must already be in WIRE form (`docNameFor(slug)`), not raw
+ * slugs — comparing a namespaced hub against flat local names would report
+ * every document as missing on both sides, which is the exact failure the
+ * namespace exists to prevent, arrived at from the reporting side.
+ */
+export function diffRemoteDocs(
+  localDocNames: readonly string[],
+  remote: RemoteDoc[] | null
+): RemoteDocDiff {
+  if (remote === null) {
+    return { shared: [], hubOnly: [], localOnly: [...localDocNames], reachable: false };
+  }
+  const local = new Set(localDocNames);
+  const remoteNames = new Set(remote.map((d) => d.name));
+  return {
+    shared: [...local].filter((n) => remoteNames.has(n)).sort(),
+    hubOnly: remote.filter((d) => !local.has(d.name)).sort((a, b) => a.name.localeCompare(b.name)),
+    localOnly: [...local].filter((n) => !remoteNames.has(n)).sort(),
+    reachable: true,
+  };
+}
+
+/**
+ * One line a person can act on.
+ *
+ * Deliberately names the documents being PULLED rather than only what already
+ * matched: "72 synced" was true and useless, because the number is drawn from
+ * the local file set and can never express what the project holds beyond it.
+ */
+export function describeRemoteDiff(diff: RemoteDocDiff): string | null {
+  if (!diff.reachable) return null;
+  if (diff.hubOnly.length === 0) return null;
+  const n = diff.hubOnly.length;
+  const names = diff.hubOnly
+    .slice(0, 3)
+    .map((d) => d.name)
+    .join(', ');
+  return `pulling ${n} canvas${n === 1 ? '' : 'es'} down from the project (${names}${n > 3 ? ', …' : ''}).`;
+}
+
+/**
+ * The local slug a hub document name maps to.
+ *
+ * Namespaced names (`ws/<workspace>/<branch>/<slug>` — DDR-192 §5) carry the
+ * slug in the last segment; a legacy flat name IS the slug. Returns null for
+ * anything that does not survive the charset the hub itself enforces on
+ * `documentName`, so a crafted name cannot become a path component.
+ */
+export function slugFromDocName(docName: string): string | null {
+  const raw = String(docName ?? '');
+  // Validate the WHOLE name against the two shapes a hub may legitimately use,
+  // never just its last segment. Taking the tail of an arbitrary string would
+  // accept `../../etc/passwd` as `passwd`: contained by the check below, and
+  // still a file this project never asked for, created from a name that should
+  // have been refused outright. A component is `[A-Za-z0-9_-]` — no dots (so no
+  // traversal and no extension smuggling), no spaces.
+  const COMPONENT = '[A-Za-z0-9_-]{1,120}';
+  const FLAT = new RegExp(`^${COMPONENT}$`);
+  const NAMESPACED = new RegExp(`^ws/${COMPONENT}/${COMPONENT}/(${COMPONENT})$`);
+  if (FLAT.test(raw)) return raw.toLowerCase();
+  const ns = NAMESPACED.exec(raw);
+  return ns ? ns[1].toLowerCase() : null;
+}
+
+export interface PullTarget {
+  slug: string;
+  docName: string;
+  /** Absolute path the body will be written to, flat under the design root. */
+  bodyAbs: string;
+}
+
+/**
+ * Where a hub-only document lands on disk.
+ *
+ * FLAT, directly under the design root — the same convention the hub applies in
+ * the mirror direction (`workspace-files.mjs defaultBodyPath`) and for the same
+ * reason: a slug is lossy, `ui-card` cannot be un-flattened into `ui/Card.tsx`
+ * without guessing, and guessing wrong scatters files into directories the user
+ * never made. A flat file is trivially moved; an invented tree is not. Moving it
+ * later does not break sync — both paths slug to the same document.
+ *
+ * Returns only targets that resolve INSIDE the design root. A document name is
+ * hub-controlled input, and this is the last point before a create.
+ */
+export function pullTargets(
+  hubOnly: readonly RemoteDoc[],
+  designRoot: string,
+  join: (...parts: string[]) => string,
+  resolve: (p: string) => string,
+  sep: string
+): PullTarget[] {
+  const rootResolved = resolve(designRoot);
+  const out: PullTarget[] = [];
+  // One slug, one target. `slugFromDocName` lowercases, so a hub advertising
+  // `Foo`, `foo` and `ws/w/main/foo` yields three targets for ONE file — three
+  // providers on the same path, and a `pulled` count that overstates what
+  // arrived by a factor the hub chooses.
+  const seen = new Set<string>();
+  for (const doc of hubOnly) {
+    const slug = slugFromDocName(doc.name);
+    if (!slug || seen.has(slug)) continue;
+    seen.add(slug);
+    const bodyAbs = join(designRoot, `${slug}.tsx`);
+    const target = resolve(bodyAbs);
+    if (target !== rootResolved && !target.startsWith(rootResolved + sep)) continue;
+    out.push({ slug, docName: doc.name, bodyAbs });
+  }
+  return out;
+}

package/apps/studio/sync/status.ts

@@ -79,7 +79,10 @@ export function createSyncStatusStore(opts: SyncStatusStoreOptions): SyncStatusS
   const conflicts: SyncConflict[] = [];
 
   let snapshot: SyncStatusSnapshot = {
-    state: 'online',
+    // Same reason the monitor is seeded `connecting` (see connection-state.ts):
+    // this is the payload a reader gets BEFORE the first monitor snapshot lands,
+    // so seeding it `online` re-introduced the born-connected lie one layer out.
+    state: 'connecting',
     queuedOps: 0,
     lastSyncAt: null,
     offlineSince: null,