@indigoai-us/hq-cli 5.345.168 → 5.345.169

package/dist/lib/doctor/fix/refresh-sync-handoff.js

@@ -0,0 +1,752 @@
+/**
+ * Supervised `hq doctor --fix` journal pulls (feedback cd56a501).
+ *
+ * A pull records `lastSync` only when its whole pass finishes. `--fix` used to
+ * kill its pull at 90s, so a large vault never refreshed its journal and the
+ * client-health hook reported it every day.
+ *
+ * Every `--fix` pull now runs under a small supervisor process. The
+ * supervisor writes a heartbeat while the pull runs, the pull's pid, and an
+ * exit file with the pull's real status when it ends. It stops the pull at
+ * {@link REFRESH_BACKGROUND_MAX_MS}. If the pull is still running at the
+ * foreground deadline, `--fix` leaves the supervisor running.
+ *
+ * One pull per HQ root. A run claims the root before it spawns
+ * ({@link claimRefreshRun}): holding an O_EXCL spawn lock, it checks that no
+ * other pull occupies the root and creates the pull's record exclusively. A
+ * second `--fix` started at the same moment either cannot get the lock or
+ * sees that record, and does not spawn.
+ *
+ * State lives in one file per company under
+ * `workspace/doctor/refresh-in-progress/`, and each run's output, heartbeat,
+ * pid and exit files are named by a per-run id.
+ *
+ * The next `--fix` harvests finished runs first: it reads the exit file and
+ * the log tail, reports the real outcome, and removes the record. A pull whose
+ * supervisor died is still alive while its process group is, until the cap.
+ * Past the cap the next run removes it as capped, and kills it only when the
+ * caller's identity check proves the pid is still that pull.
+ */
+import * as crypto from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+const STATE_DIR = path.join("workspace", "doctor", "refresh-in-progress");
+const RUNS_DIR = path.join("workspace", "doctor", "refresh-runs");
+const SPAWN_LOCK = path.join("workspace", "doctor", "refresh-spawn.lock");
+/** The supervisor stops a background pull after this long. */
+export const REFRESH_BACKGROUND_MAX_MS = 10 * 60 * 1000;
+/** The supervisor refreshes its heartbeat this often. */
+export const REFRESH_HEARTBEAT_INTERVAL_MS = 10_000;
+/** A heartbeat older than this means the supervisor is gone. */
+export const REFRESH_HEARTBEAT_STALE_MS = 60_000;
+/** After SIGTERM, the supervisor waits this long before SIGKILL of the pull's process group. */
+export const REFRESH_KILL_GRACE_MS = 5_000;
+/**
+ * A record older than this is over the cap whatever its heartbeat says. The
+ * supervisor stops the pull at {@link REFRESH_BACKGROUND_MAX_MS} and kills it
+ * {@link REFRESH_KILL_GRACE_MS} later; this adds a heartbeat interval of slack.
+ */
+export const REFRESH_RECORD_MAX_AGE_MS = REFRESH_BACKGROUND_MAX_MS + REFRESH_KILL_GRACE_MS + 15_000;
+export function safeRefreshSlug(slug) {
+    return slug.replace(/[^A-Za-z0-9._-]/g, "_").slice(0, 120) || "_";
+}
+/** Fresh per-run file names under workspace/doctor/refresh-runs/. */
+export function newRefreshRunPaths(hqRoot, slug) {
+    const id = `${safeRefreshSlug(slug)}.${Date.now()}.${crypto.randomBytes(4).toString("hex")}`;
+    return runPaths(hqRoot, id);
+}
+function runPaths(hqRoot, id) {
+    const dir = path.join(hqRoot, RUNS_DIR);
+    return {
+        id,
+        log: path.join(dir, `${id}.log`),
+        exit: path.join(dir, `${id}.exit`),
+        heartbeat: path.join(dir, `${id}.hb`),
+        pid: path.join(dir, `${id}.pid`),
+        start: path.join(dir, `${id}.start`),
+        cancel: path.join(dir, `${id}.cancel`),
+    };
+}
+function recordPath(hqRoot, slug) {
+    return path.join(hqRoot, STATE_DIR, `${safeRefreshSlug(slug)}.json`);
+}
+function recordJson(slug, run, nowMs, token) {
+    const record = {
+        version: 1,
+        slug,
+        id: run.id,
+        startedAtMs: nowMs,
+        ownerPid: process.pid,
+        token,
+    };
+    return JSON.stringify(record);
+}
+/** Write (or replace) the record for a pull of `slug`. Tests and recovery only; claims use {@link claimRefreshRun}. */
+export function recordRefreshHandoff(hqRoot, slug, run, nowMs) {
+    const file = recordPath(hqRoot, slug);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const tmp = `${file}.${crypto.randomBytes(6).toString("hex")}.tmp`;
+    fs.writeFileSync(tmp, recordJson(slug, run, nowMs, crypto.randomBytes(8).toString("hex")), { mode: 0o600 });
+    fs.renameSync(tmp, file);
+}
+/**
+ * Create the record for `slug` only if none exists: the content is written to
+ * a temp file and hard-linked into place, which fails if the name is taken,
+ * so a reader never sees a partial record and an existing one is never
+ * overwritten. Returns false when a record already exists.
+ */
+function createRecordExclusive(hqRoot, slug, run, nowMs, token) {
+    const file = recordPath(hqRoot, slug);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const tmp = `${file}.${crypto.randomBytes(6).toString("hex")}.tmp`;
+    const json = recordJson(slug, run, nowMs, token);
+    fs.writeFileSync(tmp, json, { mode: 0o600, flag: "wx" });
+    try {
+        fs.linkSync(tmp, file);
+        return true;
+    }
+    catch (error) {
+        if (error.code === "EEXIST")
+            return false;
+        // Hard links are not available on every filesystem (exFAT, FAT, some
+        // network drives: EPERM, ENOTSUP, EXDEV, ...). Fall back to an exclusive
+        // create of the record itself: still never an overwrite. A reader can
+        // briefly see it half-written; harvest leaves young unreadable records
+        // alone (see UNREADABLE_RECORD_SETTLE_MS).
+    }
+    finally {
+        fs.rmSync(tmp, { force: true });
+    }
+    try {
+        fs.writeFileSync(file, json, { mode: 0o600, flag: "wx" });
+        return true;
+    }
+    catch (error) {
+        if (error.code === "EEXIST")
+            return false;
+        throw error;
+    }
+}
+/**
+ * An unreadable record younger than this may still be mid-write (the
+ * exclusive-create fallback), so harvest does not delete it yet.
+ */
+export const UNREADABLE_RECORD_SETTLE_MS = 10_000;
+/** Remove the record for `slug` if it still names `run`. */
+export function clearRefreshRecord(hqRoot, slug, run) {
+    const file = recordPath(hqRoot, slug);
+    const record = readRecord(file);
+    if (record && record.id === run.id)
+        fs.rmSync(file, { force: true });
+}
+function readRecord(file) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+        if (parsed?.version === 1 &&
+            typeof parsed.slug === "string" &&
+            typeof parsed.id === "string" &&
+            /^[A-Za-z0-9._-]+$/.test(parsed.id) &&
+            typeof parsed.startedAtMs === "number" &&
+            (parsed.ownerPid === undefined || (typeof parsed.ownerPid === "number" && Number.isInteger(parsed.ownerPid))) &&
+            (parsed.token === undefined || typeof parsed.token === "string")) {
+            return parsed;
+        }
+    }
+    catch {
+        // unreadable
+    }
+    return null;
+}
+/** Read a supervisor exit file, or null if the run has not ended. */
+export function readRefreshRunExit(run) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(run.exit, "utf8"));
+        return {
+            status: typeof parsed.status === "number" ? parsed.status : null,
+            signal: typeof parsed.signal === "string" ? parsed.signal : null,
+            ...(parsed.preempted === true ? { preempted: true } : {}),
+            ...(parsed.capped === true ? { capped: true } : {}),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/** Last 64 KiB of a run's output: enough to classify, bounded in memory. */
+export function readRefreshRunLog(run) {
+    try {
+        const size = fs.statSync(run.log).size;
+        const length = Math.min(size, 64 * 1024);
+        const buffer = Buffer.alloc(length);
+        const fd = fs.openSync(run.log, "r");
+        try {
+            fs.readSync(fd, buffer, 0, length, size - length);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+        return buffer.toString("utf8");
+    }
+    catch {
+        return "";
+    }
+}
+function readHeartbeat(run) {
+    try {
+        return fs.readFileSync(run.heartbeat, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+function heartbeatFresh(run, nowMs) {
+    const text = readHeartbeat(run);
+    if (text === null)
+        return false;
+    const beat = Number(text);
+    return Number.isFinite(beat) && nowMs - beat <= REFRESH_HEARTBEAT_STALE_MS && beat <= nowMs + 60_000;
+}
+/**
+ * True while a capped run is still inside its kill grace period: the
+ * supervisor has stopped heartbeating but has not written its exit file yet.
+ */
+function cappedAndStopping(run, nowMs) {
+    const text = readHeartbeat(run);
+    if (!text?.startsWith("capped:"))
+        return false;
+    const at = Number(text.slice("capped:".length));
+    return Number.isFinite(at) && nowMs - at <= REFRESH_KILL_GRACE_MS + 10_000;
+}
+function readPullPid(run) {
+    try {
+        const pid = Number(fs.readFileSync(run.pid, "utf8"));
+        return Number.isInteger(pid) && pid > 0 ? pid : null;
+    }
+    catch {
+        return null;
+    }
+}
+function processExists(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
+/**
+ * True when the pull of a run whose supervisor died is still running. On POSIX
+ * the pull leads its own process group, so the group is probed; elsewhere the
+ * pid. Only called within the record's age cap, which bounds pid reuse.
+ */
+function orphanPullAlive(run) {
+    const pid = readPullPid(run);
+    if (pid === null)
+        return false;
+    return process.platform === "win32" ? processExists(pid) : processExists(-pid);
+}
+/** An orphan is only ever killed within this long of its record. */
+export const REFRESH_ORPHAN_KILL_WINDOW_MS = REFRESH_RECORD_MAX_AGE_MS + 5 * 60 * 1000;
+function orphanOf(run, record) {
+    const pid = readPullPid(run);
+    if (pid === null)
+        return null;
+    let recordedStart = null;
+    try {
+        recordedStart = fs.readFileSync(run.start, "utf8").trim() || null;
+    }
+    catch {
+        recordedStart = null;
+    }
+    return { pid, recordedStart, recordStartedAtMs: record.startedAtMs };
+}
+/** Delete a run's files. */
+export function removeRefreshRun(run) {
+    for (const file of [run.log, run.exit, run.heartbeat, run.pid, run.start, run.cancel]) {
+        try {
+            fs.rmSync(file, { force: true });
+        }
+        catch {
+            // ignore
+        }
+    }
+}
+function listRecords(hqRoot) {
+    const dir = path.join(hqRoot, STATE_DIR);
+    let names;
+    try {
+        names = fs.readdirSync(dir).filter((name) => name.endsWith(".json"));
+    }
+    catch {
+        return [];
+    }
+    return names.map((name) => {
+        const file = path.join(dir, name);
+        return { file, record: readRecord(file) };
+    });
+}
+/**
+ * Admission occupancy of one recorded run: true while its pull may still be
+ * running, including a capped run inside its stop and kill grace window. A
+ * new pull is never admitted while this is true.
+ */
+function recordOccupiesRoot(hqRoot, record, nowMs) {
+    if (recordAlive(hqRoot, record, nowMs))
+        return true;
+    if (nowMs - record.startedAtMs > REFRESH_RECORD_MAX_AGE_MS)
+        return false;
+    const run = runPaths(hqRoot, record.id);
+    return !readRefreshRunExit(run) && cappedAndStopping(run, nowMs);
+}
+/**
+ * In-progress status of one recorded run (what the journal check shows). A
+ * capped run is not in progress, even while it is being stopped.
+ */
+function recordAlive(hqRoot, record, nowMs) {
+    const age = nowMs - record.startedAtMs;
+    if (age > REFRESH_RECORD_MAX_AGE_MS)
+        return false;
+    const run = runPaths(hqRoot, record.id);
+    if (readRefreshRunExit(run))
+        return false;
+    if (heartbeatFresh(run, nowMs))
+        return true;
+    const beat = readHeartbeat(run);
+    // Claimed but the supervisor has not written its first heartbeat yet: the
+    // claiming process owns it while that process is alive.
+    if (beat === null && typeof record.ownerPid === "number" && record.ownerPid > 0 && processExists(record.ownerPid)) {
+        return true;
+    }
+    if (beat?.startsWith("capped:"))
+        return false;
+    // The supervisor is gone; the pull itself may still be running.
+    return orphanPullAlive(run);
+}
+/**
+ * Remove every run that is no longer alive and return what each one ended
+ * with. `exit` is null when the supervisor died without writing one. A run
+ * over the cap is reported as capped, and an orphaned pull still running past
+ * the cap is killed. Live runs are left in place. Unreadable records are
+ * deleted.
+ */
+export function harvestRefreshHandoffs(hqRoot, nowMs, killOrphan) {
+    const harvested = [];
+    for (const { file, record } of listRecords(hqRoot)) {
+        if (!record) {
+            let young = false;
+            try {
+                young = nowMs - fs.statSync(file).mtimeMs < UNREADABLE_RECORD_SETTLE_MS;
+            }
+            catch {
+                young = false;
+            }
+            if (!young)
+                fs.rmSync(file, { force: true });
+            continue;
+        }
+        const run = runPaths(hqRoot, record.id);
+        const exit = readRefreshRunExit(run);
+        const overCap = nowMs - record.startedAtMs > REFRESH_RECORD_MAX_AGE_MS;
+        if (!exit && !overCap && recordAlive(hqRoot, record, nowMs))
+            continue;
+        // Capped and being killed: wait for its exit file rather than guess.
+        if (!exit && !overCap && cappedAndStopping(run, nowMs))
+            continue;
+        if (!exit && overCap && killOrphan && nowMs - record.startedAtMs <= REFRESH_ORPHAN_KILL_WINDOW_MS) {
+            const orphan = orphanOf(run, record);
+            if (orphan) {
+                try {
+                    killOrphan(orphan, nowMs);
+                }
+                catch {
+                    // never let a kill attempt break harvest
+                }
+            }
+        }
+        harvested.push({
+            slug: record.slug,
+            exit: exit ?? (overCap ? { status: null, signal: null, capped: true } : null),
+            output: readRefreshRunLog(run),
+        });
+        fs.rmSync(file, { force: true });
+        removeRefreshRun(run);
+    }
+    return harvested;
+}
+/** Start time of the live pull for `slug`, or null. */
+export function refreshHandoffStartedAt(hqRoot, slug, nowMs) {
+    const record = readRecord(recordPath(hqRoot, slug));
+    if (!record || record.slug !== slug)
+        return null;
+    return recordAlive(hqRoot, record, nowMs) ? record.startedAtMs : null;
+}
+/**
+ * True when any `--fix` pull for this HQ root still occupies it: running,
+ * starting, orphaned, or capped and still inside its stop grace window.
+ */
+export function anyRefreshHandoffAlive(hqRoot, nowMs) {
+    return listRecords(hqRoot).some(({ record }) => record !== null && recordOccupiesRoot(hqRoot, record, nowMs));
+}
+function parseSpawnLock(text) {
+    try {
+        const parsed = JSON.parse(text);
+        if (typeof parsed.pid === "number" && Number.isInteger(parsed.pid) && parsed.pid > 0) {
+            return { pid: parsed.pid, start: typeof parsed.start === "string" && parsed.start ? parsed.start : null };
+        }
+        return null;
+    }
+    catch {
+        // Older "<pid>:<ms>:<hex>" form: pid only, no start time.
+        const pid = Number(text.split(":")[0]);
+        return Number.isInteger(pid) && pid > 0 ? { pid, start: null } : null;
+    }
+}
+export function acquireRefreshSpawnLock(hqRoot, nowMs, identity) {
+    const file = path.join(hqRoot, SPAWN_LOCK);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    let selfStart = null;
+    try {
+        selfStart = identity?.selfStart() ?? null;
+    }
+    catch {
+        selfStart = null;
+    }
+    const token = JSON.stringify({
+        pid: process.pid,
+        start: selfStart,
+        token: crypto.randomBytes(8).toString("hex"),
+        at: nowMs,
+    });
+    for (let attempt = 0; attempt < 2; attempt++) {
+        try {
+            fs.writeFileSync(file, token, { flag: "wx", mode: 0o600 });
+            const stillHeld = () => {
+                try {
+                    return fs.readFileSync(file, "utf8") === token;
+                }
+                catch {
+                    return false;
+                }
+            };
+            const release = (() => {
+                if (stillHeld())
+                    fs.rmSync(file, { force: true });
+            });
+            release.stillHeld = stillHeld;
+            return release;
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                return null;
+        }
+        let text = "";
+        try {
+            text = fs.readFileSync(file, "utf8");
+        }
+        catch {
+            continue;
+        }
+        const holder = parseSpawnLock(text);
+        if (!holder || !ownerProvenGone(holder, identity))
+            return null;
+        // Take it over atomically: only the process whose rename succeeds removes
+        // it. If the renamed file is not the holder we judged (a new holder raced
+        // in), put it back and give up.
+        const aside = `${file}.stale-${crypto.randomBytes(6).toString("hex")}`;
+        try {
+            fs.renameSync(file, aside);
+        }
+        catch {
+            return null;
+        }
+        let moved = "";
+        try {
+            moved = fs.readFileSync(aside, "utf8");
+        }
+        catch {
+            moved = "";
+        }
+        if (moved !== text) {
+            try {
+                fs.linkSync(aside, file);
+            }
+            catch {
+                // someone already holds it again
+            }
+            fs.rmSync(aside, { force: true });
+            return null;
+        }
+        fs.rmSync(aside, { force: true });
+    }
+    return null;
+}
+/** A spawn lock still held after this long is reported by `hq doctor`. */
+export const REFRESH_SPAWN_LOCK_WARN_MS = 10 * 60 * 1000;
+/**
+ * The current spawn lock holder and how long it has held the lock, or null
+ * when no lock is held. Read-only: never removes or changes the lock.
+ */
+export function inspectRefreshSpawnLock(hqRoot, nowMs, identity) {
+    let text;
+    try {
+        text = fs.readFileSync(path.join(hqRoot, SPAWN_LOCK), "utf8");
+    }
+    catch {
+        return null;
+    }
+    const holder = parseSpawnLock(text);
+    if (!holder)
+        return null;
+    let at = null;
+    try {
+        const parsed = JSON.parse(text);
+        if (typeof parsed.at === "number")
+            at = parsed.at;
+    }
+    catch {
+        const legacy = Number(text.split(":")[1]);
+        if (Number.isFinite(legacy))
+            at = legacy;
+    }
+    return {
+        pid: holder.pid,
+        heldMs: at === null ? null : Math.max(0, nowMs - at),
+        ownerGone: ownerProvenGone(holder, identity),
+    };
+}
+/**
+ * Release a spawn lock whose owner is proven gone (pid dead, or start time
+ * changed). A live or unverifiable owner's lock is left alone. Uses the same
+ * atomic takeover as a claim, then releases at once.
+ */
+export function releaseDeadRefreshSpawnLock(hqRoot, nowMs, identity) {
+    const lock = inspectRefreshSpawnLock(hqRoot, nowMs, identity);
+    if (!lock?.ownerGone)
+        return;
+    try {
+        acquireRefreshSpawnLock(hqRoot, nowMs, identity)?.();
+    }
+    catch {
+        // best effort
+    }
+}
+/** True only when identity proves the lock's owner no longer runs. */
+function ownerProvenGone(holder, identity) {
+    if (!processExists(holder.pid))
+        return true;
+    if (!identity || !holder.start)
+        return false;
+    let current;
+    try {
+        current = identity.startOf(holder.pid);
+    }
+    catch {
+        current = null;
+    }
+    return current !== null && current !== holder.start;
+}
+/**
+ * Claim this HQ root for a pull of `slug`; true means spawn.
+ *
+ * - The spawn lock is required. If another live or unverifiable process holds
+ *   it, nothing is written and the claim fails.
+ * - Under the lock: no other pull may occupy the root, and the record is
+ *   created exclusively, never overwritten. An existing record for `slug`
+ *   wins unless it no longer occupies the root (its pull exited, or its
+ *   owner and pull are proven gone); then it is moved aside atomically and
+ *   the create is retried once.
+ * - The claim holds only if, after writing, the record still carries this
+ *   claim's token and this process still holds the lock.
+ */
+export function claimRefreshRun(hqRoot, slug, run, nowMs, identity) {
+    const release = acquireRefreshSpawnLock(hqRoot, nowMs, identity);
+    if (!release)
+        return false;
+    const token = crypto.randomBytes(8).toString("hex");
+    let created = false;
+    try {
+        if (anyRefreshHandoffAlive(hqRoot, nowMs))
+            return false;
+        created = createRecordExclusive(hqRoot, slug, run, nowMs, token);
+        if (!created) {
+            const file = recordPath(hqRoot, slug);
+            const existing = readRecord(file);
+            if (existing && recordOccupiesRoot(hqRoot, existing, nowMs))
+                return false;
+            const aside = `${file}.dead-${crypto.randomBytes(6).toString("hex")}`;
+            try {
+                fs.renameSync(file, aside);
+            }
+            catch {
+                return false;
+            }
+            const moved = readRecord(aside);
+            const sameAsJudged = moved?.id === existing?.id && moved?.token === existing?.token;
+            if (!sameAsJudged) {
+                // Not the record we judged dead: put it back if the name is free.
+                try {
+                    fs.linkSync(aside, file);
+                }
+                catch {
+                    // a new record already took the name
+                }
+                fs.rmSync(aside, { force: true });
+                return false;
+            }
+            fs.rmSync(aside, { force: true });
+            if (existing)
+                removeRefreshRun(runPaths(hqRoot, existing.id));
+            created = createRecordExclusive(hqRoot, slug, run, nowMs, token);
+            if (!created)
+                return false;
+        }
+        const mine = readRecord(recordPath(hqRoot, slug));
+        if (!mine || mine.id !== run.id || mine.token !== token || !release.stillHeld()) {
+            if (mine && mine.id === run.id && mine.token === token)
+                clearRefreshRecord(hqRoot, slug, run);
+            return false;
+        }
+        return true;
+    }
+    catch {
+        if (created)
+            clearRefreshRecord(hqRoot, slug, run);
+        return false;
+    }
+    finally {
+        release();
+    }
+}
+/** How often the supervisor looks for another operation waiting on the lock. */
+export const REFRESH_PREEMPT_POLL_MS = 500;
+/**
+ * Supervisor program, run as
+ * `node -e SUPERVISOR log exit heartbeat pidFile cancel locksDir maxMs cmd ...args`.
+ *
+ * It appends the pull's output to `log`, writes the pull's pid to `pidFile`,
+ * refreshes `heartbeat`, and writes `{status, signal, preempted, capped}` to
+ * `exit` when the pull ends.
+ *
+ * Stopping: at `maxMs`, when `cancel` exists, or when another live process
+ * publishes a waiter for the operation lock the pull holds
+ * (`<lock>.wait-<pid>-*`; `sync` holds the lock shared, so only exclusive
+ * callers such as rescue and repairs wait), the supervisor stops the pull.
+ * On POSIX it sends SIGTERM to the pull's process group, and SIGKILL to the
+ * group after {@link REFRESH_KILL_GRACE_MS} in every case, so a grandchild
+ * cannot outlive it. SIGTERM is the same stop as Ctrl-C on `hq sync`: the
+ * lock's signal handler releases the lock, downloads are staged and renamed
+ * into place, and the journal is written by atomic rename. On Windows the
+ * stop is `taskkill /T /F` on the tree, which is a forced kill, not a
+ * cooperative one; the same staged writes and atomic journal keep completed
+ * work.
+ */
+export const REFRESH_SUPERVISOR_SOURCE = `
+const fs = require("node:fs");
+const path = require("node:path");
+const { spawn, spawnSync } = require("node:child_process");
+const [logPath, exitPath, hbPath, pidPath, cancelPath, locksDir, maxMs, cmd, ...args] = process.argv.slice(1);
+const isWin = process.platform === "win32";
+const beat = () => { try { fs.writeFileSync(hbPath, String(Date.now())); } catch {} };
+beat();
+const hb = setInterval(beat, ${REFRESH_HEARTBEAT_INTERVAL_MS});
+let fd;
+try { fd = fs.openSync(logPath, "a", 0o600); } catch { fd = "ignore"; }
+let finished = false;
+let preempted = false;
+let capped = false;
+let stopAt = 0;
+let watch;
+// Its own process group on POSIX, so a stop reaches every process the pull started.
+const child = spawn(cmd, args, { stdio: ["ignore", fd, fd], windowsHide: true, detached: !isWin });
+try { fs.writeFileSync(pidPath, String(child.pid)); } catch {}
+if (!isWin && child.pid) {
+  try {
+    const r = spawnSync("ps", ["-o", "lstart=", "-p", String(child.pid)], { encoding: "utf8" });
+    const started = (r.stdout || "").trim();
+    if (started) fs.writeFileSync(path.join(path.dirname(pidPath), path.basename(pidPath, ".pid") + ".start"), started);
+  } catch {}
+}
+const killTree = (sig) => {
+  if (isWin) {
+    try { spawnSync("taskkill", ["/PID", String(child.pid), "/T", "/F"], { stdio: "ignore", windowsHide: true }); } catch {}
+    return;
+  }
+  try { process.kill(-child.pid, sig); } catch {}
+};
+const stop = () => {
+  if (stopAt) return;
+  stopAt = Date.now();
+  killTree("SIGTERM");
+  setTimeout(() => killTree("SIGKILL"), ${REFRESH_KILL_GRACE_MS});
+};
+const exitNow = (status) => process.exit(typeof status === "number" ? status : 1);
+const done = (status, signal) => {
+  if (finished) return;
+  finished = true;
+  clearInterval(hb);
+  clearInterval(watch);
+  clearTimeout(stopper);
+  try {
+    fs.writeFileSync(exitPath + ".tmp", JSON.stringify({ status, signal, preempted, capped }));
+    fs.renameSync(exitPath + ".tmp", exitPath);
+  } catch {}
+  if (!stopAt) return exitNow(status);
+  // A stopped pull's group is always SIGKILLed after the grace period, even
+  // when the pull itself exited on SIGTERM, so no grandchild survives.
+  const left = Math.max(0, stopAt + ${REFRESH_KILL_GRACE_MS} - Date.now());
+  setTimeout(() => { killTree("SIGKILL"); exitNow(status); }, left);
+};
+const stopper = setTimeout(() => {
+  capped = true;
+  // At the cap the pull is no longer live: stop heartbeating so nothing reads it as in progress.
+  clearInterval(hb);
+  try { fs.writeFileSync(hbPath, "capped:" + Date.now()); } catch {}
+  stop();
+}, Number(maxMs));
+const alive = (pid) => { try { process.kill(pid, 0); return true; } catch (e) { return Boolean(e && e.code === "EPERM"); } };
+let lockName = null;
+const findLock = () => {
+  let names;
+  try { names = fs.readdirSync(locksDir); } catch { return null; }
+  for (const name of names) {
+    // A sync holds shared membership: <lock>.shared-<pid>-<hex>.
+    const shared = /^(.+\\.lock)\\.shared-(\\d+)-/.exec(name);
+    if (shared && Number(shared[2]) === child.pid) return shared[1];
+    if (!name.endsWith(".lock")) continue;
+    // An exclusive holder writes its record into the lock file itself.
+    try {
+      const info = JSON.parse(fs.readFileSync(path.join(locksDir, name), "utf8"));
+      if (info && info.pid === child.pid) return name;
+    } catch {}
+  }
+  return null;
+};
+const someoneWaiting = () => {
+  if (fs.existsSync(cancelPath)) return true;
+  if (!lockName) lockName = findLock();
+  if (!lockName) return false;
+  let names;
+  try { names = fs.readdirSync(locksDir); } catch { return false; }
+  const prefix = lockName + ".wait-";
+  for (const name of names) {
+    if (!name.startsWith(prefix)) continue;
+    const waiter = Number(name.slice(prefix.length).split("-")[0]);
+    if (Number.isInteger(waiter) && waiter > 0 && waiter !== child.pid && waiter !== process.pid && alive(waiter)) return true;
+  }
+  return false;
+};
+watch = setInterval(() => {
+  if (finished || stopAt) return;
+  if (someoneWaiting()) {
+    preempted = true;
+    stop();
+  }
+}, ${REFRESH_PREEMPT_POLL_MS});
+child.on("error", (error) => {
+  try { fs.appendFileSync(logPath, String((error && error.code) || error) + "\\n"); } catch {}
+  done(null, null);
+});
+child.on("exit", (status, signal) => done(status, signal));
+`;
+//# sourceMappingURL=refresh-sync-handoff.js.map