@1agh/maude 0.60.7 → 1.0.2

package/apps/studio/sync/cold-start-apply.ts

@@ -0,0 +1,211 @@
+// The ONE application body for the cold-start decision tables — Sync v2
+// Increment 0 (DDR-226), closing the drift class DDR-102's own text warned
+// about ("the decision table is a pure module consumed by BOTH sync paths" —
+// the TABLE was shared, the APPLICATION was not).
+//
+// Before this module there were two appliers:
+//
+//   1. `agent.ts reconcile()`      — the desktop two-doc path
+//   2. `migrate-seed.ts migrateSeed()` — the shared-doc / cell path
+//
+// Same table, two switches, and they had already drifted THREE times:
+//
+//   - the DDR-076 empty-hub guard had to be written twice,
+//   - the DDR-223 annotations eraser had to be FIXED twice,
+//   - and `migrateSeed`'s switch was missing a `recover-seed-dup` case *and*
+//     a default, so that decision fell through to "hub-wins" and a duplicated
+//     body was kept and materialized to disk. That one was LIVE when this
+//     module landed.
+//
+// The fix is structural, not vigilance: this switch is exhaustive over
+// `ColdStartAction` with a compile-time `never` default, so adding a row to
+// the table without handling it here is a TYPE ERROR, not a silent
+// fallthrough. Both callers import this function; `test/cold-start-apply.test.ts`
+// pins that they do.
+//
+// What stays with the callers is only what genuinely differs between the two
+// substrates, injected as three effects:
+//
+//   - `takeHub()`    — agent: write the doc body to disk + checkpoint.
+//                      migrate-seed: nothing (the projection materializes).
+//   - `takeLocal()`  — agent: seed the local body up into the doc.
+//                      migrate-seed: rebuild body (+ css) inside ONE MIGRATION
+//                      transaction.
+//   - `checkpointIdentity()` — journal write for identical non-empty sides.
+//
+// Everything else — the order of the rows, the dual snapshot, the DDR-102
+// fail-closed refusal, the conflict report, the resulting body winner — lives
+// here exactly once.
+
+import type { ColdStartAction, ColdStartDecision } from './cold-start.ts';
+
+export type ColdStartSnapshotReason = 'pre-sync-local' | 'pre-sync-hub';
+
+export interface ColdStartConflictInfo {
+  slug: string;
+  kind: 'cold-start-diverged';
+  winner?: 'local' | 'hub';
+  snapshots?: { local?: string; hub?: string };
+  /** DDR-102 fail-closed (F1) — local snapshot didn't land; hub-wins refused. */
+  snapshotFailed?: boolean;
+}
+
+export interface ColdStartApplyInput {
+  slug: string;
+  /** The verdict from `decideColdStart`. */
+  decision: ColdStartDecision;
+  /** Local body file content, or null when absent. */
+  localBody: string | null;
+  /** Body currently held by the doc. */
+  docBody: string;
+
+  /** Make the HUB body the winner (materialize / fast-forward / conflict-hub). */
+  takeHub: () => void | Promise<void>;
+  /** Make LOCAL the winner — seed it up so the hub converges on our bytes. */
+  takeLocal: (localBody: string) => void | Promise<void>;
+  /** Both sides already identical: record the journal checkpoint so the NEXT
+   *  boot fast-forwards instead of re-entering the conflict path. */
+  checkpointIdentity?: (body: string) => void;
+
+  /** DDR-102 dual snapshot. Absent ⇒ plain newest-wins (standalone/test wiring). */
+  snapshot?: (content: string, reason: ColdStartSnapshotReason) => Promise<string | null>;
+  onConflict?: (info: ColdStartConflictInfo) => void;
+
+  /** Log prefix, so the two callers keep their distinguishable lines
+   *  (`[sync/<slug>]` vs `[sync/<slug>] shared-doc`). */
+  logLabel?: string;
+  log?: { warn: (msg: string) => void; error: (msg: string) => void };
+}
+
+export interface ColdStartApplyResult {
+  /** The action that was actually applied (echo of `decision.action`). */
+  action: ColdStartAction;
+  /** Which side owns the visually-coupled lanes (css; annotations' fallback). */
+  bodyWinner: 'local' | 'hub';
+  /** Set only when `action === 'conflict'`. */
+  conflict?: {
+    /** The winner AFTER the fail-closed guard — may differ from `decision.winner`. */
+    winner: 'local' | 'hub';
+    snapshots: { local?: string; hub?: string };
+    /** True when a hub-wins verdict was REFUSED because the local snapshot
+     *  didn't land (DDR-102 fail-closed). */
+    snapshotFailed: boolean;
+  };
+}
+
+const defaultLog = {
+  warn: (msg: string) => console.warn(msg),
+  error: (msg: string) => console.error(msg),
+};
+
+/**
+ * Apply a cold-start body decision. Total over `ColdStartAction`.
+ *
+ * Returns the resolved `bodyWinner` so callers can drive the per-lane
+ * annotations table (DDR-223) and the visually-coupled css lane from one
+ * answer instead of re-deriving it from a result string.
+ */
+export async function applyColdStart(input: ColdStartApplyInput): Promise<ColdStartApplyResult> {
+  const { slug, decision, localBody, docBody, takeHub, takeLocal } = input;
+  const log = input.log ?? defaultLog;
+  const prefix = input.logLabel ? `[sync/${slug}] ${input.logLabel}` : `[sync/${slug}]`;
+
+  switch (decision.action) {
+    case 'noop': {
+      // Identical non-empty sides: checkpoint identity so the next boot
+      // fast-forwards even if the hub then moves ahead. (Both-empty falls in
+      // here too and carries nothing to checkpoint.)
+      if (localBody !== null && localBody === docBody && docBody !== '') {
+        input.checkpointIdentity?.(docBody);
+      }
+      return { action: decision.action, bodyWinner: 'hub' };
+    }
+
+    case 'materialize-hub':
+    case 'fast-forward-hub': {
+      await takeHub();
+      return { action: decision.action, bodyWinner: 'hub' };
+    }
+
+    case 'seed-local-up': {
+      // The DDR-064/076 empty-hub guard as a named row: an empty hub doc means
+      // the hub holds no body for this slug YET — never an authoritative blank.
+      await takeLocal(localBody as string);
+      return { action: decision.action, bodyWinner: 'local' };
+    }
+
+    case 'recover-seed-dup': {
+      // Concurrent cold-seed collision: the hub body is our local body repeated
+      // N≥2 times. Re-applying local makes the codec's diff delete the trailing
+      // duplicate; the content equals local, so the coupled lanes follow local.
+      // Idempotent across peers — concurrent recoveries converge.
+      //
+      // This case is why the module exists: migrate-seed used to have no row
+      // for it and no default, so the duplicated body was kept.
+      await takeLocal(localBody as string);
+      return { action: decision.action, bodyWinner: 'local' };
+    }
+
+    case 'conflict': {
+      // Divergence: snapshot BOTH versions BEFORE any write, then apply the
+      // newest-wins winner. Even a wrong pick then costs one /design:rollback.
+      const snapshots: { local?: string; hub?: string } = {};
+      let snapshotAttempted = false;
+      if (input.snapshot) {
+        snapshotAttempted = true;
+        try {
+          const localTs = await input.snapshot(localBody as string, 'pre-sync-local');
+          if (localTs) snapshots.local = localTs;
+          const hubTs = await input.snapshot(docBody, 'pre-sync-hub');
+          if (hubTs) snapshots.hub = hubTs;
+        } catch {
+          /* swallowed — the missing snapshot ref drives the fail-closed guard */
+        }
+      }
+
+      // DDR-102 fail-closed (security F1): the whole guarantee is "the loser is
+      // recoverable from _history/". A hub-wins resolution overwrites local — so
+      // if we ASKED for a snapshot and the local one did not land (full disk,
+      // read-only `_history/`, a write error), refuse the destructive overwrite:
+      // keep local and seed it up instead. Nothing is lost on either side.
+      // `snapshotAttempted` gates this to production wiring, so a snapshot-less
+      // standalone/test caller keeps plain newest-wins.
+      const localSnapshotMissing = snapshotAttempted && !snapshots.local;
+      let winner: 'local' | 'hub' = decision.winner ?? 'hub';
+      if (winner === 'hub' && localSnapshotMissing) {
+        winner = 'local';
+        log.error(
+          `${prefix} cold-start divergence: hub won newest-wins but the local snapshot FAILED — REFUSING to overwrite local (DDR-102 fail-closed). Keeping local + pushing it up; resolve the _history/ write failure (disk full / read-only?) to restore newest-wins.`
+        );
+      }
+
+      if (winner === 'local') {
+        await takeLocal(localBody as string);
+      } else {
+        await takeHub();
+      }
+
+      log.warn(`${prefix} cold-start divergence — ${decision.reason}`);
+      input.onConflict?.({
+        slug,
+        kind: 'cold-start-diverged',
+        winner,
+        ...(snapshots.local || snapshots.hub ? { snapshots } : {}),
+        ...(localSnapshotMissing ? { snapshotFailed: true } : {}),
+      });
+
+      return {
+        action: decision.action,
+        bodyWinner: winner,
+        conflict: { winner, snapshots, snapshotFailed: localSnapshotMissing },
+      };
+    }
+
+    default: {
+      // Exhaustiveness: adding a `ColdStartAction` without a row above is a
+      // compile error here, never a silent "hub keeps whatever it had".
+      const never: never = decision.action;
+      throw new Error(`cold-start: unhandled action ${String(never)}`);
+    }
+  }
+}

