@1agh/maude 0.58.2 → 0.59.0

package/apps/studio/sync/hubs-config.ts

@@ -23,6 +23,20 @@ export interface HubRecord {
    * write-capable, and nobody is demoted by an upgrade.
    */
   role?: string;
+  /**
+   * When this credential dies (ms epoch), as the workspace reported at mint.
+   *
+   * A cell session expires WITH the 12 h project token that minted it (Phase
+   * 23 B2 — that cap is the revocation window and must stay). What was
+   * missing is anyone LOOKING at the deadline: the token was saved, the
+   * expiry discarded, and ≤ 12 h later all sync died into a permanent
+   * `connecting…`. Stored so the runtime can renew BEFORE it, silently.
+   *
+   * Absent on self-hosted hubs (their tokens may not expire) and on every
+   * credential written before this shipped — both mean "no scheduled
+   * renewal", which is exactly the old behaviour.
+   */
+  expiresAt?: number;
 }
 
 export interface HubsConfig {
@@ -40,6 +54,16 @@ export function hubsConfigPath(): string {
 /** Normalize a hub URL — trim trailing slash, lower-case scheme + host. */
 export function normalizeUrl(url: string): string {
   const u = new URL(url);
+  // Reject embedded credentials outright (2026-08-10 review, claim-a residual).
+  // `URL.toString()` PRESERVES `user:pass@` — the renewal lane is safe only
+  // because it fetches the normalized string and requires it to equal a URL the
+  // cloud itself listed. A `https://evil@proj.cloud.maude.sh` config would
+  // survive normalization intact; refusing it here means such a value can never
+  // be stored or matched, so a later "fetch hubUrl directly" edit can't become
+  // credential exfiltration. A real hub URL never carries userinfo.
+  if (u.username || u.password) {
+    throw new Error('hub URL must not contain embedded credentials');
+  }
   u.protocol = u.protocol.toLowerCase();
   u.hostname = u.hostname.toLowerCase();
   let str = u.toString();
@@ -108,11 +132,15 @@ export function isHubReadOnly(url: string): boolean {
 
 /** Look up a token for `url`. Returns null when no entry exists. */
 export function getHubToken(url: string): string | null {
+  return getHubRecord(url)?.token ?? null;
+}
+
+/** The whole stored record for `url` (token + role + expiresAt), or null. */
+export function getHubRecord(url: string): HubRecord | null {
   try {
     const norm = normalizeUrl(url);
-    const cfg = loadHubsConfig();
-    const record = cfg.hubs[norm];
-    return record ? record.token : null;
+    const record = loadHubsConfig().hubs[norm];
+    return record && typeof record.token === 'string' ? record : null;
   } catch {
     return null;
   }

package/apps/studio/sync/index.ts

@@ -23,12 +23,13 @@ import path from 'node:path';
 
 import type { Awareness } from 'y-protocols/awareness';
 import * as Y from 'yjs';
-
+import { renewHubCredential } from '../cloud/renew.ts';
 import { Y_TYPES } from '../collab/persistence.ts';
 import type { Context, LinkedHub } from '../context.ts';
 import { createHistory } from '../history.ts';
 import { SYNTHETIC_FS_DELAY_MS } from '../hmr-broadcast.ts';
 import { type CanvasSyncAgent, createCanvasSyncAgent } from './agent.ts';
+import { pushAssets } from './asset-push.ts';
 import { atomicWrite } from './atomic-write.ts';
 import { createAutoCommit } from './autocommit.ts';
 import { type CellPairing, resolveCellPairing, sanitizeForLog } from './cell-pairing.ts';
@@ -41,9 +42,10 @@ import {
 import { createDocNameResolver } from './doc-name.ts';
 import { createEchoGuard } from './echo-guard.ts';
 import { createFsReader, type FsReader } from './fs-mirror.ts';
-import { getHubToken } from './hubs-config.ts';
+import { getHubRecord } from './hubs-config.ts';
 import { loadJournal, type SyncJournal } from './journal.ts';
 import { isLoopbackHost } from './loopback.ts';
+import { migrateFlatFallback } from './migrate-flat-fallback.ts';
 import { migrateSeed } from './migrate-seed.ts';
 import { ORIGINS } from './origins.ts';
 import { createDocProjection, type DocProjection } from './projection.ts';
@@ -96,15 +98,50 @@ export type AuthFailureClass = 'rate-limit' | 'not-authorized' | 'invalid-token'
  *  → `generic` (interop-safe degradation). */
 export function classifyAuthFailure(raw: string): AuthFailureClass {
   const s = raw.toLowerCase();
-  if (s.includes('rate limit')) return 'rate-limit';
-  if (s.includes('not authorized')) return 'not-authorized';
+  // Permanent classes FIRST. The hub's invalid-token bucket refuses with
+  // "invalid token — rate limited, retry in up to 60s": both substrings are
+  // present, and testing 'rate limit' first filed an expired credential under
+  // the transient class — so the runtime retried into the very bucket
+  // refusing it, and the one cause that needed a person never surfaced.
   if (s.includes('invalid token')) return 'invalid-token';
+  if (s.includes('not authorized')) return 'not-authorized';
+  if (s.includes('rate limit')) return 'rate-limit';
   return 'generic';
 }
 
 export const AUTH_WARN_DEBOUNCE_MS = 2_000;
 export const AUTH_REPROBE_MS = 5 * 60 * 1000;
 export const BOOT_SETTLE_TIMEOUT_MS = 15_000;
+/** F1 — minimum wall-clock between renewal attempts. A burst of rejections
+ *  collapses to one renewal (single-flight); the NEXT burst waits this out. */
+export const RENEW_MIN_INTERVAL_MS = 60_000;
+/** F1 — consecutive successful renewals with no completed handshake in between
+ *  before the runtime stops renewing and lets the link surface as
+ *  refused/stalled. Small: a renewal that fixed the credential clears at least
+ *  one doc, so >0 useless renewals means the credential was never the cause. */
+export const RENEW_MAX_WITHOUT_PROGRESS = 3;
+/** F2 — setTimeout clamps delays above this (2^31-1) to 1 ms, turning a
+ *  far-future expiry into a tight renewal loop. Clamp before we hand it over. */
+export const MAX_TIMER_DELAY_MS = 2_147_483_647;
+/** F2 — a hub-reported `expiresAt` further out than this is not believed for
+ *  scheduling (cloud cells issue ≤ 12 h; a month is already implausible). */
+export const MAX_CREDENTIAL_LIFETIME_MS = 30 * 24 * 60 * 60 * 1000;
+
+/**
+ * A hub-reported `expiresAt` sane enough to schedule against, or null.
+ *
+ * F2: the value crosses the DDR-054 trust boundary (a hub picks it) and is fed
+ * to `setTimeout`. A non-integer, a past stamp, or one absurdly far out (skew,
+ * or a hostile hub planting a far-future value to arm a tight loop) must not
+ * schedule a renewal — null means "no timer", the safe pre-existing behaviour.
+ * A credential already expired simply falls to the invalid-token path instead.
+ */
+export function validExpiry(raw: unknown, nowMs: number = Date.now()): number | null {
+  if (typeof raw !== 'number' || !Number.isInteger(raw)) return null;
+  if (raw <= nowMs) return null;
+  if (raw - nowMs > MAX_CREDENTIAL_LIFETIME_MS) return null;
+  return raw;
+}
 
 const AUTH_CLASS_HINT: Record<AuthFailureClass, string> = {
   'rate-limit':
@@ -202,6 +239,22 @@ export interface CreateSyncRuntimeOptions {
     settleTimeoutMs?: number;
     setTimer?: (cb: () => void, ms: number) => ReturnType<typeof setTimeout>;
     clearTimer?: (h: ReturnType<typeof setTimeout>) => void;
+    /**
+     * Silent credential renewal (cloud workspaces). Called single-flight at
+     * ~80 % of the stored credential's remaining life and on any
+     * `invalid-token` rejection; a non-null return swaps the runtime's token
+     * in place and re-probes rejected docs immediately. Default: the Maude
+     * Cloud renewal lane (`cloud/renew.ts`); it answers null for a machine
+     * that is not signed in, so self-hosted hubs keep today's behaviour.
+     * Never called under cell pairing (the cell's token comes from its env).
+     */
+    renewCredential?: () => Promise<{ token: string; expiresAt: number | null } | null>;
+    /** F1 — clock for the renewal frequency floor (test injection). Default Date.now. */
+    now?: () => number;
+    /** F1 — minimum ms between renewal attempts. Default RENEW_MIN_INTERVAL_MS. */
+    renewMinIntervalMs?: number;
+    /** F1 — consecutive no-progress renewals before giving up. Default RENEW_MAX_WITHOUT_PROGRESS. */
+    renewMaxWithoutProgress?: number;
   };
 }
 
@@ -355,14 +408,21 @@ export function createSyncRuntime(
   // this process in its environment. `~/.config/maude/hubs.json` is a PERSON's
   // credential store and does not exist in a cell (HOME=/tmp) — which is exactly
   // why the old guard was unreachable by accident rather than by design.
-  const resolvedToken = cellPairing ? cellPairing.token : getHubToken(linkedHub.url);
+  const storedRecord = cellPairing ? null : getHubRecord(linkedHub.url);
+  const resolvedToken = cellPairing ? cellPairing.token : (storedRecord?.token ?? null);
   if (!resolvedToken) {
     console.warn(
       `[sync] linked to ${linkedHub.url} but no token in ~/.config/maude/hubs.json. Re-run 'maude design link' on this machine. Solo mode for now.`
     );
     return null;
   }
-  const token: string = resolvedToken;
+  // MUTABLE on purpose: silent renewal swaps it in place, and connectCanvas
+  // reads it at call time — so every provider (re)created after a renewal
+  // carries the fresh credential without a runtime restart.
+  let token: string = resolvedToken;
+  // Through validExpiry (F2) — the stored value came off disk written from a
+  // hub body, so a bogus/far-future stamp must not schedule a renewal at boot.
+  let tokenExpiresAt: number | null = validExpiry(storedRecord?.expiresAt);
 
   // DDR-102 — the default factory multiplexes every provider over ONE shared
   // WebSocket per hub URL; the runtime owns its disposal (stop(), after the
@@ -418,6 +478,36 @@ export function createSyncRuntime(
   >();
   let authWarnTimer: TimerHandle | null = null;
   let reprobeTimer: TimerHandle | null = null;
+  let renewTimer: TimerHandle | null = null;
+  /** Single-flight guard: 73 rejected docs must trigger ONE renewal, not 73. */
+  let renewInFlight: Promise<boolean> | null = null;
+  // F1 (2026-08-10 security review) — RATE DISCIPLINE on the renew↔reprobe
+  // cycle. Single-flight bounds concurrency; these bound FREQUENCY. Without
+  // them a legitimate cell refusing on VOLUME (its invalid-token bucket, which
+  // now answers "invalid token — rate limited") classifies permanent →
+  // triggers renewal → renewal succeeds (the token was never the problem) →
+  // reprobeNow reconnects all N docs → the bucket refuses them again → loop.
+  // Reproduced at 2342 renewals/s. This is the exact retry-storm class the
+  // whole change exists to end, one level up — so it gets a floor AND a cap.
+  const renewNow = opts.auth?.now ?? (() => Date.now());
+  const renewMinIntervalMs = opts.auth?.renewMinIntervalMs ?? RENEW_MIN_INTERVAL_MS;
+  const renewMaxWithoutProgress = opts.auth?.renewMaxWithoutProgress ?? RENEW_MAX_WITHOUT_PROGRESS;
+  /** Wall-clock of the last renewal attempt (0 = never). The floor. */
+  let lastRenewAt = 0;
+  /** Successful renewals since the last completed handshake. The cap: a
+   *  renewal that keeps succeeding while nothing connects is not fixing
+   *  anything — stop, and let the link surface as refused/stalled. Reset to 0
+   *  at every `connected` doc (the handshake-success point). */
+  let renewalsSinceProgress = 0;
+  // Silent credential renewal (cloud). Absent under cell pairing — the cell's
+  // token arrives via its environment and is the hub's own to rotate.
+  const renewCredential = cellPairing
+    ? null
+    : (opts.auth?.renewCredential ??
+      (async () => {
+        const r = await renewHubCredential(linkedHub.url);
+        return r.ok ? { token: r.token, expiresAt: r.expiresAt } : null;
+      }));
   const settleTimers = new Set<TimerHandle>();
   /** Pending synthetic `fs:any` emissions (cell pairing only), keyed by the
    *  design-root-relative path so a second write to the same file inside the
@@ -446,6 +536,18 @@ export function createSyncRuntime(
     // honest seed (`connecting`, nothing known) the moment the runtime starts.
     resetPersistedStatus(ctx, linkedHub.url);
 
+    // Fix 4 (sync RCA 2026-08-10) — one-shot quarantine of the pre-fix-5 flat
+    // fallback twins, BEFORE the scan: a flat twin that survived into the scan
+    // would sync as its own document and re-seed the duplicate on every peer.
+    // Skipped under cell pairing — a cell's checkout is the hub's to manage,
+    // and quarantining there would dirty a tree the hub commits.
+    if (!cellPairing) {
+      migrateFlatFallback({
+        designRoot: ctx.paths.designRoot,
+        designRel: ctx.paths.designRel,
+      });
+    }
+
     const scan = opts.canvases ? { canvases: opts.canvases, tsxCount: 0 } : await scanCanvases(ctx);
     // DDR-064 pre-cutover A4 + A6 — two files must never share a document, and
     // the pinned set must be bounded. See `admitCanvases`.
@@ -753,22 +855,112 @@ export function createSyncRuntime(
       console.warn(`[sync] hub auth rejections (${linkedHub.url}):\n${lines.join('\n')}`);
     };
 
+    /** Reconnect every permanently-rejected doc now. Idempotent — the map is
+     *  drained, so a second call during the same burst is a no-op. */
+    const reprobeNow = (): void => {
+      if (stopped) return;
+      if (reprobeTimer !== null) {
+        authClearTimer(reprobeTimer);
+        reprobeTimer = null;
+      }
+      const entries = [...rejectedPermanent.values()];
+      rejectedPermanent.clear();
+      for (const entry of entries) {
+        mon.noteDocState(entry.canvas.slug, 'pending');
+        void connectCanvas(entry.canvas, entry.canvasPaths, entry.doc).catch((err) => {
+          console.error(`[sync/${entry.canvas.slug}] re-probe failed:`, err);
+        });
+      }
+    };
+
     const scheduleReprobe = (): void => {
       if (reprobeTimer !== null || stopped) return;
       reprobeTimer = authSetTimer(() => {
         reprobeTimer = null;
-        if (stopped) return;
-        const entries = [...rejectedPermanent.values()];
-        rejectedPermanent.clear();
-        for (const entry of entries) {
-          mon.noteDocState(entry.canvas.slug, 'pending');
-          void connectCanvas(entry.canvas, entry.canvasPaths, entry.doc).catch((err) => {
-            console.error(`[sync/${entry.canvas.slug}] re-probe failed:`, err);
-          });
-        }
+        reprobeNow();
       }, reprobeMs);
     };
 
+    /**
+     * Renew the hub credential in place — single-flight, silent, and never
+     * worse than failure: an unrenewable credential leaves the stored one
+     * untouched and every existing behaviour (slow re-probe, refused status)
+     * exactly as it was.
+     */
+    const renewCredentialNow = (): Promise<boolean> => {
+      if (!renewCredential || stopped) return Promise.resolve(false);
+      if (renewInFlight) return renewInFlight;
+      // F1 — the cap: renewals that keep succeeding without a handshake landing
+      // are not fixing anything (a real fix clears at least one doc, which
+      // resets this to 0). Stop, and let the docs' own rejected state surface
+      // as refused/stalled — both name "reconnect the workspace".
+      if (renewalsSinceProgress >= renewMaxWithoutProgress) return Promise.resolve(false);
+      // F1 — the floor: one renewal per interval, whatever the outcome. Stamped
+      // here (commit point), not on success, so a failing renewal also waits.
+      const sinceLast = renewNow() - lastRenewAt;
+      if (lastRenewAt !== 0 && sinceLast < renewMinIntervalMs) return Promise.resolve(false);
+      lastRenewAt = renewNow();
+      renewInFlight = (async () => {
+        try {
+          const fresh = await renewCredential();
+          if (stopped || !fresh || typeof fresh.token !== 'string' || !fresh.token) return false;
+          token = fresh.token;
+          tokenExpiresAt = validExpiry(fresh.expiresAt);
+          renewalsSinceProgress++;
+          console.log(`[sync] hub credential renewed for ${linkedHub.url}`);
+          scheduleRenewal();
+          return true;
+        } catch (err) {
+          console.warn(`[sync] hub credential renewal failed: ${(err as Error).message}`);
+          return false;
+        } finally {
+          renewInFlight = null;
+        }
+      })();
+      return renewInFlight;
+    };
+
+    /**
+     * Arm the pre-expiry renewal at ~80 % of the credential's REMAINING life
+     * (never sooner than a minute out). No stored expiry — a self-hosted hub,
+     * or a credential written before expiry was persisted — means no timer:
+     * exactly the old behaviour. A failed renewal retries on the re-probe
+     * cadence; once the credential actually dies, the invalid-token path
+     * below triggers renewal anyway, so the timer is an optimization, not the
+     * safety net.
+     */
+    const scheduleRenewal = (): void => {
+      if (renewTimer !== null) {
+        authClearTimer(renewTimer);
+        renewTimer = null;
+      }
+      if (!renewCredential || stopped || tokenExpiresAt === null) return;
+      // F2 — clamp both ends. The lower floor keeps a near-expiry credential
+      // from arming an immediate timer; the upper clamp stops a far-future
+      // `expiresAt` (validExpiry already rejects > 30 d, but a peer's clock
+      // skew can still land the *delay* past setTimeout's int32 ceiling, where
+      // it silently fires at 1 ms) from becoming a tight loop.
+      const raw = (tokenExpiresAt - renewNow()) * 0.8;
+      const delay = Math.min(MAX_TIMER_DELAY_MS, Math.max(60_000, raw));
+      renewTimer = authSetTimer(() => {
+        renewTimer = null;
+        void renewCredentialNow().then((ok) => {
+          // F4 — a failed pre-expiry renewal RE-ARMS on the slow cadence
+          // (through scheduleRenewal, so the frequency floor + cap still
+          // apply) instead of leaving the process with no scheduled renewal
+          // for the rest of its life.
+          if (!ok && !stopped && tokenExpiresAt !== null) {
+            renewTimer = authSetTimer(() => {
+              renewTimer = null;
+              void renewCredentialNow().then((ok2) => {
+                if (!ok2) scheduleRenewal();
+              });
+            }, reprobeMs);
+          }
+        });
+      }, delay);
+    };
+
     const handleAuthFailure = (
       canvas: CanvasDescriptor,
       canvasPaths: import('./agent.ts').CanvasSyncPaths,
@@ -777,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());
@@ -797,6 +992,17 @@ export function createSyncRuntime(
           }
           scheduleReprobe();
         }
+        // An invalid token is the one refusal the runtime can FIX: the stored
+        // credential expired (≤ 12 h cell sessions, Phase 23 B2) while the
+        // account next to it is still signed in. Renew silently — single-flight
+        // across the whole burst — and on success reconnect the rejected docs
+        // NOW instead of making the user wait out the slow re-probe (or press
+        // Connect again, which is all this ever needed).
+        if (reasonClass === 'invalid-token') {
+          void renewCredentialNow().then((renewed) => {
+            if (renewed) reprobeNow();
+          });
+        }
       }
     };
 
@@ -820,6 +1026,21 @@ export function createSyncRuntime(
       console.log(`[sync/${slug}] the hub accepted this document — clearing its refusal.`);
     };
 
+    /**
+     * Stamp `syncMeta.path` from where this canvas actually is on THIS disk —
+     * never echoed from the wire, so a value some receiver refused is never
+     * laundered onward by being re-sent. Best-effort: a failure never costs
+     * the canvas its sync.
+     */
+    const stampFromLocalFile = (doc: Y.Doc, htmlAbs: string): void => {
+      try {
+        const rel = path.relative(ctx.paths.designRoot, htmlAbs).split(path.sep).join('/');
+        if (rel && !rel.startsWith('..')) stampCanvasPath(doc, rel, ORIGINS.DISK_PROJECTION);
+      } catch {
+        /* best-effort bookkeeping — never costs the canvas its sync */
+      }
+    };
+
     /** Post-handshake reconcile — shared by first connect and re-probe. */
     const handleSynced = async (
       canvas: CanvasDescriptor,
@@ -881,21 +1102,18 @@ export function createSyncRuntime(
           }
         }
       }
-      // The path travels back OUT. `syncMeta.path` is stamped from where this
-      // canvas actually is on THIS disk — never echoed from the wire — so the
-      // next peer to receive this document can place it, and a value some
-      // receiver refused is never laundered onward by being re-sent.
-      try {
-        const rel = path.relative(ctx.paths.designRoot, canvasPaths.html).split(path.sep).join('/');
-        if (rel && !rel.startsWith('..'))
-          stampCanvasPath(provider.document, rel, ORIGINS.DISK_PROJECTION);
-      } catch {
-        /* best-effort bookkeeping — never costs the canvas its sync */
-      }
+      // The path travels back OUT — re-stamped post-reconcile as the belt to
+      // connectCanvas's pre-handshake braces (fix 5): this also covers a PULLED
+      // canvas, whose real local path exists only after relocatePulled ran.
+      stampFromLocalFile(provider.document, canvasPaths.html);
 
       // DDR-102 — honest status: the handshake + reconcile completed.
       mon.noteDocState(canvas.slug, 'connected');
       mon.noteSyncActivity(canvas.slug);
+      // F1 — a completed handshake IS progress: a renewal actually helped, so
+      // the no-progress cap resets. Without this a healthy link that renews
+      // legitimately every 12 h would burn one cap slot per renewal forever.
+      renewalsSinceProgress = 0;
     };
 
     /**
@@ -1070,6 +1288,17 @@ export function createSyncRuntime(
         document,
       });
       providers.set(canvas.slug, provider);
+      // Fix 5 (sync RCA 2026-08-10): stamp the canvas path BEFORE the
+      // handshake, not only after reconcile. The path derives from this peer's
+      // real local file, so it is known NOW — and the hub's FIRST
+      // onDocumentStored must see it, or it memoises a flat fallback in its
+      // pathIndex and a stub is born. Pulled canvases are the one exception:
+      // their local path is a guess until the document arrives, and a guessed
+      // stamp would be laundered into every other peer (handleSynced stamps
+      // them after relocatePulled instead).
+      if (!pulledSlugs.has(canvas.slug)) {
+        stampFromLocalFile(provider.document, canvasPaths.html);
+      }
       // First-connect setup (agent/projection creation + doc-scoped wiring)
       // MUST run before handleSynced — that function resolves the
       // agent/projection from the maps, and a test stub's onceSynced can
@@ -1311,7 +1540,33 @@ export function createSyncRuntime(
       // place after each handshake, and the markers are the one consumer that
       // read them before that and would otherwise never read them again.
       markUntrusted();
+
+      // DDR-217 (fix 6) — mirror local assets up AFTER the handshakes settle
+      // (they carry the canvases; assets ride behind, never in front). Not
+      // under pairing: a cell's assets are already on the cell. Fire-and-forget
+      // — a miss is retried on the next boot for free.
+      if (!cellPairing) {
+        void pushAssets({
+          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}`);
+        });
+      }
     });
+
+    // Arm the pre-expiry renewal from the credential that just booted. Placed
+    // last — the timer needs nothing from boot, and boot needs nothing from it
+    // (a credential that dies mid-boot lands in the invalid-token path, which
+    // triggers renewal on its own).
+    scheduleRenewal();
   }
 
   async function stop(): Promise<void> {
@@ -1367,6 +1622,10 @@ export function createSyncRuntime(
       authClearTimer(reprobeTimer);
       reprobeTimer = null;
     }
+    if (renewTimer !== null) {
+      authClearTimer(renewTimer);
+      renewTimer = null;
+    }
     for (const h of settleTimers) authClearTimer(h);
     settleTimers.clear();
     for (const h of announceTimers.values()) clearTimeout(h);

package/apps/studio/sync/migrate-flat-fallback.ts

@@ -0,0 +1,121 @@
+// One-shot quarantine of the pre-fix-5 flat fallback twins — fix 4 of the
+// 2026-08-10 sync RCA (v0.58.2's `f2a38c46` changed the fallback rule with no
+// migration of what the old rule had already written).
+//
+// Until then the no-path fallback wrote a pulled canvas FLAT at the design root
+// (`ui-welcome.tsx`); the group-aware fallback plus the stamp-race fix (phase
+// sync-2) stopped producing new ones, but whatever the old rule wrote is still
+// on disk NEXT TO the real grouped file — two files, one slug, one document
+// (DDR-064 A4's collision class), and the tree lists both.
+//
+// The rules, in migrate-seed.ts's posture (idempotent, best-effort, never
+// throws into boot):
+//
+//   - Only a flat file WITH a grouped twin of the same slug moves — the flat
+//     copy is provably the redundant one. A flat file with NO twin is a
+//     genuinely-flat canvas somebody authored; moving it would lose work, so
+//     it stays (fix 5 + a future re-sync relocates it).
+//   - Quarantine, never delete: the loser goes to `_trash/<slug>-flat-<ts>/`
+//     (the established runtime quarantine, DDR-115), `.meta.json`/`.css`
+//     siblings riding along. The `<slug>.annotations.svg` sidecar does NOT
+//     move — annotations are keyed by the flat slug at the design root and
+//     serve the surviving grouped twin.
+//   - One log line per move, so a tenant can find their bytes.
+
+import { type Dirent, existsSync, mkdirSync, readdirSync, renameSync } from 'node:fs';
+import path from 'node:path';
+
+import { canvasSlugFromRel } from '../canvas-slug.ts';
+
+export interface FlatFallbackMove {
+  slug: string;
+  /** Design-root-relative flat body that moved. */
+  from: string;
+  /** Design-root-relative grouped body that made it redundant. */
+  keptTwin: string;
+  /** Design-root-relative quarantine dir the flat set landed in. */
+  trashedTo: string;
+}
+
+/**
+ * Scan the design root, quarantine every flat body whose slug a grouped file
+ * also claims. Returns what moved (empty on a clean tree — the idempotent
+ * steady state). Never throws.
+ */
+export function migrateFlatFallback(opts: {
+  designRoot: string;
+  /** Design root relative to the repo root (`.design`) — for slug derivation. */
+  designRel: string;
+  log?: (line: string) => void;
+}): FlatFallbackMove[] {
+  const { designRoot, designRel } = opts;
+  const log = opts.log ?? ((line: string) => console.log(line));
+  const moves: FlatFallbackMove[] = [];
+  try {
+    // slug → every body path claiming it, design-root-relative.
+    const claims = new Map<string, string[]>();
+    for (const rel of walk(designRoot)) {
+      if (!/\.tsx$/i.test(rel)) continue;
+      const slug = canvasSlugFromRel(rel, designRel);
+      const list = claims.get(slug);
+      if (list) list.push(rel);
+      else claims.set(slug, [rel]);
+    }
+
+    for (const [slug, rels] of claims) {
+      const flat = rels.find((rel) => !rel.includes('/'));
+      const twin = rels.find((rel) => rel.includes('/'));
+      if (!flat || !twin) continue;
+
+      const trashedTo = `_trash/${slug}-flat-${Date.now()}`;
+      const base = flat.replace(/\.tsx$/i, '');
+      const movedLanes: string[] = [];
+      try {
+        mkdirSync(path.join(designRoot, trashedTo), { recursive: true });
+        for (const lane of [flat, `${base}.meta.json`, `${base}.css`]) {
+          const src = path.join(designRoot, lane);
+          if (!existsSync(src)) continue;
+          renameSync(src, path.join(designRoot, trashedTo, path.basename(lane)));
+          movedLanes.push(lane);
+        }
+      } catch (err) {
+        log(
+          `[sync/migrate-flat-fallback] could not quarantine ${flat}: ${(err as Error).message} — leaving it in place`
+        );
+        continue;
+      }
+      moves.push({ slug, from: flat, keptTwin: twin, trashedTo });
+      log(
+        `[sync/migrate-flat-fallback] ${flat} duplicated ${twin} (slug ${slug}) — moved ${movedLanes.join(
+          ', '
+        )} to ${trashedTo}/`
+      );
+    }
+  } catch {
+    /* best-effort — a scan failure must never cost the boot */
+  }
+  return moves;
+}
+
+/** Files under `dir`, relative to it, skipping runtime-state (`_*`) and repo
+ *  internals — the same exclusions the hub's checkout scan applies. */
+function walk(dir: string, prefix = '', out: string[] = []): string[] {
+  let entries: Dirent[];
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const entry of entries) {
+    const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) {
+      if (entry.name.startsWith('_') || entry.name === '.git' || entry.name === 'node_modules') {
+        continue;
+      }
+      walk(path.join(dir, entry.name), rel, out);
+    } else if (entry.isFile()) {
+      out.push(rel);
+    }
+  }
+  return out;
+}