@1agh/maude 0.58.3 → 0.59.0

package/apps/studio/sync/asset-push.ts

@@ -1,32 +1,67 @@
-// Desktop→cell asset push — DDR-217 (fix 6 of the 2026-08-10 sync RCA).
+// Desktop→cell asset push — DDR-217 + the 2026-08-11 addendum (fix 6 of the
+// 2026-08-10 sync RCA, completed).
 //
 // The sync lanes are text-only (`html`/`css`/`meta`/`syncMeta`), so a
-// desktop-linked project's `<designRoot>/assets/*` never reached the cell: its
-// `/assets/` proxy and its studio child both served bytes they did not have —
-// the grey boxes. The desktop is the one peer that HAS the bytes and already
-// holds an authenticated channel to the hub, so it pushes them over the asset
-// route: `HEAD /assets/<key>` to skip what the cloud already holds, then a
-// streamed `PUT /assets/<key>` for the rest. The hub writes into its checkout
-// and mirrors to the bucket (the browser-upload precedent) — see
-// `apps/hub/src/assets.mjs`.
+// desktop-linked project's binary assets never reached the cell — the grey
+// boxes. The desktop is the one peer that HAS the bytes and already holds an
+// authenticated channel to the hub, so it pushes them. There are TWO asset
+// classes, served two different ways, so they push to two different routes:
 //
-// The key-shape rules here MIRROR the hub's `ASSET_KEY` (assets.mjs) — a file
-// this pushes but the hub refuses is a wasted upload, and one this skips but
-// the proxy would serve is a broken image. The HUB's validation stays the
-// authoritative gate (each trust boundary validates its own input); this list
-// is the courtesy filter that keeps junk off the wire.
+//   1. TOP-LEVEL content-addressed uploads (`<designRoot>/assets/<sha8>.<ext>`)
+//      — referenced by the `/assets/<key>` shortcut, served on the cloud from
+//      the BUCKET proxy. Push → `PUT /assets/<key>` (bucket + checkout mirror).
+//   2. DS / BRAND assets (`<designRoot>/system/<ds>/assets/logos/x.svg`, fonts,
+//      photos) — referenced by their FULL designRoot path
+//      (`/.design/system/<ds>/assets/…`) and served from the CHECKOUT by the
+//      studio child, never the bucket. The original fix only swept class 1, so
+//      these stayed grey (alligators has 93 of them). Push → `PUT
+//      /_asset-file/<designRoot-rel>` (checkout only, no bucket).
+//
+// Both are HEAD-first (skip what the cloud already holds) and streamed. The
+// HUB's validation is the authoritative gate at each trust boundary; the
+// filters here are the courtesy layer that keeps junk off the wire.
 
 import { type Dirent, readdirSync, statSync } from 'node:fs';
 import path from 'node:path';
 
-/** One path segment of a pushable key — the hub's `ASSET_KEY` charset. */
-const KEY_SEGMENT = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+/** One path segment charset — matches the hub's component regexes. */
+const SEGMENT = /^[A-Za-z0-9][A-Za-z0-9 ._-]*$/;
+
+/** Max designRoot-relative depth (matches the hub's 8-segment cap). */
+const MAX_SEGMENTS = 8;
 
-/** `ASSET_KEY` allows the name plus up to 4 directory segments. */
-const MAX_SEGMENTS = 5;
+/** Max relative-path length (matches the hub's 512 cap). */
+const MAX_REL_LEN = 512;
 
