/**
 * Background sync for tracked git repos:
 *   - System repo (~/.agents/.system/) is read-only locally — fast-forward auto-pull is safe.
 *   - User repo (~/.agents/) and enabled extras may have local commits, so we only
 *     `git fetch` and write a status marker. `agents doctor` surfaces these markers
 *     as a "Repo updates" section instead of printing to stderr on every command.
 *     Pulling is left to the user via `agents repo pull`.
 *
 * Public API:
 *   spawnDetachedSync()      — fire-and-forget; never blocks the foreground command.
 *   readRepoBehindMarkers()  — synchronous; reads markers without consuming them.
 *   shouldSkipDetachedSync() — parent-side recency gate (RUSH-2324).
 *   markDetachedSyncComplete() — worker stamps a completed cycle for the parent gate.
 */
/**
 * Shared 5-minute recency window for per-repo locks (worker) and the parent
 * spawn gate (RUSH-2324). Worker skips a repo when its lock mtime is younger
 * than this; the parent skips the entire detached spawn when a recent cycle
 * completed or every existing lock is still within the window.
 */
export declare const SYNC_LOCK_TTL_MS: number;
/** Per-repo lock file path. mtime acts as a recency check. */
export declare function lockFilePath(alias: string, fetchDir?: string): string;
/** Per-repo status marker path (for user/extras only). */
export declare function statusFilePath(alias: string, fetchDir?: string): string;
/**
 * Stamp written at the end of every detached-worker cycle (including the
 * no-target / all-locks-skipped path). Parent `spawnDetachedSync` stats this
 * one file instead of forking a child on every ordinary CLI invocation.
 */
export declare function lastSyncStampPath(fetchDir?: string): string;
export interface FetchStatusMarker {
    alias: string;
    dir: string;
    ahead: number;
    behind: number;
    branch: string;
    fetchedAt: number;
}
/**
 * Whether the parent should skip forking the detached auto-pull worker.
 *
 * True when either:
 *   1. `.last-sync` exists and its mtime is within {@link SYNC_LOCK_TTL_MS}
 *      (a prior cycle completed recently — the common warm path), or
 *   2. the fetch dir has at least one `*.lock` and every lock is still within
 *      the same window (a worker is mid-flight, or a cycle left locks that
 *      still count as fresh).
 *
 * False (spawn) when the stamp is missing/stale and there are no fresh locks
 * — including a missing fetch dir and an empty one. Cheap: one `stat` or one
 * `readdir` + a few `stat`s; never spawns and never reads git.
 *
 * @param fetchDir - Override the fetch state dir (for tests). Defaults to the
 *   production getFetchCacheDir() path.
 * @param now - Override the clock (for tests).
 * @param ttlMs - Override the recency window (for tests).
 */
export declare function shouldSkipDetachedSync(fetchDir?: string, now?: number, ttlMs?: number): boolean;
/**
 * Record that a detached-worker cycle finished (success, empty targets, or
 * every repo skipped by its lock). Best-effort; a failed write just means the
 * next foreground invocation will re-spawn the worker.
 */
export declare function markDetachedSyncComplete(fetchDir?: string): void;
/** Spawn the detached worker. No-op when AGENTS_NO_AUTOPULL=1 is set. */
export declare function spawnDetachedSync(fetchDir?: string): void;
/**
 * Read all current status markers and return those where the local repo is
 * behind upstream. Markers are NOT deleted — they persist until the next
 * background fetch overwrites them with fresh data.
 *
 * Synchronous, cheap (small JSON files). Used by `agents doctor` to surface
 * repo-behind warnings in one place instead of printing to stderr on every
 * command.
 *
 * @param fetchDir - Override the fetch state dir (for tests). Defaults to the
 *   production getFetchCacheDir() path.
 */
export declare function readRepoBehindMarkers(fetchDir?: string): FetchStatusMarker[];
