@reticlehq/server 3.7.0 → 3.8.1

package/dist/memory/cloud/sync-daemon.js

@@ -10,9 +10,13 @@
  * work is happening" costs nobody anything.
  *
  * ── THE THREE RULES THAT KEEP IT INVISIBLE ────────────────────────────────────────────────────
- * QUIET WHEN IDLE. A cycle on an unchanged session is one small GET and nothing else. That is what
- * makes a one-minute timer affordable; it is also why the timer is not adaptive — a scheme that
- * "backs off when idle" is complexity paid for a cost that is already near zero.
+ * QUIET WHEN IDLE. A cycle runs because something under `.reticle` CHANGED: the whole root is
+ * watched, and a change schedules one cycle after a short debounce, so a drive that writes forty
+ * files costs one cycle. Nothing changed, nothing sent. A slow timer (ten minutes) stays as the
+ * backstop — for a filesystem that cannot be watched and the team's decisions to pull down — and a
+ * cycle that moved something still earns the fast active rate. A FAILED cycle retries after a
+ * minute, doubling per failure up to the backstop, and a success returns it to the idle rhythm.
+ * The sync's own bookkeeping writes are ignored, or every cycle would schedule the next.
  *
  * NEVER IN THE WAY. Nothing here is awaited by a tool call. A sync that can slow down or fail a
  * verification would be a sync worth switching off, and the local record is authoritative anyway.
@@ -21,23 +25,80 @@
  * laptop on a train would otherwise fill the log with the same line four hundred times and teach
  * everyone to ignore it.
  */
+import { ReticleDir } from '@reticlehq/core';
 import { reticleDirPaths } from '../project/dir/reticle-dir.js';
 import { syncRequest } from './cloud-sync.js';
 import { log } from '../../log.js';
 import { homedir } from 'node:os';
 import { emitSyncHook } from '../../hooks/hook-emit.js';
-import { MemoryReadHeader, MemoryReadPurpose, memoryReadUrl, scopedMemoryEntries, } from './memory-scope.js';
+import { MemoryReadHeader, MemoryReadPurpose, MemoryScopeField, MEMORY_PAGE_LIMIT, memoryReadUrl, readMemoryPages, scopedMemoryEntries, } from './memory-scope.js';
 import { IntentShardStore } from '../intent/intent-shard-store.js';
 import { applySettledWords, keptWordsInRequest, settledWordsIn, } from '../intent/settled-words.js';
 import { createNodeFileSystem } from '../project/fs/fs-port.js';
 import { flushPendingWrites } from '../../hooks/hook-bus.js';
-import { describeSync, runSyncCycle } from './sync-cycle.js';
-import { diskSink, diskSource, readCloudState } from './sync-disk.js';
-import { CLOUD_LINK_FILE, resolveProjectCloud } from './cloud-config.js';
+import { runSyncCycle } from './sync-cycle.js';
+import { describeSync } from './sync-describe.js';
+import { diskSink, diskSource, policyScreenshots, readCloudState } from './sync-disk.js';
+import { resolveProjectCloud } from './cloud-config.js';
 import { watch } from 'node:fs';
+import { BackgroundSyncState, backgroundSyncGate, } from './background-sync.js';
 import { unmatchedRoots, unsyncedRoots } from './unsynced-roots.js';
