@indigoai-us/hq-cli 5.312.2-beta.0 → 5.314.0

package/dist/lib/report-snapshot.js

@@ -1,135 +0,0 @@
-/**
- * Report preview snapshot.
- *
- * Renders a report's index.html in a browser already installed on this
- * computer and returns a PNG of the first screen. The snapshot is a nicety:
- * every failure (no browser, timeout, empty file) returns null and the
- * publish carries on without a preview.
- */
-import { spawn } from "node:child_process";
-import * as fs from "node:fs";
-import * as os from "node:os";
-import * as path from "node:path";
-import { pathToFileURL } from "node:url";
-/** File name of the snapshot inside the published report. */
-export const REPORT_PREVIEW_FILE = "hq-preview.png";
-const REPORT_PREVIEW_WIDTH = 1280;
-const REPORT_PREVIEW_HEIGHT = 720;
-const SNAPSHOT_TIMEOUT_MS = 30_000;
-const PNG_MAGIC = Buffer.from([0x89, 0x50, 0x4e, 0x47]);
-const BROWSER_PATHS = {
-    darwin: [
-        "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
-        "/Applications/Chromium.app/Contents/MacOS/Chromium",
-        "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge",
-        "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
-    ],
-    linux: [
-        "/usr/bin/google-chrome",
-        "/usr/bin/google-chrome-stable",
-        "/usr/bin/chromium",
-        "/usr/bin/chromium-browser",
-        "/snap/bin/chromium",
-    ],
-    win32: [
-        "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe",
-        "C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe",
-        "C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe",
-    ],
-};
-/** First installed browser that can take a snapshot, or null. */
-export function findSnapshotBrowser(env = process.env, platform = process.platform, exists = fs.existsSync) {
-    const override = (env.HQ_REPORT_BROWSER ?? "").trim();
-    if (override)
-        return exists(override) ? override : null;
-    return (BROWSER_PATHS[platform] ?? []).find((file) => exists(file)) ?? null;
-}
-export function snapshotArgs(indexFile, outFile, profileDir) {
-    return [
-        "--headless=new",
-        "--disable-gpu",
-        "--hide-scrollbars",
-        "--no-first-run",
-        "--no-default-browser-check",
-        "--disable-extensions",
-        `--user-data-dir=${profileDir}`,
-        `--window-size=${REPORT_PREVIEW_WIDTH},${REPORT_PREVIEW_HEIGHT}`,
-        "--virtual-time-budget=5000",
-        `--screenshot=${outFile}`,
-        pathToFileURL(indexFile).toString(),
-    ];
-}
-function stop(child) {
-    if (child.pid === undefined)
-        return;
-    try {
-        // The browser is its own process group, so its helpers stop with it.
-        if (process.platform === "win32")
-            child.kill("SIGKILL");
-        else
-            process.kill(-child.pid, "SIGKILL");
-    }
-    catch {
-        // Already gone.
-    }
-}
-/**
- * Some browser versions write the snapshot and then never exit. The run is
- * done when the file is complete, so the browser is stopped at that point
- * instead of waited on.
- */
-const runBrowser = (browser, args, outFile, timeoutMs) => new Promise((resolve, reject) => {
-    const child = spawn(browser, args, { stdio: "ignore", detached: process.platform !== "win32" });
-    let lastSize = -1;
-    let settled = false;
-    const finish = (error) => {
-        if (settled)
-            return;
-        settled = true;
-        clearInterval(poll);
-        clearTimeout(limit);
-        stop(child);
-        if (error)
-            reject(error);
-        else
-            resolve();
-    };
-    const poll = setInterval(() => {
-        let size = 0;
-        try {
-            size = fs.statSync(outFile).size;
-        }
-        catch {
-            return;
-        }
-        if (size > 0 && size === lastSize)
-            finish();
-        lastSize = size;
-    }, 250);
-    const limit = setTimeout(() => finish(new Error("The snapshot timed out.")), timeoutMs);
-    child.once("error", (error) => finish(error));
-    child.once("exit", () => finish(fs.existsSync(outFile) ? undefined : new Error("The browser wrote no snapshot.")));
-});
-/** PNG of the report's first screen, or null when one cannot be made. */
-export async function snapshotReport(directory, options = {}) {
-    const browser = options.browser === undefined ? findSnapshotBrowser() : options.browser;
-    if (!browser)
-        return null;
-    const indexFile = path.join(path.resolve(directory), "index.html");
-    if (!fs.existsSync(indexFile))
-        return null;
-    const work = fs.mkdtempSync(path.join(os.tmpdir(), "hq-report-preview-"));
-    try {
-        const outFile = path.join(work, REPORT_PREVIEW_FILE);
-        await (options.run ?? runBrowser)(browser, snapshotArgs(indexFile, outFile, path.join(work, "profile")), outFile, SNAPSHOT_TIMEOUT_MS);
-        const bytes = fs.readFileSync(outFile);
-        return bytes.subarray(0, 4).equals(PNG_MAGIC) ? bytes : null;
-    }
-    catch {
-        return null;
-    }
-    finally {
-        fs.rmSync(work, { recursive: true, force: true });
-    }
-}
-//# sourceMappingURL=report-snapshot.js.map

