@unbrained/pm-cli 2026.3.12 → 2026.5.1-2

package/dist/core/test/background-runs.js

@@ -0,0 +1,760 @@
+import fs from "node:fs/promises";
+import { spawn } from "node:child_process";
+import { createHash, randomBytes } from "node:crypto";
+import path from "node:path";
+import { ensureDir, pathExists, readFileIfExists, writeFileAtomic } from "../fs/fs-utils.js";
+import { PmCliError } from "../shared/errors.js";
+import { EXIT_CODE } from "../shared/constants.js";
+import { nowIso } from "../shared/time.js";
+import { getTestRunRecordPath, getTestRunResultPath, getTestRunStderrPath, getTestRunStdoutPath, getTestRunsPath, getTestRunsRecordsPath, getTestRunsResultsPath, getTestRunsStderrPath, getTestRunsStdoutPath, } from "../store/paths.js";
+const BACKGROUND_RUN_ACTIVE_STATUSES = new Set(["queued", "running"]);
+const BACKGROUND_RUN_TERMINAL_STATUSES = new Set(["passed", "failed", "stopped", "canceled"]);
+const DEFAULT_BACKGROUND_RUN_RESOURCE_SNAPSHOT_INTERVAL_MS = 3000;
+const DEFAULT_BACKGROUND_RUN_FORCE_KILL_DELAY_MS = 3000;
+const DEFAULT_BACKGROUND_RUN_HEARTBEAT_STALE_MS = 30000;
+const DEFAULT_BACKGROUND_RUN_LOG_TAIL_LINES = 100;
+const PROC_STAT_TICKS_PER_SECOND = 100;
+function nowMs() {
+    return Date.now();
+}
+function normalizeCommandArgs(args) {
+    return args.map((entry) => entry.trim()).filter((entry) => entry.length > 0);
+}
+function summarizeCommandLabel(args) {
+    const joined = args.join(" ").replaceAll(/\s+/g, " ").trim();
+    if (joined.length <= 180) {
+        return joined;
+    }
+    return `${joined.slice(0, 177)}...`;
+}
+function buildRunId() {
+    const timePart = Date.now().toString(36);
+    const randomPart = randomBytes(3).toString("hex");
+    return `tr-${timePart}-${randomPart}`;
+}
+export function buildBackgroundTestRunFingerprint(kind, commandArgs, pmRoot) {
+    const payload = {
+        kind,
+        command: normalizeCommandArgs(commandArgs),
+        pm_root: path.resolve(pmRoot),
+    };
+    return createHash("sha256").update(JSON.stringify(payload)).digest("hex");
+}
+function isPidRunning(pid) {
+    if (!Number.isInteger(pid) || !pid || pid <= 0) {
+        return false;
+    }
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        const code = typeof error === "object" && error !== null && "code" in error ? error.code : undefined;
+        return code === "EPERM";
+    }
+}
+async function ensureBackgroundRunStorage(pmRoot) {
+    await ensureDir(getTestRunsPath(pmRoot));
+    await ensureDir(getTestRunsRecordsPath(pmRoot));
+    await ensureDir(getTestRunsStdoutPath(pmRoot));
+    await ensureDir(getTestRunsStderrPath(pmRoot));
+    await ensureDir(getTestRunsResultsPath(pmRoot));
+}
+async function parseBackgroundRunRecord(raw, recordPath) {
+    try {
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== "object" || typeof parsed.id !== "string") {
+            throw new Error("invalid run record payload");
+        }
+        return parsed;
+    }
+    catch (error) {
+        throw new PmCliError(`Failed to parse background test run record at ${recordPath}: ${error instanceof Error ? error.message : String(error)}`, EXIT_CODE.GENERIC_FAILURE);
+    }
+}
+async function writeBackgroundRunRecord(pmRoot, record) {
+    const next = {
+        ...record,
+        updated_at: nowIso(),
+    };
+    await writeFileAtomic(getTestRunRecordPath(pmRoot, record.id), `${JSON.stringify(next, null, 2)}\n`);
+}
+export async function readBackgroundTestRunRecord(pmRoot, runId) {
+    const recordPath = getTestRunRecordPath(pmRoot, runId);
+    const raw = await readFileIfExists(recordPath);
+    if (!raw) {
+        return null;
+    }
+    return parseBackgroundRunRecord(raw, recordPath);
+}
+async function listBackgroundRunRecordPaths(pmRoot) {
+    const recordsRoot = getTestRunsRecordsPath(pmRoot);
+    if (!(await pathExists(recordsRoot))) {
+        return [];
+    }
+    const entries = await fs.readdir(recordsRoot, { withFileTypes: true });
+    return entries
+        .filter((entry) => entry.isFile() && entry.name.endsWith(".json"))
+        .map((entry) => path.join(recordsRoot, entry.name))
+        .sort((left, right) => right.localeCompare(left));
+}
+async function readLinuxRssBytes(pid) {
+    if (process.platform !== "linux") {
+        return undefined;
+    }
+    try {
+        const raw = await fs.readFile(`/proc/${pid}/status`, "utf8");
+        const match = raw.match(/^VmRSS:\s+(\d+)\s+kB$/m);
+        if (!match) {
+            return undefined;
+        }
+        const value = Number.parseInt(match[1] ?? "", 10);
+        if (!Number.isFinite(value)) {
+            return undefined;
+        }
+        return value * 1024;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function readLinuxCpuSeconds(pid) {
+    if (process.platform !== "linux") {
+        return {};
+    }
+    try {
+        const raw = await fs.readFile(`/proc/${pid}/stat`, "utf8");
+        const closeParenIndex = raw.lastIndexOf(")");
+        if (closeParenIndex < 0) {
+            return {};
+        }
+        const remainder = raw.slice(closeParenIndex + 2).trim();
+        const parts = remainder.split(/\s+/);
+        const utimeTicks = Number.parseInt(parts[11] ?? "", 10);
+        const stimeTicks = Number.parseInt(parts[12] ?? "", 10);
+        if (!Number.isFinite(utimeTicks) || !Number.isFinite(stimeTicks)) {
+            return {};
+        }
+        return {
+            cpu_user_seconds: utimeTicks / PROC_STAT_TICKS_PER_SECOND,
+            cpu_system_seconds: stimeTicks / PROC_STAT_TICKS_PER_SECOND,
+        };
+    }
+    catch {
+        return {};
+    }
+}
+async function buildResourceSnapshot(record) {
+    const pid = record.child_pid ?? record.worker_pid;
+    if (!isPidRunning(pid)) {
+        return undefined;
+    }
+    const rssBytes = await readLinuxRssBytes(pid);
+    const cpu = await readLinuxCpuSeconds(pid);
+    const startedAtMs = record.started_at ? Date.parse(record.started_at) : Number.NaN;
+    const uptimeSeconds = Number.isFinite(startedAtMs) ? Math.max(0, (nowMs() - startedAtMs) / 1000) : undefined;
+    return {
+        recorded_at: nowIso(),
+        rss_bytes: rssBytes,
+        cpu_user_seconds: cpu.cpu_user_seconds,
+        cpu_system_seconds: cpu.cpu_system_seconds,
+        uptime_seconds: uptimeSeconds,
+    };
+}
+function readCount(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+function evaluateWorkerResult(kind, payload) {
+    if (!payload || typeof payload !== "object") {
+        return {
+            summary: {
+                passed: 0,
+                failed: 1,
+                skipped: 0,
+            },
+            parsedResult: null,
+        };
+    }
+    const record = payload;
+    if (kind === "test-all") {
+        const totals = (record.totals ?? {});
+        return {
+            summary: {
+                items: typeof totals.items === "number" ? totals.items : undefined,
+                linked_tests: typeof totals.linked_tests === "number" ? totals.linked_tests : undefined,
+                passed: readCount(totals.passed),
+                failed: readCount(totals.failed),
+                skipped: readCount(totals.skipped),
+                fail_on_skipped_triggered: record.fail_on_skipped_triggered === true ? true : undefined,
+            },
+            parsedResult: payload,
+        };
+    }
+    const runResults = Array.isArray(record.run_results) ? record.run_results : [];
+    let passed = 0;
+    let failed = 0;
+    let skipped = 0;
+    for (const entry of runResults) {
+        if (!entry || typeof entry !== "object") {
+            continue;
+        }
+        const status = entry.status;
+        if (status === "passed") {
+            passed += 1;
+            continue;
+        }
+        if (status === "failed") {
+            failed += 1;
+            continue;
+        }
+        skipped += 1;
+    }
+    return {
+        summary: {
+            passed,
+            failed,
+            skipped,
+            fail_on_skipped_triggered: record.fail_on_skipped_triggered === true ? true : undefined,
+        },
+        parsedResult: payload,
+    };
+}
+function parseProgressLine(stderrLine) {
+    const line = stderrLine.trim();
+    if (line.length === 0) {
+        return null;
+    }
+    const match = line.match(/\[pm test\]\s+linked-test\s+(\d+)\/(\d+)\s+(start|running|end)(?:.*elapsed_ms=(\d+))?/i);
+    if (!match) {
+        return null;
+    }
+    const index = Number.parseInt(match[1] ?? "", 10);
+    const total = Number.parseInt(match[2] ?? "", 10);
+    const elapsed = match[4] ? Number.parseInt(match[4], 10) : undefined;
+    return {
+        linked_test_index: Number.isFinite(index) ? index : undefined,
+        linked_test_total: Number.isFinite(total) ? total : undefined,
+        elapsed_ms: Number.isFinite(elapsed) ? elapsed : undefined,
+        heartbeat_at: nowIso(),
+        phase: match[3]?.toLowerCase() === "end" ? "finished" : "running",
+    };
+}
+function splitLines(value) {
+    return value
+        .split(/\r?\n/)
+        .map((entry) => entry.trimEnd())
+        .filter((entry) => entry.length > 0);
+}
+function tailLines(value, limit) {
+    if (limit <= 0) {
+        return [];
+    }
+    const lines = splitLines(value);
+    if (lines.length <= limit) {
+        return lines;
+    }
+    return lines.slice(lines.length - limit);
+}
+async function resolveBackgroundCliEntry(cwd) {
+    const configured = process.env.PM_BACKGROUND_CLI_ENTRY?.trim();
+    if (configured && configured.length > 0) {
+        const resolvedConfigured = path.resolve(cwd, configured);
+        if (await pathExists(resolvedConfigured)) {
+            return resolvedConfigured;
+        }
+    }
+    const distEntry = path.resolve(cwd, "dist", "cli.js");
+    if (await pathExists(distEntry)) {
+        return distEntry;
+    }
+    const argvEntry = process.argv[1]?.trim();
+    if (argvEntry && argvEntry.length > 0) {
+        const resolvedArgvEntry = path.resolve(cwd, argvEntry);
+        if (await pathExists(resolvedArgvEntry)) {
+            return resolvedArgvEntry;
+        }
+    }
+    throw new PmCliError("Unable to resolve a CLI entrypoint for background test runs. Build the project or set PM_BACKGROUND_CLI_ENTRY.", EXIT_CODE.GENERIC_FAILURE);
+}
+async function refreshRunIfStale(pmRoot, record) {
+    if (!BACKGROUND_RUN_ACTIVE_STATUSES.has(record.status)) {
+        return record;
+    }
+    const workerAlive = isPidRunning(record.worker_pid);
+    if (workerAlive) {
+        return record;
+    }
+    if (record.finished_at) {
+        return record;
+    }
+    const next = {
+        ...record,
+        status: "failed",
+        finished_at: nowIso(),
+        error: record.error ?? "Background test run worker exited before writing terminal status.",
+    };
+    await writeBackgroundRunRecord(pmRoot, next);
+    return next;
+}
+export async function startBackgroundTestRun(options) {
+    await ensureBackgroundRunStorage(options.pmRoot);
+    const normalizedArgs = normalizeCommandArgs(options.commandArgs);
+    if (normalizedArgs.length === 0) {
+        throw new PmCliError("Background test run requires command arguments.", EXIT_CODE.USAGE);
+    }
+    const fingerprint = buildBackgroundTestRunFingerprint(options.kind, normalizedArgs, options.pmRoot);
+    const existingRuns = await listBackgroundTestRuns(options.pmRoot, {});
+    for (const existing of existingRuns) {
+        const refreshed = await refreshRunIfStale(options.pmRoot, existing);
+        if (refreshed.fingerprint !== fingerprint) {
+            continue;
+        }
+        if (!BACKGROUND_RUN_ACTIVE_STATUSES.has(refreshed.status)) {
+            continue;
+        }
+        if (!isPidRunning(refreshed.worker_pid)) {
+            continue;
+        }
+        return {
+            started: false,
+            run: {
+                ...refreshed,
+                duplicate_of: refreshed.id,
+            },
+            duplicate_of: refreshed.id,
+        };
+    }
+    const runId = buildRunId();
+    const createdAt = nowIso();
+    const stdoutPath = getTestRunStdoutPath(options.pmRoot, runId);
+    const stderrPath = getTestRunStderrPath(options.pmRoot, runId);
+    const resultPath = getTestRunResultPath(options.pmRoot, runId);
+    await fs.writeFile(stdoutPath, "", "utf8");
+    await fs.writeFile(stderrPath, "", "utf8");
+    const record = {
+        id: runId,
+        kind: options.kind,
+        status: "queued",
+        created_at: createdAt,
+        updated_at: createdAt,
+        requested_by: options.requestedBy,
+        fingerprint,
+        command_args: normalizedArgs,
+        command_label: summarizeCommandLabel(normalizedArgs),
+        pm_root: options.pmRoot,
+        global_pm_root: options.globalPmRoot,
+        target_id: options.targetId,
+        status_filter: options.statusFilter,
+        attempt: typeof options.attempt === "number" && Number.isFinite(options.attempt) && options.attempt >= 1
+            ? Math.floor(options.attempt)
+            : 1,
+        resumed_from: options.resumedFrom,
+        resumed_by: options.resumedBy,
+        stdout_path: stdoutPath,
+        stderr_path: stderrPath,
+        result_path: resultPath,
+        progress: {
+            phase: "queued",
+            message: "Queued for background execution.",
+            heartbeat_at: createdAt,
+        },
+    };
+    await writeBackgroundRunRecord(options.pmRoot, record);
+    return {
+        started: true,
+        run: record,
+    };
+}
+export async function spawnBackgroundTestRunWorker(options) {
+    const record = await readBackgroundTestRunRecord(options.pmRoot, options.runId);
+    if (!record) {
+        throw new PmCliError(`Background test run ${options.runId} not found`, EXIT_CODE.NOT_FOUND);
+    }
+    if (BACKGROUND_RUN_TERMINAL_STATUSES.has(record.status)) {
+        throw new PmCliError(`Background test run ${record.id} is already terminal (${record.status}).`, EXIT_CODE.CONFLICT);
+    }
+    const cliEntry = await resolveBackgroundCliEntry(process.cwd());
+    const args = [];
+    if (options.noExtensions === true) {
+        args.push("--no-extensions");
+    }
+    args.push("--path", record.pm_root, "test-runs-worker", record.id);
+    const env = {
+        ...process.env,
+        PM_PATH: record.pm_root,
+        PM_GLOBAL_PATH: record.global_pm_root,
+        PM_BACKGROUND_TEST_RUN_ID: record.id,
+        PM_BACKGROUND_TEST_RUN_ATTEMPT: String(record.attempt),
+        PM_BACKGROUND_TEST_RUN_RESUMED_FROM: record.resumed_from ?? "",
+        FORCE_COLOR: "0",
+    };
+    const child = spawn(process.execPath, [cliEntry, ...args], {
+        cwd: process.cwd(),
+        env,
+        detached: true,
+        stdio: "ignore",
+        windowsHide: true,
+    });
+    child.unref();
+    const next = {
+        ...record,
+        status: "queued",
+        worker_pid: child.pid && child.pid > 0 ? child.pid : record.worker_pid,
+        progress: {
+            phase: "queued",
+            message: "Worker process started.",
+            heartbeat_at: nowIso(),
+        },
+    };
+    await writeBackgroundRunRecord(options.pmRoot, next);
+    return next;
+}
+async function appendFileOrdered(queue, filePath, text) {
+    await queue;
+    await fs.appendFile(filePath, text, "utf8");
+}
+export async function runBackgroundTestRunWorker(pmRoot, runId, noExtensions = false) {
+    const loaded = await readBackgroundTestRunRecord(pmRoot, runId);
+    if (!loaded) {
+        throw new PmCliError(`Background test run ${runId} not found`, EXIT_CODE.NOT_FOUND);
+    }
+    const record = {
+        ...loaded,
+        status: "running",
+        started_at: loaded.started_at ?? nowIso(),
+        worker_pid: process.pid,
+        progress: {
+            phase: "running",
+            message: "Worker started.",
+            heartbeat_at: nowIso(),
+        },
+    };
+    const cliEntry = await resolveBackgroundCliEntry(process.cwd());
+    const env = {
+        ...process.env,
+        PM_PATH: record.pm_root,
+        PM_GLOBAL_PATH: record.global_pm_root,
+        FORCE_COLOR: "0",
+    };
+    await writeBackgroundRunRecord(pmRoot, record);
+    const childArgs = noExtensions ? ["--no-extensions", ...record.command_args] : [...record.command_args];
+    const child = spawn(process.execPath, [cliEntry, ...childArgs], {
+        cwd: process.cwd(),
+        env,
+        detached: false,
+        stdio: ["ignore", "pipe", "pipe"],
+        windowsHide: true,
+    });
+    record.child_pid = child.pid && child.pid > 0 ? child.pid : undefined;
+    let writeQueue = Promise.resolve();
+    const scheduleRecordWrite = () => {
+        writeQueue = writeQueue.then(async () => {
+            await writeBackgroundRunRecord(pmRoot, record);
+        }).catch(() => {
+            // Keep worker alive even if a single metadata write fails.
+        });
+    };
+    let stdoutWriteQueue = Promise.resolve();
+    let stderrWriteQueue = Promise.resolve();
+    let stdoutBuffer = "";
+    let stopRequested = false;
+    const requestStop = async () => {
+        if (stopRequested) {
+            return;
+        }
+        stopRequested = true;
+        record.stop_requested_at = nowIso();
+        record.progress = {
+            ...record.progress,
+            phase: "stopping",
+            message: "Stop requested for background run.",
+            heartbeat_at: nowIso(),
+        };
+        scheduleRecordWrite();
+        if (!child.pid || child.pid <= 0) {
+            return;
+        }
+        try {
+            child.kill("SIGTERM");
+        }
+        catch {
+            // Child may already be gone.
+        }
+        const forceKillDelayMs = Number.parseInt(process.env.PM_BACKGROUND_RUN_FORCE_KILL_DELAY_MS ?? "", 10);
+        const delay = Number.isFinite(forceKillDelayMs) && forceKillDelayMs > 0
+            ? forceKillDelayMs
+            : DEFAULT_BACKGROUND_RUN_FORCE_KILL_DELAY_MS;
+        const forceTimer = setTimeout(() => {
+            try {
+                child.kill("SIGKILL");
+            }
+            catch {
+                // Child may already be gone.
+            }
+        }, delay);
+        forceTimer.unref?.();
+    };
+    const onSignal = () => {
+        void requestStop();
+    };
+    process.on("SIGTERM", onSignal);
+    process.on("SIGINT", onSignal);
+    const resourceIntervalMs = Number.parseInt(process.env.PM_BACKGROUND_RUN_RESOURCE_INTERVAL_MS ?? "", 10);
+    const resourceInterval = Number.isFinite(resourceIntervalMs) && resourceIntervalMs > 0
+        ? resourceIntervalMs
+        : DEFAULT_BACKGROUND_RUN_RESOURCE_SNAPSHOT_INTERVAL_MS;
+    const resourceTimer = setInterval(() => {
+        void (async () => {
+            record.resource = await buildResourceSnapshot(record);
+            if (record.progress) {
+                record.progress.heartbeat_at = nowIso();
+            }
+            scheduleRecordWrite();
+        })();
+    }, resourceInterval);
+    resourceTimer.unref?.();
+    child.stdout?.on("data", (chunk) => {
+        const text = typeof chunk === "string" ? chunk : chunk.toString("utf8");
+        stdoutBuffer += text;
+        stdoutWriteQueue = appendFileOrdered(stdoutWriteQueue, record.stdout_path, text);
+    });
+    child.stderr?.on("data", (chunk) => {
+        const text = typeof chunk === "string" ? chunk : chunk.toString("utf8");
+        stderrWriteQueue = appendFileOrdered(stderrWriteQueue, record.stderr_path, text);
+        const lines = splitLines(text);
+        const latestLine = lines.at(-1);
+        if (latestLine) {
+            const progressPatch = parseProgressLine(latestLine);
+            record.progress = {
+                phase: record.progress?.phase ?? "running",
+                message: latestLine,
+                heartbeat_at: nowIso(),
+                linked_test_index: progressPatch?.linked_test_index ?? record.progress?.linked_test_index,
+                linked_test_total: progressPatch?.linked_test_total ?? record.progress?.linked_test_total,
+                elapsed_ms: progressPatch?.elapsed_ms ?? record.progress?.elapsed_ms,
+            };
+            if (progressPatch?.phase === "finished" && !stopRequested) {
+                record.progress.phase = "running";
+            }
+            scheduleRecordWrite();
+        }
+    });
+    let exitCode = null;
+    let signal = null;
+    try {
+        ({ code: exitCode, signal } = await new Promise((resolve) => {
+            child.on("close", (code, closeSignal) => {
+                resolve({ code, signal: closeSignal });
+            });
+        }));
+    }
+    finally {
+        clearInterval(resourceTimer);
+        process.off("SIGTERM", onSignal);
+        process.off("SIGINT", onSignal);
+    }
+    await stdoutWriteQueue;
+    await stderrWriteQueue;
+    let parsedResult = null;
+    if (stdoutBuffer.trim().length > 0) {
+        try {
+            parsedResult = JSON.parse(stdoutBuffer);
+        }
+        catch {
+            parsedResult = null;
+        }
+    }
+    const evaluated = evaluateWorkerResult(record.kind, parsedResult);
+    record.summary = evaluated.summary;
+    record.exit_code = typeof exitCode === "number" ? exitCode : undefined;
+    record.signal = signal ?? undefined;
+    record.finished_at = nowIso();
+    record.status = stopRequested
+        ? "stopped"
+        : (record.exit_code === 0 &&
+            (record.summary.failed ?? 0) === 0 &&
+            record.summary.fail_on_skipped_triggered !== true)
+            ? "passed"
+            : "failed";
+    record.progress = {
+        phase: "finished",
+        message: stopRequested ? "Background run stopped." : `Background run finished with status=${record.status}.`,
+        heartbeat_at: nowIso(),
+        linked_test_index: record.progress?.linked_test_index,
+        linked_test_total: record.progress?.linked_test_total,
+        elapsed_ms: record.progress?.elapsed_ms,
+    };
+    record.resource = await buildResourceSnapshot(record);
+    if (parsedResult !== null) {
+        await writeFileAtomic(record.result_path, `${JSON.stringify(parsedResult, null, 2)}\n`);
+    }
+    else {
+        await writeFileAtomic(record.result_path, `${JSON.stringify({
+            parse_error: "Background run output was not valid JSON.",
+            stdout_excerpt: tailLines(stdoutBuffer, DEFAULT_BACKGROUND_RUN_LOG_TAIL_LINES),
+        }, null, 2)}\n`);
+    }
+    await writeBackgroundRunRecord(pmRoot, record);
+    await writeQueue;
+    return record;
+}
+export async function listBackgroundTestRuns(pmRoot, options) {
+    const recordPaths = await listBackgroundRunRecordPaths(pmRoot);
+    const runs = [];
+    for (const recordPath of recordPaths) {
+        const raw = await readFileIfExists(recordPath);
+        if (!raw) {
+            continue;
+        }
+        const parsed = await parseBackgroundRunRecord(raw, recordPath);
+        runs.push(parsed);
+    }
+    const refreshed = [];
+    for (const run of runs) {
+        refreshed.push(await refreshRunIfStale(pmRoot, run));
+    }
+    const filtered = options.status ? refreshed.filter((entry) => entry.status === options.status) : refreshed;
+    const sorted = filtered.sort((left, right) => {
+        const byUpdated = Date.parse(right.updated_at) - Date.parse(left.updated_at);
+        if (Number.isFinite(byUpdated) && byUpdated !== 0) {
+            return byUpdated;
+        }
+        return right.id.localeCompare(left.id);
+    });
+    const limit = typeof options.limit === "number" && options.limit >= 0 ? options.limit : undefined;
+    return limit === undefined ? sorted : sorted.slice(0, limit);
+}
+export async function getBackgroundTestRunStatus(pmRoot, runId) {
+    const loaded = await readBackgroundTestRunRecord(pmRoot, runId);
+    if (!loaded) {
+        throw new PmCliError(`Background test run ${runId} not found`, EXIT_CODE.NOT_FOUND);
+    }
+    const refreshed = await refreshRunIfStale(pmRoot, loaded);
+    const workerAlive = isPidRunning(refreshed.worker_pid);
+    const childAlive = isPidRunning(refreshed.child_pid);
+    if (refreshed.status === "running" && !childAlive && !refreshed.finished_at && !workerAlive) {
+        refreshed.status = "failed";
+        refreshed.finished_at = nowIso();
+        refreshed.error = refreshed.error ?? "Background run process exited unexpectedly.";
+        await writeBackgroundRunRecord(pmRoot, refreshed);
+    }
+    if (refreshed.status === "running") {
+        refreshed.resource = await buildResourceSnapshot(refreshed);
+        await writeBackgroundRunRecord(pmRoot, refreshed);
+    }
+    const heartbeatAt = refreshed.progress?.heartbeat_at;
+    const heartbeatAtMs = heartbeatAt ? Date.parse(heartbeatAt) : Number.NaN;
+    const lagMs = Number.isFinite(heartbeatAtMs) ? Math.max(0, nowMs() - heartbeatAtMs) : undefined;
+    const staleMs = Number.parseInt(process.env.PM_BACKGROUND_RUN_HEARTBEAT_STALE_MS ?? "", 10);
+    const staleThresholdMs = Number.isFinite(staleMs) && staleMs > 0 ? staleMs : DEFAULT_BACKGROUND_RUN_HEARTBEAT_STALE_MS;
+    const healthState = refreshed.status === "running"
+        ? lagMs !== undefined && lagMs > staleThresholdMs
+            ? "stale"
+            : "healthy"
+        : "inactive";
+    return {
+        run: refreshed,
+        health: {
+            state: healthState,
+            last_heartbeat_at: heartbeatAt,
+            heartbeat_lag_ms: lagMs,
+            worker_alive: workerAlive,
+            child_alive: childAlive,
+        },
+    };
+}
+export async function stopBackgroundTestRun(pmRoot, runId, force = false) {
+    const loaded = await readBackgroundTestRunRecord(pmRoot, runId);
+    if (!loaded) {
+        throw new PmCliError(`Background test run ${runId} not found`, EXIT_CODE.NOT_FOUND);
+    }
+    const refreshed = await refreshRunIfStale(pmRoot, loaded);
+    if (BACKGROUND_RUN_TERMINAL_STATUSES.has(refreshed.status)) {
+        return {
+            run: refreshed,
+            signal_sent: "none",
+        };
+    }
+    let signalSent = "none";
+    const signal = force ? "SIGKILL" : "SIGTERM";
+    if (isPidRunning(refreshed.worker_pid) && refreshed.worker_pid) {
+        try {
+            process.kill(refreshed.worker_pid, signal);
+            signalSent = signal;
+        }
+        catch {
+            signalSent = "none";
+        }
+    }
+    if (signalSent === "none") {
+        refreshed.status = "stopped";
+        refreshed.finished_at = refreshed.finished_at ?? nowIso();
+    }
+    refreshed.stop_requested_at = nowIso();
+    refreshed.progress = {
+        phase: "stopping",
+        message: signalSent === "none" ? "Run marked stopped." : `Stop requested via ${signalSent}.`,
+        heartbeat_at: nowIso(),
+        linked_test_index: refreshed.progress?.linked_test_index,
+        linked_test_total: refreshed.progress?.linked_test_total,
+        elapsed_ms: refreshed.progress?.elapsed_ms,
+    };
+    await writeBackgroundRunRecord(pmRoot, refreshed);
+    return {
+        run: refreshed,
+        signal_sent: signalSent,
+    };
+}
+export async function resumeBackgroundTestRun(pmRoot, runId, requestedBy, noExtensions = false) {
+    const loaded = await readBackgroundTestRunRecord(pmRoot, runId);
+    if (!loaded) {
+        throw new PmCliError(`Background test run ${runId} not found`, EXIT_CODE.NOT_FOUND);
+    }
+    const refreshed = await refreshRunIfStale(pmRoot, loaded);
+    if (!BACKGROUND_RUN_TERMINAL_STATUSES.has(refreshed.status)) {
+        throw new PmCliError(`Background test run ${runId} is not terminal and cannot be resumed.`, EXIT_CODE.CONFLICT);
+    }
+    const started = await startBackgroundTestRun({
+        pmRoot: refreshed.pm_root,
+        globalPmRoot: refreshed.global_pm_root,
+        kind: refreshed.kind,
+        commandArgs: refreshed.command_args,
+        requestedBy,
+        targetId: refreshed.target_id,
+        statusFilter: refreshed.status_filter,
+        resumedFrom: refreshed.id,
+        resumedBy: requestedBy,
+        attempt: refreshed.attempt + 1,
+    });
+    if (!started.started) {
+        return started.run;
+    }
+    const spawned = await spawnBackgroundTestRunWorker({
+        pmRoot,
+        runId: started.run.id,
+        noExtensions,
+    });
+    const prior = {
+        ...refreshed,
+        resumed_by: spawned.id,
+    };
+    await writeBackgroundRunRecord(pmRoot, prior);
+    return spawned;
+}
+export async function readBackgroundTestRunLogs(pmRoot, runId, stream, tail) {
+    const loaded = await readBackgroundTestRunRecord(pmRoot, runId);
+    if (!loaded) {
+        throw new PmCliError(`Background test run ${runId} not found`, EXIT_CODE.NOT_FOUND);
+    }
+    const resolvedTail = typeof tail === "number" && Number.isFinite(tail) && tail >= 0 ? Math.floor(tail) : DEFAULT_BACKGROUND_RUN_LOG_TAIL_LINES;
+    const stdoutRaw = stream === "stdout" || stream === "both" ? (await readFileIfExists(loaded.stdout_path)) ?? "" : "";
+    const stderrRaw = stream === "stderr" || stream === "both" ? (await readFileIfExists(loaded.stderr_path)) ?? "" : "";
+    return {
+        run: loaded,
+        stream,
+        tail: resolvedTail,
+        stdout: stream === "stdout" || stream === "both" ? tailLines(stdoutRaw, resolvedTail) : [],
+        stderr: stream === "stderr" || stream === "both" ? tailLines(stderrRaw, resolvedTail) : [],
+    };
+}
+//# sourceMappingURL=background-runs.js.map