cursedbelt-server 1.1.0 → 2.0.0

package/dist/server/sync/signal.js

@@ -0,0 +1,348 @@
+/**
+ * **The peer says it has news. Nobody asks.**
+ *
+ * This is the half of the replication story that deleting the dialer (`./timer`,
+ * `./http`'s old `GET /requested`) would otherwise have left open, and it is the
+ * reason that deletion costs nothing.
+ *
+ * ## The three ways, and why this is the one
+ *
+ * Push-from-the-Mac answers Mac → peer completely: the side that has news calls
+ * `markDirty()` and pushes. It does not answer **peer → Mac**, and something must:
+ *
+ * | | |
+ * |---|---|
+ * | the Mac polls an outbox | ❌ polling. Ruled out 2026-09-15 |
+ * | the peer dials the Mac | ❌ needs the Mac reachable — a tunnel, an open port, a laptop that cannot sleep. That is the thing we are trying to delete |
+ * | 🟢 **the Mac holds a stream open and the peer pushes down it** | ✅ the Mac is still purely a client: it dials **out**, listens on nothing, and no timer fires |
+ *
+ * So: one long-lived outbound connection, opened by the dialing half, carrying a
+ * `news` frame whenever the receiver's op log grows. The Mac's reaction is
+ * `syncNow()` — the push it would have made anyway, at the moment there is a reason
+ * for it instead of 4,320 times a day on the chance.
+ *
+ * ## 🔴 Two honest caveats, neither of which is a poll
+ *
+ *   · **A sleeping Mac drops the connection.** On wake it reconnects and catches up
+ *     from `since` — the same catch-up a push model needs anyway, so it costs
+ *     nothing extra. `since` is the receiver's head as the client last saw it.
+ *   · **The reconnect backoff is a timer.** It runs *only while disconnected*, never
+ *     against a healthy peer, and it is written below as an `await sleep()` in a
+ *     loop rather than a `setTimeout` that calls `fetch` — the shape matters,
+ *     because the second one is indistinguishable from the poll this file exists to
+ *     replace. A connected client issues **exactly one** outbound request for as
+ *     long as it stays connected, and `signal.spec.ts` measures that over 24
+ *     simulated hours.
+ *
+ * ## Why this is not `cursedbelt-cc`'s `serverPush.ts`
+ *
+ * `libs/cursedbelt-cc/src/server/stream/serverPush.ts` is the real tenant-scoped
+ * push tier — heartbeats, backpressure, SSE — and on shape it is exactly this.
+ * It is not imported here for a reason that survives the preference:
+ * `cursedbelt-server/sync` is a **leaf** whose only runtime dependency is `hono`
+ * (see `./index.ts`), and `cursedbelt-cc` is a separate published package with zero
+ * consumers today, parked whole. Importing it would make every app that wants an
+ * op log install the cc platform to get one — the precise trade `./index.ts` was
+ * split to refuse, and the one `leafSubpathsImportNothing.spec.ts` now gates.
+ *
+ * The hub below is therefore the same model at a tenth the surface: this channel
+ * carries one frame kind, to one peer, with no tenant dimension. If `cursedbelt-cc`
+ * ever gains consumers and the two packages can depend on each other, {@link
+ * SyncSignalHub} is a strict subset of `ServerPushHub` and swaps in without
+ * touching a producer.
+ *
+ * ## The Workers path, named and not required yet
+ *
+ * On Cloudflare the durable form of "the Mac holds a connection all day" is a
+ * **Durable Object with WebSocket Hibernation**: the socket stays open while the
+ * object is evicted from memory, so an idle connection is not billed for duration.
+ * That is what keeps this free at rest, and it is the shape task `195` (the Mac is
+ * a client, never an origin) lands on. Nothing here needs it today — SSE over the
+ * existing receiver works on Bun and on Workers alike — but the frame format below
+ * is deliberately transport-free so the move is a transport swap, not a protocol
+ * change.
+ */
+/** SSE frame headers. `x-accel-buffering` keeps nginx from holding the stream in a
+ *  proxy buffer, which turns a live channel into a silent one — the same trap that
+ *  makes a cached `200` sit over a dead origin elsewhere in this fleet. */
+export const SIGNAL_SSE_HEADERS = Object.freeze({
+    "content-type": "text/event-stream",
+    "cache-control": "no-store",
+    connection: "keep-alive",
+    "x-accel-buffering": "no",
+});
+/**
+ * Comment-frame interval. Without it an idle stream dies silently behind a proxy
+ * with an idle timeout and the client never learns it should reconnect.
+ *
+ * 🔴 This is a heartbeat on an ALREADY-OPEN socket, not a request. It is row (c) of
+ * the 2026-09-15 ruling — a local housekeeping timer that issues no outbound
+ * request — and it is why that row had to be carved out explicitly: a rule that
+ * said "no `setInterval`" would have deleted the one mechanism that keeps a
+ * no-polling design alive.
+ */
+const HEARTBEAT_MS = 15_000;
+export function createSyncSignalHub() {
+    const listeners = new Set();
+    let closed = false;
+    return {
+        announce(news) {
+            if (closed)
+                return;
+            // Snapshot: a listener that unsubscribes itself mid-fanout (the normal
+            // teardown path) must not mutate the set being iterated.
+            for (const listener of [...listeners]) {
+                try {
+                    listener(news);
+                }
+                catch {
+                    // A broken transport is that subscriber's problem, never the
+                    // producer's: drop it and keep fanning out. An `announce` may be
+                    // called from inside an op-log write, so it can never throw upward.
+                    listeners.delete(listener);
+                }
+            }
+        },
+        subscribe(listener) {
+            if (closed)
+                return () => undefined;
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        get subscriberCount() {
+            return listeners.size;
+        },
+        close() {
+            if (closed)
+                return;
+            closed = true;
+            listeners.clear();
+        },
+    };
+}
+/**
+ * Bridge a hub subscription onto a `ReadableStream` of SSE bytes.
+ *
+ * The stream ends when the client disconnects (`signal`) or the hub closes; both
+ * paths run the same teardown, so a dropped connection cannot leave a subscription
+ * — or an interval — behind.
+ */
+export function signalStream(hub, options = {}) {
+    const heartbeatMs = options.heartbeatMs ?? HEARTBEAT_MS;
+    const setIntervalFn = options.setIntervalFn ?? ((fn, ms) => setInterval(fn, ms));
+    const clearIntervalFn = options.clearIntervalFn ??
+        ((handle) => clearInterval(handle));
+    const encoder = new TextEncoder();
+    let unsubscribe = () => undefined;
+    let heartbeat = null;
+    let done = false;
+    return new ReadableStream({
+        start(controller) {
+            const teardown = () => {
+                if (done)
+                    return;
+                done = true;
+                unsubscribe();
+                if (heartbeat !== null)
+                    clearIntervalFn(heartbeat);
+                heartbeat = null;
+                try {
+                    controller.close();
+                }
+                catch {
+                    // Already closed by the runtime when the socket died — expected.
+                }
+            };
+            const write = (chunk) => {
+                if (done)
+                    return;
+                try {
+                    controller.enqueue(encoder.encode(chunk));
+                }
+                catch {
+                    teardown();
+                }
+            };
+            if (options.initial)
+                write(encodeNewsFrame(options.initial));
+            unsubscribe = hub.subscribe((news) => {
+                write(encodeNewsFrame(news));
+            });
+            heartbeat = setIntervalFn(() => {
+                // A comment frame. It wakes no client-side handler and issues no
+                // request — it keeps proxies from calling the connection idle.
+                write(": keep-alive\n\n");
+            }, heartbeatMs);
+            if (options.signal) {
+                if (options.signal.aborted)
+                    teardown();
+                else
+                    options.signal.addEventListener("abort", teardown, { once: true });
+            }
+        },
+        cancel() {
+            done = true;
+            unsubscribe();
+            if (heartbeat !== null)
+                clearIntervalFn(heartbeat);
+            heartbeat = null;
+        },
+    });
+}
+/** Serialize one announcement as an SSE frame. */
+export const encodeNewsFrame = (news) => `event: news\ndata: ${JSON.stringify(news)}\n\n`;
+/** A ready-to-return SSE `Response` — what the receiver's `GET /signal` answers. */
+export const signalResponse = (hub, options = {}) => new Response(signalStream(hub, options), { headers: { ...SIGNAL_SSE_HEADERS } });
+/**
+ * Hold one stream open against the peer, calling {@link SignalClientOptions.onNews}
+ * on every `news` frame, and reconnect with jittered backoff **while disconnected**.
+ *
+ * 🔴 Read the loop shape as load-bearing. The reconnect is `await sleep(ms)` inside
+ * an async loop, NOT a `setTimeout` whose callback calls `fetch`. The second shape
+ * is byte-for-byte what a poll looks like, and a reviewer — or a checker — cannot
+ * tell the two apart once it is written that way. Here, a connected client is
+ * parked on `reader.read()` and issues nothing; `requestCount` stops moving the
+ * moment a connection succeeds, and that is what `signal.spec.ts` asserts over 24
+ * simulated hours.
+ *
+ * The jitter is not decoration either: a fixed backoff across N clients recovering
+ * from the same outage is a synchronized stampede at the instant the peer comes
+ * back up — the worst possible moment to send it a thundering herd.
+ */
+export function connectSyncSignal(options) {
+    const doFetch = options.fetchImpl ?? fetch;
+    const base = options.basePath.replace(/\/$/, "");
+    const backoffBase = options.backoffBaseMs ?? 1_000;
+    const backoffMax = options.backoffMaxMs ?? 5 * 60_000;
+    const sleep = options.sleepFn ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const jitter = options.jitterFn ?? Math.random;
+    const log = options.log ?? (() => undefined);
+    let stopped = false;
+    let connected = false;
+    let requests = 0;
+    let failures = 0;
+    let abort = null;
+    /** Open one stream and stay on it until it ends. Throws on any failure. */
+    const runOnce = async () => {
+        const controller = new AbortController();
+        abort = controller;
+        requests += 1;
+        const response = await doFetch(`${base}/signal?peer=${encodeURIComponent(options.selfId)}`, {
+            // 🔴 A followed redirect is how a moved hostname became eight days of
+            // silence on the `/pull` side — see `./http.ts`'s header. Same rule here.
+            redirect: "manual",
+            headers: {
+                authorization: `Bearer ${options.token}`,
+                "x-sync-peer": options.selfId,
+                accept: "text/event-stream",
+            },
+            signal: controller.signal,
+        });
+        if (response.status >= 300 && response.status < 400) {
+            throw new Error(`sync/signal: ${response.status} — the peer address redirects to ` +
+                `${response.headers.get("location") ?? "an unnamed destination"}.`);
+        }
+        if (!response.ok)
+            throw new Error(`sync/signal: ${response.status}`);
+        if (!response.body)
+            throw new Error("sync/signal: the peer sent no stream body");
+        connected = true;
+        failures = 0;
+        const reader = response.body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = "";
+        try {
+            while (!stopped) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                buffer += decoder.decode(value, { stream: true });
+                // SSE frames are separated by a blank line. A partial tail stays in
+                // the buffer until the rest of it arrives.
+                let split = buffer.indexOf("\n\n");
+                while (split !== -1) {
+                    const frame = buffer.slice(0, split);
+                    buffer = buffer.slice(split + 2);
+                    const news = parseNewsFrame(frame);
+                    if (news)
+                        options.onNews(news);
+                    split = buffer.indexOf("\n\n");
+                }
+            }
+        }
+        finally {
+            connected = false;
+            try {
+                await reader.cancel();
+            }
+            catch {
+                // The socket is already gone — that is the normal end of a stream.
+            }
+        }
+    };
+    /**
+     * The supervisor. Every `await` here is either the open stream itself or a sleep
+     * between failures; there is no path that waits on a healthy peer in order to
+     * ask it something.
+     */
+    const supervise = async () => {
+        while (!stopped) {
+            try {
+                await runOnce();
+            }
+            catch (error) {
+                if (stopped)
+                    return;
+                failures += 1;
+                if (failures === 1) {
+                    log(`[sync] signal stream lost — reconnecting. This is normal (peer asleep / offline): ` +
+                        `${error instanceof Error ? error.message : String(error)}`);
+                }
+            }
+            if (stopped)
+                return;
+            const step = Math.min(backoffMax, backoffBase * 2 ** Math.max(0, failures - 1));
+            await sleep(Math.round(step * (0.5 + jitter() * 0.5)));
+        }
+    };
+    void supervise();
+    return {
+        stop() {
+            stopped = true;
+            abort?.abort();
+            abort = null;
+        },
+        get connected() {
+            return connected;
+        },
+        get requestCount() {
+            return requests;
+        },
+    };
+}
+/** `event: news\ndata: {...}` → {@link SyncNews}, or null for a heartbeat/unknown. */
+export function parseNewsFrame(frame) {
+    let isNews = false;
+    let data = null;
+    for (const line of frame.split("\n")) {
+        if (line.startsWith(":"))
+            continue; // comment frame — the heartbeat
+        if (line.startsWith("event:"))
+            isNews = line.slice(6).trim() === "news";
+        else if (line.startsWith("data:"))
+            data = line.slice(5).trim();
+    }
+    if (!isNews || data === null)
+        return null;
+    try {
+        const parsed = JSON.parse(data);
+        if (typeof parsed.head !== "number" || typeof parsed.instanceId !== "string")
+            return null;
+        return { head: parsed.head, instanceId: parsed.instanceId };
+    }
+    catch {
+        return null;
+    }
+}

