@1agh/maude 0.58.2 → 0.59.0

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

@@ -0,0 +1,432 @@
+// 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 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:
+//
+//   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 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;
+
+/** Max relative-path length (matches the hub's 512 cap). */
+const MAX_REL_LEN = 512;
+
+/**
+ * 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 {
+  pushed: string[];
+  skipped: number;
+  failed: { key: string; reason: string }[];
+}
+
+/**
+ * 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 out: string[] = [];
+  // 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 });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      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()) {
+        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, name)).size > MAX_PUSH_BYTES) continue;
+        } catch {
+          continue;
+        }
+        out.push(childRel);
+      }
+    }
+  };
+  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
+ * to videos, and saturating the link a fresh sync is also using would starve
+ * the handshakes this rides behind. Never throws; a failed upload is retried
+ * for free on the next boot.
+ */
+export async function pushAssets(opts: {
+  designRoot: string;
+  hubUrl: string;
+  /** Read at call time — silent renewal swaps the credential in place. */
+  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: [] };
+
+  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,
+        signal: AbortSignal.timeout(HEAD_TIMEOUT_MS),
+      });
+      if (head.ok) {
+        out.skipped += 1;
+        continue;
+      }
+      // 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,
+        file: path.join(designRoot, rel),
+        sleep,
+        backoff,
+        timeoutFor,
+      });
+      if (put.ok) out.pushed.push(rel);
+      else {
+        out.failed.push({ key: rel, reason: await failureReason(put) });
+        emitProgress(rel, false, true);
+      }
+    } catch (err) {
+      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?.(
+      `[sync/assets] pushed ${out.pushed.length} asset(s) to ${base} (${out.skipped} already there)`
+    );
+  }
+  if (out.failed.length > 0) {
+    log.warn?.(
+      `[sync/assets] ${out.failed.length} asset(s) did not reach ${base} (retried next boot): ${out.failed
+        .slice(0, 3)
+        .map((f) => `${f.key} — ${f.reason}`)
+        .join('; ')}`
+    );
+  }
+  return out;
+}

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). */
@@ -42,11 +51,31 @@ export interface SyncStatusSnapshot {
   flash: 'synced' | null;
   /** ms epoch this snapshot was produced. */
   updatedAt: number;
+  /**
+   * ms epoch this link's monitor was created — i.e. when this runtime started
+   * trying. The one clock `connecting…` can honestly be measured against:
+   * `updatedAt` moves on every emit (an auth-rejection storm refreshes it
+   * forever), so "how long has nothing synced" needs a stamp that does NOT
+   * reset while nothing is actually working. Absent in pre-existing payloads.
+   */
+  startedAt?: number;
   /** DDR-102 — per-doc rollup (additive; absent in pre-DDR-102 payloads). */
   docs?: { synced: number; pending: number; rejected: number };
   /** 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.
@@ -86,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;
@@ -104,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;
@@ -117,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
@@ -130,6 +181,8 @@ export function createConnectionMonitor(opts: ConnectionMonitorOptions = {}): Co
   let lastSyncAt: number | null = null;
   let offlineSince: number | null = null;
   let flash: 'synced' | null = null;
+  /** When this monitor began trying — see `SyncStatusSnapshot.startedAt`. */
+  const startedAt = now();
 
   let graceTimer: TimerHandle | null = null;
   let escalateTimer: TimerHandle | null = null;
@@ -165,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,
@@ -172,8 +238,11 @@ export function createConnectionMonitor(opts: ConnectionMonitorOptions = {}): Co
       offlineSince,
       flash,
       updatedAt: now(),
+      startedAt,
       docs,
       rejectedSlugs,
+      items,
+      ...(itemsTruncated > 0 ? { itemsTruncated } : {}),
       ...(pulled ? { pulled } : {}),
     };
   }
@@ -336,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/hub-link.ts

@@ -22,7 +22,7 @@
 // phase-9's hub model expects private hosts), so we do NOT block private IPs; the safety
 // is the loopback caller gate + no reflection + no token on the probe.
 
-import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
 import { dirname } from 'node:path';
 
 import { hubsConfigPath, normalizeUrl } from './hubs-config.ts';