package/dist/lib/report-templates.d.ts

@@ -1,9 +0,0 @@
-export type ReportTemplate = {
-    name: string;
-    path: string;
-    body: string;
-};
-export declare function listReportTemplates(root?: string): ReportTemplate[];
-/** Verbatim runbook. Callers substitute `<reportId>` when the id is known. */
-export declare function loadUpdateReportRunbook(root?: string): string;
-//# sourceMappingURL=report-templates.d.ts.map

package/dist/lib/report-templates.js

@@ -1,21 +0,0 @@
-/** Report templates and the update-report runbook shipped with hq-cli. */
-import { readdirSync, readFileSync } from "node:fs";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
-export function listReportTemplates(root = PACKAGE_ROOT) {
-    const dir = path.join(root, "templates", "reports");
-    return readdirSync(dir)
-        .filter((name) => name.endsWith(".md"))
-        .sort()
-        .map((file) => ({
-        name: file.slice(0, -3),
-        path: path.posix.join("templates", "reports", file),
-        body: readFileSync(path.join(dir, file), "utf8"),
-    }));
-}
-/** Verbatim runbook. Callers substitute `<reportId>` when the id is known. */
-export function loadUpdateReportRunbook(root = PACKAGE_ROOT) {
-    return readFileSync(path.join(root, "templates", "runbooks", "update-report.md"), "utf8");
-}
-//# sourceMappingURL=report-templates.js.map

package/dist/lib/scaffold-cli-floor.d.ts

@@ -1,8 +0,0 @@
-export type ScaffoldCliFloorComparison = {
-    status: "pass" | "fail" | "warn" | "skip";
-    message: string;
-    remediation?: string;
-};
-/** Compare an installed CLI version with the scaffold's supported floor. */
-export declare function compareScaffoldCliFloor(required: unknown, currentVersion: string): ScaffoldCliFloorComparison;
-//# sourceMappingURL=scaffold-cli-floor.d.ts.map

package/dist/lib/scaffold-cli-floor.js

