@reticlehq/server 2.12.0 → 2.13.0

package/dist/cloud/sync-cycle.js

@@ -0,0 +1,270 @@
+/**
+ * One full conversation with the dashboard: ask, send the difference, collect what came back.
+ *
+ * ── WHY IT LOOKS LIKE THIS ─────────────────────────────────────────────────────────────────────
+ * `.reticle/` is the source of truth and always will be. Reticle has to work with no account and no
+ * network; a verification that blocks on an HTTP round trip is one somebody switches off. So the
+ * dashboard is a REPLICA, and this is the replication protocol:
+ *
+ *   1. ASK      GET /v1/sync/status  → run ids it already holds, a content hash per derived record
+ *   2. SEND     POST /v1/sync        → only unseen runs, only records whose hash moved
+ *   3. COLLECT  GET /v1/sync/pull    → decisions a human made there, since our cursor
+ *   4. APPLY    write them to .reticle/issues.json so the HUD and the next run can see them
+ *
+ * ASK-THEN-SEND, not send-everything. A three-hour session rewrites impact.json on every tool call;
+ * uploading it each time would re-send the same megabytes dozens of times, and a sync that costs
+ * that much is one people turn off — which is the real failure, because a dashboard nobody syncs to
+ * is a dashboard nobody opens. When nothing has moved, a cycle sends nothing at all, and that is
+ * what makes running it on a timer affordable.
+ *
+ * HASHES, NOT TIMESTAMPS. Two machines comparing their own clocks is a guess: they drift, and a
+ * laptop that was asleep will cheerfully decide it is current. A content hash is an answer.
+ *
+ * BOTH DIRECTIONS, ALWAYS. The pull runs even when there is nothing to push — a quiet machine is
+ * precisely the one whose dashboard somebody has been triaging on, so skipping the pull when the
+ * push is empty would starve the direction that matters most.
+ *
+ * NOTHING IS DELETED LOCALLY ON SUCCESS. A lost response costs one redundant upload rather than a
+ * hole in the record, and the server dedupes by run id anyway.
+ *
+ * Every dependency is injected — the clock, the fetch, the reads and writes — because this is the
+ * one piece of Reticle that talks to a network AND to a disk, and it must be provable without either.
+ */
+import { ReticleDir } from '@reticlehq/core';
+import { hashPayload } from './sync-hash.js';
+/** The server's own doors. Kept beside the code that calls them, like the other cloud paths. */
+const SYNC_PATH = '/v1/sync';
+const SYNC_STATUS_PATH = '/v1/sync/status';
+const SYNC_PULL_PATH = '/v1/sync/pull';
+/**
+ * The derived records that ride along with runs, and the file each one lives in.
+ *
+ * A list rather than three hand-written blocks so adding a fourth is one line and cannot be
+ * half-done — the bundle, the hashing and the reporting all walk this.
+ */
+export const DERIVED_RECORDS = [
+    { kind: 'impact', file: ReticleDir.IMPACT_FILE },
+    { kind: 'flake', file: ReticleDir.FLAKE_FILE },
+    { kind: 'intent', file: ReticleDir.INTENT_FILE },
+];
+const asJson = (text) => {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+};
+const isRecord = (v) => 'object' === typeof v && null !== v;
+/**
+ * Run one cycle. Never throws: the local record is already safe on disk, and a sync that can take
+ * down the thing it is backing up is worse than no sync.
+ */
+export async function runSyncCycle(deps) {
+    const empty = {
+        ok: false,
+        runsSent: 0,
+        runsRejected: [],
+        flowsSent: 0,
+        derivedSent: [],
+        pulled: 0,
+        morePending: false,
+    };
+    const call = async (path, init) => {
+        const res = await deps.request(`${deps.config.url}${path}`, {
+            method: init?.method ?? 'GET',
+            headers: {
+                'content-type': 'application/json',
+                authorization: `Bearer ${deps.config.apiKey}`,
+            },
+            ...(init?.body === undefined ? {} : { body: init.body }),
+        });
+        return { status: res.status, json: asJson(res.text), text: res.text };
+    };
+    const nextState = { ...deps.state };
+    try {
+        // 1. ASK.
+        const status = await call(SYNC_STATUS_PATH);
+        if (200 !== status.status) {
+            const error = `status ${String(status.status)}: ${status.text.slice(0, 200)}`;
+            deps.sink.writeState({ ...nextState, lastError: error });
+            return { ...empty, error };
+        }
+        const held = isRecord(status.json) ? status.json : {};
+        /*
+         * Validated, not trusted. `new Set(someString)` builds a set of CHARACTERS, so a `knownRunIds`
+         * that arrived as a string made `known.has('a')` true and silently skipped any run whose id was
+         * one of those letters — the client deciding, on the server's malformed word, not to upload
+         * something the server does not have. Silent data loss is the one failure this protocol must
+         * not have, and an unreadable answer has to mean "it knows nothing", never "it knows this".
+         */
+        const known = new Set(Array.isArray(held.knownRunIds)
+            ? held.knownRunIds.filter((id) => 'string' === typeof id)
+            : []);
+        // Same rule for the hashes: only a string can equal a hash we computed, so anything else reads
+        // as "unknown" and the record is sent once. Re-sending costs a request; skipping costs the data.
+        const hashes = isRecord(held.stateHashes) ? held.stateHashes : {};
+        // 2. SEND — only what the server does not already have.
+        const allRuns = deps.source.runs();
+        const unsent = allRuns.filter((r) => !known.has(r.runId));
+        const derivedSent = [];
+        const bundle = {};
+        if (unsent.length > 0)
+            bundle['runs'] = unsent.map((r) => r.payload);
+        for (const { kind } of DERIVED_RECORDS) {
+            const payload = deps.source.derived(kind);
+            if (payload === undefined)
+                continue;
+            // The one comparison the whole protocol rests on. Same hash, do not send it.
+            if (hashPayload(payload) === hashes[kind])
+                continue;
+            bundle[kind] = payload;
+            derivedSent.push(kind);
+        }
+        // Flows are small and upserted by name, so they ride along whenever anything else does rather
+        // than earning a round trip of their own.
+        const flows = bundle['runs'] === undefined && 0 === derivedSent.length ? [] : deps.source.flows();
+        if (flows.length > 0)
+            bundle['flows'] = flows;
+        let runsSent = 0;
+        let flowsSent = 0;
+        let runsRejected = [];
+        if (Object.keys(bundle).length > 0) {
+            const pushed = await call(SYNC_PATH, { method: 'POST', body: JSON.stringify(bundle) });
+            if (200 !== pushed.status) {
+                const error = `sync ${String(pushed.status)}: ${pushed.text.slice(0, 200)}`;
+                deps.sink.writeState({ ...nextState, lastError: error });
+                return { ...empty, error };
+            }
+            const body = isRecord(pushed.json) ? pushed.json : {};
+            const runs = isRecord(body['runs']) ? body['runs'] : {};
+            const flowsPart = isRecord(body['flows']) ? body['flows'] : {};
+            runsSent = 'number' === typeof runs['accepted'] ? runs['accepted'] : 0;
+            flowsSent = 'number' === typeof flowsPart['accepted'] ? flowsPart['accepted'] : 0;
+            runsRejected = Array.isArray(runs['rejected'])
+                ? runs['rejected']
+                : [];
+            nextState.lastPushAt = deps.now();
+        }
+        // 3. COLLECT — always, even when there was nothing to send.
+        const query = nextState.cursor === undefined ? '' : `?since=${encodeURIComponent(nextState.cursor)}`;
+        const pull = await call(`${SYNC_PULL_PATH}${query}`);
+        if (200 !== pull.status) {
+            // The push already landed; report it rather than throwing the whole cycle away.
+            const error = `pull ${String(pull.status)}: ${pull.text.slice(0, 200)}`;
+            deps.sink.writeState({ ...nextState, lastError: error });
+            return { ...empty, ok: false, runsSent, flowsSent, derivedSent, runsRejected, error };
+        }
+        const pulled = isRecord(pull.json) ? pull.json : {};
+        const decisions = pulled.triage ?? [];
+        // 4. APPLY.
+        if (decisions.length > 0) {
+            const triage = {};
+            for (const d of decisions) {
+                triage[d.fingerprint] = {
+                    status: d.status,
+                    flowName: d.flowName ?? null,
+                    title: d.title ?? '',
+                    at: d.at,
+                };
+            }
+            deps.sink.writeIssues({ triage });
+        }
+        // The cursor is written even on an empty page: it is the server's, and it never goes backwards.
+        if ('string' === typeof pulled.cursor)
+            nextState.cursor = pulled.cursor;
+        nextState.lastPullAt = deps.now();
+        delete nextState.lastError;
+        deps.sink.writeState(nextState);
+        return {
+            ok: true,
+            runsSent,
+            runsRejected,
+            flowsSent,
+            derivedSent,
+            pulled: decisions.length,
+            morePending: true === pulled.more,
+            /*
+             * Nothing on disk at all, as opposed to nothing NEW. Computed from what the source offered
+             * before any cursor filtering, because a repo whose runs were all already pushed is healthy
+             * and a repo that has never recorded one is usually misconfigured.
+             */
+            localIsEmpty: 0 === allRuns.length &&
+                0 === deps.source.flows().length &&
+                DERIVED_RECORDS.every(({ kind }) => deps.source.derived(kind) === undefined),
+        };
+    }
+    catch (error) {
+        // A network that is down is not an error condition for a local-first tool; it is Tuesday.
+        const message = describeTransportError(error, deps.config.url);
+        deps.sink.writeState({ ...nextState, lastError: message });
+        return { ...empty, error: message };
+    }
+}
+/**
+ * Say WHICH host failed and WHY.
+ *
+ * Node's fetch rejects with the bare string "fetch failed" and hides the real reason — a refused
+ * connection, a bad hostname, an expired certificate — one level down in `cause`. A machine that
+ * has quietly stopped syncing shows that string in `reticle whoami`, and on its own it is
+ * indistinguishable from every other network problem, so the person reading it learns nothing and
+ * checks nothing. Naming the origin and the underlying code turns it into one thing to look at.
+ */
+function describeTransportError(error, url) {
+    if (!(error instanceof Error))
+        return String(error);
+    const cause = error.cause;
+    if (!(cause instanceof Error))
+        return `${error.message} (${url})`;
+    const code = cause.code;
+    // The code and the message are each sometimes empty — an aggregate DNS failure carries a code and
+    // no text, a TLS failure the reverse. Joined only when both are there, so the line never trails
+    // off into a dangling separator.
+    const parts = ['string' === typeof code && code.length > 0 ? code : '', cause.message].filter((part) => part.length > 0);
+    const detail = parts.join(': ');
+    return 0 === detail.length
+        ? `${error.message} (${url})`
+        : `${error.message} — ${detail} (${url})`;
+}
+/** One line a human can read, for the CLI and the daemon log. */
+export function describeSync(report) {
+    if (report.error !== undefined)
+        return `sync failed — ${report.error}`;
+    const sent = [];
+    if (report.runsSent > 0)
+        sent.push(`${String(report.runsSent)} run(s)`);
+    if (report.flowsSent > 0)
+        sent.push(`${String(report.flowsSent)} flow(s)`);
+    if (report.derivedSent.length > 0)
+        sent.push(report.derivedSent.join(', '));
+    /*
+     * "Nothing to send" is a statement about the QUEUE, and it is false the moment the queue was full
+     * and the server threw it away. Built from what was accepted, the sentence used to read "nothing
+     * to send, 3 rejected" — something was very much sent, and the reader is told both that it was
+     * not and nothing about why.
+     */
+    const push = sent.length > 0
+        ? `sent ${sent.join(' + ')}`
+        : report.runsRejected.length > 0
+            ? 'nothing accepted'
+            : true === report.localIsEmpty
+                ? // Not the same statement as "nothing to send", which describes a repo that is simply up
+                    // to date. This one has never recorded anything, which for a LINKED repo usually means
+                    // the app announces no projectId and its runs are landing under a different root.
+                    'nothing recorded here yet — if this app has been driven, it is reporting somewhere else'
+                : 'nothing to send';
+    const pull = 0 === report.pulled
+        ? ''
+        : `, pulled ${String(report.pulled)} decision(s)${report.morePending ? ' (more waiting)' : ''}`;
+    /*
+     * One reason, not a count. A rejection count tells somebody they have a problem and nothing about
+     * which problem — and these arrive from a BACKGROUND daemon, so the summary line is often the only
+     * place anybody ever sees it. Rejections in one cycle almost always share a cause (a version skew
+     * refuses every payload the same way), so the first reason plus the count is the whole story
+     * without printing a line per run; `reticle sync` still lists them all.
+     */
+    const bad = 0 === report.runsRejected.length
+        ? ''
+        : `, ${String(report.runsRejected.length)} rejected — ${report.runsRejected[0]?.reason ?? 'no reason given'}`;
+    return `${push}${pull}${bad}`;
+}

