@celestea/tools 2.7.1

package/dist/browser/cdp.js

@@ -0,0 +1,269 @@
+/**
+ * Minimal Chrome DevTools Protocol client (F4 slice 1).
+ *
+ * Design: the TRANSPORT is a seam. \`WebSocketTransport\` is the production
+ * implementation (Node's global WebSocket), while a test supplies an in-memory
+ * fake and never needs a browser or a WebSocket server. This file owns request
+ * id correlation, response/error settling, event fan-out, per-request
+ * deadlines and close semantics.
+ *
+ * Only the domains the F4 tools need are wrapped; \`send\` stays public for
+ * anything else. Zero npm dependencies.
+ */
+/** Default per-request deadline. */
+export const DEFAULT_CDP_TIMEOUT_MS = 15_000;
+/** Default WebSocket open deadline. */
+export const DEFAULT_OPEN_TIMEOUT_MS = 10_000;
+/** The transport could not be created / connected / used. */
+export class CdpTransportError extends Error {
+    code = "cdp_transport";
+    constructor(message) {
+        super(message);
+        this.name = "CdpTransportError";
+    }
+}
+/** A request exceeded its deadline. */
+export class CdpTimeoutError extends Error {
+    code = "cdp_timeout";
+    constructor(method, timeoutMs) {
+        super("CDP " + method + " timed out after " + timeoutMs + "ms");
+        this.name = "CdpTimeoutError";
+    }
+}
+/** The browser answered with a protocol error (negative code). */
+export class CdpProtocolError extends Error {
+    code;
+    data;
+    constructor(error) {
+        super(error.message);
+        this.name = "CdpProtocolError";
+        this.code = error.code;
+        this.data = error.data;
+    }
+}
+/** The client (or its transport) is closed; no further requests are accepted. */
+export class CdpClosedError extends Error {
+    code = "cdp_closed";
+    constructor() {
+        super("CDP client is closed");
+        this.name = "CdpClosedError";
+    }
+}
+/** Production transport over Node's global WebSocket. */
+export class WebSocketTransport {
+    socket;
+    constructor(socket) {
+        this.socket = socket;
+    }
+    send(data) {
+        this.socket.send(data);
+    }
+    subscribe(handlers) {
+        this.socket.addEventListener("message", (event) => handlers.onMessage(stringifyData(event.data)));
+        this.socket.addEventListener("error", () => handlers.onError(new CdpTransportError("websocket transport error")));
+        this.socket.addEventListener("close", () => handlers.onClose());
+    }
+    close() {
+        try {
+            this.socket.close();
+        }
+        catch {
+            // already closed: closing twice is not an error
+        }
+    }
+}
+function stringifyData(data) {
+    return typeof data === "string" ? data : String(data);
+}
+/** The runtime WebSocket constructor, or a structured error when absent. */
+export function defaultWebSocketFactory() {
+    const ctor = globalThis.WebSocket;
+    if (ctor === undefined)
+        throw new CdpTransportError("global WebSocket is unavailable in this Node runtime");
+    return (url) => new ctor(url);
+}
+/** Connect and wait for the socket to open (sending before open would throw). */
+export async function openWebSocketTransport(url, options = {}) {
+    const factory = options.factory ?? defaultWebSocketFactory();
+    const socket = factory(url);
+    await waitForOpen(socket, options.openTimeoutMs ?? DEFAULT_OPEN_TIMEOUT_MS);
+    return new WebSocketTransport(socket);
+}
+function waitForOpen(socket, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const finish = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            if (error === null)
+                resolve();
+            else
+                reject(error);
+        };
+        const timer = setTimeout(() => finish(new CdpTransportError("websocket did not open within " + timeoutMs + "ms")), timeoutMs);
+        timer.unref();
+        socket.addEventListener("open", () => finish(null));
+        socket.addEventListener("error", () => finish(new CdpTransportError("websocket failed to connect")));
+    });
+}
+/** A tiny CDP client over an injected transport. */
+export class CdpClient {
+    transport;
+    timeoutMs;
+    seq = 0;
+    pending = new Map();
+    handlers = new Map();
+    closed = false;
+    constructor(options) {
+        this.transport = options.transport;
+        this.timeoutMs = options.timeoutMs ?? DEFAULT_CDP_TIMEOUT_MS;
+        this.transport.subscribe({
+            onMessage: (data) => this.receive(data),
+            onError: (error) => this.failAll(error),
+            onClose: () => this.failAll(new CdpClosedError()),
+        });
+    }
+    /** Send one request; the promise settles on its correlated response. */
+    send(method, params = {}, sessionId) {
+        if (this.closed)
+            return Promise.reject(new CdpClosedError());
+        const id = ++this.seq;
+        const envelope = { id, method, params };
+        if (sessionId !== undefined)
+            envelope["sessionId"] = sessionId;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new CdpTimeoutError(method, this.timeoutMs));
+            }, this.timeoutMs);
+            timer.unref();
+            this.pending.set(id, { method, resolve, reject, timer });
+            this.transport.send(JSON.stringify(envelope));
+        });
+    }
+    /** Subscribe to a CDP event (method name, or "*" for every event). */
+    on(event, handler) {
+        const set = this.handlers.get(event) ?? new Set();
+        set.add(handler);
+        this.handlers.set(event, set);
+        return () => set.delete(handler);
+    }
+    /** Close the transport and reject every in-flight request. */
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        try {
+            this.transport.close();
+        }
+        catch {
+            // best effort: the close path must never throw
+        }
+        this.failAll(new CdpClosedError());
+    }
+    get isClosed() {
+        return this.closed;
+    }
+    // ---- domain wrappers (only what the F4 tools need) -------------------------
+    async createTarget(url) {
+        const result = await this.send("Target.createTarget", { url });
+        return { targetId: String(result["targetId"]) };
+    }
+    async attachToTarget(targetId) {
+        const result = await this.send("Target.attachToTarget", { targetId, flatten: true });
+        return { sessionId: String(result["sessionId"]) };
+    }
+    async closeTarget(targetId) {
+        await this.send("Target.closeTarget", { targetId });
+    }
+    async pageEnable(sessionId) {
+        await this.send("Page.enable", {}, sessionId);
+    }
+    async runtimeEnable(sessionId) {
+        await this.send("Runtime.enable", {}, sessionId);
+    }
+    async accessibilityEnable(sessionId) {
+        await this.send("Accessibility.enable", {}, sessionId);
+    }
+    async navigate(url, sessionId) {
+        return this.send("Page.navigate", { url }, sessionId);
+    }
+    async evaluate(expression, sessionId, options = {}) {
+        const result = await this.send("Runtime.evaluate", { expression, returnByValue: options.returnByValue ?? true, awaitPromise: options.awaitPromise ?? false }, sessionId);
+        const remote = result["result"];
+        return remote === undefined ? undefined : remote.value;
+    }
+    async captureScreenshot(sessionId, options = {}) {
+        const result = await this.send("Page.captureScreenshot", { format: "png", ...options }, sessionId);
+        const data = typeof result["data"] === "string" ? result["data"] : "";
+        return { data, bytes: Buffer.byteLength(data, "base64") };
+    }
+    async dispatchMouseEvent(params, sessionId) {
+        await this.send("Input.dispatchMouseEvent", { ...params }, sessionId);
+    }
+    async insertText(text, sessionId) {
+        await this.send("Input.insertText", { text }, sessionId);
+    }
+    async dispatchKeyEvent(params, sessionId) {
+        await this.send("Input.dispatchKeyEvent", { ...params }, sessionId);
+    }
+    async setDeviceMetricsOverride(metrics, sessionId) {
+        await this.send("Emulation.setDeviceMetricsOverride", { deviceScaleFactor: 1, mobile: false, ...metrics }, sessionId);
+    }
+    async getFullAXTree(sessionId) {
+        const result = await this.send("Accessibility.getFullAXTree", {}, sessionId);
+        const nodes = result["nodes"];
+        return Array.isArray(nodes) ? nodes : [];
+    }
+    async getBoxModel(backendNodeId, sessionId) {
+        const result = await this.send("DOM.getBoxModel", { backendNodeId }, sessionId);
+        const model = result["model"];
+        return model === undefined ? null : model;
+    }
+    receive(data) {
+        let message;
+        try {
+            message = JSON.parse(data);
+        }
+        catch {
+            return; // malformed frame: ignore, a transport error would be separate
+        }
+        if (typeof message["id"] === "number")
+            this.settle(message["id"], message);
+        else if (typeof message["method"] === "string")
+            this.emit(message);
+    }
+    settle(id, message) {
+        const pending = this.pending.get(id);
+        if (pending === undefined)
+            return;
+        this.pending.delete(id);
+        clearTimeout(pending.timer);
+        const error = message["error"];
+        if (error !== undefined)
+            pending.reject(new CdpProtocolError(error));
+        else
+            pending.resolve(message["result"] ?? {});
+    }
+    emit(message) {
+        const method = message["method"];
+        const params = message["params"] ?? {};
+        const sessionId = typeof message["sessionId"] === "string" ? message["sessionId"] : undefined;
+        for (const key of [method, "*"]) {
+            const set = this.handlers.get(key);
+            if (set === undefined)
+                continue;
+            for (const handler of [...set])
+                handler(params, sessionId);
+        }
+    }
+    failAll(error) {
+        for (const pending of this.pending.values()) {
+            clearTimeout(pending.timer);
+            pending.reject(error);
+        }
+        this.pending.clear();
+    }
+}