package/dist/server/sync/timer.d.ts

@@ -1,20 +1,63 @@
 /**
- * The in-process dialer loop — vault's `syncTimer` generalized. Runs on the dialing
- * half only; a failure NEVER takes the host daemon down (an unsynced instance still
- * serves and still accepts writes — that is the point of two independently-writable
- * instances). The timer is `unref`'d so it never holds the process open.
- *
- * The peer is re-resolved on EVERY tick, so linking (or revoking) a peer takes
- * effect without a restart. The "Sync now" fast lane polls the receiver's request
- * stamp every ~20s while healthy, so a button press on the far side means seconds,
- * not "sometime in the next interval".
+ * The in-process sync loop. Runs on the dialing half only; a failure NEVER takes
+ * the host daemon down (an unsynced instance still serves and still accepts writes
+ * — that is the point of two independently-writable instances). The timer is
+ * `unref`'d so it never holds the process open.
+ *
+ * ── 🔴 This loop does not poll, and it may never be made to again ────────────────
+ *
+ * Until 2026-09-15 this file was a dialer twice over: a `GET /requested` probe at a
+ * peer every 20 s while healthy (`REQUEST_POLL_MS`), and a full reconciliation every
+ * 5 minutes (`DEFAULT_LOOP.intervalMs`) whether or not either side had news. The
+ * owner ruled both out — *"There should be no polling in cb unless you can make some
+ * good case for it that beats the api option"* — and the case against was asked for
+ * and not found. Measured in `vault`: the 20 s probe alone was **68 % of that app's
+ * entire traffic, one request every 22 seconds, for an app with one user.**
+ *
+ * Both are gone. Every wake-up this loop books now carries a {@link WakeReason}, and
+ * that union is deliberately closed with no periodic member — there is no value you
+ * can pass to {@link schedule} that means "again in a while". That makes the poll
+ * unrepresentable rather than merely discouraged, which matters because
+ * `REQUEST_POLL_MS` did not survive as a habit; it survived as **exported public
+ * API**, and the next consumer to import it would have made its removal a breaking
+ * change instead of an edit.
+ *
+ * What replaced each half:
+ *
+ *   · **Mac → peer** is a PUSH. `markDirty()` after a local write books one
+ *     debounced run: the side that has news says so, which is what "sync now"
+ *     should always have been.
+ *   · **peer → Mac** is `./signal` — the dialing half holds one long-lived stream
+ *     open and the receiver writes a frame when its log grows. The Mac is still
+ *     purely a client: it dials OUT, listens on nothing, and no timer fires.
+ *
+ * 🔴 **`markDirty()` is now REQUIRED wiring, not an optimization.** With the steady
+ * interval gone it is the only thing that pushes a local write. A consumer that
+ * takes the handle and drops `markDirty` (which `apps/vault` did while the interval
+ * still covered for it) will sit clean and silent forever.
+ *
+ * The peer is re-resolved on every run, so revoking a link takes effect without a
+ * restart. Linking a NEW peer is a user action and is noticed at the next
+ * `syncNow()` / `markDirty()` rather than by a timer that was watching for it —
+ * call `syncNow()` after a link and it is immediate.
  */
 import { type SyncLoopConfig } from "./planner";
 import type { SyncStatusReporter } from "./status";
 import type { SyncSummary } from "./types";
