@1agh/maude 0.55.0 → 0.57.0

package/apps/studio/input-router.tsx

@@ -407,6 +407,45 @@ export function isOverlayTarget(t: EventTarget | null): boolean {
   );
 }
 
+/**
+ * Artboard "chrome" — inside an artboard (`[data-dc-screen]`) but OUTSIDE its
+ * `.dc-artboard-body` content box, i.e. the label strip + border that
+ * `use-artboard-drag.tsx` binds its own bubble-phase `onPointerDown` to
+ * (`bindHandle()`, spread directly on the `.dc-artboard` article). The router
+ * runs in the CAPTURE phase ahead of that handler; claiming a bare press here
+ * — same as any other chrome hit, the router still selects the artboard —
+ * used to `stopImmediatePropagation` the native event before it ever reached
+ * the drag hook's listener, so no artboard could be repositioned by its
+ * header at all (issue-71). A modifier-held press is not exempted: the drag
+ * hook itself ignores Cmd/Ctrl (reserved for deep-select), so nothing
+ * downstream needs the raw event in that case.
+ */
+export function isArtboardDragChrome(t: EventTarget | null): boolean {
+  if (!t || typeof (t as Element).closest !== 'function') return false;
+  const el = t as Element;
+  return !!el.closest('[data-dc-screen]') && !el.closest('.dc-artboard-body');
+}
+
+/**
+ * Should the router's pointerdown/mousedown handler skip
+ * `stopImmediatePropagation` so the event still reaches use-artboard-drag.tsx?
+ * Pulled out of the two near-identical handlers below so the decision itself
+ * — not just `isArtboardDragChrome`'s target test — is covered by a DOM-free
+ * unit test (issue-71).
+ */
+export function yieldsToArtboardDrag(
+  action: RouterAction,
+  target: EventTarget | null,
+  modifiers: { metaKey: boolean; ctrlKey: boolean }
+): boolean {
+  return (
+    action.kind === 'select' &&
+    !modifiers.metaKey &&
+    !modifiers.ctrlKey &&
+    isArtboardDragChrome(target)
+  );
+}
+
 export function useInputRouter(opts: UseInputRouterOptions): void {
   const { hostRef, getActiveTool, isSpaceHeld, callbacks, enabled = true, claimableActions } = opts;
 
@@ -496,13 +535,22 @@ export function useInputRouter(opts: UseInputRouterOptions): void {
           activeTool: getActiveTool(),
         })
       );
+      // issue-71 — a bare press on an artboard's own drag chrome must still
+      // reach that artboard's `onPointerDown` (use-artboard-drag.tsx) so its
+      // pending→dragging state machine can arm, or no artboard can ever be
+      // repositioned by its header. The router still SELECTS (dispatch below
+      // is unconditional) and still preventDefaults the browser's native
+      // click-drag text-selection — it only skips stopImmediatePropagation,
+      // which is the one call that would keep the event from ever reaching
+      // the bubble-phase listener bound to the very element it targeted.
+      const yields = yieldsToArtboardDrag(action, e.target, e);
       if (action.kind !== 'no-op') {
         // Suppress native behavior on every event the router claims —
         // button presses don't fire, inputs don't focus, the canvas
         // content's own click handlers don't run. The router lives in
         // capture phase so this fires before descendants.
         e.preventDefault();
-        e.stopImmediatePropagation();
+        if (!yields) e.stopImmediatePropagation();
       }
       dispatch(action);
     };
@@ -531,9 +579,14 @@ export function useInputRouter(opts: UseInputRouterOptions): void {
           activeTool: getActiveTool(),
         })
       );