package/dist/browser/launch.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Browser launch / attach (F4 slice 1).
+ *
+ * Two entry points:
+ * - launchBrowser(): spawn chrome-headless-shell with
+ *   --headless --no-sandbox --remote-debugging-port=0 --user-data-dir=<tmp>,
+ *   read the ws:// DevTools endpoint off stderr, and return a handle whose
+ *   close() reclaims the whole process tree and removes the profile dir.
+ * - attachBrowser(): connect to an externally supplied --cdp-endpoint (future
+ *   real Chrome / a browser the operator started).
+ *
+ * The executable path, the process spawner and the transport opener are all
+ * injectable, so the module is unit-testable without a browser and can grow a
+ * platform-specific locator later without touching this logic.
+ */
+import { CdpClient, type CdpTransport, type OpenTransportOptions } from "./cdp.js";
+/** Default time to wait for the DevTools endpoint. */
+export declare const DEFAULT_STARTUP_TIMEOUT_MS = 15000;
+/** Default grace between SIGTERM and SIGKILL when closing. */
+export declare const DEFAULT_SHUTDOWN_GRACE_MS = 3000;
+/** Flags every launched browser gets (callers append via extraArgs). */
+export declare const DEFAULT_BROWSER_ARGS: readonly string[];
+/** The stderr marker that carries the endpoint. */
+export declare const ENDPOINT_MARKER = "DevTools listening on ";
+/** No headless-shell executable could be located. */
+export declare class BrowserNotFoundError extends Error {
+    readonly code = "browser_not_found";
+    constructor(message: string);
+}
+/** The browser died (or stayed silent) before it printed an endpoint. */
+export declare class BrowserStartupError extends Error {
+    readonly code = "browser_startup";
+    readonly stderrTail: string;
+    constructor(message: string, stderrTail: string);
+}
+/** The minimal process surface launch/close needs (spawn is injectable). */
+export interface BrowserProcess {
+    pid?: number | undefined;
+    stderr: {
+        on(event: string, listener: (chunk: unknown) => void): unknown;
+    } | null;
+    kill(signal?: NodeJS.Signals): boolean;
+    once(event: string, listener: (...args: unknown[]) => void): unknown;
+}
+/** How a browser process is created (tests inject a fake). */
+export type BrowserSpawn = (program: string, args: readonly string[]) => BrowserProcess;
+export interface FindShellInput {
+    root?: string;
+    platform?: string;
+    arch?: string;
+    list?: (dir: string) => string[];
+    exists?: (path: string) => boolean;
+}
+export interface AttachOptions {
+    openTransport?: (url: string, options?: OpenTransportOptions) => Promise<CdpTransport>;
+    clientTimeoutMs?: number;
+}
+export interface LaunchOptions extends AttachOptions {
+    executablePath?: string;
+    userDataDir?: string;
+    extraArgs?: readonly string[];
+    startupTimeoutMs?: number;
+    shutdownGraceMs?: number;
+    spawn?: BrowserSpawn;
+    findExecutable?: () => string | null;
+}
+/** A browser connected over CDP; close() also reclaims the process. */
+export interface LaunchedBrowser {
+    endpoint: string;
+    pid: number | null;
+    userDataDir: string;
+    client: CdpClient;
+    close(): Promise<void>;
+}
+/** An externally launched browser (no process we own). */
+export interface AttachedBrowser {
+    endpoint: string;
+    client: CdpClient;
+    close(): void;
+}
+/** The ws:// endpoint in a stderr buffer, or null. */
+export declare function parseDevToolsEndpoint(stderr: string): string | null;
+/** Playwright's per-platform subdirectory under a chromium_headless_shell-* dir. */
+export declare function headlessShellSubdir(platform?: string, arch?: string): string;
+/** Highest-versioned chrome-headless-shell under the Playwright cache. */
+export declare function findHeadlessShell(input?: FindShellInput): string | null;
+/** Attach to an already-running CDP endpoint. */
+export declare function attachBrowser(endpoint: string, options?: AttachOptions): Promise<AttachedBrowser>;
+/** Spawn a browser, wait for its endpoint, attach. */
+export declare function launchBrowser(options?: LaunchOptions): Promise<LaunchedBrowser>;
+/** SIGTERM the process group, wait, then SIGKILL if it is still alive. */
+export declare function terminateBrowserProcess(proc: BrowserProcess, graceMs?: number): Promise<void>;

