@1agh/maude 1.2.0 → 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,7 +60,8 @@ 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, MAX_DORUCEKA_ROWS } from './file-plane.ts';
 import { type FilePullResult, pullFiles } from './file-pull.ts';
@@ -80,7 +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';
@@ -95,6 +103,25 @@ export interface SyncProvider {
    * the bridge.
    */
   readonly awareness?: Awareness;
+  /**
+   * 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.
    *
@@ -125,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
@@ -148,6 +176,33 @@ 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. */
@@ -276,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.
@@ -311,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.',
 };
 
 /**
@@ -422,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). */
@@ -490,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;
   };
 }
 
@@ -728,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) --------------------
@@ -878,6 +1116,39 @@ export function createSyncRuntime(
     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;
@@ -894,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
@@ -1002,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.
    *
@@ -1037,6 +1314,7 @@ export function createSyncRuntime(
   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.
@@ -1061,6 +1339,7 @@ export function createSyncRuntime(
     const run = (async () => {
       try {
         const r = await lane.reconcile();
+        lastPlaneResult = r;
         planeResultSink?.(r);
       } catch (err) {
         console.error('[sync/files] pass failed:', err);
@@ -1106,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) {
@@ -1383,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
@@ -1452,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;
   }
@@ -1468,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);
@@ -1493,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;
@@ -1547,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
@@ -1798,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
@@ -1856,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.
@@ -1968,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);
         });
       }
@@ -1982,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
@@ -2084,8 +2765,9 @@ export function createSyncRuntime(
       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);
@@ -2107,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();
       }
     };
 
@@ -2126,6 +2833,8 @@ 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.`);
@@ -2138,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);
@@ -2190,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.`
             );
@@ -2214,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
@@ -2237,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') {
@@ -2246,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 ${
@@ -2344,8 +3089,8 @@ export function createSyncRuntime(
       // REFUSED IS REFUSED, WHATEVER THE CLASS.
       //
       // This guard read `rejectedPermanent`, and that map holds only the two
-      // PERMANENT classes — `handleAuthFailure` puts `generic` and `rate-limit`
-      // nowhere (they keep their provider and its backoff). `generic` is what
+      // 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
@@ -2594,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.
@@ -2663,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.
@@ -2737,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
@@ -2776,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
@@ -2986,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(
@@ -3038,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);
       }
@@ -3064,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
@@ -3402,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);
@@ -3441,7 +4314,11 @@ export function createSyncRuntime(
     //   • `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).
+    //   • `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.
@@ -3574,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
@@ -3614,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);
@@ -3650,6 +4530,10 @@ export function createSyncRuntime(
     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
@@ -3688,6 +4572,10 @@ export function createSyncRuntime(
       authClearTimer(reprobeTimer);
       reprobeTimer = null;
     }
+    if (transientRetryTimer !== null) {
+      authClearTimer(transientRetryTimer);
+      transientRetryTimer = null;
+    }
     if (renewTimer !== null) {
       authClearTimer(renewTimer);
       renewTimer = null;
@@ -3697,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()) {
@@ -3783,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;
+    },
   };
 }
 
@@ -4468,11 +5500,37 @@ export function createDefaultProviderFactory(
     };
     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
@@ -4523,6 +5581,7 @@ export function createDefaultProviderFactory(
       },
       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();