package/dist/cloud/sync-daemon.d.ts

@@ -0,0 +1,69 @@
+import { type SyncReport } from './sync-cycle.js';
+import type { ProjectCloud } from './cloud-config.js';
+/** How often the daemon cycles. See the note above on why this is a constant and not a curve. */
+export declare const DAEMON_SYNC_INTERVAL_MS = 60000;
+/**
+ * The cadence while something is actually happening.
+ *
+ * A fixed minute is the wrong shape for both states it has to cover. During a drive the ledger
+ * changes on every tool call and a minute of lag is what makes a dashboard feel dead; idle, a minute
+ * is already more often than nothing has changed deserves.
+ *
+ * So the interval follows the work: a cycle that MOVED something earns the fast rate, a cycle that
+ * moved nothing backs off to the slow one. No session plumbing and no new configuration — activity
+ * is inferred from what the last cycle actually sent, which is the only honest evidence available.
+ *
+ * Deliberately not per-tool-call. A push in the tool path would put the network in the agent's inner
+ * loop, and verification working with the network down is a promise this product makes.
+ */
+export declare const DAEMON_SYNC_ACTIVE_INTERVAL_MS = 5000;
+export interface SyncDaemonDeps {
+    reticleRoot: string;
+    /** Resolved per tick, not once: a repo linked while the daemon is alive starts syncing itself. */
+    cloud: () => Promise<ProjectCloud>;
+    /**
+     * Every OTHER `.reticle` root on this machine that might be linked.
+     *
+     * One daemon serves many projects — that is what `artifactRootFor` exists for — and this loop
+     * pushed exactly one of them: whichever directory the daemon happened to be started in. Every
+     * other linked repo went silent, and silent is indistinguishable from "nobody verified anything",
+     * which is the worst possible failure for a dashboard somebody is deciding budget on.
+     *
+     * Optional: a caller that does not supply it gets exactly the old single-root behaviour.
+     */
+    otherRoots?: () => Promise<readonly string[]>;
+    /** Resolve the link for a root that is not this daemon's own. Required to use `otherRoots`. */
+    cloudFor?: (root: string) => Promise<ProjectCloud>;
+    now?: () => number;
+    intervalMs?: number;
+    /** Injected for the test; the real one is `fetch`. */
+    request?: (url: string, init: {
+        method: string;
+        headers: Record<string, string>;
+        body?: string;
+    }) => Promise<{
+        status: number;
+        text: string;
+    }>;
+}
+export interface SyncDaemon {
+    /** Run one cycle now, whatever the timer is doing. Returns undefined when not linked. */
+    syncNow: () => Promise<SyncReport | undefined>;
+    /**
+     * Something worth shipping just landed — cycle soon rather than at the next tick.
+     *
+     * A verification RUN is the artifact people wait on, and making them wait up to a full interval
+     * for it is the difference between a dashboard that reflects the work and one that lags it. The
+     * counters keep the timer: they are a rolling aggregate, and a write per tool call to move a
+     * number nobody is watching that second is exactly the cost the interval exists to avoid.
+     *
+     * Coalescing, never additive: many nudges in a burst collapse into one cycle.
+     */
+    nudge: () => void;
+    stop: () => void;
+}
+/**
+ * Start the loop. Safe to call for an UNLINKED project: it resolves the link on every tick and does
+ * nothing until one appears, which is what lets `reticle link` take effect without a restart.
+ */
+export declare function startSyncDaemon(deps: SyncDaemonDeps): SyncDaemon;