-export declare const REQUEST_POLL_MS = 20000;
+/**
+ * 🔴 Every reason this loop is allowed to wake up. There is deliberately no
+ * `"interval"` / `"poll"` member, and adding one is the change this whole file
+ * exists to refuse.
+ *
+ *   · `boot`   — one catch-up run at start.
+ *   · `dirty`  — local ops are waiting to be pushed (debounced).
+ *   · `forced` — `syncNow()`, or a frame off `./signal` saying the peer has news.
+ *   · `retry`  — the last attempt failed. Runs only while disconnected, never
+ *                against a healthy peer; that is a reconnect backoff, not a poll.
+ */
+export type WakeReason = "boot" | "dirty" | "forced" | "retry";
 export interface SyncTimerDeps {
-    /** Re-read every tick: null = not linked (quiet no-op, re-checked next tick). */
+    /** Re-read on every run: null = not linked (quiet no-op). */
     resolvePeer: () => {
         basePath: string;
         token: string;
@@ -26,14 +69,8 @@ export interface SyncTimerDeps {
     }) => Promise<SyncSummary>;
     /** The local op-log head — a head beyond the last synced one marks dirty. */
     head: () => number;
-    /** Ask the peer whether its "Sync now" was pressed; null on any failure. */
-    checkRequest?: (peer: {
-        basePath: string;
-        token: string;
-    }) => Promise<number | null>;
     status?: SyncStatusReporter;
     loop?: SyncLoopConfig;
-    requestPollMs?: number;
     now?: () => number;
     setTimer?: (fn: () => void, ms: number) => unknown;
     clearTimer?: (handle: unknown) => void;
@@ -44,9 +81,16 @@ export interface SyncTimerDeps {
 }
 export interface SyncTimerHandle {
     stop(): void;
-    /** Run the next tick immediately (the "Sync now" button on the dialing half). */
+    /**
+     * Run now. The "Sync now" button on the dialing half, and the handler for a
+     * `./signal` frame — both are "something has news", which is a push.
+     */
     syncNow(): void;
-    /** Mark local writes pending (call after any local op) — debounces a burst. */
+    /**
+     * Mark local writes pending — call after any local op. 🔴 Required wiring: with
+     * no steady interval this is what pushes a local write. A burst coalesces into
+     * one run via the planner's debounce.
+     */
     markDirty(): void;
 }
 export declare function startSyncTimer(deps: SyncTimerDeps): SyncTimerHandle;

package/dist/server/sync/timer.js

@@ -1,16 +1,52 @@
 /**
- * The in-process dialer loop — vault's `syncTimer` generalized. Runs on the dialing
- * half only; a failure NEVER takes the host daemon down (an unsynced instance still
- * serves and still accepts writes — that is the point of two independently-writable
- * instances). The timer is `unref`'d so it never holds the process open.
+ * The in-process sync loop. Runs on the dialing half only; a failure NEVER takes
+ * the host daemon down (an unsynced instance still serves and still accepts writes
+ * — that is the point of two independently-writable instances). The timer is
+ * `unref`'d so it never holds the process open.
  *
- * The peer is re-resolved on EVERY tick, so linking (or revoking) a peer takes
- * effect without a restart. The "Sync now" fast lane polls the receiver's request
- * stamp every ~20s while healthy, so a button press on the far side means seconds,
- * not "sometime in the next interval".
+ * ── 🔴 This loop does not poll, and it may never be made to again ────────────────
+ *
+ * Until 2026-09-15 this file was a dialer twice over: a `GET /requested` probe at a
+ * peer every 20 s while healthy (`REQUEST_POLL_MS`), and a full reconciliation every
+ * 5 minutes (`DEFAULT_LOOP.intervalMs`) whether or not either side had news. The
+ * owner ruled both out — *"There should be no polling in cb unless you can make some
+ * good case for it that beats the api option"* — and the case against was asked for
+ * and not found. Measured in `vault`: the 20 s probe alone was **68 % of that app's
+ * entire traffic, one request every 22 seconds, for an app with one user.**
+ *
+ * Both are gone. Every wake-up this loop books now carries a {@link WakeReason}, and
+ * that union is deliberately closed with no periodic member — there is no value you
+ * can pass to {@link schedule} that means "again in a while". That makes the poll
+ * unrepresentable rather than merely discouraged, which matters because
+ * `REQUEST_POLL_MS` did not survive as a habit; it survived as **exported public
+ * API**, and the next consumer to import it would have made its removal a breaking
+ * change instead of an edit.
+ *
+ * What replaced each half:
+ *
+ *   · **Mac → peer** is a PUSH. `markDirty()` after a local write books one
+ *     debounced run: the side that has news says so, which is what "sync now"
+ *     should always have been.
+ *   · **peer → Mac** is `./signal` — the dialing half holds one long-lived stream
+ *     open and the receiver writes a frame when its log grows. The Mac is still
+ *     purely a client: it dials OUT, listens on nothing, and no timer fires.
+ *
+ * 🔴 **`markDirty()` is now REQUIRED wiring, not an optimization.** With the steady
+ * interval gone it is the only thing that pushes a local write. A consumer that
+ * takes the handle and drops `markDirty` (which `apps/vault` did while the interval
+ * still covered for it) will sit clean and silent forever.
+ *
+ * The peer is re-resolved on every run, so revoking a link takes effect without a
+ * restart. Linking a NEW peer is a user action and is noticed at the next
+ * `syncNow()` / `markDirty()` rather than by a timer that was watching for it —
+ * call `syncNow()` after a link and it is immediate.
  */
 import { isUnreachable, DEFAULT_LOOP, planNextSync, } from "./planner";
-export const REQUEST_POLL_MS = 20_000;
+/**
+ * One reconciliation shortly after start: catch up on whatever happened while this
+ * process was down. A single shot at boot, not a cadence — the same catch-up a push
+ * model needs anyway.
+ */
 const KICKOFF_MS = 5_000;
 function defaultPeerLabel(basePath) {
     try {
@@ -29,46 +65,63 @@ export function startSyncTimer(deps) {
     const warn = deps.warn ?? ((m) => console.error(m));
     const status = deps.status;
     const peerLabel = deps.peerLabel ?? defaultPeerLabel;
-    const requestPollMs = deps.requestPollMs ?? REQUEST_POLL_MS;
     status?.update({ enabled: true, role: "dialer" });
     const state = { lastAttempt: 0, consecutiveFailures: 0, dirtySince: null };
     let syncedHead = deps.head();
     let stopped = false;
     let handle = null;
     let reportedUnreachable = false;
-    let forceRun = false;
-    let handledRequestAt = 0;
-    let probing = false;
+    /**
+     * 🔴 Starts TRUE: the boot catch-up is a forced run, not a scheduled one.
+     *
+     * It used to fall out of the planner for free — `lastAttempt: 0` plus a steady
+     * `intervalMs` made the first tick always due. With no interval left, a clean
+     * healthy state plans nothing, so the one run this loop genuinely owes at
+     * startup has to be asked for explicitly. It has a reason: this process may have
+     * missed ops while it was down, and catching up is exactly what a push model
+     * does on reconnect.
+     */
+    let forceRun = true;
     let inFlight = false;
-    const schedule = (ms) => {
+    /** Why the currently-booked wake exists, or null when the loop is quiet. */
+    let bookedFor = null;
+    /**
+     * Book the next wake-up. 🔴 The `reason` is not decoration — it is the type-level
+     * guard: {@link WakeReason} has no periodic member, so there is no way to spell
+     * "wake again in `intervalMs`" through this function. It is also read back by
+     * {@link SyncTimerHandle.markDirty}, which must not push an imminent forced run
+     * out to a debounce.
+     */
+    const schedule = (reason, ms) => {
         if (stopped)
             return;
         if (handle !== null)
             clearTimer(handle);
         handle = setTimer(tick, ms);
         handle?.unref?.();
+        bookedFor = reason;
     };
-    const sleepFor = (waitMs) => {
-        const healthy = state.consecutiveFailures === 0 && requestPollMs > 0;
-        return Math.max(1, healthy ? Math.min(waitMs, requestPollMs) : waitMs);
+    /** Nothing to push, nothing to retry: cancel any pending wake and go quiet. */
+    const idle = () => {
+        if (handle !== null)
+            clearTimer(handle);
+        handle = null;
+        bookedFor = null;
     };
-    const probeRequest = (peer) => {
-        if (probing || requestPollMs === 0 || !deps.checkRequest)
+    /** Apply the planner's verdict — the ONE place a wake-up is booked or declined. */
+    const bookNext = () => {
+        if (stopped)
             return;
-        probing = true;
-        void deps
-            .checkRequest(peer)
-            .then((requestedAt) => {
-            if (stopped || requestedAt === null || requestedAt <= handledRequestAt)
-                return;
-            handledRequestAt = requestedAt;
-            log("[sync] sync requested from the peer — running now.");
-            forceRun = true;
-            schedule(1);
-        })
-            .finally(() => {
-            probing = false;
-        });
+        if (forceRun) {
+            schedule("forced", 1);
+            return;
+        }
+        const plan = planNextSync(state, now(), loop);
+        if (plan.waitMs === null || plan.reason === null) {
+            idle();
+            return;
+        }
+        schedule(plan.reason, Math.max(1, plan.waitMs));
     };
     const tick = () => {
         if (stopped)
@@ -84,15 +137,16 @@ export function startSyncTimer(deps) {
             pending: Math.max(0, head - syncedHead),
         });
         if (peer === null) {
-            schedule(loop.intervalMs);
+            // Not linked. Nothing to dial and nothing to wait for — `syncNow()` or the
+            // next local write re-checks. A re-check timer here would be a poll at a
+            // peer that does not exist yet.
+            forceRun = false;
+            idle();
             return;
         }
         const plan = planNextSync(state, now(), loop);
         if (!plan.runNow && !forceRun) {
-            const linkedAndHealthy = state.consecutiveFailures === 0 && requestPollMs > 0;
-            schedule(sleepFor(plan.waitMs));
-            if (linkedAndHealthy)
-                probeRequest(peer);
+            bookNext();
             return;
         }
         forceRun = false;
@@ -140,31 +194,36 @@ export function startSyncTimer(deps) {
         })
             .finally(() => {
             inFlight = false;
-            if (forceRun)
-                schedule(1);
-            else
-                schedule(sleepFor(Math.max(1_000, planNextSync(state, now(), loop).waitMs)));
+            // A local write that landed mid-run is news the planner must see.
+            if (deps.head() > syncedHead && state.dirtySince === null)
+                state.dirtySince = now();
+            bookNext();
         });
     };
-    schedule(KICKOFF_MS);
+    schedule("boot", KICKOFF_MS);
     return {
         stop: () => {
             stopped = true;
             if (handle !== null)
                 clearTimer(handle);
+            handle = null;
         },
         syncNow: () => {
             if (stopped)
                 return;
             forceRun = true;
-            schedule(1);
+            schedule("forced", 1);
         },
         markDirty: () => {
             if (stopped)
                 return;
             if (state.dirtySince === null)
                 state.dirtySince = now();
-            schedule(1);
+            // A forced run is already due in ~1ms and will push these ops; re-booking
+            // would replace it with a 3s debounce and make "Sync now" slower.
+            if (bookedFor === "forced")
+                return;
+            bookNext();
         },
     };
 }