-/** How often the daemon cycles. See the note above on why this is a constant and not a curve. */
-const DAEMON_SYNC_INTERVAL_MS = 60_000;
+/**
+ * The backstop: how often the daemon cycles when nothing under `.reticle` has changed. Long, because
+ * a change wakes the sync on its own; this exists for what a watch cannot see (an unwatchable
+ * filesystem, decisions made on the dashboard). A failed cycle retries sooner: FAILURE_RETRY_MS.
+ */
+const DAEMON_SYNC_INTERVAL_MS = 600_000;
+/**
+ * How long a change under `.reticle` waits before cycling. Coalesces the burst a drive writes, and
+ * is never extended by a later write, so a stream of writes cannot postpone the sync forever.
+ */
+const CHANGE_DEBOUNCE_MS = 2_000;
+/**
+ * What the sync itself writes into a root, plus `sessions/` (the per-event journal, appended on
+ * every browser event and never sent) and `episodes/` (every tool call, likewise never sent). A
+ * change here must not wake the sync: the first would make every cycle schedule the next, the others
+ * would turn an open tab or a working agent into a cycle every two seconds.
+ * The atomic writes' `<file>.<pid>.tmp` siblings are matched by prefix.
+ */
+const NOT_A_CHANGE = [ReticleDir.CLOUD_STATE_FILE, ReticleDir.ISSUES_FILE];
+/**
+ * The longest the team's memory decisions go unread while a drive keeps the sync busy. They must come
+ * down before changed INTENT goes up (or a word a maintainer set aside is sent back as a new
+ * disagreement), and nothing else waits on them: paging the whole memory before every run cost a
+ * real project nine round trips per cycle, the larger part of a run's time to the dashboard.
+ */
+const SETTLED_WORDS_MAX_AGE_MS = 60_000;
+/**
+ * How often the OTHER linked repos are walked while this one keeps changing. They are not watched, and
+ * each is a full cycle of round trips: walking them on every change here made a run landing in this
+ * repo wait behind all of them. The backstop timer and a requested sync always walk them.
+ */
+const OTHER_ROOTS_EVERY_MS = 60_000;
+/**
+ * How often an idle machine asks whether the team's memory moved. Conditional (If-None-Match on the
+ * first page), so an unchanged minute is one bodiless 304, and a dashboard decision lands within it
+ * rather than on the ten-minute backstop.
+ */
+const MEMORY_POLL_MS = 50_000;
+/**
+ * How often the poll looks at the clock. A read is due once MEMORY_POLL_MS have passed since the last
+ * one (any read, a cycle's too), so a decision waits at most the two together: one minute. Measured
+ * with a plain one-minute timer: 74 s and 96 s, because a cycle's read just before it pushed the
+ * next ask a whole minute on.
+ */
+const MEMORY_POLL_TICK_MS = 10_000;
+const IF_NONE_MATCH = 'if-none-match';
+const isIntent = (path) => {
+    const [head = ''] = path.split(/[\\/]/);
+    return head === ReticleDir.INTENT_SUBDIR || head.startsWith(ReticleDir.INTENT_FILE);
+};
+const isOwnWrite = (path) => {
+    const [head = ''] = path.split(/[\\/]/);
+    return (head === ReticleDir.SESSIONS_SUBDIR ||
+        head === ReticleDir.EPISODES_SUBDIR ||
+        NOT_A_CHANGE.some((file) => head === file || head.startsWith(`${file}.`)));
+};
 /**
  * The cadence while something is actually happening.
  *
@@ -53,6 +114,11 @@ const DAEMON_SYNC_INTERVAL_MS = 60_000;
  * loop, and verification working with the network down is a promise this product makes.
  */
 const DAEMON_SYNC_ACTIVE_INTERVAL_MS = 5_000;
+/**
+ * The first retry after a failed cycle, doubling with each failure after it up to the backstop. A
+ * failed upload is owed work, so it does not wait ten minutes for the idle timer.
+ */
+const FAILURE_RETRY_MS = 60_000;
 /** Given to the first cycle so a freshly-started daemon does not race the session that woke it. */
 const FIRST_CYCLE_DELAY_MS = 5_000;
 /**
@@ -65,14 +131,16 @@ const FIRST_CYCLE_DELAY_MS = 5_000;
  */
 const NUDGE_DELAY_MS = 1_500;
 /**
- * How long a flush waits for a cycle already in flight before running its own.
+ * The whole time a flush may take: the wait for a cycle in flight, and its own cycle.
  *
- * Shutdown budget, not a sync budget: every call inside a cycle already carries its own timeout, so
- * this only bounds the WAIT. Generous enough for an ordinary cycle to finish, short enough that a
- * stalled one cannot hold a daemon open.
+ * Shutdown budget, not a sync budget. `reticle stop` sends SIGKILL 5 s after SIGTERM, and the daemon
+ * sends its stop event (up to 2 s) before it flushes. A flush past this budget let the kill come
+ * first. Runs that are not sent stay on disk, and the next daemon sends them.
  */
-const FLUSH_WAIT_MS = 3_000;
+const FLUSH_BUDGET_MS = 1_500;
 const FLUSH_POLL_MS = 25;
+/** A failed status, push or pull that says the platform refused the credential. */
+const AUTH_REFUSED = /^(?:status|sync|pull) 40[13]\b/;
 /** Whether a cycle landed or collected anything — what earns the fast interval and a log line. */
 const movedAnything = (report) => report.runsSent > 0 ||
     report.flowsSent > 0 ||