package/dist/cloud/sync-daemon.js

@@ -0,0 +1,260 @@
+/**
+ * Automatic sync, for the session nobody thinks about.
+ *
+ * Somebody runs Reticle all morning. Every tool call rewrites the impact record; every verification
+ * writes a run. If sync is a command a human types, the dashboard is stale for exactly as long as
+ * they are busy — which is precisely when the numbers on it would have been worth looking at.
+ *
+ * So the daemon does it. Not a new process, not a thing to remember: the daemon is already running
+ * for the whole session (it is what the agent talks to), so it is the only place where "sync while
+ * 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.
+ *
+ * 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.
+ *
+ * SILENT UNLESS IT MATTERS. A failed cycle is logged once per NEW error, not once per minute: a
+ * laptop on a train would otherwise fill the log with the same line four hundred times and teach
+ * everyone to ignore it.
+ */
+import { log } from '../log.js';
+import { describeSync, runSyncCycle } from './sync-cycle.js';
+import { diskSink, diskSource, readCloudState } from './sync-disk.js';
+/** How often the daemon cycles. See the note above on why this is a constant and not a curve. */
+export const DAEMON_SYNC_INTERVAL_MS = 60_000;
+/**
+ * The cadence while something is actually happening.
+ *
+ * A fixed minute is the wrong shape for both states it has to cover. During a drive the ledger
+ * changes on every tool call and a minute of lag is what makes a dashboard feel dead; idle, a minute
+ * is already more often than nothing has changed deserves.
+ *
+ * So the interval follows the work: a cycle that MOVED something earns the fast rate, a cycle that
+ * moved nothing backs off to the slow one. No session plumbing and no new configuration — activity
+ * is inferred from what the last cycle actually sent, which is the only honest evidence available.
+ *
+ * Deliberately not per-tool-call. A push in the tool path would put the network in the agent's inner
+ * loop, and verification working with the network down is a promise this product makes.
+ */
+export const DAEMON_SYNC_ACTIVE_INTERVAL_MS = 5_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;
+/**
+ * How long a nudge waits before cycling.
+ *
+ * Long enough to COALESCE — a battery that writes six runs in a second must cause one cycle, not
+ * six — and short enough that finishing a verification and looking at the dashboard feels like one
+ * action. Not zero: a run artifact is renamed into place and the sibling records it implies are
+ * written just after, so cycling on the very first byte would ship a bundle that is missing them.
+ */
+const NUDGE_DELAY_MS = 1_500;
+const defaultRequest = async (url, init) => {
+    const res = await fetch(url, init);
+    return { status: res.status, text: await res.text() };
+};
+/**
+ * Start the loop. Safe to call for an UNLINKED project: it resolves the link on every tick and does
+ * nothing until one appears, which is what lets `reticle link` take effect without a restart.
+ */
+export function startSyncDaemon(deps) {
+    const intervalMs = deps.intervalMs ?? DAEMON_SYNC_INTERVAL_MS;
+    // Never slower than the idle rate: a deployment that lengthens the interval means "sync less", and
+    // an active burst must not quietly re-introduce the cost it was lowering.
+    const activeIntervalMs = Math.min(DAEMON_SYNC_ACTIVE_INTERVAL_MS, intervalMs);
+    const now = deps.now ?? (() => Date.now());
+    const request = deps.request ?? defaultRequest;
+    let timer;
+    let stopped = false;
+    let running = false;
+    /** The last error already reported. Repeats are swallowed so an offline laptop stays quiet. */
+    let reportedError;
+    /**
+     * Whether the last cycle found a link — undefined until the first one has looked.
+     *
+     * An unlinked project used to sync nothing and say nothing, which is indistinguishable from a
+     * working sync until somebody notices the dashboard is hours behind. Observed for real: the
+     * daemon was started from a sibling repo that had never been linked, so every call for an entire
+     * session was recorded into THAT repo's ledger and pushed nowhere, and the first evidence was a
+     * stale number on a dashboard nobody had reason to distrust.
+     *
+     * Announced on the FIRST cycle and on every change after it, so `reticle link` mid-session says
+     * so too. Once per transition, never per tick — a line every minute is a line people stop reading.
+     */
+    let wasLinked;
+    /** 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)
+            return undefined;
+        const full = diskSource(root);
+        return runSyncCycle({
+            config: cloud.config,
+            source: {
+                runs: () => (cloud.policy.runs ? full.runs() : []),
+                flows: () => (cloud.policy.flows ? full.flows() : []),
+                derived: (kind) => (cloud.policy.memory ? full.derived(kind) : undefined),
+            },
+            sink: diskSink(root),
+            state: readCloudState(root),
+            now,
+            request,
+        });
+    };
+    /**
+     * Push every other linked root this machine knows about.
+     *
+     * Isolated per root on purpose. A revoked credential, a deleted directory or an unreachable
+     * self-hosted server in ONE repo is a fact about that repo; letting it throw would take the
+     * daemon's own push down with it and turn one broken link into a machine-wide outage.
+     */
+    const syncOtherRoots = async () => {
+        const roots = deps.otherRoots;
+        const cloudFor = deps.cloudFor;
+        if (roots === undefined || cloudFor === undefined)
+            return;
+        let list = [];
+        try {
+            list = await roots();
+        }
+        catch {
+            // Enumeration is best-effort: a registry that cannot be read must not stop this daemon
+            // syncing the root it is standing in.
+            return;
+        }
+        for (const root of list) {
+            if (root === deps.reticleRoot)
+                continue;
+            try {
+                const cloud = await cloudFor(root);
+                if (null === cloud.config)
+                    continue;
+                const report = await pushRoot(root, cloud);
+                if (report === undefined)
+                    continue;
+                if (report.error !== undefined) {
+                    log('reticle_cloud_sync_failed', { root, error: report.error });
+                    continue;
+                }
+                const moved = report.runsSent > 0 ||
+                    report.flowsSent > 0 ||
+                    report.derivedSent.length > 0 ||
+                    report.pulled > 0;
+                // 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)
+                    log('reticle_cloud_synced', { root, summary: describeSync(report) });
+            }
+            catch (error) {
+                log('reticle_cloud_sync_failed', {
+                    root,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
+    };
+    const cycle = async () => {
+        // 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)
+            return undefined;
+        running = true;
+        try {
+            const cloud = await deps.cloud();
+            const linked = null !== cloud.config;
+            if (linked !== wasLinked) {
+                wasLinked = linked;
+                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
+                    log('reticle_cloud_unlinked', {
+                        root: deps.reticleRoot,
+                        fix: 'run `reticle link` 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)
+                return undefined;
+            const report = await pushRoot(deps.reticleRoot, cloud);
+            // `pushRoot` returns undefined only for an unlinked root, which the guard above has ruled out.
+            if (report === undefined)
+                return undefined;
+            if (report.error !== undefined) {
+                if (report.error !== reportedError) {
+                    reportedError = report.error;
+                    log('reticle_cloud_sync_failed', { error: report.error });
+                }
+            }
+            else {
+                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 = report.runsSent > 0 ||
+                    report.flowsSent > 0 ||
+                    report.derivedSent.length > 0 ||
+                    report.pulled > 0;
+                if (moved)
+                    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;
+            }
+            return report;
+        }
+        catch (error) {
+            // Belt and braces: runSyncCycle already swallows, and a throw here would kill the timer.
+            const message = error instanceof Error ? error.message : String(error);
+            if (message !== reportedError) {
+                reportedError = message;
+                log('reticle_cloud_sync_failed', { error: message });
+            }
+            return undefined;
+        }
+        finally {
+            running = false;
+        }
+    };
+    /** The delay for the NEXT cycle: fast while the last one moved something, slow once it stops. */
+    let nextDelay = intervalMs;
+    const schedule = (delay) => {
+        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)
+            clearTimeout(timer);
+        timer = setTimeout(() => {
+            void cycle().finally(() => schedule(nextDelay));
+        }, delay);
+        // Unref'd: a pending sync must never be the reason a process refuses to exit.
+        timer.unref?.();
+    };
+    schedule(FIRST_CYCLE_DELAY_MS);
+    return {
+        syncNow: cycle,
+        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: () => {
+            stopped = true;
+            if (timer !== undefined)
+                clearTimeout(timer);
+            timer = undefined;
+        },
+    };
+}

package/dist/cloud/sync-disk.d.ts

@@ -0,0 +1,9 @@
+import type { CloudSyncState, PulledIssues, SyncSink, SyncSource } from './sync-cycle.js';
+/** What the cycle reads, backed by a real `.reticle` directory. */
+export declare function diskSource(reticleRoot: string): SyncSource;
+/** What the cycle writes back into `.reticle/`. */
+export declare function diskSink(reticleRoot: string): SyncSink;
+/** This machine's side of the conversation, or a blank one on first run. */
+export declare function readCloudState(reticleRoot: string): CloudSyncState;
+/** The decisions pulled back from the dashboard, for the HUD and for the next run to read. */
+export declare function readCloudIssues(reticleRoot: string): PulledIssues;