@reticlehq/server 2.14.0 → 3.2.0

package/dist/cloud/sync-cycle.js

@@ -1,270 +0,0 @@
-/**
- * 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.
- */
-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

@@ -1,53 +0,0 @@
-import { type SyncReport } from './sync-cycle.js';
-import type { ProjectCloud } from './cloud-config.js';
-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;
-    }>;
-}
-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;
-export {};

package/dist/cloud/sync-daemon.js

@@ -1,260 +0,0 @@
-/**
- * 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. */
-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.
- */
-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;
-        },
-    };
-}