@@ -35,7 +35,7 @@ export interface HubLinkResult {
 const HUB_PROBE_TIMEOUT_MS = 4000;
 
 interface HubsFile {
-  hubs: Record<string, { token: string; linkedAt: number }>;
+  hubs: Record<string, { token: string; linkedAt: number; role?: string; expiresAt?: number }>;
   trusted?: string[];
 }
 
@@ -108,8 +108,20 @@ async function probeHealth(url: string): Promise<{ ok: boolean; version?: string
   }
 }
 
-/** Upsert the token (+ the vouched role) under `normUrl` + record per-machine trust; mode 0600. */
-export function saveHubCredential(normUrl: string, token: string, role?: string): void {
+/**
+ * Upsert the token (+ the vouched role + expiry) under `normUrl` + record
+ * per-machine trust; mode 0600.
+ *
+ * The upsert REPLACES the record, so a caller that knows the role/expiry must
+ * pass them again or they are dropped — the silent-renewal path reads the old
+ * record first and carries the role forward for exactly this reason.
+ */
+export function saveHubCredential(
+  normUrl: string,
+  token: string,
+  role?: string,
+  expiresAt?: number
+): void {
   const path = hubsConfigPath();
   const dir = dirname(path);
   if (!existsSync(dir)) mkdirSync(dir, { recursive: true, mode: 0o700 });
@@ -123,15 +135,59 @@ export function saveHubCredential(normUrl: string, token: string, role?: string)
       /* malformed → start fresh rather than throw */
     }
   }
-  cfg.hubs[normUrl] = { token, linkedAt: Date.now(), ...(role ? { role } : {}) };
+  cfg.hubs[normUrl] = {
+    token,
+    linkedAt: Date.now(),
+    ...(role ? { role } : {}),
+    ...(typeof expiresAt === 'number' && Number.isFinite(expiresAt) ? { expiresAt } : {}),
+  };
   if (!Array.isArray(cfg.trusted)) cfg.trusted = [];
   if (!cfg.trusted.includes(normUrl)) cfg.trusted.push(normUrl);
-  writeFileSync(path, `${JSON.stringify(cfg, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+  // F3 (2026-08-10 review) — atomic temp-then-rename. This write used to run
+  // only when a human pressed Connect; silent renewal now fires it on a timer,
+  // several times a minute under a rejection burst. A truncating in-place
+  // writeFileSync that is interrupted (crash / kill / full disk) leaves a
+  // half-written file — and since it holds EVERY hub credential on the machine,
+  // that drops them all. rename(2) is atomic on POSIX: a reader sees the whole
+  // old file or the whole new one, never a torn one.
+  const tmp = `${path}.${process.pid}.tmp`;
+  writeFileSync(tmp, `${JSON.stringify(cfg, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+  try {
+    chmodSync(tmp, 0o600);
+  } catch {
+    /* windows / read-only fs — best effort */
+  }
+  renameSync(tmp, path);
+}
+
+/**
+ * Forget the credential + per-machine trust for `normUrl` — the unlink half of
+ * `saveHubCredential`. Idempotent (a missing entry is simply done), and atomic
+ * for the same reason the save is: the file holds EVERY hub credential on the
+ * machine, so a torn write drops them all.
+ */
+export function deleteHubCredential(normUrl: string): void {
+  const path = hubsConfigPath();
+  if (!existsSync(path)) return;
+  let cfg: HubsFile;
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf8'));
+    if (!parsed || typeof parsed.hubs !== 'object' || parsed.hubs === null) return;
+    cfg = parsed as HubsFile;
+  } catch {
+    return; // malformed → nothing recoverable to forget
+  }
+  if (!(normUrl in cfg.hubs) && !cfg.trusted?.includes(normUrl)) return;
+  delete cfg.hubs[normUrl];
+  if (Array.isArray(cfg.trusted)) cfg.trusted = cfg.trusted.filter((u) => u !== normUrl);
+  const tmp = `${path}.${process.pid}.tmp`;
+  writeFileSync(tmp, `${JSON.stringify(cfg, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
   try {
-    chmodSync(path, 0o600);
+    chmodSync(tmp, 0o600);
   } catch {
     /* windows / read-only fs — best effort */
   }
+  renameSync(tmp, path);
 }
 
 export const __testing = { probeHealth };