package/dist/browser/launch.js

@@ -0,0 +1,232 @@
+/**
+ * Browser launch / attach (F4 slice 1).
+ *
+ * Two entry points:
+ * - launchBrowser(): spawn chrome-headless-shell with
+ *   --headless --no-sandbox --remote-debugging-port=0 --user-data-dir=<tmp>,
+ *   read the ws:// DevTools endpoint off stderr, and return a handle whose
+ *   close() reclaims the whole process tree and removes the profile dir.
+ * - attachBrowser(): connect to an externally supplied --cdp-endpoint (future
+ *   real Chrome / a browser the operator started).
+ *
+ * The executable path, the process spawner and the transport opener are all
+ * injectable, so the module is unit-testable without a browser and can grow a
+ * platform-specific locator later without touching this logic.
+ */
+import { spawn } from "node:child_process";
+import { existsSync, mkdtempSync, readdirSync, rmSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { join } from "node:path";
+import { CdpClient, openWebSocketTransport } from "./cdp.js";
+/** Default time to wait for the DevTools endpoint. */
+export const DEFAULT_STARTUP_TIMEOUT_MS = 15_000;
+/** Default grace between SIGTERM and SIGKILL when closing. */
+export const DEFAULT_SHUTDOWN_GRACE_MS = 3_000;
+/** Flags every launched browser gets (callers append via extraArgs). */
+export const DEFAULT_BROWSER_ARGS = [
+    "--headless",
+    "--no-sandbox",
+    "--disable-gpu",
+    "--remote-debugging-port=0",
+];
+/** The stderr marker that carries the endpoint. */
+export const ENDPOINT_MARKER = "DevTools listening on ";
+/** No headless-shell executable could be located. */
+export class BrowserNotFoundError extends Error {
+    code = "browser_not_found";
+    constructor(message) {
+        super(message);
+        this.name = "BrowserNotFoundError";
+    }
+}
+/** The browser died (or stayed silent) before it printed an endpoint. */
+export class BrowserStartupError extends Error {
+    code = "browser_startup";
+    stderrTail;
+    constructor(message, stderrTail) {
+        super(message);
+        this.name = "BrowserStartupError";
+        this.stderrTail = stderrTail;
+    }
+}
+/** The ws:// endpoint in a stderr buffer, or null. */
+export function parseDevToolsEndpoint(stderr) {
+    const at = stderr.indexOf(ENDPOINT_MARKER);
+    if (at < 0)
+        return null;
+    const rest = stderr.slice(at + ENDPOINT_MARKER.length).trimStart();
+    const match = /^(ws:\S+)/.exec(rest);
+    return match === null ? null : match[1];
+}
+/** Playwright's per-platform subdirectory under a chromium_headless_shell-* dir. */
+export function headlessShellSubdir(platform = process.platform, arch = process.arch) {
+    if (platform === "win32")
+        return "chrome-headless-shell-win64";
+    if (platform === "darwin")
+        return arch === "arm64" ? "chrome-headless-shell-mac-arm64" : "chrome-headless-shell-mac-x64";
+    return arch === "arm64" ? "chrome-headless-shell-linux-arm64" : "chrome-headless-shell-linux64";
+}
+/** Highest-versioned chrome-headless-shell under the Playwright cache. */
+export function findHeadlessShell(input = {}) {
+    const root = input.root ?? join(homedir(), ".cache", "ms-playwright");
+    const list = input.list ?? defaultList;
+    const exists = input.exists ?? existsSync;
+    const subdir = headlessShellSubdir(input.platform ?? process.platform, input.arch ?? process.arch);
+    const versions = list(root).filter((name) => name.startsWith("chromium_headless_shell-")).sort(compareVersionDesc);
+    for (const version of versions) {
+        const candidate = join(root, version, subdir, "chrome-headless-shell");
+        if (exists(candidate))
+            return candidate;
+    }
+    return null;
+}
+function defaultList(dir) {
+    try {
+        return readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+}
+function compareVersionDesc(a, b) {
+    return versionTail(b) - versionTail(a);
+}
+function versionTail(name) {
+    const match = /-(\d+)$/.exec(name);
+    return match === null ? -1 : Number(match[1]);
+}
+/** Attach to an already-running CDP endpoint. */
+export async function attachBrowser(endpoint, options = {}) {
+    const open = options.openTransport ?? openWebSocketTransport;
+    const transport = await open(endpoint);
+    const client = new CdpClient({ transport, timeoutMs: options.clientTimeoutMs });
+    return { endpoint, client, close: () => client.close() };
+}
+/** Spawn a browser, wait for its endpoint, attach. */
+export async function launchBrowser(options = {}) {
+    const executable = resolveExecutable(options);
+    const userDataDir = options.userDataDir ?? mkdtempSync(join(tmpdir(), "celestea-browser-"));
+    const ownsDir = options.userDataDir === undefined;
+    const grace = options.shutdownGraceMs ?? DEFAULT_SHUTDOWN_GRACE_MS;
+    const args = [...DEFAULT_BROWSER_ARGS, "--user-data-dir=" + userDataDir, ...(options.extraArgs ?? []), "about:blank"];
+    const proc = (options.spawn ?? defaultBrowserSpawn)(executable, args);
+    let endpoint;
+    try {
+        endpoint = await readEndpoint(proc, options.startupTimeoutMs ?? DEFAULT_STARTUP_TIMEOUT_MS);
+    }
+    catch (error) {
+        await terminateBrowserProcess(proc, grace);
+        if (ownsDir)
+            removeDir(userDataDir);
+        throw error;
+    }
+    const attached = await attachBrowser(endpoint, options);
+    return {
+        endpoint,
+        pid: proc.pid ?? null,
+        userDataDir,
+        client: attached.client,
+        close: async () => {
+            attached.close();
+            await terminateBrowserProcess(proc, grace);
+            if (ownsDir)
+                removeDir(userDataDir);
+        },
+    };
+}
+function resolveExecutable(options) {
+    // An injected locator is authoritative (a null from it means "none"), so a
+    // test can force the not-found path without touching the real cache.
+    const found = options.executablePath ?? (options.findExecutable === undefined ? findHeadlessShell() : options.findExecutable());
+    if (found === null || found === undefined || found === "") {
+        throw new BrowserNotFoundError("no chrome-headless-shell found; pass executablePath or install Playwright chromium");
+    }
+    return found;
+}
+function readEndpoint(proc, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        let buffer = "";
+        let settled = false;
+        const finish = (endpoint, error) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            if (error === null)
+                resolve(endpoint);
+            else
+                reject(error);
+        };
+        const timer = setTimeout(() => finish(null, new BrowserStartupError("browser did not print a DevTools endpoint within " + timeoutMs + "ms", tail(buffer))), timeoutMs);
+        timer.unref();
+        proc.stderr?.on("data", (chunk) => {
+            buffer += chunkToText(chunk);
+            const endpoint = parseDevToolsEndpoint(buffer);
+            if (endpoint !== null)
+                finish(endpoint, null);
+        });
+        proc.once("exit", (code) => finish(null, new BrowserStartupError("browser exited (code " + String(code) + ") before a DevTools endpoint", tail(buffer))));
+        proc.once("error", (error) => finish(null, error instanceof Error ? error : new Error(String(error))));
+    });
+}
+function chunkToText(chunk) {
+    if (typeof chunk === "string")
+        return chunk;
+    if (Buffer.isBuffer(chunk))
+        return chunk.toString("utf8");
+    return String(chunk);
+}
+function tail(text, max = 2000) {
+    return text.length > max ? text.slice(text.length - max) : text;
+}
+function defaultBrowserSpawn(program, args) {
+    return spawn(program, [...args], { detached: true, stdio: ["ignore", "ignore", "pipe"] });
+}
+/** SIGTERM the process group, wait, then SIGKILL if it is still alive. */
+export async function terminateBrowserProcess(proc, graceMs = DEFAULT_SHUTDOWN_GRACE_MS) {
+    const exited = waitForExit(proc, graceMs);
+    signalBrowser(proc, "SIGTERM");
+    if (!(await exited))
+        signalBrowser(proc, "SIGKILL");
+}
+function signalBrowser(proc, signal) {
+    const pid = proc.pid;
+    if (pid !== undefined) {
+        try {
+            process.kill(-pid, signal);
+            return;
+        }
+        catch {
+            // not a group leader (or already gone): fall through to the direct child
+        }
+    }
+    try {
+        proc.kill(signal);
+    }
+    catch {
+        // already reaped
+    }
+}
+function waitForExit(proc, timeoutMs) {
+    return new Promise((resolve) => {
+        let settled = false;
+        const finish = (exited) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve(exited);
+        };
+        const timer = setTimeout(() => finish(false), timeoutMs);
+        timer.unref();
+        proc.once("exit", () => finish(true));
+    });
+}
+function removeDir(dir) {
+    try {
+        rmSync(dir, { recursive: true, force: true });
+    }
+    catch {
+        // a leftover profile dir must never fail close()
+    }
+}

