@indigoai-us/hq-cli 5.345.166 → 5.345.169

package/dist/lib/doctor/fix/apply.d.ts

@@ -42,6 +42,8 @@ import type { CheckResult, DoctorStatus } from "../types.js";
 import { type GateProfile } from "../hook-gate-profiles.js";
 import { type FixClass } from "./remediation.js";
 import { type RemovePs1ShimsResult } from "../../windows/ps1-shims.js";
+import { processStartTime } from "./process-identity.js";
+import { type HarvestedRefreshRun, type OrphanPull, type RefreshOwnerIdentity } from "./refresh-sync-handoff.js";
 import { type RefreshSyncOutcome } from "./refresh-sync-outcome.js";
 /** The tree subtrees whose uncommitted changes block a `--fix` run. */
 export declare const HOOK_CONFIG_DIRS: readonly [".claude", ".codex", ".grok"];
@@ -290,10 +292,45 @@ export declare function unresolvedSyncChecks(findings: readonly CheckResult[], a
 /**
  * Default `refresh-sync` repair: a bounded, pull-only, keep-conflicts
  * `hq sync pull --company <slug>` (or `--personal`) against the tree
- * `--fix` is repairing. Never a push, never interactive. A timeout or
- * non-zero exit is reported rather than thrown so later plans still run.
+ * `--fix` is repairing. Never a push, never interactive. A non-zero exit is
+ * reported rather than thrown so later plans still run.
+ *
+ * A pull still running after {@link REFRESH_SYNC_TIMEOUT_MS} is NOT killed
+ * (feedback cd56a501). A pull writes `lastSync` only when its pass finishes,
+ * so killing it at the deadline left a large vault, or a pull queued behind
+ * the sync runner's lock, stale on every run. It is left running detached and
+ * recorded in refresh-sync-handoff.ts; the journal check reports it as
+ * "refresh in progress" until it finishes.
+ */
+export declare function defaultRefreshSync(target: RefreshSyncTarget, deps?: RefreshSyncSpawnDeps): Promise<RefreshSyncResult>;
+/** Map a finished supervised pull to a {@link RefreshSyncResult}. */
+export declare function harvestedRefreshSyncResult(harvested: HarvestedRefreshRun): RefreshSyncResult;
+export { processStartTime };
+/**
+ * Kill an orphaned --fix pull past its cap, but only when the pid still names
+ * that pull: its process start time must match the one recorded when it
+ * started. A reused pid has a different start time and is left alone. On
+ * Windows no start time is recorded, so nothing is killed there.
+ */
+export declare function killOrphanPullIfSame(orphan: OrphanPull, _nowMs: number, probe?: (pid: number) => string | null): void;
+/** Test seams for {@link defaultRefreshSync}. */
+export interface RefreshSyncSpawnDeps {
+    command?: string;
+    args?: string[];
+    timeoutMs?: number;
+    maxBackgroundMs?: number;
+    nowMs?: () => number;
+    /** Directory holding hq-cloud's operation-lock files. */
+    locksDir?: string;
+    /** Process start-time probe for the spawn lock. */
+    identity?: RefreshOwnerIdentity;
+}
+/**
+ * How long a `--fix` pull waits for the operation lock. Unchanged from before
+ * the hand-off: a background pull must never queue on the lock longer than a
+ * foreground one did.
  */
-export declare function defaultRefreshSync(target: RefreshSyncTarget): Promise<RefreshSyncResult>;
+export declare const REFRESH_SYNC_LOCK_TIMEOUT_SEC = 30;
 /**
  * Default `refresh-manifest` repair: a bounded `hq sync manifest --scope <s>`
  * against the tree `--fix` is repairing. Exit 0 also covers throttled,
@@ -349,5 +386,4 @@ export declare function addHookIdToGateProfiles(source: string, hookId: string,
  * non-object `hooks` value — it is replaced rather than trusted.
  */
 export declare function registerHookInSettings(settings: unknown, event: string, command: string): Record<string, unknown>;
-export {};
 //# sourceMappingURL=apply.d.ts.map

package/dist/lib/doctor/fix/apply.js

@@ -37,9 +37,10 @@
  * (the command resolves it once), keeping this module decoupled from the CLI and
  * trivially testable against a fake tree.
  */
-import { spawnSync } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { getStateDir } from "@indigoai-us/hq-cloud";
 import { isPersonalJournalSlug } from "../checks/sync-health.js";
 import { createDefaultRegistry } from "../registry.js";
 import { flattenFamilies } from "../report.js";
@@ -51,6 +52,8 @@ import { HQ_CLI_BINS, removeHqCliPs1Shims } from "../../windows/ps1-shims.js";
 import { botDir } from "../../bot/paths.js";
 import { readBotConfig } from "../../bot/config.js";
 import { buildBotDaemonPaths, installedDaemonHqBinary, repairBotDaemonIfStale, rewriteBotDaemonNodePath, } from "../../bot/daemon.js";
+import { DEFAULT_OWNER_IDENTITY, processStartTime } from "./process-identity.js";
+import { REFRESH_BACKGROUND_MAX_MS, REFRESH_SUPERVISOR_SOURCE, anyRefreshHandoffAlive, harvestRefreshHandoffs, releaseDeadRefreshSpawnLock, newRefreshRunPaths, readRefreshRunExit, readRefreshRunLog, claimRefreshRun, clearRefreshRecord, removeRefreshRun, } from "./refresh-sync-handoff.js";
 import { classifyRefreshSyncOutcome, } from "./refresh-sync-outcome.js";
 import { pullOutputShowsCompanyNotResolved, recordCompanyResolution, } from "../company-resolution-state.js";
 import { readRefreshManifestCursor, readRefreshSyncProgress, writeRefreshManifestCursor, writeRefreshSyncCursor, writeRefreshSyncLastRun, } from "./refresh-sync-progress.js";
@@ -184,6 +187,10 @@ export async function applyFixes(options) {
     };
     const refreshSync = async (target) => {
         const result = await performRefreshSync(target);
+        // Still running in the background: no evidence about the company yet.
+        // The next --fix harvests its real exit before it plans anything.
+        if (result.outcome === "pull-handed-off")
+            return result;
         if (target.personal)
             return result;
         noteCompanyOutcome(target.slug, result.ok, result.companyNotResolved === true);
@@ -205,6 +212,17 @@ export async function applyFixes(options) {
     // 2. Collect findings, then plan each newly unlocked allowlisted repair.
     //    Identity is deliberately the check id + target pair: an unsuccessful
     //    repair must not be applied repeatedly in one invocation.
+    // Background pulls from an earlier --fix: record how each really ended
+    // before planning, then drop the finished records (feedback cd56a501).
+    // A spawn lock left by a crashed claimer is released here when its owner is
+    // proven gone, even if no journal is stale this run.
+    releaseDeadRefreshSpawnLock(hqRoot, Date.now(), DEFAULT_OWNER_IDENTITY);
+    for (const harvested of harvestRefreshHandoffs(hqRoot, Date.now(), killOrphanPullIfSame)) {
+        const outcome = harvestedRefreshSyncResult(harvested);
+        if (harvested.slug === "personal" || isPersonalJournalSlug(harvested.slug))
+            continue;
+        noteCompanyOutcome(harvested.slug, outcome.ok, outcome.companyNotResolved === true);
+    }
     let findings = await collect(hqRoot);
     let lastAttemptedRefreshSyncSlug = readRefreshSyncProgress(hqRoot)?.lastAttemptedSlug ?? null;
     let refreshSyncAppliedThisRun = 0;
@@ -333,6 +351,11 @@ export async function applyFixes(options) {
             // left over and reported "not attempted" rather than as a failed repair.
             if (network && !networkBudgetLeft())
                 continue;
+            // One background pull per HQ root. While it runs it holds the operation
+            // lock, so another pull would only wait on it; leave the rest for the
+            // next run.
+            if (plan.fixClass === "refresh-sync" && anyRefreshHandoffAlive(hqRoot, Date.now()))
+                continue;
             if (plan.fixClass === "refresh-sync") {
                 // Persist before starting the bounded pull. If this process is killed,
                 // the next invocation resumes after this company instead of starving
@@ -540,85 +563,176 @@ async function defaultRunChecks(hqRoot) {
 /**
  * Default `refresh-sync` repair: a bounded, pull-only, keep-conflicts
  * `hq sync pull --company <slug>` (or `--personal`) against the tree
- * `--fix` is repairing. Never a push, never interactive. A timeout or
- * non-zero exit is reported rather than thrown so later plans still run.
+ * `--fix` is repairing. Never a push, never interactive. A non-zero exit is
+ * reported rather than thrown so later plans still run.
+ *
+ * A pull still running after {@link REFRESH_SYNC_TIMEOUT_MS} is NOT killed
+ * (feedback cd56a501). A pull writes `lastSync` only when its pass finishes,
+ * so killing it at the deadline left a large vault, or a pull queued behind
+ * the sync runner's lock, stale on every run. It is left running detached and
+ * recorded in refresh-sync-handoff.ts; the journal check reports it as
+ * "refresh in progress" until it finishes.
  */
-export function defaultRefreshSync(target) {
+export async function defaultRefreshSync(target, deps = {}) {
     const hqBin = process.argv[1];
     const selector = target.personal || isPersonalJournalSlug(target.slug)
         ? ["--personal"]
         : ["--company", target.slug];
-    const args = hqBin
-        ? [
-            hqBin,
-            "sync",
-            "pull",
-            ...selector,
-            "--hq-root",
-            target.hqRoot,
-            "--on-conflict",
-            "keep",
-            "--lock-timeout",
-            "30",
-        ]
-        : [
-            "sync",
-            "pull",
-            ...selector,
-            "--hq-root",
-            target.hqRoot,
-            "--on-conflict",
-            "keep",
-            "--lock-timeout",
-            "30",
-        ];
-    const result = spawnSync(hqBin ? process.execPath : "hq", args, {
-        encoding: "utf8",
-        timeout: REFRESH_SYNC_TIMEOUT_MS,
-        cwd: target.hqRoot,
-    });
-    if (result.error) {
-        const spawnError = result.error;
-        const outcome = classifyRefreshSyncOutcome({
-            errorCode: spawnError.code,
-            ...(result.error.message.includes("ETIMEDOUT")
-                ? { errorCode: "ETIMEDOUT" }
-                : {}),
-            signal: result.signal,
-            status: result.status,
-            stdout: result.stdout,
-            stderr: result.stderr,
-        });
-        return Promise.resolve({
+    const pullArgs = [
+        "sync",
+        "pull",
+        ...selector,
+        "--hq-root",
+        target.hqRoot,
+        "--on-conflict",
+        "keep",
+        "--lock-timeout",
+        String(REFRESH_SYNC_LOCK_TIMEOUT_SEC),
+    ];
+    // Run the same CLI script under this node. Without a script path there is no
+    // safe way to start `hq` on Windows (it is a .cmd shim that needs a shell),
+    // so only POSIX falls back to `hq` on PATH.
+    if (!deps.command && !hqBin && process.platform === "win32") {
+        return {
             ok: false,
-            outcome,
-            message: outcome === "pull-timeout"
-                ? `timed out pulling '${target.slug}'`
-                : `could not start pull for '${target.slug}': ${result.error.message}`,
-        });
+            outcome: "pull-failed:other",
+            message: `could not start pull for '${target.slug}': the hq CLI script path is unknown`,
+        };
     }
-    if (result.status !== 0) {
-        const outcome = classifyRefreshSyncOutcome({
-            status: result.status,
-            stdout: result.stdout,
-            stderr: result.stderr,
-        });
-        const detail = (result.stderr || result.stdout || "").trim().split("\n").at(-1) ?? "";
-        return Promise.resolve({
+    const command = deps.command ?? (hqBin ? process.execPath : "hq");
+    const args = deps.args ?? (hqBin ? [hqBin, ...pullArgs] : pullArgs);
+    const timeoutMs = deps.timeoutMs ?? REFRESH_SYNC_TIMEOUT_MS;
+    const maxBackgroundMs = deps.maxBackgroundMs ?? REFRESH_BACKGROUND_MAX_MS;
+    const nowMs = deps.nowMs ?? (() => Date.now());
+    // The pull runs under a supervisor that records its real exit status, so a
+    // pull left running past the deadline is still classified by the next run.
+    const run = newRefreshRunPaths(target.hqRoot, target.slug);
+    // One pull per HQ root: claim it (record written under the spawn lock)
+    // before spawning, so a concurrent --fix sees this pull and backs off.
+    if (!claimRefreshRun(target.hqRoot, target.slug, run, nowMs(), deps.identity ?? DEFAULT_OWNER_IDENTITY)) {
+        return {
             ok: false,
-            outcome,
-            message: `pull of '${target.slug}' exited ${result.status}${detail ? `: ${detail}` : ""}`,
-            companyNotResolved: !target.personal &&
-                !isPersonalJournalSlug(target.slug) &&
-                pullOutputShowsCompanyNotResolved(`${result.stdout ?? ""}\n${result.stderr ?? ""}`),
-        });
+            outcome: "pull-failed:lock-busy",
+            message: `another hq doctor --fix pull is already running; '${target.slug}' is left for the next run`,
+        };
+    }
+    let supervisor;
+    try {
+        fs.mkdirSync(path.dirname(run.log), { recursive: true });
+        supervisor = spawn(process.execPath, [
+            "-e",
+            REFRESH_SUPERVISOR_SOURCE,
+            run.log,
+            run.exit,
+            run.heartbeat,
+            run.pid,
+            run.cancel,
+            deps.locksDir ?? defaultLocksDir(),
+            String(maxBackgroundMs),
+            command,
+            ...args,
+        ], { cwd: target.hqRoot, detached: true, stdio: "ignore", windowsHide: true });
+    }
+    catch (error) {
+        clearRefreshRecord(target.hqRoot, target.slug, run);
+        removeRefreshRun(run);
+        return {
+            ok: false,
+            outcome: classifyRefreshSyncOutcome({ errorCode: error.code }),
+            message: `could not start pull for '${target.slug}': ${error.message}`,
+        };
     }
-    return Promise.resolve({
-        ok: true,
-        outcome: "pull-succeeded",
-        message: `pulled '${target.slug}'`,
+    const finished = await new Promise((resolve) => {
+        let settled = false;
+        const settle = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve(value);
+        };
+        supervisor.once("error", () => settle(true));
+        supervisor.once("exit", () => settle(true));
+        const timer = setTimeout(() => settle(false), timeoutMs);
     });
+    if (!finished) {
+        // Leave the pull running on its own. It records lastSync when it
+        // finishes; until then the journal check reports "refresh in progress".
+        supervisor.removeAllListeners();
+        supervisor.unref();
+        return {
+            ok: false,
+            outcome: "pull-handed-off",
+            message: `still pulling '${target.slug}' after ${timeoutMs / 1000}s; it keeps running in the background`,
+        };
+    }
+    const result = harvestedRefreshSyncResult({
+        slug: target.slug,
+        exit: readRefreshRunExit(run),
+        output: readRefreshRunLog(run),
+    });
+    clearRefreshRecord(target.hqRoot, target.slug, run);
+    removeRefreshRun(run);
+    return result;
+}
+/** Map a finished supervised pull to a {@link RefreshSyncResult}. */
+export function harvestedRefreshSyncResult(harvested) {
+    const { slug, exit, output } = harvested;
+    if (!exit) {
+        return { ok: false, outcome: "pull-failed:other", message: `pull of '${slug}' ended without a result` };
+    }
+    if (exit.capped) {
+        // Stopped at the background time cap. Completed downloads are kept.
+        return { ok: false, outcome: "pull-timeout-capped", message: `stopped pulling '${slug}' at the background time limit` };
+    }
+    if (exit.preempted) {
+        // Stopped so a sync the user or the runner started could take the lock.
+        // Completed downloads are kept; the next --fix resumes the journal.
+        return { ok: false, outcome: "pull-preempted", message: `paused pulling '${slug}' for another sync` };
+    }
+    if (exit.status === 0 && !exit.signal) {
+        return { ok: true, outcome: "pull-succeeded", message: `pulled '${slug}'` };
+    }
+    const outcome = classifyRefreshSyncOutcome({ status: exit.status, signal: exit.signal, stdout: output });
+    const detail = output.trim().split("\n").at(-1) ?? "";
+    const personal = slug === "personal" || isPersonalJournalSlug(slug);
+    return {
+        ok: false,
+        outcome,
+        message: `pull of '${slug}' exited ${exit.status ?? exit.signal}${detail ? `: ${detail}` : ""}`,
+        companyNotResolved: !personal && pullOutputShowsCompanyNotResolved(output),
+    };
 }
+export { processStartTime };
+/**
+ * Kill an orphaned --fix pull past its cap, but only when the pid still names
+ * that pull: its process start time must match the one recorded when it
+ * started. A reused pid has a different start time and is left alone. On
+ * Windows no start time is recorded, so nothing is killed there.
+ */
+export function killOrphanPullIfSame(orphan, _nowMs, probe = processStartTime) {
+    if (process.platform === "win32" || !orphan.recordedStart)
+        return;
+    const current = probe(orphan.pid);
+    if (!current || current !== orphan.recordedStart)
+        return;
+    try {
+        process.kill(-orphan.pid, "SIGKILL");
+    }
+    catch {
+        // gone
+    }
+}
+/** hq-cloud keeps operation locks in `<stateDir>/locks`. */
+function defaultLocksDir() {
+    return path.join(getStateDir(), "locks");
+}
+/**
+ * How long a `--fix` pull waits for the operation lock. Unchanged from before
+ * the hand-off: a background pull must never queue on the lock longer than a
+ * foreground one did.
+ */
+export const REFRESH_SYNC_LOCK_TIMEOUT_SEC = 30;
 /**
  * Default `refresh-manifest` repair: a bounded `hq sync manifest --scope <s>`
  * against the tree `--fix` is repairing. Exit 0 also covers throttled,

package/dist/lib/doctor/fix/process-identity.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Process start times, used to tell the owner of a pid from a later process
+ * that reused it (feedback cd56a501).
+ */
+import type { RefreshOwnerIdentity } from "./refresh-sync-handoff.js";
+/**
+ * A process's start time, or null if it cannot be read: `ps -o lstart=` on
+ * POSIX, the process StartTime from PowerShell on Windows.
+ */
+export declare function processStartTime(pid: number): string | null;
+/** Real process-table identity for the refresh spawn lock. */
+export declare const DEFAULT_OWNER_IDENTITY: RefreshOwnerIdentity;
+//# sourceMappingURL=process-identity.d.ts.map

package/dist/lib/doctor/fix/process-identity.js

@@ -0,0 +1,34 @@
+/**
+ * Process start times, used to tell the owner of a pid from a later process
+ * that reused it (feedback cd56a501).
+ */
+import { spawnSync } from "node:child_process";
+/**
+ * A process's start time, or null if it cannot be read: `ps -o lstart=` on
+ * POSIX, the process StartTime from PowerShell on Windows.
+ */
+export function processStartTime(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return null;
+    try {
+        const result = process.platform === "win32"
+            ? spawnSync("powershell.exe", [
+                "-NoProfile",
+                "-NonInteractive",
+                "-Command",
+                `(Get-Process -Id ${pid} -ErrorAction Stop).StartTime.ToUniversalTime().ToString('o')`,
+            ], { encoding: "utf8", timeout: 10_000, windowsHide: true })
+            : spawnSync("ps", ["-o", "lstart=", "-p", String(pid)], { encoding: "utf8", timeout: 5_000 });
+        const text = (result.stdout ?? "").trim();
+        return result.status === 0 && text ? text : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Real process-table identity for the refresh spawn lock. */
+export const DEFAULT_OWNER_IDENTITY = {
+    selfStart: () => processStartTime(process.pid),
+    startOf: (pid) => processStartTime(pid),
+};
+//# sourceMappingURL=process-identity.js.map

package/dist/lib/doctor/fix/refresh-sync-handoff.d.ts

@@ -0,0 +1,201 @@
+/**
+ * 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.
+ */
+/** The supervisor stops a background pull after this long. */
+export declare const REFRESH_BACKGROUND_MAX_MS: number;
+/** The supervisor refreshes its heartbeat this often. */
+export declare const REFRESH_HEARTBEAT_INTERVAL_MS = 10000;
+/** A heartbeat older than this means the supervisor is gone. */
+export declare const REFRESH_HEARTBEAT_STALE_MS = 60000;
+/** After SIGTERM, the supervisor waits this long before SIGKILL of the pull's process group. */
+export declare const REFRESH_KILL_GRACE_MS = 5000;
+/**
+ * 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 declare const REFRESH_RECORD_MAX_AGE_MS: number;
+/**
+ * Reads a process's start time, to tell the owner of a pid from a later
+ * process that reused it. Supplied by the caller (it needs a process table
+ * probe). `null` means the start time could not be read.
+ */
+export interface RefreshOwnerIdentity {
+    /** This process's start time. */
+    selfStart: () => string | null;
+    /** Start time of `pid`, or null if unreadable. */
+    startOf: (pid: number) => string | null;
+}
+/** Files for one supervised pull. */
+export interface RefreshRunPaths {
+    id: string;
+    log: string;
+    exit: string;
+    heartbeat: string;
+    /** The supervisor writes the pull's pid (its process group on POSIX) here. */
+    pid: string;
+    /** The supervisor writes the pull's process start time (`ps -o lstart=`) here, on POSIX. */
+    start: string;
+    /** Create this file to ask the supervisor to stop the pull. */
+    cancel: string;
+}
+/** Exit file the supervisor writes when the pull ends. */
+export interface RefreshRunExit {
+    status: number | null;
+    signal: string | null;
+    /** True when the supervisor stopped the pull because another operation waited on the lock. */
+    preempted?: boolean;
+    /** True when the pull was stopped at the background time cap. */
+    capped?: boolean;
+}
+export declare function safeRefreshSlug(slug: string): string;
+/** Fresh per-run file names under workspace/doctor/refresh-runs/. */
+export declare function newRefreshRunPaths(hqRoot: string, slug: string): RefreshRunPaths;
+/** Write (or replace) the record for a pull of `slug`. Tests and recovery only; claims use {@link claimRefreshRun}. */
+export declare function recordRefreshHandoff(hqRoot: string, slug: string, run: RefreshRunPaths, nowMs: number): void;
+/**
+ * An unreadable record younger than this may still be mid-write (the
+ * exclusive-create fallback), so harvest does not delete it yet.
+ */
+export declare const UNREADABLE_RECORD_SETTLE_MS = 10000;
+/** Remove the record for `slug` if it still names `run`. */
+export declare function clearRefreshRecord(hqRoot: string, slug: string, run: RefreshRunPaths): void;
+/** Read a supervisor exit file, or null if the run has not ended. */
+export declare function readRefreshRunExit(run: RefreshRunPaths): RefreshRunExit | null;
+/** Last 64 KiB of a run's output: enough to classify, bounded in memory. */
+export declare function readRefreshRunLog(run: RefreshRunPaths): string;
+/** What an identity-checked killer needs to know about an orphaned pull. */
+export interface OrphanPull {
+    pid: number;
+    /** Start time the supervisor recorded for the pull, or null if none. */
+    recordedStart: string | null;
+    /** When the record was written (the pull started at or before this). */
+    recordStartedAtMs: number;
+}
+/**
+ * Kills an orphaned pull only if it can prove the pid is still that pull.
+ * Supplied by the caller (it needs a process table probe); without one,
+ * harvest never kills.
+ */
+export type OrphanPullKiller = (orphan: OrphanPull, nowMs: number) => void;
+/** An orphan is only ever killed within this long of its record. */
+export declare const REFRESH_ORPHAN_KILL_WINDOW_MS: number;
+/** Delete a run's files. */
+export declare function removeRefreshRun(run: RefreshRunPaths): void;
+/** A run that has ended (or died) and been removed. */
+export interface HarvestedRefreshRun {
+    slug: string;
+    exit: RefreshRunExit | null;
+    output: string;
+}
+/**
+ * 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 declare function harvestRefreshHandoffs(hqRoot: string, nowMs: number, killOrphan?: OrphanPullKiller): HarvestedRefreshRun[];
+/** Start time of the live pull for `slug`, or null. */
+export declare function refreshHandoffStartedAt(hqRoot: string, slug: string, nowMs: number): number | 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 declare function anyRefreshHandoffAlive(hqRoot: string, nowMs: number): boolean;
+/**
+ * Take the per-root spawn lock: an O_EXCL file holding this process's pid,
+ * its start time and a random token.
+ *
+ * An existing lock is taken over only when identity proves its owner is gone:
+ * the pid is dead, or the pid is alive but its start time differs from the
+ * recorded one (the pid was reused). Age never counts. If the owner's start
+ * time cannot be verified the lock is left alone and this returns null.
+ */
+/** Releases the spawn lock; `stillHeld` re-reads the lock file for this holder's token. */
+export type SpawnLockRelease = (() => void) & {
+    stillHeld: () => boolean;
+};
+export declare function acquireRefreshSpawnLock(hqRoot: string, nowMs: number, identity?: RefreshOwnerIdentity): SpawnLockRelease | null;
+/** A spawn lock still held after this long is reported by `hq doctor`. */
+export declare const REFRESH_SPAWN_LOCK_WARN_MS: number;
+/**
+ * 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 declare function inspectRefreshSpawnLock(hqRoot: string, nowMs: number, identity?: RefreshOwnerIdentity): {
+    pid: number;
+    heldMs: number | null;
+    ownerGone: boolean;
+} | null;
+/**
+ * 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 declare function releaseDeadRefreshSpawnLock(hqRoot: string, nowMs: number, identity?: RefreshOwnerIdentity): void;
+/**
+ * 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 declare function claimRefreshRun(hqRoot: string, slug: string, run: RefreshRunPaths, nowMs: number, identity?: RefreshOwnerIdentity): boolean;
+/** How often the supervisor looks for another operation waiting on the lock. */
+export declare 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 declare const REFRESH_SUPERVISOR_SOURCE = "\nconst fs = require(\"node:fs\");\nconst path = require(\"node:path\");\nconst { spawn, spawnSync } = require(\"node:child_process\");\nconst [logPath, exitPath, hbPath, pidPath, cancelPath, locksDir, maxMs, cmd, ...args] = process.argv.slice(1);\nconst isWin = process.platform === \"win32\";\nconst beat = () => { try { fs.writeFileSync(hbPath, String(Date.now())); } catch {} };\nbeat();\nconst hb = setInterval(beat, 10000);\nlet fd;\ntry { fd = fs.openSync(logPath, \"a\", 0o600); } catch { fd = \"ignore\"; }\nlet finished = false;\nlet preempted = false;\nlet capped = false;\nlet stopAt = 0;\nlet watch;\n// Its own process group on POSIX, so a stop reaches every process the pull started.\nconst child = spawn(cmd, args, { stdio: [\"ignore\", fd, fd], windowsHide: true, detached: !isWin });\ntry { fs.writeFileSync(pidPath, String(child.pid)); } catch {}\nif (!isWin && child.pid) {\n  try {\n    const r = spawnSync(\"ps\", [\"-o\", \"lstart=\", \"-p\", String(child.pid)], { encoding: \"utf8\" });\n    const started = (r.stdout || \"\").trim();\n    if (started) fs.writeFileSync(path.join(path.dirname(pidPath), path.basename(pidPath, \".pid\") + \".start\"), started);\n  } catch {}\n}\nconst killTree = (sig) => {\n  if (isWin) {\n    try { spawnSync(\"taskkill\", [\"/PID\", String(child.pid), \"/T\", \"/F\"], { stdio: \"ignore\", windowsHide: true }); } catch {}\n    return;\n  }\n  try { process.kill(-child.pid, sig); } catch {}\n};\nconst stop = () => {\n  if (stopAt) return;\n  stopAt = Date.now();\n  killTree(\"SIGTERM\");\n  setTimeout(() => killTree(\"SIGKILL\"), 5000);\n};\nconst exitNow = (status) => process.exit(typeof status === \"number\" ? status : 1);\nconst done = (status, signal) => {\n  if (finished) return;\n  finished = true;\n  clearInterval(hb);\n  clearInterval(watch);\n  clearTimeout(stopper);\n  try {\n    fs.writeFileSync(exitPath + \".tmp\", JSON.stringify({ status, signal, preempted, capped }));\n    fs.renameSync(exitPath + \".tmp\", exitPath);\n  } catch {}\n  if (!stopAt) return exitNow(status);\n  // A stopped pull's group is always SIGKILLed after the grace period, even\n  // when the pull itself exited on SIGTERM, so no grandchild survives.\n  const left = Math.max(0, stopAt + 5000 - Date.now());\n  setTimeout(() => { killTree(\"SIGKILL\"); exitNow(status); }, left);\n};\nconst stopper = setTimeout(() => {\n  capped = true;\n  // At the cap the pull is no longer live: stop heartbeating so nothing reads it as in progress.\n  clearInterval(hb);\n  try { fs.writeFileSync(hbPath, \"capped:\" + Date.now()); } catch {}\n  stop();\n}, Number(maxMs));\nconst alive = (pid) => { try { process.kill(pid, 0); return true; } catch (e) { return Boolean(e && e.code === \"EPERM\"); } };\nlet lockName = null;\nconst findLock = () => {\n  let names;\n  try { names = fs.readdirSync(locksDir); } catch { return null; }\n  for (const name of names) {\n    // A sync holds shared membership: <lock>.shared-<pid>-<hex>.\n    const shared = /^(.+\\.lock)\\.shared-(\\d+)-/.exec(name);\n    if (shared && Number(shared[2]) === child.pid) return shared[1];\n    if (!name.endsWith(\".lock\")) continue;\n    // An exclusive holder writes its record into the lock file itself.\n    try {\n      const info = JSON.parse(fs.readFileSync(path.join(locksDir, name), \"utf8\"));\n      if (info && info.pid === child.pid) return name;\n    } catch {}\n  }\n  return null;\n};\nconst someoneWaiting = () => {\n  if (fs.existsSync(cancelPath)) return true;\n  if (!lockName) lockName = findLock();\n  if (!lockName) return false;\n  let names;\n  try { names = fs.readdirSync(locksDir); } catch { return false; }\n  const prefix = lockName + \".wait-\";\n  for (const name of names) {\n    if (!name.startsWith(prefix)) continue;\n    const waiter = Number(name.slice(prefix.length).split(\"-\")[0]);\n    if (Number.isInteger(waiter) && waiter > 0 && waiter !== child.pid && waiter !== process.pid && alive(waiter)) return true;\n  }\n  return false;\n};\nwatch = setInterval(() => {\n  if (finished || stopAt) return;\n  if (someoneWaiting()) {\n    preempted = true;\n    stop();\n  }\n}, 500);\nchild.on(\"error\", (error) => {\n  try { fs.appendFileSync(logPath, String((error && error.code) || error) + \"\\n\"); } catch {}\n  done(null, null);\n});\nchild.on(\"exit\", (status, signal) => done(status, signal));\n";
+//# sourceMappingURL=refresh-sync-handoff.d.ts.map