+      // issue-71 — same exemption as onPointerDown above: preventDefault still
+      // runs (blocks the native click-drag text-selection an un-prevented
+      // mousedown would start), but stopImmediatePropagation is skipped so the
+      // paired pointerdown reaching use-artboard-drag.tsx isn't undone here.
+      const yields = yieldsToArtboardDrag(action, e.target, e);
       if (action.kind !== 'no-op') {
         e.preventDefault();
-        e.stopImmediatePropagation();
+        if (!yields) e.stopImmediatePropagation();
         // preventDefault above stops mousedown's default FOCUS, so a Cmd-click
         // select would leave the iframe unfocused and every in-canvas keyboard
         // shortcut (arrow-nudge, Cmd+D, copy/paste-style, Delete) dead until a

package/apps/studio/server.ts

@@ -34,7 +34,7 @@ import { createHttp } from './http.ts';
 import { createInspectRegistry } from './inspect.ts';
 import { startHeapWatch } from './mem.ts';
 import { normalizeSessionKey, runInSession, SESSION_HEADER } from './session-scope.ts';
-import { createSyncRuntime } from './sync/index.ts';
+import { createSyncSupervisor } from './sync/supervisor.ts';
 import {
   assertContainment,
   isForbiddenRoute,
@@ -680,13 +680,15 @@ ctx.bus.on('fs:json', (rel: string) => {
 // Phase 9 Task 4 — bidirectional sync agent. No-op when the project isn't
 // linked to a hub (`.design/config.json` has no `linkedHub` field). Kicked
 // off after fsWatch so the agent's bus subscription receives every fs event.
-const syncRuntime = createSyncRuntime(ctx, collab ? { registry: collab.registry } : {});
-if (syncRuntime) {
-  try {
-    await syncRuntime.start();
-  } catch (err) {
-    console.error('[sync] startup failed — continuing in solo mode:', err);
-  }
+// Owned by a supervisor rather than started inline: linking a project from the
+// cloud panel cycles the runtime in place (ctx.syncControl), so pressing
+// Connect starts syncing instead of printing "restart the studio server".
+const syncRuntime = createSyncSupervisor(ctx, collab ? { registry: collab.registry } : {});
+ctx.syncControl = syncRuntime;
+try {
+  await syncRuntime.start();
+} catch (err) {
+  console.error('[sync] startup failed — continuing in solo mode:', err);
 }
 
 const url = `http://localhost:${server.port}`;
@@ -733,6 +735,17 @@ async function shutdown() {
   // previously-unanswered "how does app-quit reach the grandchild" question.
   cancelSignin();
   cancelInstall();
+  // Addendum Task 8 — bridges now outlive their WebSocket, so socket-close is
+  // no longer the reaper it used to be. App quit / dev-server shutdown is the
+  // ONE lifetime boundary the detached model deliberately does NOT survive
+  // (DDR-166's SIGTERM-first path): extending a session across a project or
+  // branch *switch* is the point; extending it across a quit is not, and a
+  // surviving `claude` subprocess after quit would be an orphan.
+  try {
+    acp.stopAll();
+  } catch {
+    /* best-effort — the process is exiting either way */
+  }
   fsWatch.stop();
   try {
     gitWatch.stop();
@@ -750,7 +763,7 @@ async function shutdown() {
     /* timer cleanup is best-effort */
   }
   try {
-    if (syncRuntime) await syncRuntime.stop();
+    await syncRuntime.stop();
   } catch {
     /* best-effort — provider sockets will be closed by process exit anyway */
   }

package/apps/studio/sync/autocommit.ts

@@ -32,6 +32,16 @@ import { withRepoLock } from '../git/repo-lock.ts';
 /** How long the tree must be quiet before a commit fires. */
 const DEFAULT_DEBOUNCE_MS = 3000;
 
+/**
+ * The ceiling on that quiescence — how long a PENDING batch may be deferred by
+ * a continuing stream of notes before it commits anyway. Without it, quiescence
+ * batching has no upper bound and a steady note cadence defers history forever
+ * (see `note`). Generous enough that ordinary typing still coalesces into one
+ * commit, small enough that a cell's ephemeral disk is never far ahead of its
+ * history.
+ */
+const DEFAULT_MAX_DEBOUNCE_MS = 15_000;
+
 export interface GitRunResult {
   code: number;
   stdout: string;
@@ -53,6 +63,12 @@ export interface AutoCommitOptions {
   run: GitRunner;
   /** Quiescence window. */
   debounceMs?: number;
+  /**
+   * Ceiling on that quiescence: a pending batch commits after at most this long
+   * from its first note, however many notes keep arriving. Bounds the
+   * "steady stream defers history forever" case — see `note`.
+   */
+  maxDebounceMs?: number;
   /** Committer identity — the machine, never the human. */
   bot?: EditAttribution;
   log?: Pick<Console, 'warn' | 'error' | 'log'>;
@@ -154,6 +170,7 @@ export function createAutoCommit(opts: AutoCommitOptions): AutoCommit {
     repoRoot,
     run,
     debounceMs = DEFAULT_DEBOUNCE_MS,
+    maxDebounceMs = DEFAULT_MAX_DEBOUNCE_MS,
     bot = DEFAULT_BOT,
     log = console,
   } = opts;
@@ -163,9 +180,13 @@ export function createAutoCommit(opts: AutoCommitOptions): AutoCommit {
   let timer: ReturnType<typeof setTimeout> | null = null;
   let inFlight: Promise<CommitOutcome | null> | null = null;
   let stopped = false;
+  /** When the currently-pending batch received its first note (see `note`). */
+  let batchStartedAt = 0;
 
   function note(relPath: string, who?: EditAttribution | null): void {
     if (stopped) return;
+    // Start of a batch — the clock the ceiling below is measured against.
+    if (touched.size === 0) batchStartedAt = Date.now();
     touched.add(relPath);
     // Last writer wins for attribution. A commit that coalesced two people's
     // edits can only name one author; the message body names them, and the
@@ -173,6 +194,23 @@ export function createAutoCommit(opts: AutoCommitOptions): AutoCommit {
     // that keeps this history readable.
     if (who) author = who;
     if (timer) clearTimeout(timer);
+    // QUIESCENCE, BUT WITH A CEILING. Resetting the timer on every note is what
+    // makes a typing session one commit instead of four hundred — and, alone,
+    // it means a steady stream of notes defers the commit forever. That is not
+    // hypothetical here: the hub notes on every stored document, Hocuspocus
+    // stores on its own ~2 s debounce, and anyone who can drive doc updates at
+    // a cadence under `debounceMs` — including a VIEWER, who deliberately holds
+    // the `comment` capability — can hold a project's history open indefinitely
+    // while `/health` stays green. Before the commit set stopped being "files
+    // we just wrote", a no-write store event returned before reaching here, so
+    // the reachable cadence was bounded by real edits.
+    //
+    // So: still coalesce, but never defer a pending batch past `maxDebounceMs`
+    // from its first note. Worst-case commit latency becomes bounded and small,
+    // and the batching behaviour for ordinary typing is unchanged (a human
+    // pauses long before the ceiling).
+    const sinceBatchStart = Date.now() - batchStartedAt;
+    const delay = Math.max(0, Math.min(debounceMs, maxDebounceMs - sinceBatchStart));
     timer = setTimeout(() => {
       timer = null;
       // `.catch` and not just `void`: a discarded rejection here is an
@@ -180,7 +218,7 @@ export function createAutoCommit(opts: AutoCommitOptions): AutoCommit {
       flush().catch((err) => {
         log.warn?.(`[autocommit] flush failed: ${err instanceof Error ? err.message : err}`);
       });
-    }, debounceMs);
+    }, delay);
   }
 
   async function flush(): Promise<CommitOutcome | null> {
@@ -242,12 +280,33 @@ export function createAutoCommit(opts: AutoCommitOptions): AutoCommit {
     const add = await run(['add', '--', ...files], { cwd: repoRoot });
     if (add.code !== 0) {
       log.warn?.(`[autocommit] git add failed: ${add.stderr.trim()}`);
+      // RE-QUEUE, exactly as the `commit` branch below does. `touched` was
+      // cleared by `flush()` before we got here, so returning without this
+      // drops the whole coalesced batch — including other people's edits in
+      // the same window — from history, permanently and silently.
+      // One bad pathspec is enough: `git add -- <path that vanished>` exits
+      // 128, and paths are now noted on the strength of a read taken up to
+      // `debounceMs` earlier, for files whose lifetime this process does not
+      // own (a canvas deleted inside the quiescence window).
+      for (const f of files) touched.add(f);
       return { ok: false, reason: 'git-failed', detail: add.stderr.trim(), files };
     }
 
     // Nothing staged ⇒ the write was a no-op (an echo, or identical bytes).
     // Not an error, and committing an empty change would be noise.
-    const staged = await run(['diff', '--cached', '--name-only'], { cwd: repoRoot });
+    //
+    // SCOPED TO `files`, and that pathspec is load-bearing. The question is
+    // "did OUR paths stage anything", and an unrelated entry sitting in the
+    // index answers it wrongly — the probe says yes, then `commit --only --
+    // <our unchanged paths>` exits non-zero with "no changes added to commit".
+    // `touched` re-queues but nothing re-arms the timer, so the agent wedges
+    // and fails identically forever while `/health` keeps answering 200.
+    // Reachable since the commit set stopped being "files we just wrote": a
+    // batch of exclusively-unchanged paths is now routine under cell pairing,
+    // where the studio child's projector writes the bytes first.
+    const staged = await run(['diff', '--cached', '--name-only', '--', ...files], {
+      cwd: repoRoot,
+    });
     if (staged.code === 0 && staged.stdout.trim() === '') {
       return { ok: false, reason: 'nothing-to-commit', files };
     }

package/apps/studio/sync/cell-pairing.ts

@@ -0,0 +1,174 @@
+// Desktop ↔ cloud live pairing, variant C2 — the ONE exception to "a cell does
+// not sync" (DDR-209 / Cloud Phase 27 D2).
+//
+// THE PROBLEM THIS OPENS A DOOR FOR. A cell holds two disjoint Y.Doc worlds: the
+// hub's Hocuspocus documents (which the DESKTOP syncs to, SQLite-backed) and the
+// studio child's own collab rooms (which BROWSERS join, in-memory). Nothing
+// crosses. Two people on the same project — one in the app, one in a tab — never
+// see each other's cursors and never see each other's edits, which is the
+// headline of the cloud product.
+//
+// WHY THE DOOR IS SHAPED LIKE THIS. DDR-209 forbids the studio child from
+// syncing out, for two named reasons, and BOTH are preserved literally here
+// rather than argued away:
+//
+//   1. "dial OUT from the cell to a third-party hub carrying the project's
+//      canvases" — so the URL must be LOOPBACK. Not "usually loopback", not
+//      "loopback in production": the resolver refuses anything else, and the
+//      tenant's own `.design/config.json linkedHub.url` is never read for it.
+//      A cell talking to 127.0.0.1 is a process talking to itself.
+//   2. "start a SECOND autocommit over the working tree the hub is already
+//      committing" — so autocommit must be explicitly DISABLED, by a flag the
+//      caller has to set on purpose. Default-absent means refuse.
+//
+// A third condition is ours, not DDR-209's, and it narrows further: shared-doc
+// must be ON. Without it the loopback provider would open a SECOND Y.Doc per
+// canvas beside the room's — the two-doc world this pairing exists to collapse —
+// and its agent would become a second doc→file writer for no benefit at all.
+//
+// WHAT IS TAKEN FROM THE TENANT'S CONFIG, AND WHY IT MUST BE. The URL and the
+// credential come from the environment (the hub minted them for its own child).
+// The WORKSPACE ID does not: it comes from `linkedHub.workspaceId`, the tenant's
+// own file, because it decides the DOCUMENT NAME on the wire (DDR-192 §5). The
+// desktop resolves it from that same field. If the cell derived a different one,
+// the browser and the desktop would sync to two differently-named documents and
+// converge on nothing — this whole feature, silently doing exactly what it did
+// before. Honouring the tenant's `url` is a dial-out; honouring their
+// `workspaceId` is the only way the two ends can meet.
+
+import { isLoopbackHost } from './loopback.ts';
+
+/** Everything the runtime needs to open the loopback provider. */
+export interface CellPairing {
+  /** Always a loopback http(s) URL — asserted, never assumed. */
+  url: string;
+  /** The hub-minted, cell-derived credential. Never a user's own token. */
+  token: string;
+}
+
+/** Why pairing is off, when the operator asked for it and it did not engage. */
+export type CellPairingRefusal =
+  | 'not-workspace-mode'
+  | 'not-requested'
+  | 'no-url'
+  | 'not-loopback'
+  | 'no-token'
+  | 'autocommit-enabled'
+  | 'shared-doc-off';
+
+export interface CellPairingVerdict {
+  pairing: CellPairing | null;
+  /** Present whenever `pairing` is null. */
+  refusal?: CellPairingRefusal;
+  /** One sentence for the log — populated only when the operator ASKED for
+   *  pairing and we refused, so a silent misconfiguration is impossible. */
+  detail?: string;
+}
+
+/** Env truthiness, matching `server.ts`'s MAUDE_SHARED_DOC parsing exactly. */
+function on(value: string | undefined): boolean {
+  return /^(1|true|on|yes)$/i.test(value ?? '');
+}
+
+/**
+ * Strip control characters and cap length before a value reaches a log line.
+ *
+ * Every refusal `detail` this module builds interpolates `MAUDE_LOOPBACK_SYNC_URL`
+ * verbatim, and today that env var is hub-set only — no tenant-reachable input
+ * writes it. But this feature's entire threat model rests on "the URL is
+ * provably loopback," so the log line proving that should not be the one place
+ * that still trusts the string unsanitized. Mirrors the codebase's own
+ * precedent (`sanitizeForLog` in `apps/hub/src/server.mjs`) rather than
+ * inventing a second scrub shape.
+ */
+export function sanitizeForLog(value: string): string {
+  let out = '';
+  const s = value.slice(0, 256);
+  for (let i = 0; i < s.length; i++) {
+    const code = s.charCodeAt(i);
+    out += code < 0x20 || code === 0x7f ? '·' : s[i];
+  }
+  return out;
+}
+
+/**
+ * Resolve the cell pairing from the environment, or explain the refusal.
+ *
+ * Every condition is a hard gate. There is no "warn and continue" branch on
+ * purpose: the failure mode of a partial pairing (a provider that dials out, or
+ * a second committer) is worse than no pairing at all, and no pairing is exactly
+ * what shipped before this feature.
+ */
+export function resolveCellPairing(
+  env: Record<string, string | undefined> = process.env
+): CellPairingVerdict {
+  if (env.MAUDE_WORKSPACE_MODE !== '1') {
+    return { pairing: null, refusal: 'not-workspace-mode' };
+  }
+  if (!on(env.MAUDE_CELL_PAIRING)) {
+    return { pairing: null, refusal: 'not-requested' };
+  }
+
+  // From here on the operator ASKED for pairing, so every refusal gets a
+  // sentence — a cell that quietly declines is the bug this feature is fixing.
+  const url = (env.MAUDE_LOOPBACK_SYNC_URL ?? '').trim();
+  if (!url) {
+    return {
+      pairing: null,
+      refusal: 'no-url',
+      detail: 'MAUDE_CELL_PAIRING is set but MAUDE_LOOPBACK_SYNC_URL is empty.',
+    };
+  }
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return {
+      pairing: null,
+      refusal: 'not-loopback',
+      detail: `MAUDE_LOOPBACK_SYNC_URL is not a URL: ${sanitizeForLog(url)}`,
+    };
+  }
+  if (!isLoopbackHost(parsed.hostname)) {
+    return {
+      pairing: null,
+      refusal: 'not-loopback',
+      detail:
+        `refusing MAUDE_LOOPBACK_SYNC_URL ${sanitizeForLog(url)} — a cell syncs to ITSELF or to nothing. ` +
+        'Only 127.0.0.1 / localhost / ::1 are accepted (DDR-209: no dial-out).',
+    };
+  }
+
+  const token = (env.MAUDE_LOOPBACK_SYNC_TOKEN ?? '').trim();
+  if (!token) {
+    return {
+      pairing: null,
+      refusal: 'no-token',
+      detail: 'MAUDE_CELL_PAIRING is set but MAUDE_LOOPBACK_SYNC_TOKEN is empty.',
+    };
+  }
+
+  if (!on(env.MAUDE_SYNC_NO_AUTOCOMMIT)) {
+    return {
+      pairing: null,
+      refusal: 'autocommit-enabled',
+      detail:
+        'refusing to pair without MAUDE_SYNC_NO_AUTOCOMMIT=1 — the hub is the sole committer ' +
+        'in a cell, and a second autocommit over the same working tree is the exact ' +
+        'duplication DDR-209 exists to prevent.',
+    };
+  }
+
+  if (!on(env.MAUDE_SHARED_DOC)) {
+    return {
+      pairing: null,
+      refusal: 'shared-doc-off',
+      detail:
+        'refusing to pair without MAUDE_SHARED_DOC=1 — pairing IS the single-shared-doc ' +
+        'model (DDR-064). Without it the loopback provider would open a second Y.Doc per ' +
+        'canvas beside the browser room, which is the two-doc world pairing exists to end.',
+    };
+  }
+
+  return { pairing: { url, token } };
+}

package/apps/studio/sync/codec.ts

@@ -26,6 +26,13 @@ import { hostname } from 'node:os';
 import type * as Y from 'yjs';
 
 import { Y_TYPES } from '../collab/persistence.ts';
+import {
+  MAX_ANNOTATIONS_BYTES,
+  MAX_COMMENTS_BYTES,
+  MAX_CSS_BYTES,
+  MAX_HTML_BYTES,
+  MAX_META_BYTES,
+} from './limits.ts';
 
 /**
  * Y.Doc shared-type names introduced by Task 4. Distinct namespace from
@@ -59,12 +66,11 @@ export const Y_SYNC_TYPES = {
  * has no upstream-enforced size cap; the codec is the consumer's guard.
  * Mirrors the existing /_api/annotations 1 MB cap (api.ts) so the sync path
  * doesn't bypass the HTTP-layer guard.
+ *
+ * Defined in `limits.ts` (a leaf) and re-exported here so every existing
+ * importer is unchanged — see that file for why they had to move.
  */
-export const MAX_HTML_BYTES = 4 * 1024 * 1024;
-export const MAX_COMMENTS_BYTES = 1 * 1024 * 1024;
-export const MAX_ANNOTATIONS_BYTES = 1 * 1024 * 1024;
-export const MAX_META_BYTES = 1 * 1024 * 1024;
-export const MAX_CSS_BYTES = 4 * 1024 * 1024;
+export { MAX_ANNOTATIONS_BYTES, MAX_COMMENTS_BYTES, MAX_CSS_BYTES, MAX_HTML_BYTES, MAX_META_BYTES };
 
 function byteLengthUtf8(s: string): number {
   return Buffer.byteLength(s, 'utf8');

package/apps/studio/sync/connection-state.ts

@@ -47,6 +47,22 @@ export interface SyncStatusSnapshot {
   /** DDR-102 — slugs currently auth-rejected, capped at 20 (see docs.rejected
    *  for the true count). Treat as text, never HTML. */
   rejectedSlugs?: string[];
+  /**
+   * Canvases this run brought DOWN from the project — documents that existed
+   * only on the hub and are now real local files.
+   *
+   * This field was briefly `remoteGap`, "what the project has that this machine
+   * does not". That name stopped being true the moment the pull landed: the
+   * diff is computed before providers are built and recorded after, so it
+   * enumerated exactly the documents that had just arrived. Observed live —
+   * `_sync.json` naming two canvases that were sitting on disk.
+   *
+   * "What arrived this run" is both true and the more useful fact: it is what
+   * the Synced state tells the user to go and open. Absent when the hub could
+   * not be asked (old hub, offline) or when nothing was pulled. Names are
+   * hub-controlled — treat as text, never HTML, and see the cap in `notePulled`.
+   */
+  pulled?: { names: string[]; count: number };
 }
 
 type TimerHandle = ReturnType<typeof setTimeout>;
@@ -75,6 +91,8 @@ export interface ConnectionMonitor {
   /** DDR-102 — real sync activity for a slug (reconcile done, hub-pushed flush
    *  applied): bumps `lastSyncAt` to now. */
   noteSyncActivity(slug: string): void;
+  /** Record the canvases this run pulled down from the project (see `pulled`). */
+  notePulled(slugs: readonly string[]): void;
   /** Current snapshot (defensive copy). */
   snapshot(): SyncStatusSnapshot;
   /** Tear down timers. */
@@ -100,7 +118,14 @@ export function createConnectionMonitor(opts: ConnectionMonitorOptions = {}): Co
   // DDR-102 — per-doc states (pending/connected/auth-rejected).
   const docStates = new Map<string, DocSyncState>();
 
-  let state: SyncState = 'online';
+  // NOT born connected. The monitor used to start `online`, so from the instant
+  // a link was created — before a socket, before a token was accepted, before a
+  // byte moved — every surface reading `state` reported success. On a healthy
+  // fast connect that was harmless (the truth arrived milliseconds later); on a
+  // refused or unreachable one it was the whole bug: the user was shown the
+  // intention and read it as the result. `connecting` is the honest seed, and
+  // it is the state a link genuinely occupies until a provider says otherwise.
+  let state: SyncState = 'connecting';
   let queuedOps = 0;
   let lastSyncAt: number | null = null;
   let offlineSince: number | null = null;
@@ -111,6 +136,25 @@ export function createConnectionMonitor(opts: ConnectionMonitorOptions = {}): Co
   let flashTimer: TimerHandle | null = null;
   let stopped = false;
 
+  /** Canvases pulled down from the project this run. */
+  let pulled: SyncStatusSnapshot['pulled'];
+
+  /**
+   * Start the clock at construction, not at the first provider event.
+   *
+   * `enterGrace` is reachable ONLY from `noteProviderStatus`, so a link where
+   * no provider ever reports — every provider rejected during boot, a hub that
+   * never completes an upgrade — would have sat in `connecting` forever and
+   * never reached the offline banner. Seeding `state` honestly is not enough on
+   * its own; something has to be counting from the moment the link exists.
+   */
+  function armInitialGrace(): void {
+    graceTimer = setTimer(() => {
+      graceTimer = null;
+      goOffline();
+    }, graceMs);
+  }
+
   function snapshot(): SyncStatusSnapshot {
     const docs = { synced: 0, pending: 0, rejected: 0 };
     const rejectedSlugs: string[] = [];
@@ -130,9 +174,31 @@ export function createConnectionMonitor(opts: ConnectionMonitorOptions = {}): Co
       updatedAt: now(),
       docs,
       rejectedSlugs,
+      ...(pulled ? { pulled } : {}),
     };
   }
 
+  /**
+   * Record the canvases this run pulled down from the project.
+   *
+   * `names` is capped like `rejectedSlugs` — this reaches a UI and a JSON file,
+   * and an unbounded list of hub-chosen names is a hub-controlled payload size.
+   * `count` keeps the true total, so the cap never falsifies the number the
+   * user is shown. An empty list clears the field rather than recording a zero:
+   * a run that pulled nothing has nothing to say.
+   */
+  function notePulled(slugs: readonly string[]): void {
+    // Every other mutator carries this guard; without it a late call could
+    // write `_sync.json` and broadcast for a monitor that has been torn down.
+    // Unreachable today (the sole caller checks `stopped` too) — kept so the
+    // invariant does not depend on the caller remembering it.
+    if (stopped) return;
+    pulled = slugs.length
+      ? { names: slugs.slice(0, MAX_REJECTED_SLUGS), count: slugs.length }
+      : undefined;
+    emit();
+  }
+
   function emit(): void {
     onChange?.(snapshot());
   }
@@ -181,15 +247,20 @@ export function createConnectionMonitor(opts: ConnectionMonitorOptions = {}): Co
   }
 
   function enterGrace(): void {
-    // Already counting down or already offline — don't restart the clock.
-    if (state !== 'online') return;
+    // Already offline — stay there until a provider reports 'connected'.
+    if (state === 'offline' || state === 'offline-long') return;
+    // Already counting down — don't restart the clock. The guard used to be
+    // `state !== 'online'`; the timer, not the state, is what says whether a
+    // countdown is running, and with the `connecting` seed those are no longer
+    // the same question.
+    if (graceTimer !== null) return;
     state = 'connecting';
-    if (graceTimer !== null) clearTimer(graceTimer);
     graceTimer = setTimer(() => {
       graceTimer = null;
       goOffline();
     }, graceMs);
-    emit();
+    // No emit here — the sole caller emits once for the whole update, so a
+    // demotion that does not change `state` still reaches the readers.
   }
 
   function goOffline(): void {
@@ -204,19 +275,56 @@ export function createConnectionMonitor(opts: ConnectionMonitorOptions = {}): Co
     emit();
   }
 
+  armInitialGrace();
+
   return {
     noteProviderStatus(providerId, status) {
       if (stopped) return;
+
+      // EMIT ONLY ON A REAL CHANGE.
+      //
+      // Every emit is a synchronous `_sync.json` write plus a WS broadcast to
+      // every open tab. Provider status is driven by the socket lifecycle,
+      // which the hub controls, and there is one provider per canvas — 75+ in
+      // the reported project. An unconditional emit here turns a flapping (or
+      // deliberately hostile) hub into a sustained disk-write and fan-out loop
+      // on the dev-server's main thread. The pre-existing code emitted only on
+      // a transition; adding the demotion below must not cost that property.
+      const prevStatus = providerStatuses.get(providerId);
       providerStatuses.set(providerId, status);
+      let changed = prevStatus !== status;
+
+      // A document whose socket is gone is not a synced document.
+      //
+      // `docs.synced` used to only ever RISE — nothing demoted a `connected`
+      // doc, so a hub that died left the last count frozen on screen, which is
+      // the most convincing form of the lie: it was true a moment ago. The
+      // provider id IS the slug (`index.ts` passes `canvas.slug`), so the
+      // monitor already knows which document just lost its socket.
+      //
+      // `auth-rejected` is deliberately NOT demoted. The hub gave an answer;
+      // losing the socket afterwards does not turn that answer back into
+      // "still trying", and letting it would hide a rotated credential behind
+      // a spinner.
+      if (status !== 'connected' && docStates.get(providerId) === 'connected') {
+        docStates.set(providerId, 'pending');
+        changed = true;
+      }
+
       const agg = aggregate();
       if (agg === 'connected') {
+        // goOnline() emits for the transition; otherwise only a real change
+        // (this provider's status moved, or a document was demoted) is news.
         if (state !== 'online') goOnline();
+        else if (changed) emit();
         return;
       }
       // Aggregate is connecting or disconnected → start (or continue) the
       // grace countdown. Once offline/offline-long we stay there until a
       // provider reports 'connected' again.
-      if (state === 'online') enterGrace();
+      const before = state;
+      enterGrace();
+      if (changed || state !== before) emit();
     },
 
     noteLocalEdit() {
@@ -245,6 +353,8 @@ export function createConnectionMonitor(opts: ConnectionMonitorOptions = {}): Co
       emit();
     },
 
+    notePulled,
+
     snapshot,
 
     stop() {