package/apps/studio/sync/ctl-heal.ts

@@ -0,0 +1,253 @@
+// Poke → `fs:any` → the existing HMR heal — Sync v2 Increment 2 (DDR-226 §6).
+//
+// This is the last hop of the fix, and it deliberately adds no new UI path: the
+// studio already knows how to repoint a broken `<img>` when a media file lands
+// (`canvas-hmr {mode:'asset'}`, DDR-224) and how to hot-swap a stylesheet. All
+// that was ever missing in a container was the EVENT — `fs.watch` does not fire
+// for the hub process's atomic tmp+rename writes, so the child never learned.
+//
+// So: the hub pokes, this asks the journal WHICH paths moved, and emits the
+// `fs:any` the watcher owed us. Everything downstream is unchanged.
+//
+// WHY IT ASKS INSTEAD OF BEING TOLD. The poke carries a head and nothing else,
+// on purpose (DDR-054 — a frame carrying a path would be a path the hub chose).
+// The journal read is authenticated and scope-filtered, its rows are re-shaped
+// on arrival (`journal-client.ts`), and this only ever emits a bus event for a
+// path — it materializes nothing. A hostile hub's best case here is making the
+// child re-read files it already has.
+//
+// A LOST POKE COSTS LATENCY, NEVER CORRECTNESS. The cursor only ever moves
+// forward on a page we actually parsed, and the 20 s reconciler poll is still
+// underneath. If the channel is down for an hour, the heal is late by an hour;
+// nothing diverges.
+
+import { fetchJournal } from './journal-client.ts';
+
+/** Coalesce a burst of pokes into one journal read. */
+const READ_DEBOUNCE_MS = 150;
+
+export interface CtlHealerOptions {
+  hubUrl: string;
+  token: string;
+  /** Emit the `fs:any` the container's watcher failed to (one per path). */
+  emit: (rel: string) => void;
+  fetchImpl?: typeof fetch;
+  log?: Pick<Console, 'log' | 'warn'>;
+  debounceMs?: number;
+  setTimeoutImpl?: typeof setTimeout;
+  clearTimeoutImpl?: typeof clearTimeout;
+}
+
+export interface CtlHealer {
+  /** A poke arrived. `head` is the hub's hint; the journal is the answer. */
+  onPoke(head: number): void;
+  /**
+   * Set the baseline from the hub's CURRENT head, replaying nothing.
+   *
+   * Without this the cursor is adopted from the FIRST POKE — and the hub pokes
+   * only when the journal appends, so that first poke IS a change this child
+   * has not seen. Adopting its head as the baseline therefore swallowed exactly
+   * one change per boot: the first asset a peer delivered after a cell started
+   * never healed an open canvas, and looked like the channel was dead. Called
+   * once at attach; a failure is harmless (the first poke still anchors, as
+   * before).
+   */
+  anchor(): Promise<void>;
+  /** Read now (tests; boot). Resolves once the pass is done. */
+  drain(): Promise<void>;
+  stop(): void;
+  /** Paths announced so far — the receiver half of the honesty counters. */
+  healed(): number;
+  /** Pokes whose head was at or below the cursor: pure noise, and expected. */
+  ignored(): number;
+}
+
+/**
+ * Turn pokes into heal events.
+ *
+ * The cursor starts at the FIRST head we are told about rather than at 0. A
+ * child that has just booted has already read the checkout from disk — every
+ * row before now describes a file it can already see, so replaying them would
+ * be a reload storm on every cell wake for zero benefit. What matters is
+ * everything AFTER the child started looking.
+ */
+export function createCtlHealer(opts: CtlHealerOptions): CtlHealer {
+  const log = opts.log ?? console;
+  const debounceMs = opts.debounceMs ?? READ_DEBOUNCE_MS;
+  const setTimeoutImpl = opts.setTimeoutImpl ?? setTimeout;
+  const clearTimeoutImpl = opts.clearTimeoutImpl ?? clearTimeout;
+
+  let cursor: number | null = null;
+  let epoch: string | null = null;
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  let inFlight: Promise<void> | null = null;
+  let again = false;
+  let stopped = false;
+  let healed = 0;
+  let ignored = 0;
+  /**
+   * Is there anything to read?
+   *
+   * Without this, `drain()` would fire a request every time it is called even
+   * when nothing has moved — which on a quiet project is a poll we did not ask
+   * for, against a route that is rate-limited. Only `schedule()` sets it, and
+   * only a completed read clears it.
+   */
+  let dirty = false;
+
+  async function readOnce(): Promise<void> {
+    if (stopped || cursor === null || !dirty) return;
+    dirty = false;
+    const page = await fetchJournal({
+      hubUrl: opts.hubUrl,
+      token: opts.token,
+      since: cursor,
+      epoch,
+      ...(opts.fetchImpl ? { fetchImpl: opts.fetchImpl } : {}),
+    });
+    // Unreachable / refused / unparseable — ask again on the next poke or the
+    // next poll. Never advance the cursor on a page we did not read, and stay
+    // dirty so the retry actually retries rather than short-circuiting.
+    if (page === null) {
+      dirty = true;
+      return;
+    }
+
+    if (page.reanchor) {
+      // The log no longer contains our cursor (an epoch rotation, or a
+      // compaction past it). For the HEAL path specifically there is nothing to
+      // replay — the child re-reads the tree from disk on demand anyway — so
+      // the honest move is to jump to the new head and say so, rather than
+      // pretend a page arrived.
+      log.warn?.(
+        `[sync/ctl] the hub asked us to re-anchor (${page.reason ?? 'cursor not in this log'}); heal cursor moves to ${page.head}.`
+      );
+      cursor = page.head;
+      epoch = page.epoch;
+      return;
+    }
+
+    epoch = page.epoch;
+    // WHAT THIS PASS ACTUALLY ANNOUNCED. The counters exist but nothing reads
+    // them, so "the poke arrived but the canvas never repainted" was a question
+    // with no evidence on either side of it. One line per non-empty pass, named
+    // paths, capped — the receiving half of the "N poke(s) folded" line the
+    // sender already prints.
+    const announced: string[] = [];
+    for (const entry of page.entries) {
+      // A tombstone is not a heal — Increment 6 owns deletion, and emitting
+      // `fs:any` for a vanished path would make the canvas layer look for a
+      // file that is deliberately gone.
+      if (entry.deleted) continue;
+      try {
+        opts.emit(entry.path);
+        healed += 1;
+        announced.push(entry.path);
+      } catch (err) {
+        log.warn?.(`[sync/ctl] heal emit failed for ${entry.path}: ${(err as Error).message}`);
+      }
+    }
+    if (announced.length > 0) {
+      const shown = announced.slice(0, 5).join(', ');
+      log.log?.(
+        `[sync/ctl] healed ${announced.length} path(s) from the journal: ${shown}${
+          announced.length > 5 ? `, +${announced.length - 5} more` : ''
+        }`
+      );
+    }
+    // Advance only over what we actually consumed. `truncated` means the next
+    // pass has more, and the poke that follows (or the next drain) takes it.
+    const last = page.entries.at(-1);
+    cursor = last ? last.seq : page.head;
+    if (page.truncated) schedule();
+  }
+
+  function schedule(): void {
+    if (stopped) return;
+    dirty = true;
+    if (timer !== null) return;
+    timer = setTimeoutImpl(() => {
+      timer = null;
+      void drain();
+    }, debounceMs);
+    timer.unref?.();
+  }
+
+  async function drain(): Promise<void> {
+    if (inFlight) {
+      again = true;
+      return inFlight;
+    }
+    inFlight = (async () => {
+      try {
+        await readOnce();
+      } finally {
+        inFlight = null;
+        if (again) {
+          again = false;
+          void drain();
+        }
+      }
+    })();
+    return inFlight;
+  }
+
+  return {
+    async anchor(): Promise<void> {
+      if (stopped || cursor !== null) return;
+      const page = await fetchJournal({
+        hubUrl: opts.hubUrl,
+        token: opts.token,
+        since: 0,
+        epoch: null,
+        ...(opts.fetchImpl ? { fetchImpl: opts.fetchImpl } : {}),
+      });
+      // Unreachable → stay unanchored; `onPoke` still has the old fallback.
+      if (page === null || cursor !== null) return;
+      cursor = page.head;
+      epoch = page.epoch;
+    },
+    onPoke(head: number): void {
+      if (stopped) return;
+      // A HEAD BELOW THE CURSOR IS A QUESTION FOR THE JOURNAL, NOT NOISE.
+      //
+      // `reanchor` recovers from an epoch rotation, a compaction, or a
+      // restore-from-backup — and every one of those moves the head BACKWARD,
+      // which the "at or below the cursor is noise" rule below then swallowed.
+      // The recovery path was therefore unreachable from precisely the states it
+      // was written for, and a cursor parked above the log (an over-large head,
+      // honest or not) left the healer permanently deaf.
+      //
+      // We do NOT move the cursor here — a coalesced or reordered frame can
+      // carry a stale head, and trusting it would rewind a healthy cursor on the
+      // hub's say-so. We only ASK: `GET /api/journal` answers `reanchor` when
+      // `since > head` (its own rule), and the branch in `readOnce` then takes
+      // the new head and epoch from a page we actually read.
+      if (cursor !== null && Number.isFinite(head) && head < cursor) {
+        schedule();
+        return;
+      }
+      if (cursor === null) {
+        // First contact: adopt the hub's head as the baseline. Everything
+        // before it is already on disk and already rendered.
+        cursor = head;
+        return;
+      }
+      if (head <= cursor) {
+        ignored += 1;
+        return;
+      }
+      schedule();
+    },
+    drain,
+    stop(): void {
+      stopped = true;
+      if (timer !== null) {
+        clearTimeoutImpl(timer);
+        timer = null;
+      }
+    },
+    healed: () => healed,
+    ignored: () => ignored,
+  };
+}

