/** First probe: warm-up + jitter so N machines never check together. */ export declare const FIRST_CHECK_DELAY_MS: number; export declare const FIRST_CHECK_JITTER_MS: number; /** Subsequent probes. */ export declare const CHECK_INTERVAL_MS: number; export declare const CHECK_INTERVAL_JITTER_MS: number; /** * While a newer version is KNOWN and we are merely waiting for the machine to * go quiet, come back far sooner than the 6-hourly cadence. * * The flat 6h cadence was a quiet way to strand the feature: an update could be * published at 09:00, the machine idle at 15:00, and the update would still wait * until 21:00 for no reason other than which side of a jittered timer the boot * landed on. A known-pending version has no discovery left to do, so retrying it * on a short cadence is strictly better. */ export declare const PENDING_RETRY_MS: number; /** * Where the pending-update record lives, so `auto-upgrade status` (a different * process) can report a blocked update instead of leaving the human to infer * "broken" from the absence of a version bump. */ export declare const PENDING_STATE_PATH: string; /** How often the busy/idle sampler runs while an upgrade is pending. */ export declare const SAMPLE_MS = 30000; /** The machine must have been continuously idle this long before dispatch. */ export declare const MIN_IDLE_MS: number; /** Never upgrade seconds after boot (a daemon restart is not "idle time"). */ export declare const MIN_UPTIME_MS: number; /** * Grace period after a wake lands, covering the gap before its session takes * the agent lock (hidden launch + node boot + settings fetch - seconds). After * that the lock/session checks take over. */ export declare const WAKE_QUIET_MS: number; /** Give up on this window and retry at the next scheduled check. */ export declare const IDLE_WAIT_TIMEOUT_MS: number; /** After a failed install, wait before trying again... */ export declare const FAILURE_BACKOFF_MS: number; /** ...and stop trying entirely after this many failures in one boot. */ export declare const MAX_FAILURES = 3; /** * Newer version we know exists but have not installed yet, or null. * * Kept on disk as well as in memory because the thing that most needs to read * it - `teamshare-bridge auto-upgrade status` - runs in a different process * from the daemon holding the scheduler. In-memory only would make the single * most useful diagnostic ("is an update waiting, and what is blocking it?") * unavailable exactly when a human goes looking for it. */ export interface PendingUpgrade { to: string; since: string; /** Why we are not installing it yet. Null once it is dispatching. */ reason: string | null; } export declare function pendingUpgrade(): PendingUpgrade | null; /** Read the pending record from disk (a different process than the daemon). */ export declare function readPendingUpgrade(path?: string): PendingUpgrade | null; export interface AutoUpgradeOptions { /** Daemon logger (writes to ~/.teamshare/daemon.log). */ log: (line: string) => void; /** Fresh opt-out check (`config.autoUpgrade === false` disables the loop). */ enabled: () => boolean; /** Reason the machine is busy, or null when completely idle. */ busyReason: () => string | null; /** Installed version (package.json of THIS install). */ version: string; /** Probe port the daemon bound; the restarted daemon reuses it. */ port: number; /** * Durable queued wakes, for the pending-update report only. * * A queue that cannot be reported is a queue that looks like a broken * feature: "waiting for idle" with no explanation reads identically to * "auto-upgrade is broken". */ describeQueue?: () => number; /** Graceful daemon exit, called once the helper has been dispatched. */ shutdown: () => void; /** Best-effort hub report (diagnostics). Resolves when delivered/queued. */ report: (severity: 'warning' | 'error', message: string, context?: Record) => Promise; } /** Verdict for one idle sample - exported so the gates are unit-testable. */ export declare function idleVerdict(input: { busyReason: string | null; lastBusyAt: number; now: number; bootAt: number; }): { ready: boolean; why: string; }; /** One agent's upgrade-relevant state, as the daemon can observe it. */ export interface AgentActivity { agentId: string; /** Holds a session lock (a run is mid-flight). */ lockBusy: boolean; /** A live console/session stream is attached. */ liveSession: boolean; /** ISO timestamp of the most recent wake for this agent, if any. */ lastWakeAt?: string | null; /** * Durable queued wakes. DELIBERATELY NOT PART OF THE VERDICT - see below. * Accepted so callers can pass a whole activity snapshot and so a regression * has to delete the field to reintroduce the bug. */ queuedWakes?: number; /** Injectable clock (tests). */ now?: number; } /** * Why an upgrade must WAIT for this agent, or null when it may proceed. * * ── WHY QUEUED WORK IS NOT A BLOCKER ────────────────────────────────────── * This used to treat a non-empty wake outbox as busy. The outbox is a DURABLE * on-disk queue (`wake-outbox.ts` writes with an atomic writeFileSync + * renameSync), so a wake parked waiting for a busy folder survives the very * process exit an upgrade performs and is re-read on the next boot. Blocking on * it protected nothing. * * It cost everything. Because such a wake can sit parked indefinitely (waiting * on another agent's folder lock), the gate could never open: on any machine * with a backlog, auto-upgrade silently never fired. It waited 60 min, gave up, * and slept another 6 h - forever, with a single daemon.log line as evidence. * The feature was indistinguishable from being switched off. * * A restart destroys a LIVE SESSION (its transcript streams from memory and * the child process dies with us), so sessions and held locks still block. A * queued wake has nothing to lose. * * Pure and exported on purpose: this is the single decision the whole fix * rests on, and a closure inside the daemon could only ever be tested by * inference. */ export declare function upgradeBlockingReason(activity: AgentActivity, now?: number): string | null; /** * Starts the periodic check. Returns a stop function (the daemon clears it * on shutdown). Idempotent per call - one scheduler per daemon process. */ export declare function startAutoUpgrade(opts: AutoUpgradeOptions): () => void;