@indigoai-us/hq-cloud 6.18.89 → 6.18.90

package/dist/bin/sync-runner-self-profile.js

@@ -0,0 +1,751 @@
+/**
+ * Sync-runner self-profile.
+ *
+ * Once a minute the runner samples its own CPU time and RSS. When CPU use
+ * averaged over ten minutes goes above a fraction of one core, or RSS goes
+ * above a byte limit, it writes ONE plain stderr line. That part is always on.
+ *
+ * Capture is opt-in (HQ_SYNC_SELF_PROFILE=1, or `"enabled": true` in
+ * `<state dir>/sync-runner-self-profile.json`). With capture on, a trip also
+ * writes a local diagnostics folder under `<state dir>/diagnostics/sync-runner/`:
+ * a redacted summary JSON and a 60 s CPU profile taken through node:inspector.
+ * File paths in both are rewritten relative to the HQ root, and the home folder
+ * is shown as `~`. There is no heap snapshot: it would hold tokens and synced
+ * file contents. Only the newest three folders are kept. Nothing here sends
+ * anything over the network. `hq-sync-runner --diagnostics` prints the redacted
+ * summary for a bug report; the profile folder stays on this computer.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { Session } from "node:inspector";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { heavyWatchKind } from "../watcher.js";
+export const SELF_PROFILE_ENV = "HQ_SYNC_SELF_PROFILE";
+export const SELF_PROFILE_CPU_CORES_ENV = "HQ_SYNC_SELF_PROFILE_CPU_CORES";
+export const SELF_PROFILE_RSS_MB_ENV = "HQ_SYNC_SELF_PROFILE_RSS_MB";
+export const SELF_PROFILE_CONFIG_FILE = "sync-runner-self-profile.json";
+export const DEFAULT_SELF_PROFILE_CPU_CORES = 0.25;
+export const DEFAULT_SELF_PROFILE_RSS_MB = 600;
+export const SELF_PROFILE_SAMPLE_INTERVAL_MS = 60_000;
+export const SELF_PROFILE_CPU_WINDOW_MS = 10 * 60_000;
+export const SELF_PROFILE_CPU_PROFILE_MS = 60_000;
+/** Minimum gap between two warnings, even when usage dips and recovers. */
+export const SELF_PROFILE_WARNING_COOLDOWN_MS = 60 * 60_000;
+/** Minimum gap between two captures. */
+export const SELF_PROFILE_CAPTURE_COOLDOWN_MS = 6 * 60 * 60_000;
+export const SELF_PROFILE_KEEP_CAPTURES = 3;
+export const SELF_PROFILE_MAX_CPU_PROFILE_BYTES = 64 * 1024 * 1024;
+/** Total size cap for every kept capture folder together. */
+export const SELF_PROFILE_MAX_TOTAL_BYTES = 1024 * 1024 * 1024;
+const CAPTURE_DIR_PREFIX = "self-profile-";
+const MAX_EVENT_PREFIXES = 200;
+const COVERAGE_SCAN_MAX_DIRS = 20_000;
+const COVERAGE_SAMPLE_PATHS = 10;
+function positiveNumber(raw) {
+    const value = typeof raw === "string" ? Number(raw.trim()) : raw;
+    return typeof value === "number" && Number.isFinite(value) && value > 0
+        ? value
+        : undefined;
+}
+function enabledFlag(raw) {
+    if (typeof raw === "boolean")
+        return raw;
+    if (typeof raw !== "string")
+        return undefined;
+    const value = raw.trim().toLowerCase();
+    if (value === "1" || value === "true" || value === "yes" || value === "on")
+        return true;
+    if (value === "0" || value === "false" || value === "no" || value === "off")
+        return false;
+    return undefined;
+}
+export function selfProfileConfigPath(stateDir) {
+    return path.join(stateDir, SELF_PROFILE_CONFIG_FILE);
+}
+export function selfProfileDiagnosticsDir(stateDir) {
+    return path.join(stateDir, "diagnostics", "sync-runner");
+}
+/**
+ * Environment variables win over the config file; anything missing or invalid
+ * falls back to the defaults. Capture stays off unless one of them turns it on.
+ */
+export function resolveSelfProfileConfig(env, stateDir, readFile = (file) => fs.readFileSync(file, "utf8")) {
+    let file = {};
+    try {
+        const parsed = JSON.parse(readFile(selfProfileConfigPath(stateDir)));
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+            file = parsed;
+        }
+    }
+    catch {
+        /* no config file, or not JSON: use env and defaults */
+    }
+    const captureEnabled = enabledFlag(env[SELF_PROFILE_ENV]) ?? enabledFlag(file.enabled) ?? false;
+    const cpuCores = positiveNumber(env[SELF_PROFILE_CPU_CORES_ENV]) ??
+        positiveNumber(file.cpuCores) ??
+        DEFAULT_SELF_PROFILE_CPU_CORES;
+    const rssMb = positiveNumber(env[SELF_PROFILE_RSS_MB_ENV]) ??
+        positiveNumber(file.rssMb) ??
+        DEFAULT_SELF_PROFILE_RSS_MB;
+    return { captureEnabled, cpuCores, rssBytes: Math.round(rssMb * 1024 * 1024) };
+}
+// ---------------------------------------------------------------------------
+// Activity counters fed by the watch loop
+// ---------------------------------------------------------------------------
+/**
+ * Group a watcher path for the per-prefix event rate: two segments, or three
+ * under `companies/` so one company's areas stay apart.
+ */
+export function eventPathPrefix(relativePath) {
+    const segments = relativePath.split(/[\\/]+/).filter((segment) => segment !== "");
+    if (segments.length === 0)
+        return ".";
+    const depth = segments[0] === "companies" ? 3 : 2;
+    // A file directly under the prefix depth reports its parent folder.
+    const take = Math.min(depth, Math.max(1, segments.length - 1));
+    return segments.slice(0, take).join("/");
+}
+export class SelfProfileActivity {
+    now;
+    startedAt;
+    eventsByPrefix = new Map();
+    passes = 0;
+    constructor(now) {
+        this.now = now;
+        this.startedAt = now();
+    }
+    recordEvent(relativePath) {
+        let prefix = eventPathPrefix(relativePath);
+        if (!this.eventsByPrefix.has(prefix) && this.eventsByPrefix.size >= MAX_EVENT_PREFIXES) {
+            prefix = "(other)";
+        }
+        this.eventsByPrefix.set(prefix, (this.eventsByPrefix.get(prefix) ?? 0) + 1);
+    }
+    recordPass() {
+        this.passes += 1;
+    }
+    snapshot() {
+        const minutes = Math.max((this.now() - this.startedAt) / 60_000, 1 / 60);
+        const rate = (count) => Math.round((count / minutes) * 100) / 100;
+        const ranked = [...this.eventsByPrefix.entries()].sort((a, b) => b[1] - a[1]);
+        let events = 0;
+        const eventsPerMinuteByPrefix = {};
+        for (const [prefix, count] of ranked) {
+            events += count;
+            eventsPerMinuteByPrefix[prefix] = rate(count);
+        }
+        return {
+            minutes: Math.round(minutes * 10) / 10,
+            events,
+            eventsPerMinuteByPrefix,
+            passes: this.passes,
+            passesPerMinute: rate(this.passes),
+        };
+    }
+}
+const heavyKind = heavyWatchKind;
+/**
+ * Report whether any OS watch is on, or (for a recursive watch) above,
+ * workspace/worktrees, a node_modules folder, or a nested .git folder. The
+ * walk under recursive roots is bounded so a large tree cannot stall the
+ * runner while it writes diagnostics.
+ */
+export function assessWatchCoverage(hqRoot, watched, readDir = (dir) => fs.readdirSync(dir, { withFileTypes: true })) {
+    const root = path.resolve(hqRoot);
+    const found = new Map();
+    const note = (abs, kind) => {
+        const relative = path.relative(root, abs);
+        // Never report an absolute or out-of-root path in the summary.
+        const rel = relative.startsWith("..") || path.isAbsolute(relative)
+            ? OUTSIDE_HQ_ROOT
+            : relative.split(path.sep).join("/") || ".";
+        if (!found.has(rel))
+            found.set(rel, kind);
+    };
+    let budget = COVERAGE_SCAN_MAX_DIRS;
+    let scanTruncated = false;
+    const scanned = new Set();
+    for (const entry of watched) {
+        const abs = path.resolve(entry.path);
+        const rel = path.relative(root, abs);
+        const kind = heavyKind(rel);
+        if (kind) {
+            note(abs, kind);
+            continue;
+        }
+        if (!entry.recursive)
+            continue;
+        const stack = [abs];
+        while (stack.length > 0) {
+            const dir = stack.pop();
+            if (scanned.has(dir))
+                continue;
+            scanned.add(dir);
+            if (budget <= 0) {
+                scanTruncated = true;
+                break;
+            }
+            budget -= 1;
+            let entries;
+            try {
+                entries = readDir(dir);
+            }
+            catch {
+                continue;
+            }
+            for (const child of entries) {
+                if (!child.isDirectory())
+                    continue;
+                const childAbs = path.join(dir, child.name);
+                const childKind = heavyKind(path.relative(root, childAbs));
+                if (childKind)
+                    note(childAbs, childKind);
+                else
+                    stack.push(childAbs);
+            }
+        }
+    }
+    const kinds = new Set(found.values());
+    return {
+        watchedPathCount: watched.length,
+        recursiveRootCount: watched.filter((entry) => entry.recursive).length,
+        watchesWorktrees: kinds.has("worktrees"),
+        watchesNodeModules: kinds.has("node_modules"),
+        watchesNestedGit: kinds.has("git"),
+        examples: [...found.keys()].sort().slice(0, COVERAGE_SAMPLE_PATHS),
+        scanTruncated,
+    };
+}
+/**
+ * Pure threshold state. `observe` takes one sample and returns the reading;
+ * `trip` reports a reason only when the runner is over a threshold, a warning
+ * has not already been given for this episode, and the cooldown has passed.
+ */
+export class SelfProfileThresholds {
+    config;
+    windowMs;
+    cooldownMs;
+    samples = [];
+    armed = true;
+    lastWarnedAt = null;
+    constructor(config, windowMs = SELF_PROFILE_CPU_WINDOW_MS, cooldownMs = SELF_PROFILE_WARNING_COOLDOWN_MS) {
+        this.config = config;
+        this.windowMs = windowMs;
+        this.cooldownMs = cooldownMs;
+    }
+    observe(at, cpu, rssBytes) {
+        this.samples.push({ at, cpuMicros: cpu.user + cpu.system });
+        // Keep the newest sample that is at least one window old as the baseline.
+        while (this.samples.length > 2 && this.samples[1].at <= at - this.windowMs) {
+            this.samples.shift();
+        }
+        const oldest = this.samples[0];
+        const newest = this.samples[this.samples.length - 1];
+        const span = newest.at - oldest.at;
+        const cpuCores = span >= this.windowMs
+            ? (newest.cpuMicros - oldest.cpuMicros) / 1000 / span
+            : null;
+        return { cpuCores, rssBytes };
+    }
+    trip(at, reading) {
+        const cpuOver = reading.cpuCores !== null && reading.cpuCores > this.config.cpuCores;
+        const rssOver = reading.rssBytes > this.config.rssBytes;
+        if (!cpuOver && !rssOver) {
+            // Re-arm only once a full CPU window is back under the threshold.
+            if (reading.cpuCores !== null)
+                this.armed = true;
+            return null;
+        }
+        if (!this.armed)
+            return null;
+        if (this.lastWarnedAt !== null && at - this.lastWarnedAt < this.cooldownMs)
+            return null;
+        this.armed = false;
+        this.lastWarnedAt = at;
+        return cpuOver && rssOver ? "cpu+rss" : cpuOver ? "cpu" : "rss";
+    }
+}
+const HQ_ROOT_TOKEN = "<hq>";
+const HOME_TOKEN = "~";
+const OUTSIDE_HQ_ROOT = "(outside HQ root)";
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function isAbsoluteAnyPlatform(value) {
+    return path.isAbsolute(value) || path.win32.isAbsolute(value) || /^[A-Za-z]:[\\/]/.test(value);
+}
+/** Spellings of one absolute path that can appear in a profile or message. */
+function pathSpellings(abs) {
+    const trimmed = abs.replace(/[\\/]+$/, "");
+    // A filesystem root or an empty value would match everything.
+    if (trimmed.length < 2 || !isAbsoluteAnyPlatform(abs))
+        return [];
+    const forward = trimmed.replace(/\\/g, "/");
+    const backward = trimmed.replace(/\//g, "\\");
+    const spellings = new Set([trimmed, forward, backward]);
+    try {
+        spellings.add(pathToFileURL(trimmed).href);
+    }
+    catch {
+        /* not convertible on this platform */
+    }
+    // JSON text escapes each backslash.
+    for (const spelling of [...spellings])
+        spellings.add(JSON.stringify(spelling).slice(1, -1));
+    return [...spellings].sort((a, b) => b.length - a.length);
+}
+/**
+ * Replace every spelling of the HQ root with `<hq>` and of the home folder
+ * with `~`. Matching ignores letter case, because macOS and Windows paths do.
+ */
+export function scrubLocalPaths(text, redaction) {
+    let out = text;
+    for (const [abs, token] of [
+        [redaction.hqRoot, HQ_ROOT_TOKEN],
+        [redaction.homeDir, HOME_TOKEN],
+    ]) {
+        for (const spelling of pathSpellings(abs)) {
+            out = out.replace(new RegExp(escapeRegExp(spelling), "gi"), token);
+        }
+    }
+    return out;
+}
+function relativeInside(root, abs) {
+    const rel = path.relative(path.resolve(root), path.resolve(abs));
+    if (rel === "")
+        return ".";
+    if (rel.startsWith("..") || path.isAbsolute(rel))
+        return null;
+    return rel.split(path.sep).join("/");
+}
+/**
+ * Rewrite a script URL or file path from a CPU profile: inside the HQ root it
+ * becomes relative to the root, inside the home folder it starts with `~/`.
+ * Non-file URLs such as `node:internal/...` are kept.
+ */
+export function redactProfilePath(value, redaction) {
+    let candidate = value;
+    if (/^file:/i.test(value)) {
+        try {
+            candidate = fileURLToPath(value);
+        }
+        catch {
+            return scrubLocalPaths(value, redaction);
+        }
+    }
+    if (isAbsoluteAnyPlatform(candidate)) {
+        const inRoot = relativeInside(redaction.hqRoot, candidate);
+        if (inRoot !== null)
+            return inRoot;
+        const inHome = relativeInside(redaction.homeDir, candidate);
+        if (inHome !== null)
+            return inHome === "." ? HOME_TOKEN : `${HOME_TOKEN}/${inHome}`;
+        return scrubLocalPaths(value, redaction);
+    }
+    const scheme = /^([a-z][a-z0-9+.-]*):/i.exec(value)?.[1]?.toLowerCase();
+    // A data: or blob: URL carries the script body itself; other URLs can carry
+    // credentials in the query string or the user-info part.
+    if (scheme === "data" || scheme === "blob")
+        return `${scheme}:(omitted)`;
+    if (scheme && scheme !== "node") {
+        const stripped = value.replace(/[?#].*$/s, "").replace(/^([a-z][a-z0-9+.-]*:\/\/)[^/@]*@/i, "$1");
+        return scrubLocalPaths(stripped, redaction);
+    }
+    return scrubLocalPaths(value, redaction);
+}
+function finiteNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+function numberArray(value) {
+    return Array.isArray(value) ? value.filter((item) => typeof item === "number") : undefined;
+}
+/**
+ * Copy only the fields DevTools needs from a V8 CPU profile, with every script
+ * URL rewritten by `redactProfilePath`. Anything else V8 adds is dropped.
+ */
+export function redactCpuProfile(profile, redaction) {
+    if (!profile || typeof profile !== "object")
+        return null;
+    const source = profile;
+    const nodes = Array.isArray(source.nodes) ? source.nodes : [];
+    return {
+        nodes: nodes.map((raw) => {
+            const node = (raw && typeof raw === "object" ? raw : {});
+            const frame = (node.callFrame && typeof node.callFrame === "object" ? node.callFrame : {});
+            const positionTicks = Array.isArray(node.positionTicks)
+                ? node.positionTicks.map((tick) => {
+                    const entry = (tick && typeof tick === "object" ? tick : {});
+                    return { line: finiteNumber(entry.line) ?? 0, ticks: finiteNumber(entry.ticks) ?? 0 };
+                })
+                : undefined;
+            return {
+                id: finiteNumber(node.id) ?? 0,
+                callFrame: {
+                    functionName: scrubLocalPaths(String(frame.functionName ?? ""), redaction),
+                    scriptId: String(frame.scriptId ?? ""),
+                    url: redactProfilePath(String(frame.url ?? ""), redaction),
+                    lineNumber: finiteNumber(frame.lineNumber) ?? -1,
+                    columnNumber: finiteNumber(frame.columnNumber) ?? -1,
+                },
+                hitCount: finiteNumber(node.hitCount) ?? 0,
+                children: numberArray(node.children),
+                positionTicks,
+            };
+        }),
+        startTime: finiteNumber(source.startTime) ?? 0,
+        endTime: finiteNumber(source.endTime) ?? 0,
+        samples: numberArray(source.samples) ?? [],
+        timeDeltas: numberArray(source.timeDeltas) ?? [],
+    };
+}
+function post(session, method) {
+    return new Promise((resolve, reject) => {
+        session.post(method, (err, result) => (err ? reject(err) : resolve(result)));
+    });
+}
+function captureStamp(at) {
+    return new Date(at).toISOString().replace(/[:.]/g, "-");
+}
+function directorySize(dir) {
+    let total = 0;
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const abs = path.join(dir, entry.name);
+        if (entry.isDirectory())
+            total += directorySize(abs);
+        else if (entry.isFile())
+            total += fs.statSync(abs).size;
+    }
+    return total;
+}
+/**
+ * Keep the newest `keep` capture folders and, within those, delete the oldest
+ * until the total fits `maxTotalBytes`. The newest folder is always kept.
+ * Folders that are not self-profile captures are left alone.
+ */
+export function pruneSelfProfileCaptures(diagnosticsDir, keep = SELF_PROFILE_KEEP_CAPTURES, maxTotalBytes = SELF_PROFILE_MAX_TOTAL_BYTES) {
+    let names;
+    try {
+        names = fs.readdirSync(diagnosticsDir, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory() && entry.name.startsWith(CAPTURE_DIR_PREFIX))
+            .map((entry) => entry.name)
+            .sort();
+    }
+    catch {
+        return [];
+    }
+    const removed = [];
+    const remove = (name) => {
+        fs.rmSync(path.join(diagnosticsDir, name), { recursive: true, force: true });
+        removed.push(name);
+    };
+    while (names.length > Math.max(keep, 1))
+        remove(names.shift());
+    let total = names.reduce((sum, name) => sum + directorySize(path.join(diagnosticsDir, name)), 0);
+    while (names.length > 1 && total > maxTotalBytes) {
+        const name = names.shift();
+        total -= directorySize(path.join(diagnosticsDir, name));
+        remove(name);
+    }
+    return removed;
+}
+export function latestSelfProfileCapture(stateDir) {
+    const dir = selfProfileDiagnosticsDir(stateDir);
+    try {
+        const names = fs.readdirSync(dir, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory() && entry.name.startsWith(CAPTURE_DIR_PREFIX))
+            .map((entry) => entry.name)
+            .sort();
+        const newest = names[names.length - 1];
+        return newest ? path.join(dir, newest) : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The redacted summary: counts, rates, thresholds, backend, platform and
+ * versions, and paths relative to the HQ root. No absolute paths, file
+ * contents, environment values or tokens.
+ */
+export function buildSelfProfileSummary(options, inputs) {
+    const coverage = assessWatchCoverage(inputs.hqRoot, inputs.watchedDirectories, options.readDir);
+    return {
+        schema: "hq-sync-runner-self-profile.v2",
+        capturedAt: new Date(options.now()).toISOString(),
+        uploaded: false,
+        redacted: true,
+        trip: {
+            reason: options.reason,
+            cpuCoresAveraged10m: options.reading.cpuCores,
+            rssBytes: options.reading.rssBytes,
+            cpuCoresThreshold: options.config.cpuCores,
+            rssBytesThreshold: options.config.rssBytes,
+        },
+        watch: {
+            backend: inputs.watchBackend,
+            mode: inputs.watchMode,
+            ...coverage,
+        },
+        activity: {
+            minutesObserved: inputs.activity.minutes,
+            events: inputs.activity.events,
+            eventsPerMinuteByPrefix: inputs.activity.eventsPerMinuteByPrefix,
+            passes: inputs.activity.passes,
+            passesPerMinute: inputs.activity.passesPerMinute,
+            telemetryEvents: inputs.telemetryEvents,
+        },
+        platform: {
+            os: process.platform,
+            arch: process.arch,
+            release: os.release(),
+            cpus: os.cpus().length,
+            node: process.versions.node,
+            v8: process.versions.v8,
+            runner: options.runnerVersion ?? null,
+        },
+    };
+}
+async function captureCpuProfile(session, file, durationMs, maxBytes, sleep, redaction) {
+    await post(session, "Profiler.enable");
+    await post(session, "Profiler.start");
+    let result;
+    try {
+        await sleep(durationMs);
+    }
+    finally {
+        // Always stop the profiler, even when the wait is interrupted.
+        result = (await post(session, "Profiler.stop"));
+        await post(session, "Profiler.disable").catch(() => undefined);
+    }
+    // Rewrite paths field by field, then scrub the text once more as a backstop.
+    const body = scrubLocalPaths(JSON.stringify(redactCpuProfile(result?.profile, redaction)), redaction);
+    if (Buffer.byteLength(body) > maxBytes) {
+        return `cpu profile skipped: ${Buffer.byteLength(body)} bytes is over the ${maxBytes} byte limit`;
+    }
+    fs.writeFileSync(file, body, { mode: 0o600 });
+    return null;
+}
+/**
+ * Write one capture folder: a redacted summary and a redacted CPU profile.
+ * There is no heap snapshot: a snapshot holds the whole JS heap, including
+ * tokens and synced file contents. Everything is local; the folder is pruned
+ * to the retention limits before and after writing.
+ */
+export async function captureSelfProfile(options) {
+    const keep = options.keep ?? SELF_PROFILE_KEEP_CAPTURES;
+    const maxTotalBytes = options.maxTotalBytes ?? SELF_PROFILE_MAX_TOTAL_BYTES;
+    const diagnosticsDir = selfProfileDiagnosticsDir(options.stateDir);
+    fs.mkdirSync(diagnosticsDir, { recursive: true, mode: 0o700 });
+    // Leave room for the new folder inside the keep limit.
+    pruneSelfProfileCaptures(diagnosticsDir, Math.max(keep - 1, 1), maxTotalBytes);
+    const dir = path.join(diagnosticsDir, `${CAPTURE_DIR_PREFIX}${captureStamp(options.now())}-${options.reason.replace("+", "-")}`);
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const files = [];
+    const notes = [];
+    const inputs = options.summary();
+    const redaction = {
+        hqRoot: inputs.hqRoot,
+        homeDir: options.homeDir ?? os.homedir(),
+    };
+    const summary = buildSelfProfileSummary(options, inputs);
+    const writeSummary = () => {
+        const text = JSON.stringify({ ...summary, files: [...files], notes: notes.map((note) => scrubLocalPaths(note, redaction)) }, null, 2);
+        fs.writeFileSync(path.join(dir, "summary.json"), `${scrubLocalPaths(text, redaction)}\n`, {
+            mode: 0o600,
+        });
+    };
+    // Write the summary first so a crash during profiling still leaves it.
+    writeSummary();
+    const session = (options.createSession ?? (() => new Session()))();
+    session.connect();
+    try {
+        const skipped = await captureCpuProfile(session, path.join(dir, "cpu.cpuprofile"), options.cpuProfileMs ?? SELF_PROFILE_CPU_PROFILE_MS, options.maxCpuProfileBytes ?? SELF_PROFILE_MAX_CPU_PROFILE_BYTES, options.sleep, redaction);
+        if (skipped)
+            notes.push(skipped);
+        else
+            files.push("cpu.cpuprofile");
+    }
+    catch (err) {
+        notes.push(`cpu profile failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    finally {
+        try {
+            session.disconnect();
+        }
+        catch {
+            /* already disconnected */
+        }
+    }
+    writeSummary();
+    files.unshift("summary.json");
+    pruneSelfProfileCaptures(diagnosticsDir, keep, maxTotalBytes);
+    return { dir, files, notes };
+}
+// ---------------------------------------------------------------------------
+// Messages
+// ---------------------------------------------------------------------------
+/** Show the home folder as `~` in log lines and command output. */
+function displayPath(abs, homeDir = os.homedir()) {
+    const inHome = relativeInside(homeDir, abs);
+    if (inHome === null || pathSpellings(homeDir).length === 0)
+        return abs;
+    return inHome === "." ? HOME_TOKEN : `${HOME_TOKEN}/${inHome}`;
+}
+const DIAGNOSTICS_HINT = "Run hq-sync-runner --diagnostics to print a redacted summary you can paste into a bug report.";
+function describeTrip(reason, reading, config) {
+    const parts = [];
+    if (reason !== "rss" && reading.cpuCores !== null) {
+        parts.push(`CPU averaged ${Math.round(reading.cpuCores * 100)}% of one core over 10 minutes (limit ${Math.round(config.cpuCores * 100)}%)`);
+    }
+    if (reason !== "cpu") {
+        parts.push(`memory is ${Math.round(reading.rssBytes / 1024 / 1024)} MB (limit ${Math.round(config.rssBytes / 1024 / 1024)} MB)`);
+    }
+    return parts.join(" and ");
+}
+export function selfProfileWarningLine(reason, reading, config, stateDir) {
+    if (config.captureEnabled) {
+        return (`hq-sync-runner: high resource use: ${describeTrip(reason, reading, config)}. ` +
+            `A profile was saved recently, so no new one was taken. ${DIAGNOSTICS_HINT}\n`);
+    }
+    return (`hq-sync-runner: high resource use: ${describeTrip(reason, reading, config)}. ` +
+        `To save a local CPU profile next time, set ${SELF_PROFILE_ENV}=1 (or "enabled": true in ${displayPath(selfProfileConfigPath(stateDir))}) ` +
+        `and restart HQ Sync; it stays on this computer and is never uploaded.\n`);
+}
+export function selfProfileCapturedLine(reason, reading, config, result) {
+    return (`hq-sync-runner: high resource use: ${describeTrip(reason, reading, config)}. ` +
+        `Saved a local CPU profile in ${displayPath(result.dir)}; it stays on this computer and nothing was uploaded. ` +
+        `${DIAGNOSTICS_HINT}\n`);
+}
+function unrefTimer(handle) {
+    handle.unref?.();
+}
+export function startSelfProfileSampler(options) {
+    const thresholds = new SelfProfileThresholds(options.config);
+    const capture = options.capture ?? captureSelfProfile;
+    const captureCooldownMs = options.captureCooldownMs ?? SELF_PROFILE_CAPTURE_COOLDOWN_MS;
+    const pendingSleeps = new Set();
+    let stopped = false;
+    let inFlight = null;
+    let lastCaptureAt = null;
+    const sleep = options.sleep ?? ((ms) => new Promise((resolve) => {
+        const timer = setTimeout(() => {
+            pendingSleeps.delete(finish);
+            resolve();
+        }, ms);
+        unrefTimer(timer);
+        const finish = () => {
+            clearTimeout(timer);
+            resolve();
+        };
+        pendingSleeps.add(finish);
+    }));
+    const sample = () => {
+        if (stopped)
+            return;
+        const at = options.now();
+        let reading;
+        try {
+            reading = thresholds.observe(at, options.cpuUsage(), options.rssBytes());
+        }
+        catch {
+            return;
+        }
+        const reason = thresholds.trip(at, reading);
+        if (!reason)
+            return;
+        const canCapture = options.config.captureEnabled &&
+            inFlight === null &&
+            (lastCaptureAt === null || at - lastCaptureAt >= captureCooldownMs);
+        if (!canCapture) {
+            options.write(selfProfileWarningLine(reason, reading, options.config, options.stateDir));
+            return;
+        }
+        lastCaptureAt = at;
+        inFlight = capture({
+            stateDir: options.stateDir,
+            reason,
+            reading,
+            config: options.config,
+            summary: options.summary,
+            now: options.now,
+            sleep,
+            runnerVersion: options.runnerVersion,
+        }).then((result) => {
+            options.write(selfProfileCapturedLine(reason, reading, options.config, result));
+        }, (err) => {
+            options.write(`hq-sync-runner: high resource use: ${describeTrip(reason, reading, options.config)}. ` +
+                `Saving a profile failed (${err instanceof Error ? err.message : String(err)}); nothing was uploaded.\n`);
+        }).catch(() => {
+            /* a failed log write must not become an unhandled rejection */
+        }).finally(() => {
+            inFlight = null;
+        });
+    };
+    const every = options.every ?? ((ms, run) => {
+        const timer = setInterval(run, ms);
+        unrefTimer(timer);
+        return () => clearInterval(timer);
+    });
+    const cancel = every(options.intervalMs ?? SELF_PROFILE_SAMPLE_INTERVAL_MS, () => {
+        try {
+            sample();
+        }
+        catch {
+            /* diagnostics must never affect sync */
+        }
+    });
+    // Baseline sample so the first window closes ten minutes after start.
+    sample();
+    return {
+        sample,
+        idle: async () => {
+            await inFlight;
+        },
+        stop: () => {
+            stopped = true;
+            cancel();
+            // End a running CPU profile early so shutdown is not held for a minute.
+            for (const finish of pendingSleeps)
+                finish();
+            pendingSleeps.clear();
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// --diagnostics
+// ---------------------------------------------------------------------------
+export function printSelfProfileDiagnostics(stateDir, out, homeDir = os.homedir()) {
+    const latest = latestSelfProfileCapture(stateDir);
+    if (!latest) {
+        out.write(`No sync-runner self-profile captures in ${displayPath(selfProfileDiagnosticsDir(stateDir), homeDir)}.\n` +
+            `Capture is off by default. Set ${SELF_PROFILE_ENV}=1 (or "enabled": true in ${displayPath(selfProfileConfigPath(stateDir), homeDir)}) and restart HQ Sync to turn it on.\n`);
+        return 0;
+    }
+    let summary;
+    try {
+        summary = fs.readFileSync(path.join(latest, "summary.json"), "utf8");
+    }
+    catch {
+        out.write(`Latest capture ${displayPath(latest, homeDir)} has no readable summary.json.\n`);
+        return 1;
+    }
+    // Captures from older runner versions were not redacted; scrub the home path here too.
+    summary = scrubLocalPaths(summary, { hqRoot: "", homeDir });
+    out.write(`Latest capture: ${displayPath(latest, homeDir)}\n` +
+        `The summary below is redacted: counts, rates, versions and paths relative to the HQ root. ` +
+        `Paste it into a bug report. The profile folder stays on this computer and has not been uploaded.\n\n`);
+    out.write(summary.endsWith("\n") ? summary : `${summary}\n`);
+    return 0;
+}
+/** The runner's package version, or undefined when package.json is not readable. */
+export function readRunnerVersion() {
+    try {
+        const pkg = JSON.parse(fs.readFileSync(new URL("../../package.json", import.meta.url), "utf8"));
+        return typeof pkg.version === "string" ? pkg.version : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=sync-runner-self-profile.js.map