package/apps/studio/sync/ctl-provider.ts

@@ -0,0 +1,217 @@
+// The file-plane control channel, receiver side — Sync v2 Increment 2
+// (DDR-226 §4).
+//
+// ── The bug, and why the fix has to live OUTSIDE the pairing gate ───────────
+//
+// A hub-process write (a desktop asset PUT, a bucket→checkout refill) lands in
+// the checkout via tmp+rename. In a container, recursive `fs.watch` does not
+// fire for that — verified live in this repo, three separate times, and the
+// reason `announceWrite` exists for projection writes. So the studio child
+// never learns, no `fs:any` is synthesized, no `canvas-hmr {mode:'asset'}` heal
+// goes out, and an open cloud tab keeps its broken-image glyph until somebody
+// reloads by hand. Bytes delivered; nothing visible.
+//
+// The obvious place to receive the hub's poke is the child's EXISTING loopback
+// Hocuspocus provider. That provider only exists under cell pairing, and
+// pairing is a one-tenant pilot allowlist (`CELL_LIVE_PAIRING`) — a breaker
+// caught the claim "the child hears it on its existing provider" as false
+// fleet-wide. So the control attach is its OWN thing, gated only on what it
+// actually needs:
+//
+//   workspace mode + a loopback hub URL + a token.
+//
+// All three are already injected into every cell's studio child (the hub mints
+// the loopback token whenever it supervises a child at all). Pairing's five
+// preconditions govern SHARED-DOC CONTENT — two writers over one working tree,
+// one committer, one Y.Doc per canvas. None of them is about a read-only
+// stateless channel that carries `{t:'files', head}` and cannot write anything.
+// Applying them here would buy no safety and would leave the bug alive on every
+// cell but one.
+//
+// ── What this channel is allowed to do ─────────────────────────────────────
+//
+// Receive a number. That is the whole vocabulary. `head` is a HINT — the
+// receiver re-reads `GET /api/journal` (authenticated, scope-filtered,
+// fail-closed) or simply re-runs its existing missing-only pull, and believes
+// THAT. A lost poke costs latency and never correctness, because the 20 s
+// reconciler poll is still underneath it. That is why this file has no
+// retry-until-delivered machinery and no ordering guarantees: it is a doorbell,
+// not a delivery.
+
+import { parsePoke } from './poke.ts';
+
+/** The reserved control document. Must match the hub's `files-ctl.mjs`. */
+export const FILES_CTL_DOC = 'maude.files';
+
+export interface CellCtlTarget {
+  url: string;
+  token: string;
+}
+
+function isLoopbackHost(host: string): boolean {
+  const h = host.toLowerCase().replace(/^\[|\]$/g, '');
+  return h === 'localhost' || h === '127.0.0.1' || h === '::1' || h.startsWith('127.');
+}
+
+/**
+ * Resolve the cell child's control target from the environment.
+ *
+ * Deliberately NOT `resolveCellPairing`: this needs three facts, not eight, and
+ * conflating them is what would keep the watcher-gap bug alive on every
+ * unpaired cell. The loopback assertion is kept verbatim from the pairing
+ * resolver, because "a cell talks to ITSELF or to nothing" (DDR-209) is about
+ * egress and applies to every socket the child opens, control or not.
+ */
+export function resolveCellCtl(
+  env: Record<string, string | undefined> = process.env
+): CellCtlTarget | null {
+  if (env.MAUDE_WORKSPACE_MODE !== '1') return null;
+  // The one opt-out, and it is a CONFIG-shaped kill switch rather than a
+  // feature flag: `linkedHub.fileEvents:false` is the documented rollback, and
+  // this env var is its cell-side twin for the operator runbook.
+  if (env.MAUDE_FILE_EVENTS === '0') return null;
+  const url = (env.MAUDE_LOOPBACK_SYNC_URL ?? '').trim();
+  const token = (env.MAUDE_LOOPBACK_SYNC_TOKEN ?? '').trim();
+  if (!url || !token) return null;
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return null;
+  }
+  if (!isLoopbackHost(parsed.hostname)) return null;
+  return { url, token };
+}
+
+/** The minimal provider surface this needs — injectable, so tests need no WS. */
+export interface CtlProviderLike {
+  on(event: 'stateless', cb: (data: { payload: string }) => void): void;
+  on(event: 'status', cb: (data: { status?: string }) => void): void;
+  destroy(): void;
+}
+
+export interface CtlProviderOptions {
+  url: string;
+  token: string;
+  /** Fired with the hub's head on every well-formed poke. */
+  onPoke: (head: number) => void;
+  documentName?: string;
+  log?: Pick<Console, 'log' | 'warn' | 'error'>;
+  /** Injected in tests; production builds one from `@hocuspocus/provider`. */
+  connect?: (args: {
+    wsUrl: string;
+    token: string;
+    documentName: string;
+  }) => CtlProviderLike | Promise<CtlProviderLike>;
+}
+
+export interface CtlProvider {
+  stop(): void;
+  connected(): boolean;
+  /** Well-formed pokes received — the honesty counter's receiver half. */
+  received(): number;
+  /** Frames that arrived and were refused. Non-zero means someone is lying. */
+  malformed(): number;
+}
+
+/** `http(s)://host` → `ws(s)://host` — the same mapping the sync runtime uses. */
+export function toWsUrl(url: string): string {
+  return url
+    .replace(/^http:/i, 'ws:')
+    .replace(/^https:/i, 'wss:')
+    .replace(/\/+$/, '');
+}
+
+/**
+ * Attach the control channel.
+ *
+ * Never throws: a control channel that cannot open is a latency regression to
+ * exactly today's behaviour, and taking a studio server down over a doorbell
+ * would be a far worse trade.
+ */
+export function createCtlProvider(opts: CtlProviderOptions): CtlProvider {
+  const log = opts.log ?? console;
+  const documentName = opts.documentName ?? FILES_CTL_DOC;
+  let provider: CtlProviderLike | null = null;
+  let status: string = 'connecting';
+  let received = 0;
+  let malformed = 0;
+
+  const connect =
+    opts.connect ??
+    (async ({ wsUrl, token, documentName: name }) => {
+      // Loaded lazily and defensively: the provider package is a runtime dep of
+      // the studio, and a failure to load it must degrade to "no control
+      // channel", never to "the studio did not start". Dynamic `import` rather
+      // than `require` — this is an ES module, exactly like the sync runtime's
+      // own provider factory.
+      // biome-ignore lint/suspicious/noExplicitAny: provider runtime is typed at the call site.
+      const mod: any = await import('@hocuspocus/provider');
+      // Its OWN socket, not the sync runtime's multiplexed one: in a cell the
+      // sync runtime frequently does not exist at all (unpaired), which is the
+      // whole point of this file.
+      return new mod.HocuspocusProvider({ url: wsUrl, name, token }) as CtlProviderLike;
+    });
+
+  const wire = (p: CtlProviderLike): void => {
+    p.on('status', (data: { status?: string }) => {
+      if (typeof data?.status === 'string') status = data.status;
+    });
+    p.on('stateless', (data: { payload: string }) => {
+      const poke = parsePoke(data?.payload);
+      if (poke === null) {
+        malformed += 1;
+        // One line, not a flood: a hub sending garbage on this channel is
+        // worth seeing exactly once, and the counter carries the rest.
+        if (malformed === 1) {
+          log.warn?.(
+            '[sync/ctl] refused a malformed control frame — the channel carries {t:"files", head} and nothing else.'
+          );
+        }
+        return;
+      }
+      received += 1;
+      try {
+        opts.onPoke(poke.head);
+      } catch (err) {
+        log.error?.(`[sync/ctl] poke handler threw: ${(err as Error).message}`);
+      }
+    });
+  };
+
+  // Attach without making every caller await: a doorbell that is one tick late
+  // is a doorbell. `stopped` covers the race where the caller tears the runtime
+  // down while the module is still resolving.
+  let stopped = false;
+  void (async () => {
+    try {
+      const p = await connect({ wsUrl: toWsUrl(opts.url), token: opts.token, documentName });
+      if (stopped) {
+        p.destroy();
+        return;
+      }
+      provider = p;
+      wire(p);
+    } catch (err) {
+      log.warn?.(
+        `[sync/ctl] control channel unavailable (${(err as Error).message}) — falling back to the reconciler poll.`
+      );
+      provider = null;
+    }
+  })();
+
+  return {
+    stop() {
+      stopped = true;
+      try {
+        provider?.destroy();
+      } catch {
+        /* best-effort */
+      }
+      provider = null;
+    },
+    connected: () => status === 'connected',
+    received: () => received,
+    malformed: () => malformed,
+  };
+}