@@ -91,6 +159,13 @@ export function startSyncDaemon(deps) {
     const activeIntervalMs = Math.min(DAEMON_SYNC_ACTIVE_INTERVAL_MS, intervalMs);
     const now = deps.now ?? (() => Date.now());
     const request = deps.request ?? defaultRequest;
+    /** Per root, the credential the platform refused (401/403). Stopped until the sign-in changes. */
+    const refusedUnder = new Map();
+    /** Per root, the gate as of this tick. */
+    const gates = new Map();
+    /** Per root, the state last logged: one line per change, never one per tick. */
+    const loggedState = new Map();
+    let lastPushAt;
     let timer;
     let stopped = false;
     let running = false;
@@ -131,8 +206,9 @@ export function startSyncDaemon(deps) {
         [...linked.keys(), ...unmatchedRoots(homedir())], (r) => Promise.resolve(true === linked.get(r)), (r) => Promise.resolve(sendsFlows.has(r)));
         for (const entry of unsynced) {
             const held = entry.runs + entry.flows;
-            if (entry.linked || announced.get(entry.root) === held)
+            if (entry.linked || announced.get(entry.root) === held) {
                 continue;
+            }
             announced.set(entry.root, held);
             log('reticle_cloud_unsynced_root', {
                 root: entry.root,
@@ -143,15 +219,63 @@ export function startSyncDaemon(deps) {
             });
         }
     };
+    /**
+     * The cloud as this tick may use it: unchanged when the gate lets the root send, else with no
+     * config, which every caller below already reads as "send nothing". A credential the platform
+     * refused stays refused until the sign-in or the key changes.
+     */
+    const admit = (root, cloud) => {
+        if (deps.gate === undefined) {
+            return cloud;
+        }
+        let gate = deps.gate(root, cloud);
+        if (BackgroundSyncState.ON === gate.state && gate.credential !== undefined) {
+            if (refusedUnder.get(root) === gate.credential) {
+                gate = {
+                    state: BackgroundSyncState.REFUSED,
+                    why: 'the platform refused this sign-in: run `reticle connect` again',
+                };
+            }
+            else {
+                refusedUnder.delete(root);
+            }
+        }
+        gates.set(root, gate);
+        // A root starts as unlinked: `reticle_cloud_unsynced_root` already names one that never linked.
+        if ((loggedState.get(root) ?? BackgroundSyncState.UNLINKED) !== gate.state) {
+            loggedState.set(root, gate.state);
+            log('reticle_background_sync', { root, state: gate.state, why: gate.why });
+        }
+        return BackgroundSyncState.ON === gate.state ? cloud : { ...cloud, config: null };
+    };
+    /** Stop sending for this root until its sign-in changes. */
+    const refuse = (root) => {
+        const credential = gates.get(root)?.credential;
+        if (credential !== undefined) {
+            refusedUnder.set(root, credential);
+        }
+    };
     /** One root's bundle. The state, source and sink are already per-root; only the caller was not. */
-    const pushRoot = async (root, cloud) => {
-        if (null === cloud.config)
+    const pushRoot = async (root, cloud, readMemory = true) => {
+        if (null === cloud.config) {
             return undefined;
+        }
+        const report = await sendRoot(root, cloud, readMemory);
+        if (report.error !== undefined && AUTH_REFUSED.test(report.error)) {
+            refuse(root);
+        }
+        return report;
+    };
+    const sendRoot = async (root, cloud, readMemory) => {
+        if (null === cloud.config) {
+            throw new Error('sendRoot needs a linked cloud');
+        }
         const full = diskSource(root);
         // The team's decisions come down too: an author's record kept the words a maintainer set aside,
         // and re-sent them every cycle as a new disagreement.
-        if (cloud.policy.memory)
+        if (cloud.policy.memory && readMemory) {
             await pullSettledWords(root, cloud.config, cloud.projectId).catch(() => 0);
+        }
         return runSyncCycle({
             config: cloud.config,
             ...(cloud.link === undefined ? {} : { link: cloud.link }),
@@ -162,33 +286,97 @@ export function startSyncDaemon(deps) {
                 flows: () => (cloud.policy.flows ? full.flows() : []),
                 capsules: () => (cloud.policy.capsules ? full.capsules() : []),
                 derived: (kind) => (cloud.policy.memory ? full.derived(kind) : undefined),
-                ...(cloud.policy.screenshots && full.screenshot !== undefined
-                    ? { screenshot: full.screenshot }
-                    : {}),
+                ...policyScreenshots(full.screenshot, cloud.policy),
             },
             sink: diskSink(root),
             state: readCloudState(root),
             now,
+            ...(deps.clientVersion === undefined ? {} : { clientVersion: deps.clientVersion }),
             request,
         });
     };
+    /** The tag of this root's first memory page as last read: what a conditional read names. */
+    let memoryTag;
+    let polling = false;
+    let lastCloud;
     /** Bring the dashboard's memory decisions down to this root's records. Returns how many changed. */
-    const pullSettledWords = async (root, config, projectId) => {
-        const res = await request(memoryReadUrl(config.url, { projectId }), {
-            method: 'GET',
-            // The sync, not an agent: without this every cycle counted as an agent consulting memory.
-            headers: {
-                authorization: `Bearer ${config.apiKey}`,
-                [MemoryReadHeader.PURPOSE]: MemoryReadPurpose.SYNC,
-            },
+    const pullSettledWords = async (root, config, projectId, 
+    /** A first page already in hand (the poll's 200), so it is not asked for twice. */
+    first) => {
+        const body = await readMemoryPages(config.url, { projectId }, async (url) => {
+            if (first !== undefined && url === first.url) {
+                return first.body;
+            }
+            const res = await request(url, {
+                method: 'GET',
+                // The sync, not an agent: without this every cycle counted as an agent consulting memory.
+                headers: {
+                    authorization: `Bearer ${config.apiKey}`,
+                    [MemoryReadHeader.PURPOSE]: MemoryReadPurpose.SYNC,
+                },
+            });
+            if (root === deps.reticleRoot && !url.includes(`${MemoryScopeField.CURSOR}=`)) {
+                memoryTag = res.etag;
+            }
+            return 200 === res.status ? JSON.parse(res.text) : undefined;
         });
-        if (200 !== res.status)
+        if (body === undefined) {
             return 0;
-        const entries = scopedMemoryEntries(JSON.parse(res.text), projectId) ?? [];
+        }
+        const entries = scopedMemoryEntries(body, projectId) ?? [];
         const settled = settledWordsIn(entries);
         await keptWordsInRequest(reticleDirPaths(root).request, settled);
         return applySettledWords(new IntentShardStore(createNodeFileSystem(), root, { now }), settled);
     };
+    /**
+     * Ask whether the team's memory moved and, when it did, bring its decisions down. Skipped while a
+     * cycle runs or one read it within the minute.
+     * ponytail: the tag covers the first page, which is ordered newest-updated first, so any decision
+     * moves it; a fact deleted past the first page waits for the backstop.
+     */
+    const pollMemory = async () => {
+        if (stopped || running || polling || now() - memoryReadAt < MEMORY_POLL_MS) {
+            return;
+        }
+        polling = true;
+        try {
+            // The link the last cycle resolved: the poll costs no link read of its own.
+            const cloud = lastCloud;
+            if (cloud === undefined || null === cloud.config || !cloud.policy.memory) {
+                return;
+            }
+            const url = memoryReadUrl(cloud.config.url, {
+                projectId: cloud.projectId,
+                limit: MEMORY_PAGE_LIMIT,
+            });
+            const res = await request(url, {
+                method: 'GET',
+                headers: {
+                    authorization: `Bearer ${cloud.config.apiKey}`,
+                    [MemoryReadHeader.PURPOSE]: MemoryReadPurpose.SYNC,
+                    ...(memoryTag === undefined ? {} : { [IF_NONE_MATCH]: memoryTag }),
+                },
+            });
+            // Answered either way, 304 included: the memory is known current as of now.
+            if (200 === res.status || 304 === res.status) {
+                memoryReadAt = now();
+            }
+            if (200 !== res.status) {
+                return;
+            }
+            memoryTag = res.etag;
+            await pullSettledWords(deps.reticleRoot, cloud.config, cloud.projectId, {
+                url,
+                body: JSON.parse(res.text),
+            });
+        }
+        catch {
+            // Offline is not news; the next minute asks again.
+        }
+        finally {
+            polling = false;
+        }
+    };
     /**
      * Push every other linked root this machine knows about.
      *
@@ -199,8 +387,9 @@ export function startSyncDaemon(deps) {
     const syncOtherRoots = async () => {
         const roots = deps.otherRoots;
         const cloudFor = deps.cloudFor;
-        if (roots === undefined || cloudFor === undefined)
+        if (roots === undefined || cloudFor === undefined) {
             return;
+        }
         let list = [];
         try {
             list = await roots();
@@ -211,35 +400,41 @@ export function startSyncDaemon(deps) {
             return;
         }
         for (const root of list) {
-            if (root === deps.reticleRoot)
+            if (root === deps.reticleRoot) {
                 continue;
+            }
             rootsLinked.set(root, false);
             try {
-                const cloud = await cloudFor(root);
+                const cloud = admit(root, await cloudFor(root));
                 // Linked HERE, by its own link file. An unlinked root resolves to the environment's key,
                 // which is the right answer for the root this daemon stands in and somebody else's project
                 // for every other one: a daemon started with RETICLE_API_KEY pushed every project this
                 // machine had seen into that one, a status and a pull per root on every cycle.
                 // Never silently: `refreshUnsynced` names this root if it holds runs.
-                if (null === cloud.config || null === cloud.projectId)
+                if (null === cloud.config || null === cloud.projectId) {
                     continue;
+                }
                 rootsLinked.set(root, true);
-                if (cloud.policy.flows)
+                if (cloud.policy.flows) {
                     rootsSendFlows.add(root);
+                }
                 const report = await pushRoot(root, cloud);
-                if (report === undefined)
+                if (report === undefined) {
                     continue;
+                }
                 if (report.error !== undefined) {
                     log('reticle_cloud_sync_failed', { root, error: report.error });
                     continue;
                 }
-                if (!report.ok)
+                if (!report.ok) {
                     log('reticle_cloud_sync_failed', { root, error: describeSync(report) });
+                }
                 const moved = movedAnything(report);
                 // The root is NAMED here and not in the single-root log below, because with several repos
                 // reporting, "synced 3 runs" without a directory is not an answer to "synced from where".
-                if (moved)
+                if (moved) {
                     log('reticle_cloud_synced', { root, summary: describeSync(report) });
+                }
             }
             catch (error) {
                 log('reticle_cloud_sync_failed', {
@@ -249,46 +444,84 @@ export function startSyncDaemon(deps) {
             }
         }
     };
-    const cycle = async () => {
+    /** When this root last read the team's memory, and whether its intent moved since. */
+    let memoryReadAt = Number.NEGATIVE_INFINITY;
+    /** When the other linked repos were last walked. */
+    let othersAt = Number.NEGATIVE_INFINITY;
+    let intentMoved = true;
+    /**
+     * A change landed that no cycle has delivered yet. Work saved while offline used to wait out the
+     * longest backoff after the network returned (each save's failed cycle doubled it): owed work
+     * retries every minute, and only an idle machine backs off.
+     */
+    let owed = false;
+    const memoryDue = (forced) => {
+        if (!forced && !intentMoved && now() - memoryReadAt < SETTLED_WORDS_MAX_AGE_MS) {
+            return false;
+        }
+        intentMoved = false;
+        memoryReadAt = now();
+        return true;
+    };
+    /** `asked`: a sync somebody requested: read the memory and walk every repo, whatever is due. */
+    const cycle = async (asked = false) => {
         // Overlap guard: a slow cycle must not have a second one started on top of it, or two bundles
         // race and the cursor written by the loser silently rewinds the winner's progress.
-        if (running)
+        if (running) {
             return undefined;
+        }
         running = true;
-        rootsLinked = new Map();
-        rootsSendFlows = new Set();
+        // Owed work this cycle carries; a failed exchange leaves it owed, and a change meanwhile adds to it.
+        const carried = owed;
+        owed = false;
+        // The other repos' entries stand until their next pass, so what they owe is still reported.
+        const othersDue = asked || now() - othersAt >= OTHER_ROOTS_EVERY_MS;
+        if (othersDue) {
+            othersAt = now();
+            rootsLinked = new Map();
+            rootsSendFlows = new Set();
+        }
+        const own = deps.reticleRoot;
+        rootsSendFlows.delete(own);
         try {
-            const cloud = await deps.cloud();
+            const cloud = admit(deps.reticleRoot, await deps.cloud());
+            lastCloud = cloud;
             const linked = null !== cloud.config;
-            const own = deps.reticleRoot;
             rootsLinked.set(own, linked);
-            if (linked && cloud.policy.flows)
+            if (linked && cloud.policy.flows) {
                 rootsSendFlows.add(own);
-            if (linked !== wasLinked || (linked && cloud.projectId !== wasProject)) {
-                wasLinked = linked;
-                wasProject = cloud.projectId;
-                if (linked)
+            }
+            // Another project's memory is another project's decisions: a re-link reads it at once.
+            const relinked = cloud.projectId !== wasProject;
+            const linkChanged = linked !== wasLinked || (linked && relinked);
+            wasLinked = linked;
+            wasProject = cloud.projectId;
+            // With a gate, `admit` already said why once per change; this would say "run connect" to
+            // somebody who only signed out or switched sync off.
+            if (deps.gate === undefined && linkChanged) {
+                if (linked) {
                     log('reticle_cloud_linked', {
                         projectId: cloud.projectId,
                         root: deps.reticleRoot,
                     });
+                }
                 // Names the ROOT, because the answer is almost always "the daemon is not where you think it
                 // is" — and a message that omits the directory sends people to check their key instead.
-                else
+                else {
                     log('reticle_cloud_unlinked', {
                         root: deps.reticleRoot,
                         fix: 'run `reticle connect` in this directory, or start the daemon in the linked one — nothing is being synced from here',
                     });
+                }
             }
-            // Every OTHER linked root, first. Their failures are logged and never abort this daemon's own
-            // push: one repo whose credential was revoked must not silence the rest of the machine.
-            await syncOtherRoots();
-            if (null === cloud.config)
+            if (null === cloud.config) {
                 return undefined;
-            const report = await pushRoot(deps.reticleRoot, cloud);
+            }
+            const report = await pushRoot(deps.reticleRoot, cloud, memoryDue(asked || relinked));
             // `pushRoot` returns undefined only for an unlinked root, which the guard above has ruled out.
-            if (report === undefined)
+            if (report === undefined) {
                 return undefined;
+            }
             // Said out loud on EVERY cycle, including the ones that moved nothing and the ones that
             // failed. The log below is deliberately quiet when idle, which is right for a log and wrong
             // for a hook: from outside, "nothing changed" and "sync has been broken since Tuesday" are
@@ -307,21 +540,36 @@ export function startSyncDaemon(deps) {
                 reportedError = failure;
                 log('reticle_cloud_sync_failed', { error: failure });
             }
-            if (report.error === undefined) {
-                if (failure === undefined)
+            if (report.error === undefined && report.ok) {
+                lastPushAt = now();
+            }
+            if (report.error !== undefined) {
+                owed ||= carried;
+                failedCycle();
+            }
+            else {
+                if (failure === undefined) {
                     reportedError = undefined;
+                }
                 // Only when something actually moved. A per-minute "nothing to send" is noise that trains
                 // people to stop reading the log.
                 const moved = movedAnything(report);
-                if (moved && failure === undefined)
+                if (moved && failure === undefined) {
                     log('reticle_cloud_synced', { summary: describeSync(report) });
+                }
                 /*
                  * A cycle that moved something means a drive is in progress, so the next one comes sooner;
                  * one that moved nothing means the machine is idle, so it backs straight off. The rate
                  * follows the work without needing to be told about sessions, and an idle laptop settles at
                  * the same cost it had before this existed.
                  */
-                nextDelay = moved ? activeIntervalMs : intervalMs;
+                if (failure !== undefined && !moved) {
+                    failedCycle();
+                }
+                else {
+                    failures = 0;
+                    nextDelay = moved ? activeIntervalMs : intervalMs;
+                }
             }
             return report;
         }
@@ -332,66 +580,177 @@ export function startSyncDaemon(deps) {
                 reportedError = message;
                 log('reticle_cloud_sync_failed', { error: message });
             }
+            owed ||= carried;
+            failedCycle();
             return undefined;
         }
         finally {
+            // Every OTHER linked root, after this one: the root that changed is the one somebody is waiting
+            // on. Their failures are logged and never touch this root's push, whichever ran first.
+            if (othersDue) {
+                await syncOtherRoots().catch(() => undefined);
+            }
             await refreshUnsynced().catch(() => undefined);
             running = false;
+            startWatching();
         }
     };
     /** The delay for the NEXT cycle: fast while the last one moved something, slow once it stops. */
     let nextDelay = intervalMs;
+    /** Consecutive failed cycles: the retry waits a minute, then doubles, never past the backstop. */
+    let failures = 0;
+    function failedCycle() {
+        if (owed) {
+            nextDelay = FAILURE_RETRY_MS;
+            return;
+        }
+        nextDelay = Math.min(FAILURE_RETRY_MS * 2 ** failures, intervalMs);
+        failures += 1;
+    }
+    /** When the armed timer fires; Infinity when none is armed. */
+    let dueAt = Number.POSITIVE_INFINITY;
+    /** A change landed while a cycle was running: that cycle may have read the disk before it. */
+    let dirty = false;
     const schedule = (delay) => {
-        if (stopped)
+        if (stopped) {
             return;
+        }
         // Replace, never stack. `nudge` and the interval both schedule, and leaving the old timer armed
         // would let every nudge add a permanent extra cycle per minute for the life of the process.
-        if (timer !== undefined)
+        if (timer !== undefined) {
             clearTimeout(timer);
+        }
+        dueAt = now() + delay;
         timer = setTimeout(() => {
-            void cycle().finally(() => schedule(nextDelay));
+            dueAt = Number.POSITIVE_INFINITY;
+            void cycle().finally(() => {
+                schedule(nextDelay);
+                afterCycle();
+            });
         }, delay);
         // Unref'd: a pending sync must never be the reason a process refuses to exit.
         timer.unref?.();
     };
+    /** Cycle within `delay`, but never LATER than a cycle already armed. */
+    const soon = (delay) => {
+        if (now() + delay < dueAt) {
+            schedule(delay);
+        }
+    };
+    /** One follow-up for the changes a cycle may have missed, however many there were. */
+    const afterCycle = () => {
+        if (!dirty) {
+            return;
+        }
+        dirty = false;
+        soon(CHANGE_DEBOUNCE_MS);
+    };
+    const onChange = (path) => {
+        if (stopped || isOwnWrite(path)) {
+            return;
+        }
+        if (isIntent(path)) {
+            intentMoved = true;
+        }
+        owed = true;
+        if (running) {
+            dirty = true;
+        }
+        else {
+            soon(CHANGE_DEBOUNCE_MS);
+        }
+    };
+    let unwatch;
+    /** Watch the root once it exists; a root created mid-session is picked up after the next cycle. */
+    const startWatching = () => {
+        if (stopped || unwatch !== undefined || deps.watch === undefined) {
+            return;
+        }
+        unwatch = deps.watch(onChange);
+    };
+    const stopWatching = () => {
+        unwatch?.();
+        unwatch = undefined;
+    };
     schedule(FIRST_CYCLE_DELAY_MS);
-    // A nudge, not an immediate cycle: the link file and its key are written one after the other.
-    const unwatch = deps.watchLink?.(() => schedule(NUDGE_DELAY_MS));
+    startWatching();
+    const poll = setInterval(() => void pollMemory(), MEMORY_POLL_TICK_MS);
+    poll.unref?.();
     return {
         // A sync somebody asked for writes what is held on a timer first: a drive's run waits a few
         // seconds after its last verdict, and a push straight after `session end` sent "0 of 0".
         syncNow: async () => {
             await flushPendingWrites();
-            return cycle();
+            const report = await cycle(true);
+            afterCycle();
+            return report;
         },
         unsyncedRoots: () => unsynced,
+        background: () => {
+            const gate = gates.get(deps.reticleRoot);
+            return {
+                state: gate?.state ?? BackgroundSyncState.ON,
+                why: gate?.why ?? 'not checked yet',
+                failures,
+                ...(reportedError === undefined ? {} : { lastError: reportedError }),
+                ...(lastPushAt === undefined ? {} : { lastPushAt }),
+            };
+        },
         nudge: () => {
             // A cycle already in flight will not pick this up, so the nudge is still scheduled behind it
             // rather than dropped — otherwise the run that arrived during a slow cycle waits a full tick.
             schedule(NUDGE_DELAY_MS);
         },
         stop: () => {
-            unwatch?.();
+            stopWatching();
+            clearInterval(poll);
             stopped = true;
-            if (timer !== undefined)
+            if (timer !== undefined) {
                 clearTimeout(timer);
+            }
             timer = undefined;
         },
         flush: async () => {
-            unwatch?.();
+            stopWatching();
+            clearInterval(poll);
             stopped = true;
-            if (timer !== undefined)
+            if (timer !== undefined) {
                 clearTimeout(timer);
+            }
             timer = undefined;
             // A cycle already running may have started BEFORE the write being flushed, so its report says
             // nothing about that artifact. Wait it out rather than skipping on the overlap guard.
-            const deadline = Date.now() + FLUSH_WAIT_MS;
-            while (running && Date.now() < deadline)
+            const deadline = now() + FLUSH_BUDGET_MS;
+            while (running && now() < deadline) {
                 await new Promise((resolve) => setTimeout(resolve, FLUSH_POLL_MS));
-            await cycle();
+            }
+            // Not `asked`: on the way out, the run goes first; the memory and the other repos only if due.
+            // Bounded by what is left of the budget: a cycle can wait on a network that does not answer.
+            let lateTimer;
+            const late = new Promise((resolve) => {
+                lateTimer = setTimeout(resolve, Math.max(0, deadline - now()));
+            });
+            await Promise.race([cycle().then(() => undefined), late]);
+            clearTimeout(lateTimer);
         },
     };
 }
+/**
+ * Flush, but return after `budgetMs` at the latest, and never throw.
+ *
+ * For a process on its way out. The cycle has per-call timeouts, but a stalled network still adds
+ * them up, and an exit must not wait on that. A cycle cut short loses nothing: the artifacts stay
+ * on disk, and the next daemon or `reticle sync` sends them.
+ */
+export async function flushWithin(daemon, budgetMs) {
+    let timer;
+    const deadline = new Promise((resolve) => {
+        timer = setTimeout(resolve, budgetMs);
+        timer.unref?.();
+    });
+    await Promise.race([daemon.flush().catch(() => undefined), deadline]);
+    clearTimeout(timer);
+}
 /**
  * Start cloud sync for a daemon and hand back the two hooks the daemon wires to it.
  *
@@ -405,30 +764,61 @@ export function startSyncDaemon(deps) {
  * resolving a credential — and the part a bootstrap file has no business spelling out.
  */
 export function attachCloudSync(deps) {
+    const signedIn = deps.signedIn;
     return startSyncDaemon({
         reticleRoot: deps.reticleRoot,
+        clientVersion: deps.clientVersion,
         cloud: () => resolveProjectCloud(deps.fs, deps.reticleRoot, deps.homeDir, deps.env),
         // Every OTHER linked repo on this machine, not just the directory the daemon was started in.
         // One daemon serves many projects, and pushing only its own root left the rest silently
         // reporting nothing — indistinguishable, on the dashboard, from nobody having verified anything.
         otherRoots: () => Promise.resolve(deps.otherRoots()),
         cloudFor: (root) => resolveProjectCloud(deps.fs, root, deps.homeDir, deps.env),
-        // ponytail: this root only; a sibling root's re-link is still read on the next tick.
-        watchLink: (onChange) => watchLinkFile(deps.reticleRoot, onChange),
+        // ponytail: this root only; sibling roots sync at most once a minute, when this one changes,
+        // and on the backstop timer.
+        // Watching them too means one recursive watcher per linked repo — add it if siblings lag.
+        watch: (onChange) => watchReticleRoot(deps.reticleRoot, onChange),
+        // Sent only while somebody is signed in, to a linked project that did not switch it off.
+        ...(signedIn === undefined
+            ? {}
+            : {
+                gate: (root, cloud) => backgroundSyncGate({ reticleRoot: root, cloud, env: deps.env, signedIn }),
+            }),
+        ...(deps.request === undefined ? {} : { request: deps.request }),
+        ...(deps.intervalMs === undefined ? {} : { intervalMs: deps.intervalMs }),
     });
 }
-/** Watch a root for its link file changing. A root with no `.reticle` yet is picked up per tick. */
-function watchLinkFile(reticleRoot, onChange) {
+/**
+ * Watch a whole `.reticle` root, reporting each change by its path under the root.
+ *
+ * Returns undefined only when the root does not exist yet, so the caller tries again later. Where a
+ * recursive watch is unsupported (an old Node on Linux, a network filesystem) or fails later (too
+ * many files), it says so ONCE and returns a no-op: the backstop timer is the whole sync from then on.
+ */
+export function watchReticleRoot(reticleRoot, onChange, watchFn = (root, listener) => watch(root, { recursive: true }, listener)) {
+    const unavailable = (error) => log('reticle_cloud_watch_unavailable', {
+        root: reticleRoot,
+        error: error instanceof Error ? error.message : String(error),
+        fallback: 'syncing on the timer only',
+    });
     try {
-        const watcher = watch(reticleRoot, (_event, name) => {
-            if (CLOUD_LINK_FILE === String(name))
-                onChange();
+        const watcher = watchFn(reticleRoot, (_event, name) => {
+            if (name !== null) {
+                onChange(name);
+            }
+        });
+        watcher.on('error', (error) => {
+            unavailable(error);
+            watcher.close();
         });
-        watcher.on('error', () => watcher.close());
         watcher.unref();
         return () => watcher.close();
     }
-    catch {
+    catch (error) {
+        if ('ENOENT' === error.code) {
+            return undefined;
+        }
+        unavailable(error);
         return () => undefined;
     }
 }