-/** Mirror of the sweeper's implausibility bound — a 2 GB file in `assets/` is
- *  a mistake, and paying to move it silently is the wrong response. */
+/**
+ * The binary asset extensions that actually render — images, fonts, media.
+ * Deliberately NOT `.json`/`.meta.json`/`.photo.json`/`.tsx`/`.css`: a
+ * `.photo.json` sidecar is edit metadata, not a served asset, and the checkout
+ * route refuses non-asset extensions anyway (so pushing them would just waste
+ * the wire and 400). Case-insensitive — a DS ships `…P1020428.JPG`.
+ */
+const ASSET_EXTS = new Set([
+  'png',
+  'jpg',
+  'jpeg',
+  'gif',
+  'webp',
+  'avif',
+  'svg',
+  'mp4',
+  'webm',
+  'mov',
+  'mp3',
+  'wav',
+  'm4a',
+  'ogg',
+  'woff2',
+  'woff',
+  'ttf',
+  'otf',
+]);
+
+/** A 2 GB file in an assets dir is a mistake — don't move it silently. */
 const MAX_PUSH_BYTES = 512 * 1024 * 1024;
 
 export interface AssetPushResult {
@@ -35,11 +70,107 @@ export interface AssetPushResult {
   failed: { key: string; reason: string }[];
 }
 
-/** Pushable keys under `<designRoot>/assets/`, relative to it. Missing dir → []. */
+/**
+ * feature-sync-progress-modal — incremental asset-push progress, emitted onto
+ * the sync bus so the Sync panel can show assets moving instead of a silent
+ * gap between "canvases synced" and a log line at the end. Keys are LOCAL
+ * designRoot-relative paths (never hub-supplied); `failures` is capped at
+ * MAX_LISTED_FAILURES with `failedCount` carrying the true number.
+ */
+export interface AssetPushProgress {
+  /** Total pushable assets found this boot. */
+  total: number;
+  /** Files settled so far (pushed + skipped + failed). */
+  done: number;
+  pushed: number;
+  skipped: number;
+  failedCount: number;
+  /** First MAX_LISTED_FAILURES failures — enough to name the broken paths. */
+  failures: { key: string; reason: string }[];
+  /** The designRoot-relative path on the wire right now, null when finished. */
+  active: string | null;
+  /** True exactly once, on the final emit (also fires when total is 0). */
+  finished: boolean;
+}
+
+/** Cap on `failures` in a progress emit (same spirit as MAX_REJECTED_SLUGS —
+ *  the payload reaches `_sync.json` + every open tab, so it stays bounded). */
+export const MAX_LISTED_FAILURES = 20;
+
+/** Longest single pause the hub can ask for. Matches the hub's rate-limit
+ *  window (60 s) — a `Retry-After` larger than that is either a typo or a hub
+ *  we should not be blocking a boot sweep on. */
+const MAX_RETRY_DELAY_MS = 60_000;
+
+/** Where an absent/unparsable `Retry-After` lands. Old hubs (pre-fix) send a
+ *  bare 429 with no header, and their window is the same 60 s. */
+const DEFAULT_RETRY_DELAY_MS = 60_000;
+
+/** Total time ONE sweep may spend waiting out 429s. The paced retry exists to
+ *  keep an un-upgraded hub livable, not to turn a boot into an hour-long
+ *  background stall — past this, the remaining refusals fail fast and the
+ *  next-boot backstop takes them. */
+const MAX_SWEEP_BACKOFF_MS = 5 * 60_000;
+
+/** How much of an error body reaches `failed[].reason`. Enough to tell "rate
+ *  limit exceeded" from a Cloudflare error page — the distinction the 2026-08-11
+ *  RCA had to reconstruct from edge logs because the client kept only a status
+ *  code. Hub-supplied text ⇒ bounded and stripped before it reaches the UI. */
+const ERROR_SNIPPET_CHARS = 80;
+
+/**
+ * Every upload closes its connection. NOT an optimization — a correctness
+ * requirement, learned the expensive way (2026-08-11, second pass).
+ *
+ * A peer that refuses a PUT **before reading the body** (the cloud studio door
+ * answering 401, the edge answering 503) leaves unread request bytes in an
+ * HTTP/1.1 keep-alive socket. The connection is then desynchronized: the next
+ * request Bun sends over it NEVER gets a response. With no retry that stayed
+ * invisible — the refusal was reported and the sweep moved on. The moment a
+ * retry re-sent on that same pooled socket, the sweep wedged forever and the
+ * dev-server sidecar died with it (Bun segfault, 4 crash-loops, alligators).
+ * Measured: `connection: close` on the retry ALONE does not help (the retry is
+ * handed the already-poisoned socket) — it has to be on the request that may be
+ * refused, i.e. every PUT. One TLS handshake per asset against multi-MB bodies
+ * is not a cost worth reasoning about.
+ */
+const UPLOAD_CONNECTION_HEADERS = { connection: 'close' } as const;
+
+/** HEAD is a small, bodyless probe — a hub that has not answered in 30 s is not
+ *  about to. */
+const HEAD_TIMEOUT_MS = 30_000;
+
+/**
+ * How long one upload may take before the sweep abandons it: a fixed floor plus
+ * an allowance for the bytes at a deliberately pessimistic 100 kB/s, capped.
+ * The backstop for anything that wedges a connection the way the keep-alive
+ * desync above did — a sweep that hangs forever takes the whole dev-server with
+ * it, and "this asset failed, next boot retries it" is always the better end.
+ */
+export function putTimeoutMs(bytes: number): number {
+  return Math.min(10 * 60_000, 60_000 + (Number.isFinite(bytes) ? bytes : 0) / 100);
+}
+
+/** Min ms between mid-flight progress emits. A 90-file DS at LAN speed would
+ *  otherwise broadcast 90 payloads in a couple of seconds; failures and the
+ *  final emit always go out regardless. */
+const PROGRESS_INTERVAL_MS = 200;
+
+function extOf(name: string): string {
+  const dot = name.lastIndexOf('.');
+  return dot < 0 ? '' : name.slice(dot + 1).toLowerCase();
+}
+
+/**
+ * Every pushable binary asset under designRoot, as a designRoot-relative path.
+ * Walks into any directory named `assets` at any level (top-level `assets/`,
+ * `system/<ds>/assets/`, …) and collects the asset-extension files inside it.
+ * Skips runtime-state (`_*`), `.git`, `node_modules`. Missing root → [].
+ */
 export function listPushableAssets(designRoot: string): string[] {
-  const root = path.join(designRoot, 'assets');
   const out: string[] = [];
-  const walk = (dir: string, prefix: string, depth: number): void => {
+  // Walk the tree; once inside an `assets` dir, collect asset files below it.
+  const walk = (dir: string, rel: string, insideAssets: boolean): void => {
     let entries: Dirent[];
     try {
       entries = readdirSync(dir, { withFileTypes: true });
@@ -47,24 +178,127 @@ export function listPushableAssets(designRoot: string): string[] {
       return;
     }
     for (const entry of entries) {
-      if (!KEY_SEGMENT.test(entry.name)) continue; // dotfiles fail the leading-alnum rule
-      const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+      const name = entry.name;
+      if (name.startsWith('_') || name === '.git' || name === 'node_modules') continue;
+      if (!SEGMENT.test(name)) continue; // dotfiles + odd charset
+      const childRel = rel ? `${rel}/${name}` : name;
+      if (childRel.length > MAX_REL_LEN || childRel.split('/').length > MAX_SEGMENTS) continue;
       if (entry.isDirectory()) {
-        if (depth + 1 < MAX_SEGMENTS) walk(path.join(dir, entry.name), rel, depth + 1);
+        walk(path.join(dir, name), childRel, insideAssets || name === 'assets');
       } else if (entry.isFile()) {
+        if (!insideAssets) continue; // only files under some assets/ dir
+        if (!ASSET_EXTS.has(extOf(name))) continue;
         try {
-          if (statSync(path.join(dir, entry.name)).size > MAX_PUSH_BYTES) continue;
+          if (statSync(path.join(dir, name)).size > MAX_PUSH_BYTES) continue;
         } catch {
           continue;
         }
-        out.push(rel);
+        out.push(childRel);
       }
     }
   };
-  walk(root, '', 1);
+  walk(designRoot, '', false);
   return out.sort();
 }
 
+/** Where a given asset pushes: the bucket-backed route (top-level `assets/`) or
+ *  the checkout route (a nested `…/assets/…` served from disk). */
+function routeFor(rel: string): { url: string } {
+  const parts = rel.split('/');
+  if (parts[0] === 'assets') {
+    // Top-level content-addressed → the bucket `/assets/<key>` route.
+    return { url: `/assets/${parts.slice(1).join('/')}` };
+  }
+  // DS / brand asset served from the checkout → the checkout-file route, keyed
+  // by its FULL designRoot-relative path.
+  return { url: `/_asset-file/${rel.split('/').map(encodeURIComponent).join('/')}` };
+}
+
+/** `Retry-After: <seconds>` → ms, clamped. Only the delta-seconds form is
+ *  parsed; the HTTP-date form is not something our hub emits. */
+function retryAfterMs(header: string | null): number {
+  const secs = Number(String(header ?? '').trim());
+  if (!Number.isFinite(secs) || secs <= 0) return DEFAULT_RETRY_DELAY_MS;
+  return Math.min(secs * 1000, MAX_RETRY_DELAY_MS);
+}
+
+/**
+ * Why an upload was refused, in words — status PLUS a bounded snippet of the
+ * body. The hub says `{"error":"rate limit exceeded"}`; an edge that never
+ * reached the hub says HTML. Those are different bugs and the Sync panel should
+ * not make a person read logs to tell them apart.
+ *
+ * The body is hub-supplied ⇒ untrusted (DDR-054): control characters stripped,
+ * whitespace collapsed, hard length cap, and it only ever renders as text.
+ */
+async function failureReason(res: Response): Promise<string> {
+  let snippet = '';
+  try {
+    snippet = (await res.text())
+      // biome-ignore lint/suspicious/noControlCharactersInRegex: stripping them is the point.
+      .replace(/[\u0000-\u001f\u007f]/g, ' ')
+      .replace(/\s+/g, ' ')
+      .trim()
+      .slice(0, ERROR_SNIPPET_CHARS);
+  } catch {
+    /* a body we cannot read tells us nothing — the status still does */
+  }
+  return snippet ? `HTTP ${res.status} — ${snippet}` : `HTTP ${res.status}`;
+}
+
+/**
+ * One upload, with the two retries that are worth having in-boot.
+ *
+ * 429 — the hub tells us when to come back (`Retry-After`), so come back then,
+ * ONCE. Before the 2026-08-11 fix the write lane sat in a 5/min per-IP bucket
+ * and the sweep ignored the header entirely, so a 182-asset project burned the
+ * window and moved ~5 files per boot. The hub half of the fix is the real
+ * one — this half is what keeps a not-yet-upgraded hub (the fleet rolls only on
+ * a release tag) finishing a sweep instead of grinding.
+ *
+ * 5xx — one immediate retry, because a transient edge/proxy hiccup on a 30 MB
+ * body should not need a whole new boot to get past.
+ *
+ * A second refusal is a real failure: report it and move on (the next-boot
+ * backstop is unchanged).
+ */
+async function putWithRetry(ctx: {
+  fetchImpl: typeof fetch;
+  url: string;
+  headers: Record<string, string>;
+  file: string;
+  sleep: (ms: number) => Promise<void>;
+  /** Mutable per-sweep pause budget, shared across every asset. */
+  backoff: { remainingMs: number };
+  timeoutFor: (bytes: number) => number;
+}): Promise<Response> {
+  const send = (): Promise<Response> => {
+    const body = Bun.file(ctx.file);
+    return ctx.fetchImpl(ctx.url, {
+      method: 'PUT',
+      headers: {
+        ...ctx.headers,
+        ...UPLOAD_CONNECTION_HEADERS,
+        // Bun derives this from the file anyway (measured) — stated explicitly
+        // so a body length is never something a future body type has to guess.
+        'content-length': String(body.size),
+      },
+      body,
+      signal: AbortSignal.timeout(ctx.timeoutFor(body.size)),
+    });
+  };
+  const first = await send();
+  if (first.status === 429) {
+    const wait = retryAfterMs(first.headers?.get?.('retry-after') ?? null);
+    if (wait > ctx.backoff.remainingMs) return first;
+    ctx.backoff.remainingMs -= wait;
+    await ctx.sleep(wait);
+    return send();
+  }
+  if (first.status >= 500) return send();
+  return first;
+}
+
 /**
  * Mirror local assets up to the hub. Idempotent and skip-first (one HEAD per
  * asset per boot; upload only on a miss), sequential on purpose — assets run
@@ -79,33 +313,107 @@ export async function pushAssets(opts: {
   token: () => string;
   fetchImpl?: typeof fetch;
   log?: Pick<Console, 'log' | 'warn'>;
+  /** feature-sync-progress-modal — incremental progress (throttled; failures
+   *  and the final emit always fire). Never throws into the push loop. */
+  onProgress?: (progress: AssetPushProgress) => void;
+  /** Injectable clock for the throttle (tests). */
+  now?: () => number;
+  /** Injectable pause for the 429 backoff (tests — a fake clock, not a wait). */
+  sleep?: (ms: number) => Promise<void>;
+  /** Injectable per-request time budget (tests — seconds, not minutes). */
+  timeoutFor?: (bytes: number) => number;
 }): Promise<AssetPushResult> {
   const { designRoot, hubUrl } = opts;
   const fetchImpl = opts.fetchImpl ?? fetch;
   const log = opts.log ?? console;
+  const now = opts.now ?? Date.now;
+  const sleep =
+    opts.sleep ??
+    ((ms: number) =>
+      new Promise<void>((res) => {
+        setTimeout(res, ms);
+      }));
+  const timeoutFor = opts.timeoutFor ?? putTimeoutMs;
+  // Shared across the whole sweep — see MAX_SWEEP_BACKOFF_MS.
+  const backoff = { remainingMs: MAX_SWEEP_BACKOFF_MS };
   const base = hubUrl.replace(/\/+$/, '');
   const out: AssetPushResult = { pushed: [], skipped: 0, failed: [] };
 
-  for (const key of listPushableAssets(designRoot)) {
-    const url = `${base}/assets/${key}`;
+  const assets = listPushableAssets(designRoot);
+  // -Infinity seeds the throttle open, so the first emit always passes.
+  let lastEmit = -Infinity;
+  const emitProgress = (active: string | null, finished: boolean, force = false): void => {
+    if (!opts.onProgress) return;
+    const t = now();
+    if (!force && t - lastEmit < PROGRESS_INTERVAL_MS) return;
+    lastEmit = t;
+    try {
+      opts.onProgress({
+        total: assets.length,
+        done: out.pushed.length + out.skipped + out.failed.length,
+        pushed: out.pushed.length,
+        skipped: out.skipped,
+        failedCount: out.failed.length,
+        failures: out.failed.slice(0, MAX_LISTED_FAILURES),
+        active,
+        finished,
+      });
+    } catch {
+      /* a broken listener must never break the push */
+    }
+  };
+
+  for (const rel of assets) {
+    emitProgress(rel, false);
+    const url = `${base}${routeFor(rel).url}`;
     const headers = { authorization: `Bearer ${opts.token()}` };
     try {
-      const head = await fetchImpl(url, { method: 'HEAD', headers });
+      const head = await fetchImpl(url, {
+        method: 'HEAD',
+        headers,
+        signal: AbortSignal.timeout(HEAD_TIMEOUT_MS),
+      });
       if (head.ok) {
         out.skipped += 1;
         continue;
       }
-      const put = await fetchImpl(url, {
-        method: 'PUT',
+      // A hub that refuses the PROBE refuses the upload — pushing the body
+      // anyway just streams megabytes at a door that already said no. The
+      // cloud studio door answers exactly this for a route the deployed hub
+      // does not have yet, once per asset, for the whole DS asset set.
+      if (head.status === 401 || head.status === 403) {
+        out.failed.push({ key: rel, reason: await failureReason(head) });
+        emitProgress(rel, false, true);
+        continue;
+      }
+      const put = await putWithRetry({
+        fetchImpl,
+        url,
         headers,
-        body: Bun.file(path.join(designRoot, 'assets', key)),
+        file: path.join(designRoot, rel),
+        sleep,
+        backoff,
+        timeoutFor,
       });
-      if (put.ok) out.pushed.push(key);
-      else out.failed.push({ key, reason: `HTTP ${put.status}` });
+      if (put.ok) out.pushed.push(rel);
+      else {
+        out.failed.push({ key: rel, reason: await failureReason(put) });
+        emitProgress(rel, false, true);
+      }
     } catch (err) {
-      out.failed.push({ key, reason: (err as Error).message });
+      const e = err as Error;
+      out.failed.push({
+        key: rel,
+        // "TimeoutError: The operation timed out" tells a person nothing about
+        // which limit fired; name the budget instead.
+        reason: e.name === 'TimeoutError' ? 'timed out — the hub stopped answering' : e.message,
+      });
+      emitProgress(rel, false, true);
     }
   }
+  // No assets → no emits at all: a project without an assets/ dir should not
+  // grow an empty assets section in its Sync panel.
+  if (assets.length > 0) emitProgress(null, true, true);
 
   if (out.pushed.length > 0) {
     log.log?.(

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

@@ -28,6 +28,15 @@ export type SyncState = 'online' | 'connecting' | 'offline' | 'offline-long';
  *  refused auth for this documentName (scope / invalid token / rate limit). */
 export type DocSyncState = 'pending' | 'connected' | 'auth-rejected';
 
+/** feature-sync-progress-modal — one row of the per-document list the Sync
+ *  panel renders. `reason` is OUR OWN classification vocabulary (the
+ *  AuthFailureClass strings), never hub-supplied text. */
+export interface SyncDocItem {
+  slug: string;
+  state: DocSyncState;
+  reason?: string;
+}
+
 export interface SyncStatusSnapshot {
   state: SyncState;
   /** Local edits made since the hub went unreachable (replayed on reconnect). */
@@ -55,6 +64,18 @@ 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[];
+  /**
+   * feature-sync-progress-modal — the per-document list behind `docs`, so the
+   * Sync panel can render rows without a second fetch. Bounded at
+   * MAX_SYNC_ITEMS with the INTERESTING states first (rejected, then pending,
+   * then connected): the truncated tail is then always the already-summarised
+   * happy case, and `itemsTruncated` says how many rows it holds. Slugs are
+   * local canvas identifiers; `reason` is our own classification vocabulary.
+   * Absent in pre-existing payloads.
+   */
+  items?: SyncDocItem[];
+  /** Rows dropped by the MAX_SYNC_ITEMS cap (all `connected` by the sort). */
+  itemsTruncated?: number;
   /**
    * Canvases this run brought DOWN from the project — documents that existed
    * only on the hub and are now real local files.
@@ -94,8 +115,10 @@ export interface ConnectionMonitor {
   noteProviderStatus(providerId: string, status: ProviderStatus): void;
   /** A local edit happened — counts toward queuedOps while not online. */
   noteLocalEdit(): void;
-  /** DDR-102 — record a document's sync state (pending/connected/auth-rejected). */
-  noteDocState(slug: string, state: DocSyncState): void;
+  /** DDR-102 — record a document's sync state (pending/connected/auth-rejected).
+   *  `reason` (feature-sync-progress-modal) is the classification for an
+   *  auth-rejected doc — our own vocabulary, ignored for other states. */
+  noteDocState(slug: string, state: DocSyncState, reason?: string): void;
   /** DDR-102 — real sync activity for a slug (reconcile done, hub-pushed flush
    *  applied): bumps `lastSyncAt` to now. */
   noteSyncActivity(slug: string): void;
@@ -112,6 +135,21 @@ const DEFAULT_ESCALATE_MS = 24 * 60 * 60 * 1000;
 const DEFAULT_FLASH_MS = 3_000;
 /** Cap on rejectedSlugs in the snapshot (the rollup carries the true count). */
 export const MAX_REJECTED_SLUGS = 20;
+/**
+ * Cap on the per-document `items` list. Every emit synchronously writes
+ * `_sync.json` and fans out over WS, so the list must stay bounded no matter
+ * how many canvases a project grows — 200 rows ≈ a few KB, and the sort keeps
+ * everything a person must ACT on (rejected, pending) inside the cap.
+ */
+export const MAX_SYNC_ITEMS = 200;
+
+/** Sort weight: the states a person must act on come first, so the cap only
+ *  ever truncates the already-summarised happy tail. */
+const ITEM_STATE_ORDER: Record<DocSyncState, number> = {
+  'auth-rejected': 0,
+  pending: 1,
+  connected: 2,
+};
 
 export function createConnectionMonitor(opts: ConnectionMonitorOptions = {}): ConnectionMonitor {
   const graceMs = opts.graceMs ?? DEFAULT_GRACE_MS;
@@ -125,6 +163,11 @@ export function createConnectionMonitor(opts: ConnectionMonitorOptions = {}): Co
   const providerStatuses = new Map<string, ProviderStatus>();
   // DDR-102 — per-doc states (pending/connected/auth-rejected).
   const docStates = new Map<string, DocSyncState>();
+  // feature-sync-progress-modal — rejection classifications, keyed by slug.
+  // Held separately from docStates so the state machine above is untouched;
+  // dropped the moment a doc leaves auth-rejected (a re-probe that succeeds
+  // must not leave a stale reason on a connected row).
+  const docReasons = new Map<string, string>();
 
   // 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
@@ -175,6 +218,19 @@ export function createConnectionMonitor(opts: ConnectionMonitorOptions = {}): Co
         if (rejectedSlugs.length < MAX_REJECTED_SLUGS) rejectedSlugs.push(slug);
       } else docs.pending++;
     }
+    // The per-row list, actionable states first so the cap only ever drops
+    // rows the aggregate counts already describe (see MAX_SYNC_ITEMS).
+    const allItems: SyncDocItem[] = [...docStates]
+      .map(([slug, st]) => {
+        const reason = docReasons.get(slug);
+        return reason ? { slug, state: st, reason } : { slug, state: st };
+      })
+      .sort(
+        (a, b) =>
+          ITEM_STATE_ORDER[a.state] - ITEM_STATE_ORDER[b.state] || a.slug.localeCompare(b.slug)
+      );
+    const items = allItems.slice(0, MAX_SYNC_ITEMS);
+    const itemsTruncated = allItems.length - items.length;
     return {
       state,
       queuedOps,
@@ -185,6 +241,8 @@ export function createConnectionMonitor(opts: ConnectionMonitorOptions = {}): Co
       startedAt,
       docs,
       rejectedSlugs,
+      items,
+      ...(itemsTruncated > 0 ? { itemsTruncated } : {}),
       ...(pulled ? { pulled } : {}),
     };
   }
@@ -347,10 +405,20 @@ export function createConnectionMonitor(opts: ConnectionMonitorOptions = {}): Co
       emit();
     },
 
-    noteDocState(slug, docState) {
+    noteDocState(slug, docState, reason) {
       if (stopped) return;
+      // STATE-ONLY dedupe. This briefly compared `reason` too, which handed a
+      // hostile hub an amplifier: the rejection text is hub-controlled, so
+      // alternating it on an open socket forced a full emit — items rebuild +
+      // synchronous `_sync.json` write + WS fanout — per frame (security
+      // review 2026-08-11, sync-progress-modal defender). The reason is
+      // LATCHED for the life of a rejection episode instead: the first
+      // classification wins, leaving the rejected state clears the latch, and
+      // a NEW episode records a fresh reason. Repeat frames stay a no-op.
       if (docStates.get(slug) === docState) return;
       docStates.set(slug, docState);
+      if (docState !== 'auth-rejected') docReasons.delete(slug);
+      else if (reason !== undefined) docReasons.set(slug, reason);
       emit();
     },
 

package/apps/studio/sync/index.ts

@@ -969,7 +969,10 @@ export function createSyncRuntime(
     ): void => {
       if (stopped) return;
       const reasonClass = classifyAuthFailure(rawReason);
-      mon.noteDocState(canvas.slug, 'auth-rejected');
+      // feature-sync-progress-modal — the class rides into the per-item list so
+      // a rejected row in the Sync panel can say WHY (our vocabulary, not the
+      // hub's raw message).
+      mon.noteDocState(canvas.slug, 'auth-rejected', reasonClass);
       rejectedReasons.set(canvas.slug, reasonClass);
       // Aggregate console output: ONE debounced warn for the whole burst.
       if (!pendingAuthWarn.has(reasonClass)) pendingAuthWarn.set(reasonClass, new Set());
@@ -1547,6 +1550,12 @@ export function createSyncRuntime(
           designRoot: ctx.paths.designRoot,
           hubUrl: linkedHub.url,
           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);
+          },
         }).catch((err) => {
           console.warn(`[sync/assets] asset push failed: ${(err as Error).message}`);
         });

package/apps/studio/sync/status.ts

@@ -12,6 +12,7 @@
 // git-pull divergence). Writes are best-effort + atomic-ish (tmp + rename via
 // the injected writer); a failed write never throws into the sync hot path.
 
+import type { AssetPushProgress } from './asset-push.ts';
 import type { SyncStatusSnapshot } from './connection-state.ts';
 
 // `cold-start-hub-wins` stays in the union for OLD payload readers (additive
@@ -46,6 +47,12 @@ export interface SyncStatusPayload extends SyncStatusSnapshot {
    * show which collaboration model is running. Absent/false = the two-doc path.
    */
   sharedDoc?: boolean;
+  /**
+   * feature-sync-progress-modal — the DDR-217 asset push's live progress
+   * (additive; absent until the first push emit of a boot). Rides the same
+   * payload as the doc counts so the Sync panel has one source, not two.
+   */
+  assets?: AssetPushProgress;
 }
 
 export interface SyncStatusStoreOptions {
@@ -67,6 +74,10 @@ export interface SyncStatusStore {
   update(snapshot: SyncStatusSnapshot): void;
   /** Record a conflict notification + persist + broadcast. */
   addConflict(conflict: Omit<SyncConflict, 'at'>): void;
+  /** feature-sync-progress-modal — merge asset-push progress + persist +
+   *  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;
   /** Current payload (defensive copy). */
   get(): SyncStatusPayload;
 }
@@ -90,6 +101,8 @@ export function createSyncStatusStore(opts: SyncStatusStoreOptions): SyncStatusS
     updatedAt: now(),
   };
 
+  let assets: AssetPushProgress | undefined;
+
   function payload(): SyncStatusPayload {
     return {
       ...snapshot,
@@ -97,6 +110,7 @@ export function createSyncStatusStore(opts: SyncStatusStoreOptions): SyncStatusS
       canvases: opts.canvases,
       conflicts: conflicts.slice(),
       ...(opts.sharedDoc ? { sharedDoc: true } : {}),
+      ...(assets ? { assets } : {}),
     };
   }
 
@@ -124,6 +138,10 @@ export function createSyncStatusStore(opts: SyncStatusStoreOptions): SyncStatusS
       if (conflicts.length > maxConflicts) conflicts.splice(0, conflicts.length - maxConflicts);
       flush();
     },
+    updateAssets(progress) {
+      assets = progress;
+      flush();
+    },
     get: payload,
   };
 }