package/dist/browser/memory-guard.d.ts

@@ -0,0 +1,55 @@
+/**
+ * F4 step 2b: the memory backstop for an RLIMIT_AS-exempted browser.
+ *
+ * Exempting RLIMIT_AS (step 2a) removes the sandbox's only virtual-memory
+ * bound, so this module re-establishes a REAL one, in this order:
+ *
+ *   1. **cgroup v2 memory.max** — exact and kernel-enforced, but only when the
+ *      service's cgroup is delegated (writable). Measured on the target host:
+ *      /sys/fs/cgroup is read-only (mkdir -> EACCES), so this path is attempted
+ *      and honestly reported as unavailable.
+ *   2. **bounded RSS watchdog** — sample the process tree's VmRSS on an interval
+ *      and SIGKILL the tree when it exceeds the cap. This is BOUNDED but not
+ *      instantaneous: a fast allocator can overshoot by one sampling window.
+ *   3. **none** — no /proc, no pid: reported as "none" with the reason. Never
+ *      silently claimed as protected.
+ *
+ * The guard is deliberately injectable (readRssKb / killTree / cgroupRoot) so
+ * the watchdog logic is unit-tested without allocating real memory.
+ */
+export type MemoryGuardKind = "cgroup-v2" | "rss-watchdog" | "none";
+/** What backstop is actually in force (reported in every browser result). */
+export interface MemoryGuardStatus {
+    kind: MemoryGuardKind;
+    limit_mb: number | null;
+    detail: string;
+    /** true once the watchdog killed the tree for exceeding the cap. */
+    killed: boolean;
+}
+export interface MemoryGuard {
+    status(): MemoryGuardStatus;
+    dispose(): void;
+}
+export interface MemoryGuardOptions {
+    pid: number | null;
+    limitMb: number;
+    /** Default "/sys/fs/cgroup". */
+    cgroupRoot?: string;
+    /** Override the current cgroup path (tests). Default: read /proc/self/cgroup. */
+    cgroupPath?: string | null;
+    /** VmRSS in KiB for the whole tree; null = unreadable. */
+    readRssKb?: (pid: number) => number | null;
+    /** SIGKILL the whole tree. */
+    killTree?: (pid: number) => void;
+    intervalMs?: number;
+}
+/** Default cap: 1 GiB of RSS for one browser tree. */
+export declare const DEFAULT_BROWSER_MEMORY_MB = 1024;
+/** Default sampling window. */
+export declare const DEFAULT_RSS_INTERVAL_MS = 500;
+/** Arm the strongest available backstop; always returns a truthful status. */
+export declare function armMemoryGuard(options: MemoryGuardOptions): MemoryGuard;
+/** Read this process's own cgroup v2 path from /proc/self/cgroup. */
+export declare function readOwnCgroupPath(procRoot?: string): string | null;
+/** Sum VmRSS (KiB) over the pid and every descendant, bounded. */
+export declare function readTreeRssKb(pid: number, procRoot?: string, maxPids?: number): number | null;