@1agh/maude 1.0.11 → 1.3.0

package/apps/studio/sync/index.ts

@@ -24,6 +24,8 @@ import {
   readFileSync,
   realpathSync,
   renameSync,
+  rmdirSync,
+  rmSync,
   writeFileSync,
 } from 'node:fs';
 import { readdir } from 'node:fs/promises';
@@ -36,6 +38,8 @@ 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 { acceptedColdStart } from './accepted-cold-start.ts';
+import { type AcceptedLink, createAcceptedLink } from './accepted-link.ts';
 import { type CanvasSyncAgent, createCanvasSyncAgent } from './agent.ts';
 import { isPushableAssetRel, pushAssets } from './asset-push.ts';
 import { atomicWrite } from './atomic-write.ts';
@@ -43,6 +47,7 @@ import { type CellPairing, resolveCellPairing, sanitizeForLog } from './cell-pai
 import {
   canvasPathFromDoc,
   clearMovedTo,
+  laneValueFromFile,
   movedToFromDoc,
   stampCanvasPath,
   stampMovedTo,
@@ -55,9 +60,10 @@ import {
 import { createCtlProvider } from './ctl-provider.ts';
 import { createRescanScheduler, diffCanvasSet, type RescanScheduler } from './discovery.ts';
 import { createDocNameResolver } from './doc-name.ts';
-import { createEchoGuard } from './echo-guard.ts';
+import { createDocumentDiscovery } from './document-discovery.ts';
+import { createEchoGuard, hashBytes } from './echo-guard.ts';
 import { createFileLedger } from './file-ledger.ts';
-import { createFilePlane } from './file-plane.ts';
+import { createFilePlane, MAX_DORUCEKA_ROWS } from './file-plane.ts';
 import { type FilePullResult, pullFiles } from './file-pull.ts';
 import { createFsReader, type FsReader } from './fs-mirror.ts';
 import { type HubDocRow, hubHolds, indexHubDocs } from './hub-listing.ts';
@@ -80,6 +86,9 @@ import {
   stateDocumentGone,
   tombstonedSlugs,
 } from './remote-docs.ts';
+import { createRevisionBarrier } from './revision-barrier.ts';
+import { computeSeedProgress } from './seed-progress.ts';
+import { replaySourceOp, type SourceOp } from './source-ops.ts';
 import { createSyncStatusStore, type SyncStatusStore } from './status.ts';
 import { quarantineCanvas } from './tombstone-apply.ts';
 import { writeUntrustedMarkers } from './untrusted.ts';
@@ -94,8 +103,38 @@ export interface SyncProvider {
    * the bridge.
    */
   readonly awareness?: Awareness;
-  /** Resolves when the first hub sync handshake completes. */
-  onceSynced(): Promise<void>;
+  /**
+   * Did this transaction origin come off the wire from the hub? Accepted
+   * revisions use it as a tripwire: under a fenced (read-only) connection any
+   * OTHER origin is a local write the hub will drop — a replica diverging.
+   * Optional: a test stub without it is simply not checked.
+   */
+  isRemoteOrigin?(origin: unknown): boolean;
+  /**
+   * May a local write to this document reach the hub right now? False before
+   * the handshake authenticates and whenever the hub admitted this connection
+   * read-only — a write made then is dropped by the hub while the local
+   * replica keeps it, which is a divergence nothing would ever repair.
+   * Optional: a provider without it is treated as writable.
+   */
+  isWritable?(): boolean;
+  /** The hub authenticated this connection (again) — scope may have changed. */
+  onAuthenticated?(cb: (scope: string) => void): () => void;
+  /** Out-of-band messages from the hub on this document's socket. */
+  onStateless?(cb: (payload: string) => void): () => void;
+  /**
+   * Resolves when the first hub sync handshake completes.
+   *
+   * `signal` lets a caller that gives up ALSO detach the underlying listener.
+   * Without it, every abandoned wait leaks a `synced` listener plus its closure
+   * for the life of the provider — bounded at one per slug while a wedged
+   * single-flight latch kept the caller from retrying, and UNBOUNDED the moment
+   * that latch was correctly fixed to release (verification review 2026-09-03,
+   * N2): one per slug per settle window per flap, all firing at once if a sync
+   * ever lands. Optional, so a test stub or a provider without the plumbing is
+   * unaffected.
+   */
+  onceSynced(signal?: AbortSignal): Promise<void>;
   /**
    * Subscribe to WS connection-status transitions (Phase 9 Task 8 offline
    * mode). Returns an unsubscribe fn. Optional — a test stub or a provider
@@ -113,9 +152,10 @@ export interface SyncProvider {
 /* ------------------------------------------------- auth-failure classification */
 
 /** DDR-102 — rejection classes the runtime distinguishes. `rate-limit` and
- *  `generic` are transient (provider backoff keeps retrying); `not-authorized`
- *  and `invalid-token` are permanent (retrying spams the hub bucket — destroy
- *  the provider and re-probe on a slow timer instead). */
+ *  `generic` are transient (the runtime re-authenticates the refused document
+ *  after one hub window, paced and backed off — see `AUTH_TRANSIENT_RETRY_MS`);
+ *  `not-authorized` and `invalid-token` are permanent (retrying spams the hub
+ *  bucket — destroy the provider and re-probe on a slow timer instead). */
 export type AuthFailureClass = 'rate-limit' | 'not-authorized' | 'invalid-token' | 'generic';
 
 /** Map a raw hub rejection reason to a class. New hubs send distinct reasons
@@ -136,14 +176,54 @@ export function classifyAuthFailure(raw: string): AuthFailureClass {
 
 export const AUTH_WARN_DEBOUNCE_MS = 2_000;
 export const AUTH_REPROBE_MS = 5 * 60 * 1000;
+/**
+ * How long a transiently-refused document (`rate-limit` / `generic`) waits
+ * before the runtime asks the hub again — one full hub window, since the
+ * refusal itself says "retry in up to 60s".
+ *
+ * The runtime owns this retry because nothing else will do it. These classes
+ * used to be left to "the provider's built-in backoff", which does not exist
+ * per document under DDR-102 multiplexing: a provider re-sends its token only
+ * when the SHARED socket opens, and a partial refusal never closes a socket
+ * that the documents which did authenticate keep busy. 16 of 112 canvases sat
+ * `auth-rejected` for the life of the process that way (RCA
+ * issue-sync-rate-limited-docs-never-retried, 2026-09-11).
+ *
+ * Repeat refusals of the same document double this, capped at the re-probe
+ * interval; a handshake that lands resets it.
+ */
+export const AUTH_TRANSIENT_RETRY_MS = 60_000;
+/** Random spread added to each transient retry, so peers refused in the same
+ *  burst do not all come back on the window boundary together. */
+export const AUTH_TRANSIENT_JITTER_MS = 15_000;
+/**
+ * Most transient re-authentications inside any `AUTH_TRANSIENT_RETRY_MS` span.
+ * A quarter of the hub's default valid-token ceiling (600/min): a 16-document
+ * retry never notices it, and a 1 000-canvas project cannot turn its own
+ * recovery into the next burst (the F1 lesson, applied to this lane).
+ */
+export const AUTH_TRANSIENT_BATCH = 150;
 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. */
+/**
+ * F1 — consecutive successful renewals with NO PROGRESS in between before the
+ * runtime stops renewing and lets the link surface as refused/stalled.
+ *
+ * The cap itself is load-bearing: it is what stopped a reproduced 2 342
+ * renewals/s storm (2026-08-10 security review). What changed on 2026-09-03 is
+ * the definition of "progress".
+ *
+ * It used to mean ONLY a completed doc handshake, on the reasoning that "a
+ * renewal that fixed the credential clears at least one doc". That is true
+ * exactly when the doc lane is the lane with work. During a long file seed
+ * against an already-converged doc lane (85/87 synced, no handshakes left to
+ * land) there is nothing to clear — so every legitimate pre-expiry renewal
+ * burned a slot, three of them exhausted the cap, and the runtime stopped
+ * renewing while the file plane was still transferring. A delivered FILE now
+ * counts too (`onProgress` on the file plane).
+ */
 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. */
@@ -167,6 +247,45 @@ export const DISCOVERY_DEBOUNCE_MS = 400;
  */
 export const REMOTE_POLL_MS = 20_000;
 
+/** Floor between two serve-log seed-progress lines. Long enough not to become
+ *  the next thing that buries the log. */
+export const SEED_PROGRESS_LOG_MS = 15_000;
+/** How often the stall watchdog looks (issue #118). Cheap — one snapshot. */
+export const STALL_CHECK_MS = 30_000;
+/**
+ * "Socket connected, not one document synced" for this long is a stall, not a
+ * slow handshake. Comfortably above a cold cell's worst observed wake (a
+ * measured `/health` on a sleeping cell answered in 14 s) and above the boot
+ * settle ceiling, so a healthy-but-slow link is never interrupted.
+ */
+export const STALL_RECONNECT_AFTER_MS = 3 * 60 * 1000;
+/** Floor between watchdog-forced reconnects — a hub that is simply down must
+ *  not be turned into a reconnect storm by its own silence. */
+export const STALL_RECONNECT_MIN_MS = 5 * 60 * 1000;
+/**
+ * Per-ATTEMPT deadline for the shared hub socket.
+ *
+ * The provider defaults to `timeout: 0` — no deadline at all — and its retry
+ * attempt resolves only on the first MESSAGE. A DO holding an upgrade open
+ * while a container boots therefore parks one attempt indefinitely, and
+ * `onClose` refuses to re-arm while a retry chain is live
+ * (`if (!this.cancelWebsocketRetry …)`), so the whole socket goes deaf. A
+ * finite attempt is what turns that into a retry.
+ */
+/**
+ * Random spread added ONCE per runtime to the stall threshold.
+ *
+ * A cell sleeping (or a hub restarting) drops every peer's socket in the same
+ * instant, so without this every peer's threshold expires inside one
+ * `STALL_CHECK_MS` tick of every other and they all re-authenticate N documents
+ * at once — the DDR-102 2026-06-11 retry storm, re-armed automatically every
+ * few minutes (attacker review 2026-09-03, F6). The floor below backs off on
+ * repeat for the same reason.
+ */
+export const STALL_JITTER_MS = 120 * 1000;
+/** Ceiling for the backed-off floor between forced reconnects. */
+export const STALL_RECONNECT_MAX_MS = 30 * 60 * 1000;
+
 /**
  * Settle window before a local write triggers a file-plane pass.
  *
@@ -176,6 +295,18 @@ export const REMOTE_POLL_MS = 20_000;
  */
 export const FILE_PASS_DEBOUNCE_MS = 400;
 
+/**
+ * The floor between two file-plane passes — issue #109.
+ *
+ * The debounce coalesces a burst of local writes; it does nothing about a
+ * steady drip, and a hub's file-event channel is a steady drip by design
+ * ("cloud changes now arrive in seconds"). 400 ms of spacing times 200
+ * requests a pass is 30k requests a minute at a door that opens 600 times.
+ * Two seconds is still well inside "arrives in seconds" and puts the client's
+ * ceiling an order of magnitude below the server's instead of above it.
+ */
+export const MIN_PASS_INTERVAL_MS = 2_000;
+
 /**
  * Settling delay for an OFF-SCHEDULE poll (reconnect).
  *
@@ -200,6 +331,11 @@ export const REMOTE_POLL_SOON_MS = 1_500;
  * edits arrive in seconds, bounded enough that spam buys almost nothing.
  */
 export const POKE_COOLDOWN_MS = REMOTE_POLL_MS / 2;
+/** Accepted revisions: how soon, and how often at most, a poke pulls. */
+export const ACCEPTED_POKE_DELAY_MS = 60;
+/** T16 — how long the last tool write of an AI action gets to reach the stage. */
+export const AI_ACTION_SETTLE_MS = 250;
+export const ACCEPTED_POKE_COOLDOWN_MS = 1_000;
 
 /**
  * How many previously-unknown canvases one listing may land.
@@ -235,13 +371,13 @@ export function validExpiry(raw: unknown, nowMs: number = Date.now()): number |
 
 const AUTH_CLASS_HINT: Record<AuthFailureClass, string> = {
   'rate-limit':
-    'boot burst hit the hub rate limit — sync settles as providers back off; if persistent, raise HUB_CONN_RATE_LIMIT on the hub (DDR-102 hubs default to 600/min for valid tokens).',
+    'refused on volume — retrying these in ~60 s, in paced batches (no restart needed). If this repeats every boot, the hub’s HUB_CONN_RATE_LIMIT is below this project’s size (DDR-102 hubs default to 600/min for valid tokens; every canvas authenticates separately).',
   'not-authorized':
     "the token's scope does not cover these canvases — mint a hub-wide token (`maude hub token generate --scope '*'` or an admin-UI invite) and re-link. Retries stopped; re-probing in 5 min.",
   'invalid-token':
     'the stored token was rejected — re-run `maude design link <url> --token …` on this machine. Retries stopped; re-probing in 5 min.',
   generic:
-    'the hub refused auth without a specific reason (older hub?) — check `maude design status` and the hub logs.',
+    'the hub refused auth without a specific reason (older hub?) — retrying these in ~60 s; if it keeps refusing, check `maude design status` and the hub logs.',
 };
 
 /**
@@ -346,9 +482,120 @@ export interface SyncRuntime {
    * flag-off) — the caller then proceeds with the plain local move.
    */
   retireForMove(fromSlug: string, toRel: string): Promise<boolean>;
+  /**
+   * Accepted-revisions mode (DDR-241): propose one lane value of a synced
+   * canvas that a privileged API route produced (comments, annotations).
+   * `null` when the project is not in that mode or this runtime does not carry
+   * the canvas — the caller then writes the shared document as before.
+   */
+  proposeLane?(
+    slug: string,
+    lane: 'comments' | 'annotations' | 'meta',
+    text: string,
+    opts?: { baseText?: string; writeId?: string }
+  ): Promise<{ status: 'accepted' | 'rejected'; code?: string }> | null;
+  /**
+   * Accepted-revisions mode: a folder operation as ONE project action. `null`
+   * when the project is not in that mode; otherwise the (possibly queued)
+   * outcome. Canvases inside are moved/deleted by the hub, not one by one.
+   */
+  proposeFolder?(
+    op:
+      | { op: 'dir.create'; path: string }
+      | { op: 'dir.delete'; path: string }
+      | {
+          op: 'dir.move';
+          from: string;
+          to: string;
+        }
+  ): Promise<{ status: 'accepted' | 'rejected'; code?: string; queued?: boolean }> | null;
+  /** True while the linked project is in accepted-revisions mode. */
+  acceptedMode?(): boolean;
+  /** Tripwire count: local writes that reached an accepted replica. */
+  acceptedWriteViolations?(): number;
+  /** Accepted revisions: the project's logical history (T27). Null when legacy. */
+  acceptedHistory?(q: {
+    limit?: number;
+    before?: number | null;
+    path?: string | null;
+  }): Promise<AcceptedHistoryRow[] | null>;
+  /** A canvas source (repo-relative path) as it stood at a revision. */
+  acceptedVersion?(repoRel: string, revision: number): Promise<string | null>;
+  /** Restore a canvas to a revision as a NEW action. */
+  acceptedRestore?(
+    repoRel: string,
+    revision: number
+  ): Promise<{ status: 'accepted' | 'rejected'; code?: string; queued?: boolean } | null>;
+  /** Personal undo/redo of one of this actor's accepted actions (T28). */
+  acceptedUndo?(
+    actionId: string,
+    redo?: boolean
+  ): Promise<{
+    status: 'accepted' | 'rejected';
+    code?: string;
+    queued?: boolean;
+    actionId?: string;
+  } | null>;
+  /**
+   * T16 — an AI action begins: file changes tools make until it ends are
+   * published together as one action (see action-stage.ts). `key` names the
+   * participant (an agent turn, a /design:edit run).
+   */
+  beginAiAction?(key: string, label: string): void;
+  /** T16 — `done` publishes (when the last participant ends); `failed` holds. */
+  endAiAction?(
+    key: string,
+    outcome: 'done' | 'failed'
+  ): Promise<{ status: 'accepted' | 'rejected'; code?: string } | null>;
+  /**
+   * T19 — make the whole project available offline now: file-plane passes
+   * back to back (no pacing floor) until nothing is left to pull, or a pass
+   * stops making progress. Resolves with what came down and what could not.
+   */
+  prepareOffline?(): Promise<{
+    complete: boolean;
+    pulled: number;
+    passes: number;
+    failed: number;
+  } | null>;
+  /** T26 — the accepted action that carried this content of a canvas, if ours. */
+  acceptedActionForContent?(repoRel: string, content: string): string | null;
+  /** T28 — the two sides of a canvas's held source conflict. */
+  conflictVersions?(repoRel: string): { slug: string; mine: string | null; theirs: string } | null;
+  /**
+   * T28 — resolve it: `mine` proposes the local version on top of the
+   * project's (a new action), `theirs` takes the project's version.
+   */
+  resolveConflict?(
+    repoRel: string,
+    choice: 'mine' | 'theirs'
+  ): Promise<{ status: 'accepted' | 'rejected' | 'taken'; code?: string } | null>;
+  /** T16 — the person's decision on a held (unfinished) AI action. */
+  resolveAiAction?(choice: 'publish' | 'discard'): Promise<{
+    status: 'accepted' | 'rejected' | 'discarded';
+    code?: string;
+    canvases?: number;
+  } | null>;
+}
+
+export interface AcceptedHistoryRow {
+  revision: number;
+  actionId: string;
+  actor: string;
+  mine: boolean;
+  kind: string;
+  label: string | null;
+  committedAt: number;
+  undoes: string | null;
+  /** Design-root-relative canvas paths the action touched. */
+  canvases: string[];
 }
 
 export interface CreateSyncRuntimeOptions {
+  /** Transaction transport override (tests) — defaults to global fetch. */
+  transactionFetch?: typeof fetch;
+  /** Base backoff between re-sends of an unanswered proposal (tests). */
+  transactionRetryMs?: number;
   /** Override the HocuspocusProvider factory (test injection). */
   providerFactory?: ProviderFactory;
   /** Force-enable/disable adopt mode (overrides cfg.linkedHub.adopt). */
@@ -361,6 +608,22 @@ export interface CreateSyncRuntimeOptions {
    * unit tests that only exercise the file-sync path.
    */
   registry?: AwarenessRegistry;
+  /**
+   * Stall-watchdog timings + clock. TEST INJECTION ONLY (see `stallCheck`).
+   *
+   * The watchdog shipped with no behavioural coverage at all — three review
+   * rounds each found a HIGH inside it, and none of them could have been caught
+   * by a test, because nothing could reach it: it required the OWNED factory
+   * and real wall-clock minutes. This is the seam that makes its predicate,
+   * its jitter and its backoff assertable.
+   */
+  stall?: {
+    checkMs?: number;
+    afterMs?: number;
+    minMs?: number;
+    jitterMs?: number;
+    now?: () => number;
+  };
   /**
    * Override the offline-mode connection monitor (Task 8 test injection —
    * lets tests pass injectable timers/clock). Defaults to a real monitor that
@@ -398,6 +661,14 @@ export interface CreateSyncRuntimeOptions {
     renewMinIntervalMs?: number;
     /** F1 — consecutive no-progress renewals before giving up. Default RENEW_MAX_WITHOUT_PROGRESS. */
     renewMaxWithoutProgress?: number;
+    /** Base wait before a transient refusal is retried. Default AUTH_TRANSIENT_RETRY_MS. */
+    transientRetryMs?: number;
+    /** Max random spread per transient retry. Default AUTH_TRANSIENT_JITTER_MS. */
+    transientJitterMs?: number;
+    /** Transient re-auths allowed per `transientRetryMs` span. Default AUTH_TRANSIENT_BATCH. */
+    transientBatch?: number;
+    /** Jitter source (test injection). Default Math.random. */
+    random?: () => number;
   };
 }
 
@@ -636,8 +907,67 @@ export function createSyncRuntime(
   // registry can hand us the canvas's single doc. Flag OFF / no registry / a
   // minimal test registry without getDoc → the proven two-doc path, unchanged.
   const useSharedDoc = !!ctx.sharedDoc && typeof opts.registry?.getDoc === 'function';
+  // ---- ACCEPTED REVISIONS (DDR-241) ----------------------------------------
+  //
+  // Asked of the hub at start and on every poll — never assumed. In
+  // `transactions` mode this runtime writes NO shared document: every local
+  // change is a proposal through the durable outbox, and the documents change
+  // when the project publishes the accepted revision. Shared-doc only: the
+  // two-doc agent path has no proposal lane and stays legacy.
+  const acceptedLink: AcceptedLink | null = useSharedDoc
+    ? createAcceptedLink({
+        hubUrl: linkedHub.url,
+        token: () => token,
+        designRoot: ctx.paths.designRoot,
+        docNameFor: (slug) => docNameFor(slug),
+        fetchImpl: opts.transactionFetch,
+        retryMs: opts.transactionRetryMs,
+        onStats: (stats) => statusStore?.updateAccepted?.(stats),
+        onStage: (summary) => statusStore?.updateAiAction?.(summary),
+      })
+    : null;
+  const acceptedOn = (): boolean => acceptedLink?.on() === true;
+  /**
+   * T26 — which accepted action carried a given canvas content of ours, so the
+   * shell's Cmd+Z of an edit can undo THAT action (effect-aware) instead of
+   * swapping the whole file back. Bounded; keyed by slug + lane + content hash.
+   */
+  const acceptedByContent = new Map<string, string>();
+  const noteAcceptedContent = (slug: string, lane: string, value: string, actionId: string) => {
+    acceptedByContent.set(`${slug}|${lane}|${hashBytes(value)}`, actionId);
+    if (acceptedByContent.size > 500) {
+      const oldest = acceptedByContent.keys().next().value;
+      if (oldest !== undefined) acceptedByContent.delete(oldest);
+    }
+  };
+  /** T14 — one barrier for every projection: a revision shows whole. */
+  const revisionBarrier = createRevisionBarrier();
+  /** Canvases a folder action already moved/deleted — nothing more to propose for them. */
+  const coveredByFolderAction = new Set<string>();
+  /** Folder entries this peer has materialized from the project manifest. */
+  const knownProjectDirs = new Set<string>();
+  /** Local writes that reached an accepted replica (tripwire; should stay 0). */
+  let acceptedWriteViolations = 0;
+  /** The synced canvas at a repo-relative (or design-root-relative) path. */
+  const slugForRepoRel = (rel: string): string | null => {
+    const clean = String(rel).replace(/\\/g, '/').replace(/^\/+/, '');
+    for (const abs of [
+      path.join(ctx.paths.repoRoot, clean),
+      path.join(ctx.paths.designRoot, clean),
+    ]) {
+      for (const [slug, d] of descriptors) if (d.html === abs) return slug;
+    }
+    return null;
+  };
+  const describeOrigin = (origin: unknown): string => {
+    if (origin === null || origin === undefined) return String(origin);
+    if (typeof origin === 'string') return origin.slice(0, 40);
+    if (typeof origin === 'object') return (origin as object).constructor?.name ?? 'object';
+    return typeof origin;
+  };
   let fsReader: FsReader | null = null;
   let busUnsub: (() => void) | null = null;
+  const activityUnsubs: Array<() => void> = [];
   let started = false;
   let stopped = false;
   // ---- THE LEGACY PUSH CLIENT (journal-less hubs only) --------------------
@@ -769,11 +1099,56 @@ export function createSyncRuntime(
   const pendingAuthWarn = new Map<AuthFailureClass, Set<string>>();
   /** Latest rejection class per slug — feeds the boot summary detail. */
   const rejectedReasons = new Map<string, AuthFailureClass>();
+  /**
+   * EVERY document the hub has refused this episode, in ANY class.
+   *
+   * `rejectedPermanent` holds only the two classes that destroy the provider;
+   * `generic` (what every pre-DDR-102 hub sends) and `rate-limit` are absent
+   * from it by design. Anything asking "has the hub refused this document?"
+   * must ask HERE — reading `rejectedPermanent` for that question is how a
+   * transient refusal got laundered into a green row (attacker review
+   * 2026-09-03, F3). Emptied only by `clearRejection`, i.e. by a handshake the
+   * hub actually completed.
+   */
+  const rejectedAny = new Set<string>();
   /** Permanently-rejected docs awaiting a slow re-probe (provider destroyed). */
   const rejectedPermanent = new Map<
     string,
     { canvas: CanvasDescriptor; canvasPaths: import('./agent.ts').CanvasSyncPaths; doc: Y.Doc }
   >();
+  /**
+   * Transiently-refused docs (`rate-limit` / `generic`) awaiting the paced
+   * retry — see `AUTH_TRANSIENT_RETRY_MS`. Unlike `rejectedPermanent` the
+   * provider is KEPT until the retry swaps it (a refused provider sends nothing
+   * more, so there is no storm to stop), and the retry acts only if `provider`
+   * is still the live one: a release or another recovery path that replaced it
+   * in the meantime owns the document now. `dueAt` is on the `renewNow` clock.
+   */
+  const rejectedTransient = new Map<
+    string,
+    {
+      canvas: CanvasDescriptor;
+      canvasPaths: import('./agent.ts').CanvasSyncPaths;
+      doc: Y.Doc;
+      provider: SyncProvider;
+      dueAt: number;
+    }
+  >();
+  /** Consecutive transient refusals per slug — the backoff exponent. Emptied
+   *  by `clearRejection`, i.e. by a handshake the hub completed. */
+  const transientStrikes = new Map<string, number>();
+  /** When each transient re-auth of the last window went out — the sliding
+   *  budget. Never longer than `transientBatch`. */
+  const transientSpent: number[] = [];
+  let transientRetryTimer: TimerHandle | null = null;
+  /**
+   * First-connect setup still OWED to a pulled canvas whose first handshake
+   * has not landed (`connectCanvas` defers it — the body path is unknown until
+   * the document arrives). Every reconnect passes it back in: without it a
+   * refusal at that first handshake stranded the setup, and the hub's eventual
+   * yes synced the document into memory while nothing ever wrote it to disk.
+   */
+  const owedSetups = new Map<string, (provider: SyncProvider) => void>();
   let authWarnTimer: TimerHandle | null = null;
   let reprobeTimer: TimerHandle | null = null;
   let renewTimer: TimerHandle | null = null;
@@ -790,6 +1165,10 @@ export function createSyncRuntime(
   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;
+  const transientRetryMs = opts.auth?.transientRetryMs ?? AUTH_TRANSIENT_RETRY_MS;
+  const transientJitterMs = opts.auth?.transientJitterMs ?? AUTH_TRANSIENT_JITTER_MS;
+  const transientBatch = Math.max(1, opts.auth?.transientBatch ?? AUTH_TRANSIENT_BATCH);
+  const authRandom = opts.auth?.random ?? Math.random;
   /** Wall-clock of the last renewal attempt (0 = never). The floor. */
   let lastRenewAt = 0;
   /** Successful renewals since the last completed handshake. The cap: a
@@ -797,6 +1176,14 @@ export function createSyncRuntime(
    *  anything — stop, and let the link surface as refused/stalled. Reset to 0
    *  at every `connected` doc (the handshake-success point). */
   let renewalsSinceProgress = 0;
+  /**
+   * When a document last reached `connected` — the ONLY evidence that this link
+   * is doing its job. Seeded at runtime construction so the stall watchdog
+   * (`armStallWatchdog`) measures from "when we started trying", exactly like
+   * `SyncStatusSnapshot.startedAt`, rather than from a promotion that may never
+   * come. Moves on first connect, on re-probe and on reconnect re-promotion.
+   */
+  let lastPromotionAt = 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
@@ -804,7 +1191,13 @@ export function createSyncRuntime(
     : (opts.auth?.renewCredential ??
       (async () => {
         const r = await renewHubCredential(linkedHub.url);
-        return r.ok ? { token: r.token, expiresAt: r.expiresAt } : null;
+        if (r.ok) return { token: r.token, expiresAt: r.expiresAt };
+        // The reason was computed and thrown away. `renewHubCredential`
+        // distinguishes signed-out from revoked from removed-from-project from
+        // unreachable — each a different sentence to a person — and every one of
+        // them reached the log as the same silence. Say which.
+        console.warn(`[sync] hub credential renewal declined: ${r.reason}`);
+        return null;
       }));
   const settleTimers = new Set<TimerHandle>();
   /** Pending synthetic `fs:any` emissions (cell pairing only), keyed by the
@@ -831,6 +1224,23 @@ export function createSyncRuntime(
   let createdUnsub: (() => void) | null = null;
   /** Periodic remote-document poll — the hub-side half of discovery. */
   let remotePollTimer: ReturnType<typeof setInterval> | null = null;
+  /** The stall watchdog's tick — see `stallCheck` in `start()`. */
+  let stallTimer: ReturnType<typeof setInterval> | null = null;
+  /** Wall-clock of the last watchdog-forced reconnect (0 = never). The floor
+   *  that keeps a silent hub from becoming a reconnect storm. */
+  let lastForcedReconnectAt = 0;
+  /** Forced reconnects so far — the exponent of the backing-off floor. */
+  let forcedReconnects = 0;
+  /** This runtime's slice of `STALL_JITTER_MS`, drawn once so peers that lost
+   *  their sockets together do not fire together. */
+  const stallNow = opts.stall?.now ?? (() => Date.now());
+  // Seeded from the same clock the watchdog reads, so "nothing has settled
+  // since we started trying" is measured against a consistent origin.
+  lastPromotionAt = stallNow();
+  const stallCheckMs = opts.stall?.checkMs ?? STALL_CHECK_MS;
+  const stallAfterMs = opts.stall?.afterMs ?? STALL_RECONNECT_AFTER_MS;
+  const stallMinMs = opts.stall?.minMs ?? STALL_RECONNECT_MIN_MS;
+  const stallJitterMs = opts.stall?.jitterMs ?? Math.floor(Math.random() * STALL_JITTER_MS);
   /**
    * The file-event control channel (Sync v2 Increment 2), when the hub
    * advertises one. Null on a journal-less hub, in a cell (the child holds it
@@ -867,6 +1277,8 @@ export function createSyncRuntime(
   let pokesSeen = 0;
   /** Assigned by `start()`; the seam `pullRemoteNow()` and tests reach. */
   let remotePull: (() => Promise<void>) | null = null;
+  let documentDiscovery: ReturnType<typeof createDocumentDiscovery> | null = null;
+  let documentDiscoveryUnsub: (() => void) | null = null;
   /**
    * Run a file-plane pass shortly, coalesced.
    *
@@ -881,14 +1293,73 @@ export function createSyncRuntime(
     if (stopped || filePassTimer !== null) return;
     filePassTimer = setTimeout(() => {
       filePassTimer = null;
-      if (stopped || !filePlane) return;
-      void filePlane
-        .reconcile()
-        .then((r) => planeResultSink?.(r))
-        .catch((err) => console.error('[sync/files] pass failed:', err));
+      void runPlanePass();
     }, FILE_PASS_DEBOUNCE_MS);
     filePassTimer.unref?.();
   }
+  /**
+   * The ONE way a pass runs — issue #109.
+   *
+   * There were two entry points (this debounce and the 20 s poll) and no
+   * mutual exclusion between them, so a busy file-event channel could start a
+   * pass every 400 ms and overlap it with the poll's. Each pass is up to
+   * `MAX_REQUESTS_PER_PASS` requests against a hub that meters per minute, so
+   * the client's own ceiling was an order of magnitude above the server's and
+   * it manufactured the rate limit it then failed on.
+   *
+   * A pass in flight absorbs the request (the running pass reads the same
+   * disk and the same cursor, so a second one would decide the identical
+   * work), and passes are floored `MIN_PASS_INTERVAL_MS` apart.
+   */
+  let planePassInFlight = false;
+  let lastPlanePassAt = 0;
+  let planePassWaiter: Promise<void> | null = null;
+  let lastPlaneResult: import('./file-plane.ts').FilePlaneResult | null = null;
+  async function runPlanePass(opts?: { floor?: boolean }): Promise<void> {
+    // Captured, not re-read: `stop()` clears `filePlane`, and a pass that has
+    // already decided to run must not dereference the field it was cleared to.
+    const lane = filePlane;
+    if (stopped || !lane) return;
+    // A pass already running IS this pass: it reads the same disk and the same
+    // cursor, so the caller waits for its answer rather than racing it. The
+    // poll's `await` therefore still means "a pass has happened".
+    if (planePassInFlight) return await (planePassWaiter ?? Promise.resolve());
+    const since = Date.now() - lastPlanePassAt;
+    // The floor governs POKES. The 20 s poll and the explicit `pullRemoteNow`
+    // seam are already bounded by their own callers, and silently deferring a
+    // caller that awaited a pass would be its own lie.
+    if (opts?.floor !== false && since < MIN_PASS_INTERVAL_MS) {
+      // Not dropped — deferred. A poke that arrives inside the floor still has
+      // news, and losing it means a local edit waits for the next 20 s tick.
+      schedulePlanePassAfter(MIN_PASS_INTERVAL_MS - since);
+      return;
+    }
+    planePassInFlight = true;
+    lastPlanePassAt = Date.now();
+    const run = (async () => {
+      try {
+        const r = await lane.reconcile();
+        lastPlaneResult = r;
+        planeResultSink?.(r);
+      } catch (err) {
+        console.error('[sync/files] pass failed:', err);
+      } finally {
+        planePassInFlight = false;
+        planePassWaiter = null;
+      }
+    })();
+    planePassWaiter = run;
+    await run;
+  }
+  /** Re-arm the debounce timer at a specific delay (the floor's deferral). */
+  function schedulePlanePassAfter(ms: number): void {
+    if (stopped || filePassTimer !== null) return;
+    filePassTimer = setTimeout(() => {
+      filePassTimer = null;
+      void runPlanePass();
+    }, ms);
+    filePassTimer.unref?.();
+  }
   /** Assigned by `start()` so a pass reports into the same status the poll does. */
   let planeResultSink: ((r: import('./file-plane.ts').FilePlaneResult) => void) | null = null;
 
@@ -914,6 +1385,23 @@ export function createSyncRuntime(
    */
   function pollRemoteSoon(opts: { cooled?: boolean } = {}): void {
     if (stopped || remotePollSoonTimer !== null) return;
+    // ACCEPTED REVISIONS: a poke means "a revision was accepted", and the
+    // canvas it created, moved or deleted — or the folder — must reach this
+    // peer now, not on the next 20 s tick. Still bounded (one pass per
+    // second, with a trailing pass so the last poke of a burst is honoured),
+    // so a hub that pokes in a loop costs one cheap request a second.
+    if (opts.cooled && acceptedOn()) {
+      const since = Date.now() - lastPokePassAt;
+      const wait = Math.max(ACCEPTED_POKE_DELAY_MS, ACCEPTED_POKE_COOLDOWN_MS - since);
+      remotePollSoonTimer = setTimeout(() => {
+        remotePollSoonTimer = null;
+        if (stopped) return;
+        lastPokePassAt = Date.now();
+        void remotePull?.().catch(() => {});
+      }, wait);
+      remotePollSoonTimer.unref?.();
+      return;
+    }
     if (opts.cooled) {
       const since = Date.now() - lastPokePassAt;
       if (since < POKE_COOLDOWN_MS) {
@@ -1191,7 +1679,17 @@ export function createSyncRuntime(
         console.log(
           `[sync/${slug}] canvas was moved on another machine — stale local copy parked in _trash/ (recoverable).`
         );
-        ctx.bus.emit('canvas-list-update');
+      }
+      // The destination is materialized and the old body is gone. Receivers
+      // need the semantic move to retarget their open canvas, even if a local
+      // watcher already noticed the two filesystem changes.
+      if (movedTo && !existsSync(desc.html)) {
+        ctx.bus.emit('canvas-list-update', {
+          action: 'moved',
+          fromRel: path.relative(ctx.paths.designRoot, desc.html).split(path.sep).join('/'),
+          rel: movedTo.replace(/\\/g, '/'),
+          fromSlug: slug,
+        });
       }
     } catch (err) {
       // Quarantine is best-effort: the doc guards already made the file
@@ -1260,6 +1758,9 @@ export function createSyncRuntime(
     // payload would be a permanent "still syncing" the user can never clear.
     monitor?.forgetDoc(slug);
     rejectedPermanent.delete(slug);
+    rejectedTransient.delete(slug);
+    transientStrikes.delete(slug);
+    owedSetups.delete(slug);
     rejectedReasons.delete(slug);
     return true;
   }
@@ -1276,6 +1777,28 @@ export function createSyncRuntime(
   async function retireForMove(fromSlug: string, toRel: string): Promise<boolean> {
     const provider = providers.get(fromSlug);
     if (!provider) return false;
+    if (acceptedOn() && acceptedLink) {
+      // The move is a PROJECT action: the hub retires the old document (with
+      // the same `movedTo` stamp receivers already follow) and opens the new
+      // one with the same content. Answered or queued, the local rename then
+      // proceeds; a refusal (path taken, outside every group) keeps it.
+      movingLocally.add(fromSlug);
+      try {
+        if (!coveredByFolderAction.delete(fromSlug)) {
+          const r = await acceptedLink.moveDoc(fromSlug, toRel);
+          if (r.status === 'rejected') {
+            console.warn(`[sync/${fromSlug}] the project did not accept the move (${r.code})`);
+            return false;
+          }
+        }
+        retiredDocs.add(fromSlug);
+        await releaseOne(fromSlug);
+        console.log(`[sync/${fromSlug}] moved in the project → ${toRel}`);
+        return true;
+      } finally {
+        movingLocally.delete(fromSlug);
+      }
+    }
     movingLocally.add(fromSlug);
     try {
       stampMovedTo(provider.document, toRel, ORIGINS.DISK_PROJECTION);
@@ -1301,6 +1824,243 @@ export function createSyncRuntime(
     }
   }
 
+  // ---- project folders (accepted revisions) --------------------------------
+  //
+  // A folder is a manifest entry, so an EMPTY folder a peer created exists in
+  // the project and appears here — no placeholder canvas. The hub is
+  // untrusted (DDR-054): every path is re-checked against the declared canvas
+  // groups and the real design root before a directory is made, and removal
+  // only ever takes a folder that holds nothing but its `.gitkeep`.
+  const projectDirsFile = path.join(ctx.paths.designRoot, '_state', 'project-dirs.json');
+  try {
+    const saved = JSON.parse(readFileSync(projectDirsFile, 'utf8')) as unknown;
+    if (Array.isArray(saved))
+      for (const d of saved) if (typeof d === 'string') knownProjectDirs.add(d);
+  } catch {
+    /* first run — nothing materialized yet */
+  }
+  const saveProjectDirs = (): void => {
+    try {
+      mkdirSync(path.dirname(projectDirsFile), { recursive: true });
+      writeFileSync(projectDirsFile, JSON.stringify([...knownProjectDirs].sort()));
+    } catch {
+      /* best-effort — a lost file only delays one removal */
+    }
+  };
+  const projectDirAbs = (rel: string): string | null => {
+    if (typeof rel !== 'string' || !rel || rel.length > 512) return null;
+    const parts = rel.split('/');
+    if (parts.length > 16) return null;
+    for (const part of parts) {
+      if (!part || part === '.' || part === '..' || part.startsWith('_') || part.startsWith('.'))
+        return null;
+      if (/[\\\0:*?"<>|]/.test(part) || part.length > 255) return null;
+    }
+    const groups = (ctx.cfg.canvasGroups ?? []).map((g) => g.path.replace(/^\/+|\/+$/g, ''));
+    if (!groups.some((g) => g && (rel === g || rel.startsWith(`${g}/`)))) return null;
+    const abs = path.resolve(ctx.paths.designRoot, ...parts);
+    const root = path.resolve(ctx.paths.designRoot);
+    if (!abs.startsWith(`${root}${path.sep}`)) return null;
+    const real = realpathOfDeepestExisting(abs);
+    const realRoot = realpathOfDeepestExisting(root);
+    if (real !== realRoot && !real.startsWith(`${realRoot}${path.sep}`)) return null;
+    return abs;
+  };
+  const designRelPosix = ctx.paths.designRel.replace(/^\.\//, '').replace(/^\/+|\/+$/g, '');
+  function applyProjectDirs(dirs: readonly string[]): void {
+    const next = new Set(dirs);
+    let changed = false;
+    for (const rel of next) {
+      if (knownProjectDirs.has(rel)) continue;
+      const abs = projectDirAbs(rel);
+      if (!abs) continue;
+      try {
+        if (!existsSync(abs)) {
+          mkdirSync(abs, { recursive: true });
+          writeFileSync(path.join(abs, '.gitkeep'), '');
+          ctx.bus.emit('canvas-list-update', {
+            action: 'mkdir',
+            dir: path.posix.join(designRelPosix, rel),
+          });
+        }
+        knownProjectDirs.add(rel);
+        changed = true;
+      } catch (err) {
+        console.warn(`[sync] could not create project folder ${rel}:`, err);
+      }
+    }
+    // Deepest first, so a removed parent is attempted after its children.
+    const gone = [...knownProjectDirs]
+      .filter((d) => !next.has(d))
+      .sort((a, b) => b.length - a.length);
+    for (const rel of gone) {
+      const abs = projectDirAbs(rel);
+      if (abs && existsSync(abs)) {
+        let entries: string[] = [];
+        try {
+          entries = readdirSync(abs).filter((e) => e !== '.DS_Store');
+        } catch {
+          continue;
+        }
+        // Canvases inside leave through their own deletion/move first; until
+        // then the folder stays and the next poll tries again.
+        if (entries.some((e) => e !== '.gitkeep')) continue;
+        try {
+          for (const e of readdirSync(abs)) rmSync(path.join(abs, e), { force: true });
+          rmdirSync(abs);
+          ctx.bus.emit('canvas-list-update', {
+            action: 'removed-folder',
+            dir: path.posix.join(designRelPosix, rel),
+          });
+        } catch {
+          continue;
+        }
+      }
+      knownProjectDirs.delete(rel);
+      changed = true;
+    }
+    if (changed) saveProjectDirs();
+  }
+
+  /**
+   * The document listing is the hub's STORAGE view: a row appears after
+   * Hocuspocus persists the document, seconds after it exists. Under accepted
+   * revisions the manifest is the project's own statement of what exists, so a
+   * canvas accepted a moment ago is pulled on the next poll, not the one after
+   * its row is written.
+   */
+  function withAcceptedDocs(
+    listing: Awaited<ReturnType<typeof fetchRemoteListing>>
+  ): Awaited<ReturnType<typeof fetchRemoteListing>> {
+    const manifest = acceptedOn() ? acceptedLink?.manifest : null;
+    if (!manifest) return listing;
+    // A document the project RETIRED (moved away) is not a canvas to fetch,
+    // even while its storage row lingers — its successor is in the manifest.
+    const retired = new Set(manifest.docs.filter((d) => d.retired).map((d) => d.doc));
+    const documents = (listing?.documents ?? []).filter((d) => !retired.has(d.name));
+    const names = new Set(documents.map((d) => d.name));
+    for (const d of manifest.docs) {
+      if (d.retired || names.has(d.doc)) continue;
+      documents.push({ name: d.doc, bytes: 1 });
+      names.add(d.doc);
+    }
+    return { ...(listing ?? { tombstones: [] }), documents, tombstones: listing?.tombstones ?? [] };
+  }
+
+  /**
+   * Re-ask the save mode, and hand every held write back to its projection —
+   * as a proposal when the project turned out to be in transactions mode, as
+   * an ordinary import when the connection simply became writable.
+   */
+  let modeRefresh: Promise<void> | null = null;
+  function refreshAcceptedMode(): Promise<void> {
+    if (!acceptedLink) return Promise.resolve();
+    if (modeRefresh) return modeRefresh;
+    modeRefresh = acceptedLink
+      .refresh()
+      .then(() => {
+        if (acceptedOn()) applyProjectDirs(acceptedLink.manifest?.dirs ?? []);
+        for (const p of projections.values()) p.retryDeferred();
+      })
+      .finally(() => {
+        modeRefresh = null;
+      });
+    return modeRefresh;
+  }
+
+  /**
+   * A folder the Maude UI made on this machine (it carries the `.gitkeep`
+   * `createFolder` writes) that the project does not list yet — made while
+   * the project was legacy, or while this machine was offline. It joins the
+   * project as ONE action at cold start. Only additive: a folder the manifest
+   * lists and this disk lacks is never proposed as a deletion from here.
+   */
+  function proposeLocalFolders(): void {
+    if (!acceptedLink) return;
+    const listed = new Set(acceptedLink.manifest?.dirs ?? []);
+    const found: string[] = [];
+    const walk = (abs: string, rel: string, depth: number) => {
+      if (depth > 16 || found.length >= 200) return;
+      let entries: import('node:fs').Dirent[];
+      try {
+        entries = readdirSync(abs, { withFileTypes: true });
+      } catch {
+        return;
+      }
+      for (const e of entries) {
+        if (!e.isDirectory() || e.name.startsWith('_') || e.name.startsWith('.')) continue;
+        const childRel = `${rel}/${e.name}`;
+        const childAbs = path.join(abs, e.name);
+        if (
+          !listed.has(childRel) &&
+          existsSync(path.join(childAbs, '.gitkeep')) &&
+          projectDirAbs(childRel)
+        ) {
+          found.push(childRel);
+        }
+        walk(childAbs, childRel, depth + 1);
+      }
+    };
+    for (const g of ctx.cfg.canvasGroups ?? []) {
+      const rel = g.path.replace(/^\/+|\/+$/g, '');
+      if (rel) walk(path.join(ctx.paths.designRoot, ...rel.split('/')), rel, 1);
+    }
+    if (found.length === 0) return;
+    void acceptedLink.dirsCreate(found).then((r) => {
+      if (r.status === 'accepted') {
+        for (const d of found) knownProjectDirs.add(d);
+        saveProjectDirs();
+        console.log(`[sync] added ${found.length} local folder(s) to the project.`);
+      }
+    });
+  }
+
+  function proposeFolder(
+    op:
+      | { op: 'dir.create'; path: string }
+      | { op: 'dir.delete'; path: string }
+      | {
+          op: 'dir.move';
+          from: string;
+          to: string;
+        }
+  ): Promise<{ status: 'accepted' | 'rejected'; code?: string; queued?: boolean }> | null {
+    if (!acceptedOn() || !acceptedLink) return null;
+    const root = op.op === 'dir.move' ? op.from : op.path;
+    const covered: string[] = [];
+    if (op.op !== 'dir.create') {
+      for (const [slug, d] of descriptors) {
+        const rel = path.relative(ctx.paths.designRoot, d.html).split(path.sep).join('/');
+        if (rel === root || rel.startsWith(`${root}/`)) covered.push(slug);
+      }
+      for (const slug of covered) coveredByFolderAction.add(slug);
+    }
+    const answer =
+      op.op === 'dir.create'
+        ? acceptedLink.dirCreate(op.path)
+        : op.op === 'dir.delete'
+          ? acceptedLink.dirDelete(op.path)
+          : acceptedLink.dirMove(op.from, op.to);
+    return answer.then((r) => {
+      if (r.status === 'rejected') {
+        for (const slug of covered) coveredByFolderAction.delete(slug);
+        return r;
+      }
+      const under = (d: string) => d === root || d.startsWith(`${root}/`);
+      if (op.op === 'dir.create') knownProjectDirs.add(op.path);
+      else {
+        for (const d of [...knownProjectDirs]) {
+          if (!under(d)) continue;
+          knownProjectDirs.delete(d);
+          if (op.op === 'dir.move') knownProjectDirs.add(`${op.to}${d.slice(op.from.length)}`);
+        }
+        if (op.op === 'dir.move') knownProjectDirs.add(op.to);
+      }
+      saveProjectDirs();
+      return r;
+    });
+  }
+
   async function start(): Promise<void> {
     if (started || stopped) return;
     started = true;
@@ -1355,7 +2115,24 @@ export function createSyncRuntime(
     // credential in place, so reading it at call time is what every other hub
     // call here does. Identical at boot; correct if start() ever re-runs after
     // a renewal (and it types, which `resolvedToken`'s `string | null` did not).
-    const remoteListing = await fetchRemoteListing(linkedHub.url, token);
+    const remoteListingRaw = await fetchRemoteListing(linkedHub.url, token);
+    if (acceptedLink) {
+      await acceptedLink.refresh();
+      if (acceptedOn()) {
+        console.log(
+          '[sync] this project saves through accepted revisions — local changes are proposed, never written into the shared document.'
+        );
+        // Work a previous run left unanswered goes first, in creation order —
+        // before any cold start can propose something built on top of it.
+        void acceptedLink.client.drainOutbox().then((results) => {
+          if (results.length)
+            console.log(`[sync/tx] resent ${results.length} unanswered change(s).`);
+        });
+        applyProjectDirs(acceptedLink.manifest?.dirs ?? []);
+        proposeLocalFolders();
+      }
+    }
+    const remoteListing = withAcceptedDocs(remoteListingRaw);
     // BOOT LEARNS THE DELETIONS BEFORE IT PULLS ANYTHING. The peer-side apply
     // lives further down (it needs the live descriptor map), so this boot pass
     // only has to make sure the pull does not fetch a canvas the project has
@@ -1606,6 +2383,9 @@ export function createSyncRuntime(
         broadcast: (payload) => ctx.bus.emit('sync:status', payload),
       });
     const store = statusStore;
+    // An unfinished AI action restored from the last session (T16).
+    const restoredStage = acceptedLink?.stage.summary();
+    if (restoredStage) store.updateAiAction?.(restoredStage);
 
     // DDR-079 — TSX sync defaults ON, so every linked non-loopback project that
     // ships .tsx broadcasts the WebRTC/self-nav exfil residual (the sandbox
@@ -1664,6 +2444,28 @@ export function createSyncRuntime(
     });
     fsReader = reader;
 
+    // Accepted revisions: an API source write announces itself before it
+    // lands (`activity:suppress`, the same signal the activity rim uses).
+    const projectionForRel = (rel: unknown): DocProjection | undefined => {
+      if (typeof rel !== 'string' || !rel) return undefined;
+      const abs = path.join(ctx.paths.designRoot, rel);
+      for (const [slug, d] of descriptors) if (d.html === abs) return projections.get(slug);
+      return undefined;
+    };
+    const unsubSuppress = ctx.bus.on('activity:suppress', (rel: unknown) => {
+      if (acceptedOn()) projectionForRel(rel)?.noteLocalWrite();
+    });
+    // T24 — the UI operation behind that write (sync/source-ops).
+    const unsubSourceOp = ctx.bus.on('source-op', (payload: unknown) => {
+      const p = payload as { rel?: unknown; op?: SourceOp } | null;
+      if (acceptedOn() && p?.op) projectionForRel(p.rel)?.noteSourceOp(p.op);
+    });
+    activityUnsubs.push(unsubSourceOp);
+    const unsubUnsuppress = ctx.bus.on('activity:unsuppress', (rel: unknown) => {
+      projectionForRel(rel)?.cancelLocalWrite();
+    });
+    activityUnsubs.push(unsubSuppress, unsubUnsuppress);
+
     busUnsub = ctx.bus.on('fs:any', (rel: string) => {
       reader.notify(rel);
       // AN ASSET THAT APPEARS AFTER BOOT HAS TO GO UP NOW, NOT NEXT LAUNCH.
@@ -1776,7 +2578,12 @@ export function createSyncRuntime(
       rejectedPermanent.clear();
       for (const entry of entries) {
         mon.noteDocState(entry.canvas.slug, 'pending');
-        void connectCanvas(entry.canvas, entry.canvasPaths, entry.doc).catch((err) => {
+        void connectCanvas(
+          entry.canvas,
+          entry.canvasPaths,
+          entry.doc,
+          owedSetups.get(entry.canvas.slug)
+        ).catch((err) => {
           console.error(`[sync/${entry.canvas.slug}] re-probe failed:`, err);
         });
       }
@@ -1790,6 +2597,72 @@ export function createSyncRuntime(
       }, reprobeMs);
     };
 
+    /**
+     * Arm the transient lane's ONE timer (single-flight) for the earliest due
+     * document — or, when the sliding budget is spent, for the moment its
+     * oldest re-auth leaves the window — plus jitter.
+     */
+    const armTransientRetry = (): void => {
+      if (transientRetryTimer !== null || stopped || rejectedTransient.size === 0) return;
+      let at = Number.POSITIVE_INFINITY;
+      for (const e of rejectedTransient.values()) at = Math.min(at, e.dueAt);
+      const oldestSpend = transientSpent[0];
+      if (transientSpent.length >= transientBatch && oldestSpend !== undefined) {
+        at = Math.max(at, oldestSpend + transientRetryMs);
+      }
+      const delay = Math.max(0, at - renewNow()) + Math.floor(authRandom() * transientJitterMs);
+      transientRetryTimer = authSetTimer(
+        () => {
+          transientRetryTimer = null;
+          retryTransientNow();
+        },
+        Math.min(MAX_TIMER_DELAY_MS, delay)
+      );
+    };
+
+    /**
+     * Re-authenticate the due transiently-refused documents — only those, never
+     * the shared socket — up to the budget, oldest first; the rest wait for the
+     * next arm. The swap is the re-probe's: destroy the refused provider and
+     * reconnect on the SAME doc, so the agent and projection wiring carry over.
+     * A provider attached to an already-open socket sends its token at once
+     * (`HocuspocusProviderWebsocket.attach` → `provider.onOpen`).
+     */
+    const retryTransientNow = (): void => {
+      if (stopped) return;
+      const now = renewNow();
+      while (transientSpent.length > 0 && now - (transientSpent[0] ?? now) >= transientRetryMs) {
+        transientSpent.shift();
+      }
+      const due = [...rejectedTransient.entries()]
+        .filter(([, e]) => e.dueAt <= now)
+        .sort((x, y) => x[1].dueAt - y[1].dueAt)
+        .slice(0, Math.max(0, transientBatch - transientSpent.length));
+      for (const [slug, entry] of due) {
+        rejectedTransient.delete(slug);
+        if (providers.get(slug) !== entry.provider) continue;
+        transientSpent.push(now);
+        providers.delete(slug);
+        try {
+          entry.provider.destroy();
+        } catch {
+          /* best-effort */
+        }
+        mon.noteDocState(slug, 'pending');
+        // Not a boot connect — a retry must never join the one-shot boot summary.
+        void connectCanvas(
+          entry.canvas,
+          entry.canvasPaths,
+          entry.doc,
+          owedSetups.get(slug),
+          false
+        ).catch((err) => {
+          console.error(`[sync/${slug}] transient re-auth failed:`, err);
+        });
+      }
+      armTransientRetry();
+    };
+
     /**
      * Renew the hub credential in place — single-flight, silent, and never
      * worse than failure: an unrenewable credential leaves the stored one
@@ -1883,14 +2756,18 @@ export function createSyncRuntime(
       // hub's raw message).
       mon.noteDocState(canvas.slug, 'auth-rejected', reasonClass);
       rejectedReasons.set(canvas.slug, reasonClass);
+      // Every class, including the transient ones that keep their provider —
+      // see `rejectedAny`. This is the set the reconnect path consults.
+      rejectedAny.add(canvas.slug);
       // Aggregate console output: ONE debounced warn for the whole burst.
       if (!pendingAuthWarn.has(reasonClass)) pendingAuthWarn.set(reasonClass, new Set());
       pendingAuthWarn.get(reasonClass)?.add(canvas.slug);
       if (authWarnTimer === null) authWarnTimer = authSetTimer(flushAuthWarn, warnDebounceMs);
       // Permanent classes: retrying only spams the hub (and its rate bucket) —
       // destroy the provider and re-probe on a slow timer. Transient classes
-      // (rate-limit / generic) keep the provider's built-in backoff.
+      // (rate-limit / generic) get the paced retry below.
       if (reasonClass === 'not-authorized' || reasonClass === 'invalid-token') {
+        rejectedTransient.delete(canvas.slug);
         if (!rejectedPermanent.has(canvas.slug)) {
           rejectedPermanent.set(canvas.slug, { canvas, canvasPaths, doc: provider.document });
           providers.delete(canvas.slug);
@@ -1912,6 +2789,31 @@ export function createSyncRuntime(
             if (renewed) reprobeNow();
           });
         }
+      } else if (!rejectedTransient.has(canvas.slug)) {
+        // THE HUB MAY WELL SAY YES NEXT WINDOW — BUT NOTHING WOULD ASK IT.
+        //
+        // These classes used to be left to "the provider's built-in backoff".
+        // Under DDR-102 multiplexing that backoff is the SOCKET's reconnect
+        // loop, and a partial refusal never closes a socket the other
+        // documents keep healthy — so a refused document stayed refused until
+        // the process ended. Queue it for the runtime's own retry instead: one
+        // hub window out, doubling on each repeat (capped at the re-probe
+        // interval), reset by a handshake that lands. The `has` guard keeps a
+        // repeated event for one refusal from counting as a second strike.
+        const strikes = (transientStrikes.get(canvas.slug) ?? 0) + 1;
+        transientStrikes.set(canvas.slug, strikes);
+        const wait = Math.min(
+          Math.max(transientRetryMs, reprobeMs),
+          transientRetryMs * 2 ** (strikes - 1)
+        );
+        rejectedTransient.set(canvas.slug, {
+          canvas,
+          canvasPaths,
+          doc: provider.document,
+          provider,
+          dueAt: renewNow() + wait,
+        });
+        armTransientRetry();
       }
     };
 
@@ -1931,6 +2833,9 @@ export function createSyncRuntime(
      */
     const clearRejection = (slug: string): void => {
       rejectedPermanent.delete(slug);
+      rejectedTransient.delete(slug);
+      transientStrikes.delete(slug);
+      rejectedAny.delete(slug);
       if (!rejectedReasons.delete(slug)) return;
       console.log(`[sync/${slug}] the hub accepted this document — clearing its refusal.`);
     };
@@ -1942,6 +2847,8 @@ export function createSyncRuntime(
      * the canvas its sync.
      */
     const stampFromLocalFile = (doc: Y.Doc, htmlAbs: string): void => {
+      // The accepted replica carries the path the PROJECT gave the document.
+      if (acceptedOn()) return;
       try {
         const rel = path.relative(ctx.paths.designRoot, htmlAbs).split(path.sep).join('/');
         if (rel && !rel.startsWith('..')) stampCanvasPath(doc, rel, ORIGINS.DISK_PROJECTION);
@@ -1994,7 +2901,7 @@ export function createSyncRuntime(
           canvas.html &&
           path.resolve(canvas.html) === movedAbs
         ) {
-          if (clearMovedTo(provider.document, ORIGINS.MIGRATION)) {
+          if (!acceptedOn() && clearMovedTo(provider.document, ORIGINS.MIGRATION)) {
             console.log(
               `[sync/${canvas.slug}] this document is stamped as moved to its OWN path — clearing the stale retirement and keeping the canvas.`
             );
@@ -2018,7 +2925,28 @@ export function createSyncRuntime(
       mon.noteDocState(canvas.slug, 'pending');
       const projection = projections.get(canvas.slug);
       const agent = agents.get(canvas.slug);
-      if (projection) {
+      if (projection && acceptedOn() && acceptedLink) {
+        const docName = docNameFor(canvas.slug);
+        let inProject = acceptedLink.manifest?.docs.some((d) => d.doc === docName && !d.retired);
+        if (!inProject) {
+          // A canvas adopted after boot: ask again before creating anything.
+          await acceptedLink.refresh();
+          inProject = acceptedLink.manifest?.docs.some((d) => d.doc === docName && !d.retired);
+        }
+        const rel = path.relative(ctx.paths.designRoot, canvas.html).split(path.sep).join('/');
+        await acceptedColdStart({
+          slug: canvas.slug,
+          doc: provider.document,
+          paths: canvasPaths,
+          rel,
+          inProject: inProject === true,
+          projection,
+          historyDir: path.join(ctx.paths.historyDir, canvas.slug),
+          journal: journal ?? undefined,
+          createDoc: (lanes) => acceptedLink.createDoc(canvas.slug, rel, lanes),
+        });
+        projection.reconcile();
+      } else if (projection) {
         // Phase E (DDR-064 Task 9) — one-time authoritative seed BEFORE
         // materializing: escapes the duplication trap by picking ONE source
         // inside a MIGRATION transaction. DDR-102: body divergence now takes
@@ -2041,6 +2969,9 @@ export function createSyncRuntime(
             }
           },
           onConflict: (info) => store.addConflict(info),
+          // An unmergeable local candidate: keep both, and let the projection
+          // report and hold it from the shared base (T2).
+          onHold: (base) => projection.adoptBase(base),
           hubHasState: (slug) => hubHolds(hubDocIndex, docNameFor(slug)),
         });
         if (result === 'local-adopt') {
@@ -2050,6 +2981,16 @@ export function createSyncRuntime(
             `[sync/${canvas.slug}] shared-doc: not seeding — the hub already holds this ` +
               'document; waiting for its state to arrive.'
           );
+        } else if (result === 'conflict-merged') {
+          console.log(
+            `[sync/${canvas.slug}] shared-doc: merged a local edit with the project's newer ` +
+              `version (both sides were in _history/${canvas.slug}/ first).`
+          );
+        } else if (result === 'conflict-held') {
+          console.warn(
+            `[sync/${canvas.slug}] shared-doc: a local edit overlaps the project's newer version — ` +
+              'both kept; the canvas waits for a resolving save.'
+          );
         } else if (result === 'conflict-local-wins' || result === 'conflict-hub-wins') {
           console.warn(
             `[sync/${canvas.slug}] shared-doc: diverged — kept the ${
@@ -2079,6 +3020,8 @@ export function createSyncRuntime(
       // DDR-102 — honest status: the handshake + reconcile completed.
       mon.noteDocState(canvas.slug, 'connected');
       mon.noteSyncActivity(canvas.slug);
+      lastPromotionAt = stallNow();
+      forcedReconnects = 0;
       // 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.
@@ -2108,6 +3051,122 @@ export function createSyncRuntime(
       }
     };
 
+    /**
+     * A DOCUMENT THAT RE-HANDSHAKES IS A SYNCED DOCUMENT AGAIN.
+     *
+     * The bug this closes (issue #118), stated plainly: `noteDocState(slug,
+     * 'connected')` had exactly ONE call site — the post-handshake reconcile
+     * inside `connectCanvas`, which runs at attach, adopt and auth-re-probe and
+     * at no other time. A dropped socket demotes every `connected` document to
+     * `pending` (`noteProviderStatus`, deliberately — a document whose socket is
+     * gone is not a synced document), and NOTHING re-promoted it when the socket
+     * came back. The demotion was therefore permanent for the life of the
+     * runtime: observed live as `state:"online", docs:{synced:0, pending:85}`
+     * fifteen minutes after a boot whose own log line read `85/87 synced`.
+     *
+     * Downstream that reads as the worst kind of wrong: `syncPresentation` sees
+     * "connected to the hub, zero documents settled, and it has been like that a
+     * while" and reports a STALL blamed on the credential — so the remedy the
+     * product offered (reconnect the workspace) was the one thing that could not
+     * help, and the Resync it prompts re-handshakes every document against a
+     * cold cell and lands on `offline`.
+     *
+     * What this does NOT do is re-run `handleSynced`. That path carries
+     * migrate-seed, cold-start divergence resolution and history snapshots — a
+     * one-time authoritative seed, correctly named as such, and firing it for
+     * every canvas on every reconnect would turn a network blip into a
+     * conflict-resolution storm. The honest signal is narrower and sufficient:
+     * the hub completed a sync handshake for THIS document, so it is connected
+     * again. Nothing on disk is touched.
+     *
+     * Single-flight per slug — a flapping socket must not stack one pending
+     * promise per transition — and every guard is re-checked AFTER the await,
+     * because a runtime can stop, and a canvas can be released, while we wait.
+     */
+    const repromoting = new Set<string>();
+    const repromoteOnReconnect = async (slug: string, provider: SyncProvider): Promise<void> => {
+      if (stopped || repromoting.has(slug)) return;
+      // REFUSED IS REFUSED, WHATEVER THE CLASS.
+      //
+      // This guard read `rejectedPermanent`, and that map holds only the two
+      // PERMANENT classes — `generic` and `rate-limit` keep their provider
+      // until the transient retry swaps it, and never enter it. `generic` is what
+      // EVERY pre-DDR-102 hub sends. So a refusal in a transient class passed
+      // straight through this guard and got overwritten with `connected`
+      // (attacker review 2026-09-03, F3): the hub was dropping this document's
+      // writes while the panel rendered it green, `docs.rejected` fell back to
+      // 0, and the `refused` branch — plus the offline-long "git push as
+      // backup" escalation — could never fire. `rejectedAny` is the honest set:
+      // every class enters it, `clearRejection` is the only thing that empties
+      // it, and it is checked on BOTH sides of the await because the refusal
+      // that matters is the one that lands while we are waiting.
+      if (rejectedAny.has(slug)) return;
+      repromoting.add(slug);
+      try {
+        // BOUNDED, because `onceSynced()` can never settle.
+        //
+        // `handleAuthFailure` on a permanent class calls `provider.destroy()`,
+        // and destroy emits `destroy`, never `synced` — so the promise below
+        // stays pending for the life of the process, `finally` never runs, and
+        // the slug stays latched in `repromoting` forever. Every later genuine
+        // reconnect for that document would then return at the guard above:
+        // issue #118 recreated per-document, permanently, by its own fix
+        // (attacker review 2026-09-03, F4). `settleWait` already exists for
+        // exactly this ("never hangs the summary on an auth-rejected provider
+        // whose handshake never completes") — reuse it rather than invent a
+        // second ceiling.
+        //
+        // `settleWait` resolves on the TIMEOUT as well as on success, so the
+        // flag is what separates "the handshake landed" from "we stopped
+        // waiting for it". Without it the timeout would promote the document.
+        let landed = false;
+        // The ceiling below stops us WAITING; the abort is what stops us
+        // LISTENING. Skipping it leaked a `synced` listener + closure per
+        // abandoned wait, forever (N2) — invisible while the latch bug meant we
+        // never retried, unbounded once that was fixed.
+        const giveUp = new AbortController();
+        try {
+          await settleWait(
+            provider.onceSynced(giveUp.signal).then(() => {
+              landed = true;
+            })
+          );
+        } finally {
+          giveUp.abort();
+        }
+        if (!landed || stopped) return;
+        // Still ours, still not refused — either can have changed in flight.
+        if (providers.get(slug) !== provider || rejectedAny.has(slug)) return;
+        // ONE mutator, not two. `noteSyncActivity` promotes pending→connected
+        // AND stamps the clock in a single emit, and it is the one that refuses
+        // to resurrect an `auth-rejected` document — so it is both cheaper and
+        // safer here than pairing it with `noteDocState`. Every emit is a
+        // synchronous `_sync.json` write plus a fan-out to every open tab, and
+        // `noteSyncActivity` has no change-dedupe of its own: on an 85-canvas
+        // project the pair cost ~340 writes per hub-driven flap against ~170
+        // for the demotion alone (defender F4 / attacker F5).
+        //
+        // Residual, stated rather than hidden: a completed handshake is not
+        // proof that a byte was persisted, so a hub that flaps the socket and
+        // completes empty sync steps can keep `lastSyncAt` fresh. That is
+        // narrower than the socket-transition stamp this change removed from
+        // `goOnline`, but it is the same shape, and it wants a separate
+        // `noteHandshake()` the day the monitor grows one.
+        mon.noteSyncActivity(slug);
+        lastPromotionAt = stallNow();
+        // A recovery that WORKED must not leave the floor ratcheted. Without
+        // this, seven stall-and-recover cycles over a long session pin the
+        // watchdog's floor at its 30-minute cap, so the next genuine stall waits
+        // half an hour for help (verification review 2026-09-03, N3).
+        forcedReconnects = 0;
+        // A completed handshake is progress, exactly as it is on the first
+        // connect — see the `renewalsSinceProgress` reset in `handleSynced`.
+        renewalsSinceProgress = 0;
+      } finally {
+        repromoting.delete(slug);
+      }
+    };
+
     /** onceSynced() with the boot-settle ceiling — never hangs the summary on
      *  an auth-rejected provider (whose handshake never completes). */
     const settleWait = (p: Promise<void>): Promise<void> =>
@@ -2280,6 +3339,7 @@ export function createSyncRuntime(
       // the same order relative to each other.
       const deferSetup = !!setup && pulledSlugs.has(canvas.slug);
       if (!deferSetup) setup?.(provider);
+      else if (setup) owedSetups.set(canvas.slug, setup);
 
       // Task 8 — feed this provider's WS status into the offline monitor.
       // Per-provider, so a socket that never dropped never triggers a poll.
@@ -2310,7 +3370,14 @@ export function createSyncRuntime(
             // wanted here: a genuine one-off reconnect (nothing poked
             // recently) runs immediately; a churn folds into the scheduled
             // tick, costing latency and never correctness.
-            if (s === 'connected' && wasDisconnected) pollRemoteSoon({ cooled: true });
+            if (s === 'connected' && wasDisconnected) {
+              pollRemoteSoon({ cooled: true });
+              // …and re-establish this DOCUMENT's truth, not just the project's.
+              // The poll above asks the hub what canvases exist; it says nothing
+              // about whether THIS one is synced again, and for a long time
+              // nothing did. See `repromoteOnReconnect`.
+              void repromoteOnReconnect(canvas.slug, provider);
+            }
             wasDisconnected = s !== 'connected';
           })
         );
@@ -2342,6 +3409,8 @@ export function createSyncRuntime(
       // Cold-start reconcile fires once the provider has hub state.
       const synced = provider.onceSynced().then(() => {
         if (deferSetup) {
+          // Settled either way below — run, or the canvas is released.
+          owedSetups.delete(canvas.slug);
           // Abandon before `setup?.()`, so no projection and no agent is ever
           // built for a canvas we are not going to place — nothing exists that
           // could flush the document onto the provisional path on the way out.
@@ -2416,6 +3485,50 @@ export function createSyncRuntime(
                 paths: canvasPaths,
                 echoGuard,
                 journal: journal ?? undefined,
+                historyDir: path.join(ctx.paths.historyDir, canvas.slug),
+                waitForReconcile: true,
+                ...(acceptedLink
+                  ? {
+                      accepted: acceptedLink.laneLink(canvas.slug),
+                      revisionBarrier,
+                      replayOp: (op: SourceOp, head: string) =>
+                        replaySourceOp(canvas.html, op, head),
+                      onAccepted: ({
+                        lane,
+                        value,
+                        actionId,
+                      }: {
+                        lane: string;
+                        value: string;
+                        actionId: string;
+                      }) => noteAcceptedContent(canvas.slug, lane, value, actionId),
+                      onRevisionApplied: (rev: number) => store.noteAppliedRevision?.(rev),
+                    }
+                  : {}),
+                // A write the hub would drop is held, never made (see isWritable).
+                ...(provider.isWritable
+                  ? {
+                      canWriteDoc: () => provider.isWritable?.() !== false,
+                      onWriteBlocked: () => void refreshAcceptedMode(),
+                    }
+                  : {}),
+                onRecovered: () => store.clearSourceConflict(canvas.slug),
+                onConflict: (info) => {
+                  store.addConflict(info);
+                  store.notice({
+                    id: `source-conflict-${canvas.slug}`,
+                    severity: 'warn',
+                    text: `Source sync blocked for ${canvas.slug}. The local file was kept because ${
+                      info.reason === 'invalid-source'
+                        ? 'the source has syntax errors or duplicate declarations'
+                        : info.reason === 'local-edit'
+                          ? 'a local edit overlaps an incoming change'
+                          : info.reason === 'merge-budget'
+                            ? 'the edit is too large to merge safely'
+                            : 'a recovery copy could not be saved'
+                    }. ${info.snapshotFailed ? 'Recovery could not be saved; check disk space and history write access.' : `Recovery copies are in _history/${canvas.slug}/sync-recovery/.`}`,
+                  });
+                },
                 // Cell pairing only — see the DocProjectionOptions.onWrote doc.
                 // The synthetic event is delayed by the same margin the container
                 // write bridge uses, so a watcher that DOES fire wins the race and
@@ -2455,6 +3568,55 @@ export function createSyncRuntime(
             // cleans up.)
             watchForRetirement(canvas.slug, provider.document);
 
+            // THE HUB SAYS THE SAVE MODE CHANGED — on this document's own
+            // socket, ahead of closing it, so the switch is learned before any
+            // further local change is made (DDR-241 §7 switch ordering).
+            if (acceptedLink && provider.onStateless) {
+              noteDetach(
+                statusDetaches,
+                canvas.slug,
+                provider.onStateless((payload) => {
+                  let msg: { type?: unknown; mode?: unknown } | null = null;
+                  try {
+                    msg = JSON.parse(payload);
+                  } catch {
+                    return;
+                  }
+                  if (msg?.type !== 'maude.mode') return;
+                  if (msg.mode === 'transactions' || msg.mode === 'legacy') {
+                    acceptedLink.noteMode(msg.mode);
+                    void refreshAcceptedMode();
+                  }
+                })
+              );
+            }
+            if (provider.onAuthenticated) {
+              const slug = canvas.slug;
+              noteDetach(
+                statusDetaches,
+                slug,
+                provider.onAuthenticated(() => projections.get(slug)?.retryDeferred())
+              );
+            }
+
+            // ACCEPTED-REPLICA TRIPWIRE (DDR-241 §7, plan T6/T12). In
+            // transactions mode the hub drops every update this connection
+            // sends, so a local write here never reaches the project and the
+            // replica silently diverges. Nothing is supposed to do it; this is
+            // how we find out if something does.
+            if (acceptedLink && provider.isRemoteOrigin) {
+              const slug = canvas.slug;
+              const onAny = (_u: Uint8Array, origin: unknown) => {
+                if (!acceptedOn() || provider.isRemoteOrigin?.(origin)) return;
+                acceptedWriteViolations += 1;
+                console.error(
+                  `[sync/${slug}] a local write reached the accepted replica (origin: ${describeOrigin(origin)}) — it cannot reach the project.`
+                );
+              };
+              provider.document.on('update', onAny);
+              noteDetach(statusDetaches, slug, () => provider.document.off('update', onAny));
+            }
+
             // Count local edits (agent-origin doc updates) toward queuedOps while
             // the hub is unreachable — the banner's "N edits queued" figure. Under
             // sharedDoc there is no agent origin to key off (browser edits carry a
@@ -2665,6 +3827,17 @@ export function createSyncRuntime(
       if (typeof slug !== 'string' || !slug) return;
       if (revive) tombstoned.delete(slug);
       else tombstoned.add(slug);
+      if (acceptedOn() && acceptedLink) {
+        // A re-created canvas is proposed by its cold start (`doc.create`); a
+        // deletion is ONE project action unless a folder action covered it.
+        if (revive || coveredByFolderAction.delete(slug)) return;
+        void acceptedLink.deleteDoc(slug).then((r) => {
+          if (r.status === 'rejected' && r.code !== 'dependency-missing') {
+            console.warn(`[sync] the project did not accept deleting ${slug} (${r.code})`);
+          }
+        });
+        return;
+      }
       void stateDocumentGone(linkedHub.url, token, docNameFor(slug), { revive }).then((ok) => {
         if (!ok) {
           console.warn(
@@ -2717,6 +3890,13 @@ export function createSyncRuntime(
               annotations: canvas.annotations,
             },
           });
+          if (!existsSync(canvas.html)) {
+            ctx.bus.emit('canvas-list-update', {
+              action: 'removed',
+              rel: path.relative(ctx.paths.designRoot, canvas.html).split(path.sep).join('/'),
+              slug,
+            });
+          }
         }
         descriptors.delete(slug);
       }
@@ -2743,11 +3923,18 @@ export function createSyncRuntime(
     // not told the document exists.
     const pullRemoteOnce = async (): Promise<void> => {
       if (stopped) return;
+      // Accepted revisions: the save mode can change under a running peer (the
+      // hub fences every socket when it does), and folders are manifest
+      // entries — neither is in the document listing.
+      if (acceptedLink) {
+        await acceptedLink.refresh();
+        if (acceptedOn()) applyProjectDirs(acceptedLink.manifest?.dirs ?? []);
+      }
       // Read `token` at call time: a silent renewal swaps it in place.
-      const listing = await fetchRemoteListing(linkedHub.url, token);
+      const listing = withAcceptedDocs(await fetchRemoteListing(linkedHub.url, token));
       // null = unreachable, refused, or a hub without the route. Not an error
       // here any more than it is at boot — sync continues, we ask again later.
-      if (listing === null) return;
+      if (stopped || listing === null) return;
       // ABSENCE BEFORE PRESENCE. A canvas the project deleted must leave before
       // the pull runs, or a slug that is tombstoned AND still listed (the window
       // between the tombstone and the row actually going) would be trashed and
@@ -2840,6 +4027,82 @@ export function createSyncRuntime(
     // Cumulative per boot — the Sync panel's one line. `synced` is the last
     // pass's converged count; `pulled`/`conflicts` accumulate.
     const fileTotals = { synced: 0, pulled: 0, conflicts: 0 };
+    /** Previous progress, for `startedAt` continuity across ticks. */
+    let lastSeedProgress: import('./seed-progress.ts').SeedProgress | null = null;
+    /** When the last serve-log progress line went out, and what it said. */
+    let lastProgressLogAt = 0;
+    let lastProgressLine = '';
+    /**
+     * ONE LINE, PERIODICALLY, WHILE A SEED IS RUNNING.
+     *
+     * After boot the file plane printed NOTHING. Two runs of 14 and 6 minutes
+     * that moved zero files were, from the terminal, indistinguishable from two
+     * runs that were working — the only repeated line was a delete-breaker
+     * warning that fired 47 times and buried everything else. The doc lane has
+     * printed its one-shot summary since Phase 9; this is the file plane's.
+     *
+     * Rate-limited AND deduped: a converged project prints nothing at all, and
+     * a stalled one prints the same line at most once every 15 s rather than
+     * once per pass.
+     */
+    const reportSeedProgress = (
+      p: import('./seed-progress.ts').SeedProgress,
+      r: import('./file-plane.ts').FilePlaneResult
+    ): void => {
+      if (p.phase === 'converged') return;
+      const blockedTotal = p.blocked.reduce((n, b) => n + b.count, 0);
+      const bits = [`${p.delivered} / ${p.tracked} delivered`];
+      if (p.remaining > 0) bits.push(`${p.remaining} waiting`);
+      if (blockedTotal > 0) bits.push(`${blockedTotal} need attention`);
+      if (r.backedOff) bits.push(`${r.backedOff} backing off`);
+      let tail = '';
+      if (r.rateLimited) {
+        const secs = Math.max(1, Math.round((r.rateLimited.until - Date.now()) / 1000));
+        const why =
+          r.rateLimited.cause === 'unreachable'
+            ? 'could not reach the workspace'
+            : r.rateLimited.cause === 'quota'
+              ? 'hourly upload allowance used up'
+              : 'the workspace asked us to slow down';
+        tail = ` · paused ${secs}s (${why})`;
+      } else if (p.passCapped) {
+        tail = ` · more next pass (${p.passCapped} ceiling)`;
+      }
+      const line = `[sync/files] ${bits.join(' · ')}${tail}`;
+      const nowMs = Date.now();
+      if (line === lastProgressLine && nowMs - lastProgressLogAt < SEED_PROGRESS_LOG_MS) return;
+      if (nowMs - lastProgressLogAt < SEED_PROGRESS_LOG_MS) return;
+      lastProgressLogAt = nowMs;
+      lastProgressLine = line;
+      console.log(line);
+    };
+    /** When the last pass ended, so a throughput sample has a window. */
+    let lastPassEndedAt = 0;
+    /**
+     * Bytes that actually LANDED in the last pass, over the wall-clock since
+     * the previous one.
+     *
+     * Bytes DELIVERED, never bytes sent. The 2026-09-03 misreading was exactly
+     * this distinction: 616 MB left the machine across two runs and zero files
+     * landed, so a rate computed from egress said "about ten minutes" when the
+     * true answer was "never".
+     */
+    const throughputSample = (
+      r: import('./file-plane.ts').FilePlaneResult
+    ): { bytes: number; ms: number } | null => {
+      const landed = r.pushed.length + r.pulled.length;
+      const nowMs = Date.now();
+      const ms = lastPassEndedAt > 0 ? nowMs - lastPassEndedAt : 0;
+      lastPassEndedAt = nowMs;
+      if (landed === 0 || ms <= 0) return null;
+      const rows = fileLedger?.rows() ?? {};
+      let bytes = 0;
+      for (const rel of [...r.pushed, ...r.pulled]) {
+        const size = rows[rel]?.size;
+        if (Number.isFinite(size)) bytes += size as number;
+      }
+      return bytes > 0 ? { bytes, ms } : null;
+    };
     const noteFilePull = (result: FilePullResult): void => {
       fileTotals.synced = result.skipped + result.pulled.length;
       fileTotals.pulled += result.pulled.length;
@@ -2893,12 +4156,75 @@ export function createSyncRuntime(
             'The project has asked to start over repeatedly, which is what a broken or hostile hub looks like. Nothing was overwritten. Sync retries by itself; if this persists, the hub needs looking at.',
         });
       }
+      // THE DENOMINATOR, from the LEDGER — not from this pass.
+      //
+      // `fileTotals` below is derived from per-pass results, and a pass that
+      // converges nothing is legitimately all zeros: that is why `_sync.json`
+      // read `synced: 0, pushed: 0, pulled: 0` for twenty minutes while 2 961
+      // ledger rows changed underneath it. The raw counters STAY beside this
+      // (DDR-214: a panel derived from the same source it displays cannot be
+      // cross-checked), but the progress a person reads comes from the source
+      // that was correct the whole time.
+      const progress = filePlane
+        ? computeSeedProgress({
+            rows: fileLedger?.rows() ?? {},
+            now: Date.now(),
+            pausedUntil: result.rateLimited?.until ?? null,
+            pauseCause: result.rateLimited?.cause ?? null,
+            ...(result.requestsExhausted
+              ? { passCapped: 'requests' as const }
+              : result.budgetExhausted
+                ? { passCapped: 'bytes' as const }
+                : {}),
+            previous: lastSeedProgress,
+            deliveredSince: throughputSample(result),
+          })
+        : null;
+      if (progress) {
+        lastSeedProgress = progress;
+        reportSeedProgress(progress, result);
+      }
       statusStore?.updateFiles?.({
         ...fileTotals,
         pushed: filePushed,
-        ...(filePlane ? { delivery: filePlane.doruceka() } : {}),
+        ...(progress ? { progress } : {}),
+        ...(filePlane
+          ? {
+              delivery: filePlane.doruceka(),
+              ...(filePlane.dorucekaTotal() > MAX_DORUCEKA_ROWS
+                ? { deliveryTruncated: filePlane.dorucekaTotal() - MAX_DORUCEKA_ROWS }
+                : {}),
+            }
+          : {}),
         ...(held.length > 0 ? { held } : {}),
+        // A FAILED TRANSFER IS NOT A SYNCED ONE (issue #109). These had no
+        // field to land in, so a pass that refused every file still rendered
+        // as `synced` and the only trace was the console lines below — on a
+        // product whose premise is that nobody opens a terminal.
+        ...(result.failed.length > 0 ? { failed: result.failed.length } : {}),
+        ...(result.rateLimited
+          ? {
+              rateLimited: {
+                until: result.rateLimited.until,
+                waiting: result.rateLimited.waiting,
+              },
+            }
+          : {}),
       });
+      if (result.rateLimited) {
+        // Once per boot (the store dedupes by id): a pause is not an error,
+        // and the panel should say so in words rather than leave a person to
+        // read a failure count and guess.
+        statusStore?.notice?.({
+          id: 'files-rate-limited',
+          severity: 'info',
+          text: `The workspace asked this machine to slow down, so file syncing is paused for a moment. ${
+            result.rateLimited.waiting > 0
+              ? `${result.rateLimited.waiting} file(s) are still on their way — nothing is lost, they arrive when the pause lifts.`
+              : 'Nothing is lost; it resumes by itself.'
+          }`,
+        });
+      }
       for (const f of result.failed) {
         console.warn(`[sync/files] ${f.rel}: ${f.reason}`);
       }
@@ -2927,8 +4253,10 @@ export function createSyncRuntime(
       // journal-less hubs, which the compat matrix keeps working through the
       // burn-down window.
       if (filePlane) {
-        const result = await filePlane.reconcile();
-        noteFilePlane(result);
+        // Through the SAME door as the poke path, so the two can never overlap
+        // (issue #109). `floor: false` — this caller is already bounded, and a
+        // deferral would make an awaited pass silently not happen.
+        await runPlanePass({ floor: false });
         return;
       }
       const result = await pullFiles({
@@ -2940,13 +4268,20 @@ export function createSyncRuntime(
       });
       noteFilePull(result);
     };
+    documentDiscovery = createDocumentDiscovery({
+      run: pullRemoteOnce,
+      onError: (error) => console.error('[sync] document discovery failed:', error),
+    });
+    const discovery = documentDiscovery;
+    documentDiscoveryUnsub = ctx.bus.on('sync:documents-changed', () => discovery.schedule());
     const pollRemote = (): void => {
-      void pullRemoteOnce()
+      void discovery
+        .flush()
         .then(() => pullFilesOnce())
         .catch((err) => console.error('[sync] remote poll failed:', err));
     };
     remotePull = async () => {
-      await pullRemoteOnce();
+      await discovery.flush();
       await pullFilesOnce();
     };
     remotePollTimer = setInterval(pollRemote, REMOTE_POLL_MS);
@@ -2954,6 +4289,81 @@ export function createSyncRuntime(
     // dev server to refuse to exit.
     remotePollTimer.unref?.();
 
+    // ── The stall watchdog (issue #118) ────────────────────────────────────
+    //
+    // WE CANNOT TRUST THE SOCKET TO NOTICE. `HocuspocusProviderWebsocket`
+    // reports `connected` from the raw WS `open` event — before a token is
+    // presented, before a byte comes back — and its own silence watchdog
+    // (`checkConnection`) returns early while `lastMessageReceived === 0`,
+    // which is precisely the state every fresh connection starts in. So a
+    // socket that upgrades at the edge and then hears nothing (a cell woken
+    // from `sleepAfter`, still restoring behind a DO that has accepted the
+    // request) is PERMANENTLY "connected" with its watchdog switched off. No
+    // close event, no retry, no reconnect — and therefore, before this, no
+    // recovery short of the person pressing Resync.
+    //
+    // This is the liveness check the runtime should have owned all along: it
+    // judges the link by whether any DOCUMENT has settled, which is the thing
+    // the user actually wants, and it is the one signal a half-open socket
+    // cannot fake. When nothing has settled for long enough, force the socket
+    // down and back up; every provider re-authenticates on the new one and
+    // `repromoteOnReconnect` collects the result.
+    //
+    // Deliberately narrow, because a false positive costs a full re-handshake
+    // of every canvas:
+    //   • `state === 'online'`  — offline already has its own recovery path.
+    //   • `synced === 0 && pending > 0` — some progress means it is working,
+    //     just slowly; this is only for the total stall.
+    //   • `rejected === 0` — a refusal is the auth lane's: renew + re-probe for
+    //     the permanent classes, the paced per-document retry for the
+    //     transient ones. Cycling the socket would re-authenticate EVERY
+    //     document to recover a few, and a volume refusal is exactly when
+    //     that burst hurts most.
+    //   • a floor between forced reconnects, so a hub that is simply down
+    //     cannot be turned into a reconnect storm by its own silence.
+    // The socket-cycling capability, resolved once.
+    //
+    // Was `ownedFactory`, which is null whenever a factory is INJECTED — so the
+    // watchdog silently no-op'd in every test that could have exercised it, and
+    // its jitter and backoff had no coverage at all (verification review
+    // 2026-09-03). An injected factory that offers `reconnect()` is just as
+    // usable. The `typeof` check is also the N4 guard: `sockets` is a
+    // `Map<string, any>` and the provider is a caret dependency, so a 4.x minor
+    // that renames this would otherwise degrade to a watchdog that can never
+    // recover, saying nothing.
+    const reconnectable: { reconnect(): void } | null =
+      ownedFactory ??
+      (typeof (providerFactory as Partial<DisposableProviderFactory>).reconnect === 'function'
+        ? (providerFactory as DisposableProviderFactory)
+        : null);
+    const stallCheck = (): void => {
+      if (stopped || !reconnectable) return;
+      const snap = mon.snapshot();
+      const docs = snap.docs;
+      if (snap.state !== 'online' || !docs) return;
+      if (docs.synced > 0 || docs.pending === 0 || docs.rejected > 0) return;
+      const now = stallNow();
+      if (now - lastPromotionAt < stallAfterMs + stallJitterMs) return;
+      // The floor DOUBLES per forced reconnect (5 → 10 → 20 → capped at 30 min).
+      // A hub that is simply down would otherwise buy a fresh N-document auth
+      // burst from every peer every five minutes, forever.
+      const floor = Math.min(STALL_RECONNECT_MAX_MS, stallMinMs * 2 ** forcedReconnects);
+      if (lastForcedReconnectAt !== 0 && now - lastForcedReconnectAt < floor) return;
+      lastForcedReconnectAt = now;
+      forcedReconnects += 1;
+      console.warn(
+        `[sync] the hub socket says connected but not one of ${docs.pending} document(s) has ` +
+          `synced in ${Math.round((now - lastPromotionAt) / 60_000)} minute(s) — forcing a reconnect.`
+      );
+      try {
+        reconnectable.reconnect();
+      } catch (err) {
+        console.warn(`[sync] forced reconnect failed: ${(err as Error).message}`);
+      }
+    };
+    stallTimer = setInterval(stallCheck, stallCheckMs);
+    stallTimer.unref?.();
+
     // ── Sync v2 Increment 2 — the poke, desktop side (DDR-226 §4) ──────────
     //
     // CAPABILITY-GATED, and the gate is the compat matrix (§10, BINDING): a
@@ -2991,6 +4401,23 @@ export function createSyncRuntime(
               designRoot: ctx.paths.designRoot,
               hubUrl: linkedHub.url,
               token: () => token,
+              // THE FILE PLANE CAN NOW ASK FOR A CREDENTIAL. It could not
+              // before: renewal was reachable only from the doc lane's
+              // WebSocket auth failure, so a token that expired mid-seed left
+              // hundreds of files refused with nothing ever asking for a new
+              // one (2026-09-03). Same single-flight entry point the doc lane
+              // uses — never a second renewal path.
+              onAuthFailure: () => {
+                void renewCredentialNow();
+              },
+              // A DELIVERED FILE IS PROGRESS. `renewalsSinceProgress` counted
+              // only doc handshakes, and a converged doc lane has none left to
+              // land — so during a long seed the cap was reached and the
+              // runtime stopped renewing while the file plane was still
+              // working.
+              onProgress: () => {
+                renewalsSinceProgress = 0;
+              },
               ledger: fileLedger,
               canvasGroups: ctx.cfg.canvasGroups,
               allowCodeModules,
@@ -3024,6 +4451,7 @@ export function createSyncRuntime(
           fileEventsCtl = createCtlProvider({
             url: linkedHub.url,
             token,
+            onDocuments: () => documentDiscovery?.schedule(),
             onPoke: () => {
               // Reuses `pollRemoteSoon` rather than calling the file lanes
               // directly, for two reasons: it already coalesces a burst into
@@ -3064,6 +4492,8 @@ export function createSyncRuntime(
   async function stop(): Promise<void> {
     if (stopped) return;
     stopped = true;
+    acceptedLink?.stop();
+    revisionBarrier.stop();
     fileEventsProbe?.abort();
     fileEventsProbe = null;
     if (filePassTimer !== null) clearTimeout(filePassTimer);
@@ -3096,8 +4526,14 @@ export function createSyncRuntime(
     discoveryRescan = null;
     if (remotePollTimer !== null) clearInterval(remotePollTimer);
     remotePollTimer = null;
+    if (stallTimer !== null) clearInterval(stallTimer);
+    stallTimer = null;
     if (remotePollSoonTimer !== null) clearTimeout(remotePollSoonTimer);
     remotePollSoonTimer = null;
+    documentDiscoveryUnsub?.();
+    documentDiscoveryUnsub = null;
+    documentDiscovery?.stop();
+    documentDiscovery = null;
     remotePull = null;
     // A push pass that outlives its runtime keeps uploading a project the
     // person just closed — and `restart()` (the Resync button) calls stop() on
@@ -3136,6 +4572,10 @@ export function createSyncRuntime(
       authClearTimer(reprobeTimer);
       reprobeTimer = null;
     }
+    if (transientRetryTimer !== null) {
+      authClearTimer(transientRetryTimer);
+      transientRetryTimer = null;
+    }
     if (renewTimer !== null) {
       authClearTimer(renewTimer);
       renewTimer = null;
@@ -3145,8 +4585,13 @@ export function createSyncRuntime(
     for (const h of announceTimers.values()) clearTimeout(h);
     announceTimers.clear();
     rejectedPermanent.clear();
+    rejectedTransient.clear();
+    transientStrikes.clear();
+    transientSpent.length = 0;
+    owedSetups.clear();
     busUnsub?.();
     busUnsub = null;
+    for (const u of activityUnsubs.splice(0)) u();
     fsReader?.stop();
     fsReader = null;
     for (const agent of agents.values()) {
@@ -3231,6 +4676,145 @@ export function createSyncRuntime(
       return true;
     },
     retireForMove: (fromSlug, toRel) => serializeMembership(() => retireForMove(fromSlug, toRel)),
+    proposeLane: (slug, lane, text, o) => {
+      if (!acceptedOn()) return null;
+      const projection = projections.get(slug);
+      if (!projection) return null;
+      const value = laneValueFromFile(lane, text);
+      if (value === null) return null;
+      const base = o?.baseText === undefined ? undefined : laneValueFromFile(lane, o.baseText);
+      return projection.proposeLane(lane, value, {
+        ...(base !== undefined && base !== null ? { baseContent: base } : {}),
+        ...(o?.writeId ? { writeId: o.writeId } : {}),
+      });
+    },
+    proposeFolder,
+    acceptedMode: acceptedOn,
+    acceptedWriteViolations: () => acceptedWriteViolations,
+    acceptedHistory: async (q) => {
+      if (!acceptedOn() || !acceptedLink) return null;
+      // Fresh, not the cached manifest: a canvas created since the last
+      // bootstrap has history too, and a stale map named no entry for it.
+      const manifest = (await acceptedLink.refresh().catch(() => null)) ?? acceptedLink.manifest;
+      if (!manifest) return null;
+      const pathOf = new Map(manifest.docs.map((d) => [d.doc, d.path]));
+      let entry: string | null = null;
+      if (q.path) {
+        const slug = slugForRepoRel(q.path);
+        const doc = slug ? docNameFor(slug) : null;
+        entry = manifest.docs.find((d) => d.doc === doc)?.entry ?? null;
+        if (!entry) return [];
+      }
+      const { history } = await acceptedLink.history({
+        limit: Math.min(Math.max(q.limit ?? 50, 1), 200),
+        before: q.before ?? null,
+        entry,
+      });
+      const you = manifest.you?.actor ?? null;
+      return history.map((a) => {
+        const canvases = new Set<string>();
+        for (const e of a.effects) {
+          const p = e.afterPath ?? (e.doc ? pathOf.get(e.doc) : null) ?? e.beforePath;
+          if (p && /\.(tsx|html)$/i.test(p)) canvases.add(p);
+        }
+        return {
+          revision: a.revision,
+          actionId: a.actionId,
+          actor: a.actor,
+          mine: you !== null && a.actor === you,
+          kind: a.kind,
+          label: a.label,
+          committedAt: a.committedAt,
+          undoes: a.undoes,
+          canvases: [...canvases].sort(),
+        };
+      });
+    },
+    acceptedVersion: async (repoRel, revision) => {
+      if (!acceptedOn() || !acceptedLink) return null;
+      const slug = slugForRepoRel(repoRel);
+      if (!slug) return null;
+      const r = await acceptedLink.laneAt(slug, 'html', revision);
+      return r.body || null;
+    },
+    acceptedRestore: async (repoRel, revision) => {
+      if (!acceptedOn() || !acceptedLink) return null;
+      const slug = slugForRepoRel(repoRel);
+      if (!slug) return { status: 'rejected', code: 'unknown-canvas' };
+      const name = path.basename(repoRel).replace(/\.(tsx|html)$/i, '');
+      return acceptedLink.restore([slug], revision, `Restore ${name} to version ${revision}`);
+    },
+    acceptedUndo: async (actionId, redo = false) => {
+      if (!acceptedOn() || !acceptedLink) return null;
+      return acceptedLink.undo(actionId, redo);
+    },
+    prepareOffline: async () => {
+      if (!filePlane) return null;
+      let pulled = 0;
+      let passes = 0;
+      let failed = 0;
+      for (; passes < 40 && !stopped; passes += 1) {
+        lastPlaneResult = null;
+        await runPlanePass({ floor: false });
+        const r = lastPlaneResult as import('./file-plane.ts').FilePlaneResult | null;
+        if (!r) break;
+        pulled += r.pulled.length;
+        failed = r.failed.length;
+        if (r.pulled.length === 0 && !r.budgetExhausted) {
+          return { complete: failed === 0, pulled, passes: passes + 1, failed };
+        }
+      }
+      return { complete: false, pulled, passes, failed };
+    },
+    acceptedActionForContent: (repoRel, content) => {
+      const slug = slugForRepoRel(repoRel);
+      return slug ? (acceptedByContent.get(`${slug}|html|${hashBytes(content)}`) ?? null) : null;
+    },
+    conflictVersions: (repoRel) => {
+      // A slug (the Sync panel's notice id) or a repo-relative canvas path.
+      const slug = projections.has(repoRel) ? repoRel : slugForRepoRel(repoRel);
+      const sides = slug ? projections.get(slug)?.conflictSides() : null;
+      return slug && sides ? { slug, ...sides } : null;
+    },
+    resolveConflict: async (repoRel, choice) => {
+      const slug = projections.has(repoRel) ? repoRel : slugForRepoRel(repoRel);
+      const projection = slug ? projections.get(slug) : undefined;
+      if (!slug || !projection) return null;
+      const sides = projection.conflictSides();
+      if (!sides) return null;
+      if (choice === 'theirs') {
+        projection.takeAccepted();
+        return { status: 'taken' };
+      }
+      if (sides.mine === null) return { status: 'rejected', code: 'no-local-version' };
+      // Mine, on top of the version that won — a new action, never a rewind.
+      const r = await projection.proposeLane('html', sides.mine, { baseContent: sides.theirs });
+      if (!r) return null;
+      if (r.status === 'accepted') statusStore?.clearSourceConflict?.(slug);
+      return { status: r.status, ...(r.code ? { code: r.code } : {}) };
+    },
+    beginAiAction: (key, label) => {
+      if (!acceptedOn() || !acceptedLink) return;
+      acceptedLink.stage.begin(key, label);
+    },
+    endAiAction: async (key, outcome) => {
+      if (!acceptedLink) return null;
+      // The watcher delivers the last tool write a beat after the tool
+      // returns; let it land in the stage before the stage closes.
+      await new Promise((r) => setTimeout(r, AI_ACTION_SETTLE_MS));
+      await (discoveryRescan?.flush() ?? Promise.resolve()).catch(() => {});
+      const r = await acceptedLink.stage.end(key, outcome);
+      return r ? { status: r.status, ...(r.code ? { code: r.code } : {}) } : null;
+    },
+    resolveAiAction: async (choice) => {
+      if (!acceptedLink || acceptedLink.stage.state !== 'held') return null;
+      if (choice === 'discard') {
+        const canvases = acceptedLink.stage.discard();
+        return { status: 'discarded', canvases };
+      }
+      const r = await acceptedLink.stage.publish();
+      return r ? { status: r.status, ...(r.code ? { code: r.code } : {}) } : null;
+    },
   };
 }
 
@@ -3775,6 +5359,16 @@ export interface DisposableProviderFactory extends ProviderFactory {
   /** Destroy the shared HocuspocusProviderWebsocket(s). Call AFTER provider
    *  destroys — a provider detach sends a Close message over the socket. */
   dispose(): void;
+  /**
+   * Take every shared socket down and bring it back up (issue #118).
+   *
+   * The escape hatch for a socket that reports `connected` and carries nothing
+   * — see the stall watchdog in `start()`. Providers are NOT destroyed and are
+   * NOT re-created: they stay attached across the cycle and re-authenticate on
+   * the new socket, exactly as they do after any ordinary drop, so this costs a
+   * handshake and never a re-attach.
+   */
+  reconnect(): void;
 }
 
 /**
@@ -3824,7 +5418,31 @@ export function createDefaultProviderFactory(
     const wsUrl = toWsUrl(args.url);
     let socket = sockets.get(wsUrl);
     if (!socket) {
-      socket = new mod.HocuspocusProviderWebsocket({ url: wsUrl });
+      // CONFIGURED, not defaulted (issue #118). The socket used to be built
+      // from the URL alone, which inherited `timeout: 0` — no per-attempt
+      // deadline — and that is the property that let one parked connection
+      // attempt silence the whole link for as long as the process lived. The
+      // other two are pinned rather than inherited so a provider upgrade cannot
+      // move them without someone noticing here.
+      // NO `timeout`. It is tempting — the default is 0, meaning a connection
+      // attempt has no deadline at all — and it is a TRAP: `@lifeomic/attempt`
+      // handles a timeout by calling `reject` DIRECTLY, bypassing the `onError`
+      // path that is the only thing which schedules another attempt. So the
+      // deadline does not retry the attempt, it ENDS THE CHAIN — and since
+      // every one of hocuspocus's `connect()` call sites floats the promise and
+      // this process registers no `unhandledRejection` handler, a hub merely
+      // being slow would take the dev server down (security review 2026-09-03,
+      // F2). A hub slower than the deadline is the NORMAL case this whole fix
+      // is about: a sleeping cell's `/health` measured 14 s, and a container
+      // cold-boot is routinely worse.
+      //
+      // Liveness is the runtime's job instead — see the stall watchdog in
+      // `start()`, which is a layer we control and can make safe.
+      socket = new mod.HocuspocusProviderWebsocket({
+        url: wsUrl,
+        messageReconnectTimeout: 30_000,
+        maxDelay: 30_000,
+      });
       sockets.set(wsUrl, socket);
     }
     // Phase 9.2 (DDR-064) — attach to the shared room doc when the runtime
@@ -3848,11 +5466,71 @@ export function createDefaultProviderFactory(
     // With an injected websocketProvider the provider does NOT auto-attach
     // (manageSocket=false in @hocuspocus/provider 4.x) — attach explicitly.
     provider.attach();
+
+    // `provider.synced` IS NOT TRUSTWORTHY ACROSS A STATUS TRANSITION.
+    //
+    // A provider learns a socket died only from the `close` EVENT, and the
+    // library itself does not always raise one: `checkConnection()`'s
+    // force-close branch (`closeTries > 2`) CALLS `this.onClose({code:4408})`
+    // directly, and `cleanupWebSocket()` has already detached the raw handlers
+    // by then — so no `close` is emitted, no provider's `boundOnClose` runs,
+    // and every provider keeps `isSynced === true` through the teardown. That
+    // branch is reached by exactly the failure this whole change is about: a
+    // link that WAS healthy and then went quiet for 30 s.
+    //
+    // It gets worse quietly. `set synced` is a no-op when the value is
+    // unchanged, so a provider left stale-true does not emit `synced` on its
+    // NEXT genuine handshake either — the flag is wrong in both directions.
+    //
+    // Before this change the staleness was inert (nothing re-promoted on it).
+    // `repromoteOnReconnect` makes it authoritative: `onceSynced()`
+    // short-circuits on that field, so it would resolve instantly and report a
+    // handshake that never happened, for every document, then disarm the stall
+    // watchdog through its own `docs.synced > 0` guard (verification review
+    // 2026-09-03, NEW-1 — the same defect as N1, arriving through the library
+    // instead of through us).
+    //
+    // So: model the reset the missing event would have done. Assigning `false`
+    // only flips the flag (the setter emits on `true` alone), which is exactly
+    // the `synced` half of `HocuspocusProvider.onClose()` and none of its
+    // awareness side effects — those belong to the real close event, and still
+    // run when there is one.
+    const resetSyncedOnDrop = (evt: { status?: string }): void => {
+      if (evt?.status && evt.status !== 'connected' && provider.synced) provider.synced = false;
+    };
+    socket.on('status', resetSyncedOnDrop);
+
+    let authedThisConnection = false;
+    provider.on('authenticated', () => {
+      authedThisConnection = true;
+    });
+    const forgetAuthOnDrop = (evt: { status?: string }) => {
+      if (evt?.status !== 'connected') authedThisConnection = false;
+    };
+    socket.on('status', forgetAuthOnDrop);
     return {
       document,
       // HocuspocusProvider creates a hub-synced Awareness by default; expose it
       // so the runtime can bridge it to the collab Room (Task 5).
       awareness: provider.awareness as Awareness | undefined,
+      isRemoteOrigin: (origin: unknown) => origin === provider,
+      // Writable = authenticated read-write ON THIS CONNECTION. A scope left
+      // over from before a drop says nothing about the hub now: a project
+      // switched to accepted revisions while this peer was away re-admits it
+      // read-only, and anything written in between would be dropped there.
+      isWritable: () => authedThisConnection && provider.authorizedScope === 'read-write',
+      onAuthenticated(cb: (scope: string) => void): () => void {
+        const handler = (evt: { scope?: string }) => cb(String(evt?.scope ?? ''));
+        provider.on('authenticated', handler);
+        return () => provider.off('authenticated', handler);
+      },
+      onStateless(cb: (payload: string) => void): () => void {
+        const handler = (evt: { payload?: string }) => {
+          if (typeof evt?.payload === 'string') cb(evt.payload);
+        };
+        provider.on('stateless', handler);
+        return () => provider.off('stateless', handler);
+      },
       onStatus(cb: (status: ProviderStatus) => void): () => void {
         // The shared socket emits 'status' on every WS transition and every
         // ATTACHED provider re-emits it (forwardStatus), so per-provider
@@ -3875,20 +5553,35 @@ export function createDefaultProviderFactory(
         authFailedCbs.add(cb);
         return () => authFailedCbs.delete(cb);
       },
-      onceSynced(): Promise<void> {
+      onceSynced(signal?: AbortSignal): Promise<void> {
         return new Promise<void>((resolve) => {
           if (provider.synced) {
             resolve();
             return;
           }
           const handler = () => {
-            provider.off('synced', handler);
+            cleanup();
             resolve();
           };
+          // Detach on abort as well as on success — see the interface doc. The
+          // promise is deliberately NOT rejected: callers race it against their
+          // own ceiling and read a separate flag, so a rejection here would be
+          // an unhandled one at every site that stops waiting.
+          const cleanup = () => {
+            provider.off('synced', handler);
+            signal?.removeEventListener('abort', cleanup);
+          };
+          if (signal?.aborted) {
+            resolve();
+            return;
+          }
           provider.on('synced', handler);
+          signal?.addEventListener('abort', cleanup, { once: true });
         });
       },
       destroy() {
+        socket.off('status', resetSyncedOnDrop);
+        socket.off('status', forgetAuthOnDrop);
         // Detaches from the shared socket (sends a per-document Close); the
         // socket itself is destroyed by dispose() after all providers.
         provider.destroy();
@@ -3907,6 +5600,63 @@ export function createDefaultProviderFactory(
       }
       sockets.clear();
     },
+    reconnect(): void {
+      for (const socket of sockets.values()) {
+        try {
+          // NOT `disconnect()` + `connect()` — that pair WEDGES THE SOCKET SHUT,
+          // deterministically, in exactly the state this is called from
+          // (security review 2026-09-03, F1). `disconnect()` sets
+          // `shouldConnect = false` and closes the WS without touching
+          // `status`; the close event is asynchronous, so the immediately
+          // following `connect()` hits its own first guard —
+          // `if (this.status === WebSocketStatus.Connected) return;` — which
+          // sits ABOVE the line that would restore `shouldConnect`. When the
+          // close finally lands, `onClose`'s re-arm reads
+          // `!cancelWebsocketRetry && shouldConnect` → false, and nothing else
+          // re-arms it. The recovery action would have turned a stall that
+          // survives a restart into a link that never reconnects again.
+          //
+          // So take the path the library is actually built around: close the
+          // raw socket and let its OWN close-driven reconnect run — byte for
+          // byte what happens when the hub drops us, which is the best-tested
+          // path in the provider. `shouldConnect` stays true, and
+          // `cancelWebsocketRetry` is already clear (only `onOpen` clears it,
+          // and a socket reporting `connected` has been through `onOpen`).
+          //
+          // `connect()` is the fallback for the no-live-socket case ONLY, where
+          // status is not `Connected` and it therefore does not early-return.
+          //
+          // EMIT THE EVENT — do not call the handler.
+          //
+          // `HocuspocusProviderWebsocket.onClose()` looks like the right entry
+          // point (`checkConnection()` calls it with this exact 4408 frame) and
+          // calling it directly is WRONG in a way that is invisible until you
+          // read who else listens. That method emits `status` and `disconnect`
+          // — never `close`. Each attached PROVIDER learns about a drop through
+          // `websocketProvider.on('close', boundOnClose)`, and
+          // `HocuspocusProvider.onClose()` is the only thing that resets
+          // `isAuthenticated` and `synced`. Skip the event and every provider
+          // keeps `synced === true` across the reconnect; `set synced` is a
+          // no-op when unchanged, so the NEXT real handshake emits nothing
+          // either, and `onceSynced()` — which short-circuits on that field —
+          // resolves instantly for all 85 documents against a socket that has
+          // completed no handshake at all. The recovery would have manufactured
+          // `docs.synced = 85` out of nothing, and then disarmed the watchdog
+          // permanently through its own `docs.synced > 0` guard (verification
+          // review 2026-09-03, N1).
+          //
+          // Emitting is what the raw socket's own handler does
+          // (`onCloseHandler = (payload) => this.emit('close', {event: payload})`),
+          // and the constructor registers `this.on('close', this.onClose)` —
+          // so this runs every provider's reset AND the socket's own cleanup +
+          // re-arm. THAT is "byte for byte what happens when the hub drops us";
+          // the handler call only resembled it.
+          socket.emit('close', { event: { code: 4408, reason: 'forced' } });
+        } catch (err) {
+          console.warn(`[sync] socket reconnect failed: ${(err as Error).message}`);
+        }
+      }
+    },
   });
 }