@@ -1,50 +0,0 @@
-import semver from "semver";
-const SCAFFOLD_CLI_UPGRADE_COMMAND = "npm install -g @indigoai-us/hq-cli@latest";
-const MINIMUM_VERSION_RANGE = /^>=(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
-/** Compare an installed CLI version with the scaffold's supported floor. */
-export function compareScaffoldCliFloor(required, currentVersion) {
-    if (required === undefined) {
-        return {
-            status: "skip",
-            message: "No requiresHqCli floor is declared.",
-        };
-    }
-    const renderedRequired = renderValue(required);
-    if (typeof required !== "string" ||
-        !MINIMUM_VERSION_RANGE.test(required) ||
-        !semver.validRange(required)) {
-        return {
-            status: "warn",
-            message: `requiresHqCli has unsupported value ${renderedRequired}; expected a range in the form \">=X.Y.Z\".`,
-        };
-    }
-    if (!semver.valid(currentVersion)) {
-        return {
-            status: "warn",
-            message: `The running hq-cli version ${renderValue(currentVersion)} is not valid SemVer, so the scaffold CLI floor could not be checked.`,
-        };
-    }
-    if (semver.satisfies(currentVersion, required, { includePrerelease: true })) {
-        return {
-            status: "pass",
-            message: `hq-cli ${currentVersion} satisfies the scaffold requirement ${required}.`,
-        };
-    }
-    const minimum = required.slice(2);
-    return {
-        status: "fail",
-        message: `This scaffold requires hq-cli >= ${minimum} (found ${currentVersion}).`,
-        remediation: SCAFFOLD_CLI_UPGRADE_COMMAND,
-    };
-}
-function renderValue(value) {
-    if (typeof value === "string")
-        return JSON.stringify(value);
-    try {
-        return JSON.stringify(value) ?? String(value);
-    }
-    catch {
-        return String(value);
-    }
-}
-//# sourceMappingURL=scaffold-cli-floor.js.map

package/dist/lib/search-index/collection-path-repair-flag.d.ts

@@ -1,4 +0,0 @@
-export declare const QMD_COLLECTION_PATH_REPAIR_FLAG = "qmd.collection-path-repair";
-/** Keep collection-path repair off unless the hq-flags registry enables a canary. */
-export declare function qmdCollectionPathRepairEnabled(): boolean;
-//# sourceMappingURL=collection-path-repair-flag.d.ts.map

package/dist/lib/search-index/collection-path-repair-flag.js

@@ -1,7 +0,0 @@
-import { resolveProcessFlagGate } from '../flag-registry.js';
-export const QMD_COLLECTION_PATH_REPAIR_FLAG = 'qmd.collection-path-repair';
-/** Keep collection-path repair off unless the hq-flags registry enables a canary. */
-export function qmdCollectionPathRepairEnabled() {
-    return resolveProcessFlagGate(QMD_COLLECTION_PATH_REPAIR_FLAG, { fallback: false }, () => false);
-}
-//# sourceMappingURL=collection-path-repair-flag.js.map

package/dist/lib/search-index/embed-lock.d.ts

@@ -1,32 +0,0 @@
-export type EmbedLockDependencies = {
-    env: NodeJS.ProcessEnv;
-    now: () => number;
-    pid: number;
-    random: () => string;
-    isProcessAlive: (pid: number) => boolean;
-    /** Test seam for simulating a competing owner replacing the atomic record. */
-    afterOwnerPublish?: (ownerFile: string) => void;
-};
-export type EmbedLockProcessEvents = Pick<NodeJS.Process, 'once'> & {
-    removeListener?: NodeJS.Process['removeListener'];
-};
-export type EmbedLockRunResult = 'ran' | 'skipped' | 'busy' | 'unavailable';
-export declare function defaultEmbedLockDependencies(env?: NodeJS.ProcessEnv): EmbedLockDependencies;
-export declare function lockRoot(home: string): string;
-export declare function lockPath(home: string): string;
-export declare function lockState(directory: string, dependencies: EmbedLockDependencies): 'held' | 'stale' | 'free';
-export declare function acquireEmbedLock(home: string, dependencies: EmbedLockDependencies): boolean;
-export declare function releaseEmbedLock(home: string, dependencies: EmbedLockDependencies): void;
-/** Install signal and exit cleanup for a lock owner, returning an optional unregister hook. */
-export declare function installEmbedLockCleanup(cleanup: () => void, processEvents?: EmbedLockProcessEvents, exit?: (code: number) => void): () => void;
-/**
- * Run one synchronous QMD write or reindex pass while owning the shared lock.
- *
- * This deliberately does not install signal handlers. `run` is a synchronous
- * qmd child, so JavaScript cannot execute a cleanup handler until it returns;
- * registering SIGINT/SIGTERM would therefore suppress Node's immediate default
- * termination. An interrupted owner is safely reclaimed through the lock's
- * existing staleness and owner-grace protocol.
- */
-export declare function runWithEmbedLock(home: string, dependencies: EmbedLockDependencies, run: () => 'skipped' | void): EmbedLockRunResult;
-//# sourceMappingURL=embed-lock.d.ts.map

package/dist/lib/search-index/embed-lock.js

@@ -1,286 +0,0 @@
-import * as fs from 'node:fs';
-import * as path from 'node:path';
-/**
- * Serializes QMD writes started through HQ-managed hq-cli paths. A bare `qmd
- * update` / `qmd embed` (or another tool that does not call this module) cannot
- * participate, because qmd is a third-party package and does not know about
- * HQ's lock protocol.
- */
-const EMBED_LOCK_NAME = 'qmd-reindex-bg.lock';
-export function defaultEmbedLockDependencies(env = process.env) {
-    return {
-        env,
-        now: () => Math.floor(Date.now() / 1_000),
-        pid: process.pid,
-        random: () => Math.random().toString(36).slice(2),
-        isProcessAlive: (pid) => {
-            try {
-                process.kill(pid, 0);
-                return true;
-            }
-            catch {
-                return false;
-            }
-        },
-    };
-}
-export function lockRoot(home) {
-    return path.join(home, '.hq', 'locks');
-}
-export function lockPath(home) {
-    return path.join(lockRoot(home), EMBED_LOCK_NAME);
-}
-function parseFields(file) {
-    try {
-        return Object.fromEntries(fs.readFileSync(file, 'utf8').split('\n').flatMap((line) => {
-            const index = line.indexOf('=');
-            return index === -1 ? [] : [[line.slice(0, index), line.slice(index + 1)]];
-        }));
-    }
-    catch {
-        return undefined;
-    }
-}
-function readOwner(directory) {
-    const fields = parseFields(path.join(directory, 'owner'));
-    if (!fields || !/^\d+$/.test(fields.pid ?? '') || !/^\d+$/.test(fields.ts ?? '') || !/^[A-Za-z0-9._-]+$/.test(fields.nonce ?? ''))
-        return undefined;
-    return { pid: Number(fields.pid), ts: Number(fields.ts), nonce: fields.nonce };
-}
-function graceSeconds(dependencies) {
-    const value = dependencies.env.QMD_HANDOFF_LOCK_GRACE_SEC;
-    return value && /^\d+$/.test(value) ? Number(value) : 5;
-}
-function isOwnerlessLockWithinGrace(directory, dependencies) {
-    try {
-        const age = Math.max(0, dependencies.now() - Math.floor(fs.statSync(directory).mtimeMs / 1_000));
-        return age < graceSeconds(dependencies);
-    }
-    catch {
-        return true;
-    }
-}
-export function lockState(directory, dependencies) {
-    if (!fs.existsSync(directory))
-        return 'free';
-    const owner = readOwner(directory);
-    if (owner)
-        return dependencies.isProcessAlive(owner.pid) ? 'held' : 'stale';
-    return isOwnerlessLockWithinGrace(directory, dependencies) ? 'held' : 'stale';
-}
-function generation(directory) {
-    const owner = readOwner(directory);
-    if (owner)
-        return owner.nonce;
-    if (!fs.existsSync(directory))
-        return undefined;
-    return 'empty';
-}
-function removeDirectoryIfEmpty(directory) {
-    try {
-        fs.rmdirSync(directory);
-    }
-    catch { /* another claimant owns it, or it is already gone */ }
-}
-function claimWithinGrace(directory, dependencies) {
-    try {
-        const age = Math.max(0, dependencies.now() - Math.floor(fs.statSync(directory).mtimeMs / 1_000));
-        return age < Math.max(5, graceSeconds(dependencies));
-    }
-    catch {
-        return true;
-    }
-}
-function acquireClaim(home, observedGeneration, dependencies) {
-    const claim = path.join(lockRoot(home), `qmd-reindex-bg.claim.${observedGeneration}`);
-    for (let attempt = 0; attempt < 2; attempt += 1) {
-        try {
-            fs.mkdirSync(claim);
-        }
-        catch {
-            if (attempt === 1 || !recoverAbandonedClaim(claim, dependencies))
-                return undefined;
-            continue;
-        }
-        const claimant = path.join(claim, `c.${dependencies.pid}.${dependencies.random()}`);
-        try {
-            fs.mkdirSync(claimant);
-            // Test-only deterministic failure inject (unset in production) — shell
-            // parity with the script's claimant write_owner_record injection.
-            if (dependencies.env.QMD_FORCE_CLAIMANT_WRITE_FAIL)
-                throw new Error('forced claimant write failure');
-            fs.writeFileSync(path.join(claimant, 'owner'), `pid=${dependencies.pid}\nts=${dependencies.now()}\n`);
-            return { claim, claimant };
-        }
-        catch {
-            fs.rmSync(claimant, { recursive: true, force: true });
-            removeDirectoryIfEmpty(claim);
-            return undefined;
-        }
-    }
-    return undefined;
-}
-/**
- * Reclaim only exact dead claimant names, then remove the claim directory if
- * empty. This mirrors the shell's no-fixed-path-reclaim rule: a peer that has
- * recreated claim.G with a new marker makes rmdir fail and wins the race.
- *
- * A process killed after the identity-safe rename and before its rmSync leaves
- * a `*.stale-claim.*` directory behind. That name is intentionally forensic:
- * it is no longer an active claim and records the interrupted reclaim for the
- * feedback bundle, so no later acquirer should sweep it by a fixed path.
- */
-function recoverAbandonedClaim(claim, dependencies) {
-    let entries;
-    try {
-        entries = fs.readdirSync(claim, { withFileTypes: true });
-    }
-    catch {
-        return true;
-    }
-    for (const entry of entries.filter((entry) => entry.name.startsWith('c.'))) {
-        const marker = path.join(claim, entry.name);
-        const fields = parseFields(path.join(marker, 'owner'));
-        const pid = fields && /^\d+$/.test(fields.pid ?? '') ? Number(fields.pid) : undefined;
-        if (pid !== undefined && dependencies.isProcessAlive(pid))
-            return false;
-        if (pid === undefined && claimWithinGrace(claim, dependencies))
-            return false;
-        const abandoned = `${claim}.stale-claim.${dependencies.pid}.${dependencies.random()}`;
-        try {
-            fs.renameSync(marker, abandoned);
-            fs.rmSync(abandoned, { recursive: true, force: true });
-        }
-        catch {
-            return false;
-        }
-    }
-    if (entries.length === 0 && claimWithinGrace(claim, dependencies))
-        return false;
-    removeDirectoryIfEmpty(claim);
-    return !fs.existsSync(claim);
-}
-function createAndPublishLock(home, dependencies) {
-    const directory = lockPath(home);
-    try {
-        fs.mkdirSync(directory);
-    }
-    catch {
-        return false;
-    }
-    const marker = path.join(directory, `acq.${dependencies.pid}.${dependencies.random()}`);
-    try {
-        fs.mkdirSync(marker);
-    }
-    catch {
-        removeDirectoryIfEmpty(directory);
-        return false;
-    }
-    const nonce = `${dependencies.pid}.${dependencies.random()}`;
-    const ownerFile = path.join(directory, 'owner');
-    const temporary = path.join(directory, `.owner.tmp.${dependencies.pid}.${dependencies.random()}`);
-    try {
-        // Test-only deterministic failure inject (unset in production) — shell
-        // parity: the script's write_owner_record honored the same variable.
-        if (dependencies.env.QMD_FORCE_OWNER_WRITE_FAIL)
-            throw new Error('forced owner write failure');
-        fs.writeFileSync(temporary, `pid=${dependencies.pid}\nts=${dependencies.now()}\nnonce=${nonce}\n`);
-        fs.renameSync(temporary, ownerFile);
-        dependencies.afterOwnerPublish?.(ownerFile);
-        const verified = readOwner(directory);
-        if (!verified || verified.pid !== dependencies.pid || verified.nonce !== nonce)
-            throw new Error('owner publish verification failed');
-        fs.rmSync(marker, { recursive: true, force: true });
-        return true;
-    }
-    catch {
-        // The marker identifies only the directory this process created. Do not
-        // recursively remove the fixed lock path after a failed publication.
-        fs.rmSync(marker, { recursive: true, force: true });
-        removeDirectoryIfEmpty(directory);
-        return false;
-    }
-}
-function claimAndReclaim(home, dependencies) {
-    const directory = lockPath(home);
-    const observedGeneration = generation(directory);
-    if (!observedGeneration || lockState(directory, dependencies) !== 'stale')
-        return false;
-    const acquired = acquireClaim(home, observedGeneration, dependencies);
-    if (!acquired)
-        return false;
-    try {
-        // Generation fencing: only move exactly the stale generation we observed.
-        if (generation(directory) !== observedGeneration || lockState(directory, dependencies) !== 'stale')
-            return false;
-        const abandoned = `${directory}.stale.${dependencies.pid}.${dependencies.random()}`;
-        fs.renameSync(directory, abandoned);
-        fs.rmSync(abandoned, { recursive: true, force: true });
-        return createAndPublishLock(home, dependencies);
-    }
-    catch {
-        return false;
-    }
-    finally {
-        fs.rmSync(acquired.claimant, { recursive: true, force: true });
-        removeDirectoryIfEmpty(acquired.claim);
-    }
-}
-function tryAcquireEmbedLock(home, dependencies) {
-    try {
-        fs.mkdirSync(lockRoot(home), { recursive: true });
-        fs.accessSync(lockRoot(home), fs.constants.W_OK | fs.constants.X_OK);
-    }
-    catch {
-        return 'unavailable';
-    }
-    return createAndPublishLock(home, dependencies) || claimAndReclaim(home, dependencies)
-        ? 'acquired'
-        : 'busy';
-}
-export function acquireEmbedLock(home, dependencies) {
-    return tryAcquireEmbedLock(home, dependencies) === 'acquired';
-}
-export function releaseEmbedLock(home, dependencies) {
-    const directory = lockPath(home);
-    if (readOwner(directory)?.pid === dependencies.pid)
-        fs.rmSync(directory, { recursive: true, force: true });
-}
-/** Install signal and exit cleanup for a lock owner, returning an optional unregister hook. */
-export function installEmbedLockCleanup(cleanup, processEvents = process, exit = (code) => process.exit(code)) {
-    const onExit = cleanup;
-    const onSignal = () => { cleanup(); exit(0); };
-    processEvents.once('exit', onExit);
-    processEvents.once('SIGINT', onSignal);
-    processEvents.once('SIGTERM', onSignal);
-    processEvents.once('SIGHUP', onSignal);
-    return () => {
-        processEvents.removeListener?.('exit', onExit);
-        processEvents.removeListener?.('SIGINT', onSignal);
-        processEvents.removeListener?.('SIGTERM', onSignal);
-        processEvents.removeListener?.('SIGHUP', onSignal);
-    };
-}
-/**
- * Run one synchronous QMD write or reindex pass while owning the shared lock.
- *
- * This deliberately does not install signal handlers. `run` is a synchronous
- * qmd child, so JavaScript cannot execute a cleanup handler until it returns;
- * registering SIGINT/SIGTERM would therefore suppress Node's immediate default
- * termination. An interrupted owner is safely reclaimed through the lock's
- * existing staleness and owner-grace protocol.
- */
-export function runWithEmbedLock(home, dependencies, run) {
-    const acquired = tryAcquireEmbedLock(home, dependencies);
-    if (acquired === 'unavailable')
-        return 'unavailable';
-    if (acquired === 'busy')
-        return 'busy';
-    try {
-        return run() === 'skipped' ? 'skipped' : 'ran';
-    }
-    finally {
-        releaseEmbedLock(home, dependencies);
-    }
-}
-//# sourceMappingURL=embed-lock.js.map

package/dist/lib/search-index/load-gate.d.ts

@@ -1,57 +0,0 @@
-import * as os from 'node:os';
-export declare const DEFAULT_MAX_LOAD_PERCENT = 50;
-/**
- * Twelve requests is enough to avoid quietly starving a frequently requested
- * index, while still leaving several opportunities for a busy machine to cool
- * down before we spend CPU on an embed. The thirteenth request is forced.
- */
-export declare const MAX_CONSECUTIVE_DEFERRED_EMBEDS = 12;
-/** Six hours bounds deferral even when indexing requests are infrequent. */
-export declare const MAX_EMBED_DEFERRAL_SECONDS: number;
-export type LoadGateDependencies = {
-    env: NodeJS.ProcessEnv;
-    now: () => number;
-    readFile: (file: string) => string;
-    writeFile: (file: string, contents: string) => void;
-    rename: (source: string, destination: string) => void;
-    mkdir: (directory: string) => void;
-    /** A synchronous seam so the existing synchronous qmd entry points stay synchronous. */
-    sleep: (milliseconds: number) => void;
-    cpus: () => os.CpuInfo[];
-    /** Only used outside Linux, where /proc/meminfo is unavailable. */
-    freemem: () => number;
-    totalmem: () => number;
-};
-export type EmbedLoadDecision = {
-    action: 'embed';
-    forced: false;
-} | {
-    action: 'embed';
-    forced: true;
-    notice: string;
-} | {
-    action: 'skip';
-    signal: 'cpu' | 'memory';
-    percent: number;
-    limit: number;
-    notice: string;
-};
-export declare class LoadGateConfigurationError extends Error {
-    constructor(value: string);
-}
-export declare function defaultLoadGateDependencies(env?: NodeJS.ProcessEnv): LoadGateDependencies;
-/** Sample aggregate CPU busy time over 200 ms, falling back only without /proc/stat. */
-export declare function measureCpuPercent(dependencies: LoadGateDependencies): number;
-/** Prefer Linux MemAvailable, because MemFree alone treats reclaimable cache as used memory. */
-export declare function measureMemoryPercent(dependencies: LoadGateDependencies): number;
-export declare function parseLoadThreshold(env: NodeJS.ProcessEnv): number | undefined;
-export declare function loadGateStatePath(home: string): string;
-/**
- * Decide immediately before qmd embed whether this host can absorb it. The
- * caller must already own the shared embed lock, so state updates are atomic
- * with respect to hq-cli's other embed entry points.
- */
-export declare function checkEmbedLoad(home: string, dependencies: LoadGateDependencies): EmbedLoadDecision;
-/** Reset the starvation counter only after qmd embed has actually returned successfully. */
-export declare function recordSuccessfulEmbed(home: string, dependencies: LoadGateDependencies): void;
-//# sourceMappingURL=load-gate.d.ts.map