@1agh/maude 0.58.2 → 0.58.3

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 };

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,
@@ -797,6 +989,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 +1023,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 +1099,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 +1285,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 +1537,27 @@ 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,
+        }).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 +1613,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);