@repo-os/repoos 0.5.45

package/dist/server/reload.d.ts

@@ -0,0 +1,194 @@
+/** The answer POST /api/server/restart and the reload triggers report. */
+export type ReloadState = {
+    state: "reloading";
+    reason?: string;
+} | {
+    state: "deferred";
+    running: number;
+    reason?: string;
+} | {
+    state: "not-stale";
+    reason?: string;
+};
+export interface ReloadManagerOptions {
+    /** Repo root the serve process is rooted at (the replacement is spawned here). */
+    root: string;
+    host: string;
+    port: number;
+    /** Build hash captured at boot — the hash of the code this process runs. */
+    loadedHash: string | null;
+    /** False when auto-reload is impossible (dev mode, preview child, ephemeral port). */
+    enabled?: boolean;
+    /** True when this process is itself a reload replacement (skip boot self-heal). */
+    isReplacement?: boolean;
+    /** Count of running agent turns — a reload is deferred while > 0. */
+    isBusy: () => number;
+    /**
+     * True while a review→done close-out is running (0143). The close-out
+     * pipeline builds/checks dist itself, so an auto-reload must never fire
+     * under it. New builds it produces are parked (`build.available`) for a
+     * user-triggered reload instead.
+     */
+    closingOut: () => boolean;
+    /**
+     * Fired once when a new build lands on disk while a close-out holds the
+     * deferral — the build is parked for a user-triggered reload (via
+     * POST /api/server/restart) rather than applied automatically. Receives the
+     * on-disk build hash.
+     */
+    onBuildAvailable?: (hash: string) => void;
+    /** Resolve the compiled CLI entrypoint used to spawn the replacement. */
+    cliEntry: () => string | null;
+    /** Release only the HTTP listener (the drain window); the process keeps running. */
+    stopListening: () => Promise<void>;
+    /** Re-bind the HTTP listener after an aborted reload. */
+    listen: () => Promise<void>;
+    /** The replacement is confirmed ready: tear down and exit this process. */
+    onReloadConfirmed: () => Promise<void>;
+    /** A reload failed and the old process kept serving. */
+    onReloadFailed?: (reason: string) => void;
+    /** Low-frequency hash poll interval in ms (fallback when fs.watch is unreliable). */
+    pollMs?: number;
+    /** How often a deferred reload is retried while the runner stays busy, in ms. */
+    retryMs?: number;
+    /** Grace before releasing the listener (gives SO_REUSEPORT a chance), in ms. */
+    graceMs?: number;
+    /** Total time to wait for the replacement's readiness handshake, in ms. */
+    handshakeTimeoutMs?: number;
+    /**
+     * How long the replacement must stay healthy (handshake answered) before the
+     * old process logs "replacement is up" and releases its listener. Guards the
+     * #0096 incident shape: a replacement that answered once, was confirmed, then
+     * died right after the old process exited, leaving the port listenerless.
+     */
+    confirmMs?: number;
+    /** How long the old process re-binds its listener before giving up, in ms. */
+    rebindTimeoutMs?: number;
+    log?: (msg: string) => void;
+}
+/** True when running from src/ (dev mode) rather than compiled dist/. */
+export declare function isDevBuild(): boolean;
+/** Read the build hash from dist/.build-info.json, or null when absent. */
+export declare function readBuildHash(root: string): string | null;
+/**
+ * Read the build timestamp from dist/.build-stamp.json, or null. Kept separate
+ * from the hash marker so `.build-info.json` stays byte-identical across
+ * rebuilds of identical source — see readBuildStamp in core/build.ts.
+ */
+export declare function readBuildAt(root: string): string | null;
+export declare class ReloadManager {
+    private readonly options;
+    private readonly loadedHash;
+    private fsWatcher;
+    private debounceTimer;
+    private pollTimer;
+    private retryTimer;
+    private reloading;
+    private pending;
+    private stopped;
+    private child;
+    private childExited;
+    /** Whether we released our own HTTP listener for the replacement to bind. */
+    private drained;
+    /** Consecutive failed handoffs. Reset on the next successful one. */
+    private consecutiveFailures;
+    /** Automatic (non-manual) reloads are refused until this time, post-failure. */
+    private backoffUntil;
+    /**
+     * Hash of a build parked by a close-out (0143). Never auto-reloaded — it
+     * waits for the user to trigger POST /api/server/restart.
+     */
+    private buildAvailableHash;
+    /** On-disk build timestamp of the parked build (dist/.build-info.json). */
+    private buildAvailableAt;
+    constructor(options: ReloadManagerOptions);
+    get enabled(): boolean;
+    /** True while the manager is actively handing over to a replacement process. */
+    get isReloading(): boolean;
+    /**
+     * The build parked by a close-out (0143), if any — hash plus its on-disk
+     * build timestamp (dist/.build-info.json generatedAt). Exposed so /api/health
+     * can report it and a (re)connecting UI can surface the "new build available"
+     * notice without ever having seen the one-shot build.available SSE event.
+     * Null while nothing is parked.
+     */
+    get buildAvailable(): {
+        hash: string;
+        buildAt: string | null;
+    } | null;
+    /** Begin watching dist/.build-info.json (fs.watch + fallback hash poll). */
+    start(): void;
+    /** Stop watching and cancel timers. Idempotent. */
+    stop(): void;
+    /**
+     * Stale-boot self-heal: if a newer build landed while we were starting,
+     * reload immediately (deferred while an agent runs). The replacement child
+     * (REPOOS_RELOAD=1) skips this — it boots fresh on the current build.
+     */
+    bootSelfHeal(): void;
+    /**
+     * Public trigger used by the watcher, the boot self-heal, and
+     * POST /api/server/restart. Fires the reload when stale and idle; defers
+     * while an agent turn runs; reports not-stale when nothing is out of date.
+     *
+     * `manual` (POST /api/server/restart, a human explicitly asking) bypasses
+     * the post-failure backoff below — automatic triggers (the poll, boot
+     * self-heal) respect it so a run of failed handoffs doesn't retry every
+     * ~5s forever (#0271 incident).
+     */
+    requestReload(reason: string, opts?: {
+        manual?: boolean;
+    }): ReloadState;
+    /**
+     * The SSE event funnel calls this so a drained runner unblocks a deferred
+     * reload. `review` events count: an agent review is a spawned turn too, and
+     * one finishing can be what makes the server idle.
+     */
+    onEvent(e: {
+        type: string;
+    }): void;
+    private onPoll;
+    private tryFirePending;
+    /**
+     * Park a build that landed during a close-out: it is served only once the
+     * user triggers a reload. Idempotent per hash. Supersedes any armed
+     * busy-deferral so an eventual drain does not auto-fire it.
+     */
+    private parkBuild;
+    private startWatching;
+    private reload;
+    /**
+     * Poll /api/health for the replacement's handshake until it answers or the
+     * window closes. While the parent holds the port the replacement cannot bind
+     * (no SO_REUSEPORT sharing on this platform), so after a short grace we
+     * release our own listener — the drain window — and keep polling. Any answer
+     * from the parent itself has no handshake, so a spurious self-poll never
+     * confirms a replacement.
+     *
+     * A single handshake answer is NOT enough (#0096): the replacement must stay
+     * healthy for the confirm window so a briefly-up-then-dying replacement is
+     * treated as a failed reload — the parent re-binds and keeps serving rather
+     * than handing over to a process that will leave the port listenerless.
+     */
+    private waitForReplacement;
+    private killChild;
+    /**
+     * Re-bind the listener after an aborted reload so the old process keeps
+     * serving. Returns `"bound"` when the listener is back, or a reason string
+     * describing why it could not be recovered.
+     *
+     * #0284: a bind attempt by an unrelated `repoos serve` landing in our drain
+     * window can steal the port out from under us — we released the listener in
+     * waitForReplacement, it grabbed it, and now we can never re-bind (each
+     * attempt EADDRINUSEs). Distinguishing that from a transient failure lets
+     * the old process surface a loud, actionable error instead of silently
+     * looping as a listenerless zombie. We probe the port once the retry window
+     * closes: if *something else* is listening there now, the port was stolen
+     * rather than merely not-yet-freed.
+     */
+    private tryRebind;
+    private armRetry;
+    private clearRetry;
+    private clearTimers;
+    private log;
+}