@indigoai-us/hq-cli 5.314.0 → 5.315.0

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

@@ -11,6 +11,7 @@ export type QmdProcessResult = {
      */
     signal?: NodeJS.Signals | string | null;
 };
+export type QmdUpdateEntryPath = 'index-sync';
 export type QmdProcessRunner = (bin: string, args: string[], options: {
     cwd?: string;
     env?: NodeJS.ProcessEnv;
@@ -113,6 +114,10 @@ export declare class QmdExitError extends Error {
     readonly stdout: string;
     readonly stderr: string;
     name: string;
+    /** Safe route labels for telemetry; raw qmd streams remain local to the error. */
+    entryPath?: QmdUpdateEntryPath;
+    /** Present only when the invoked executable is the bundled qmd. */
+    qmdVersion?: string;
     constructor(message: string, args: string[], status: number | null, stdout: string, stderr: string);
 }
 export declare class QmdCollectionMissingError extends QmdExitError {
@@ -375,6 +380,7 @@ export declare function lastQmdStoreEnsureOutcome(): QmdStoreEnsureOutcome | und
  * An upstream-contract test pins this rule to the INSTALLED qmd so a bump that
  * changes it turns CI red instead of silently restoring the noise.
  */
+export declare function resolveQmdHome(env?: NodeJS.ProcessEnv): string;
 export declare function resolveQmdStoreDir(env?: NodeJS.ProcessEnv, cwd?: string): string;
 export type EnsureQmdStoreDirOptions = {
     /**
@@ -506,6 +512,8 @@ export type ResolveQmdInvocationOptions = {
 export declare function resolveQmdInvocation(options?: ResolveQmdInvocationOptions): QmdInvocation;
 export type RunQmdOptions = {
     bin?: string;
+    /** Source of an update failure, used only for bounded Sentry tags. */
+    entryPath?: QmdUpdateEntryPath;
     cwd?: string;
     env?: NodeJS.ProcessEnv;
     runner?: QmdProcessRunner;
@@ -536,10 +544,14 @@ export declare function deriveCollections(hqRoot: string): SearchCollection[];
 export type ReconcileCollectionsOptions = {
     bin?: string;
     runner?: QmdProcessRunner;
+    /** Test seam for the default-off collection-path repair rollout. */
+    repairPathDrift?: boolean;
 };
 /**
  * Register expected collections that qmd does not yet know about, returning the
  * collections this call actually created (a `collection add` that exited 0).
+ * When the default-off hq-flags rollout is enabled, it also replaces a registered
+ * collection whose path matches a known prior HQ-managed layout.
  *
  * A same-name idempotent duplicate — qmd already owns the exact requested name
  * in its YAML config (`Collection '<name>' already exists.`), while the

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

@@ -1,18 +1,20 @@
 import { spawnSync } from 'node:child_process';
 import * as fs from 'node:fs';
-import { createRequire } from 'node:module';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { dump, load } from 'js-yaml';
 import { isQmdModelDownloadError } from '../../utils/qmd-model-download-error.js';
 import { isQmdModuleMissingError } from '../../utils/qmd-module-missing-error.js';
 import { isQmdNativeBindingError } from '../../utils/qmd-native-binding-error.js';
 import { isQmdQueryDocumentError } from '../../utils/qmd-query-document-error.js';
 import { isQmdStoreMissingError } from '../../utils/qmd-store-missing-error.js';
 import { isQmdStoreUnopenableError } from '../../utils/qmd-store-unopenable-error.js';
+import { markExpectedUserError } from '../../utils/expected-cli-error.js';
 import { redactErrorText } from '../../utils/redact-error-text.js';
 import { planCommandSpawn } from '../../utils/windows-spawn.js';
-const require = createRequire(import.meta.url);
+import { resolveQmdConfigPath } from './max-doc-bytes.js';
+import { qmdCollectionPathRepairEnabled } from './collection-path-repair-flag.js';
 /** The `path` implementation for a (possibly injected) platform. */
 function pathFor(platform) {
     return platform === 'win32' ? path.win32 : path.posix;
@@ -74,6 +76,10 @@ export class QmdExitError extends Error {
     stdout;
     stderr;
     name = 'QmdExitError';
+    /** Safe route labels for telemetry; raw qmd streams remain local to the error. */
+    entryPath;
+    /** Present only when the invoked executable is the bundled qmd. */
+    qmdVersion;
     constructor(message, args, status, stdout, stderr) {
         super(message);
         this.args = args;
@@ -428,13 +434,16 @@ export function lastQmdStoreEnsureOutcome() {
  * An upstream-contract test pins this rule to the INSTALLED qmd so a bump that
  * changes it turns CI red instead of silently restoring the noise.
  */
+export function resolveQmdHome(env = process.env) {
+    return env.HOME || env.USERPROFILE || os.homedir() || '/tmp';
+}
 export function resolveQmdStoreDir(env = process.env, cwd = process.cwd()) {
     const indexPath = env.INDEX_PATH;
     // path.resolve leaves an absolute INDEX_PATH untouched and anchors a relative
     // one to the child cwd, so the probed/stamped directory is the one qmd uses.
     if (indexPath)
         return path.dirname(path.resolve(cwd, indexPath));
-    const home = env.HOME || env.USERPROFILE || os.homedir() || '/tmp';
+    const home = resolveQmdHome(env);
     const cacheDir = env.XDG_CACHE_HOME || path.join(home, '.cache');
     return path.join(cacheDir, 'qmd');
 }
@@ -1002,6 +1011,22 @@ function describeQmdTermination(stdout, stderr) {
         return `qmd reported: ${summary.reason}`;
     return '';
 }
+/**
+ * qmd caller-state failures that the top-level boundary may surface without a
+ * crash report. The match is deliberately against qmd's raw stderr and a
+ * closed subcommand set: a query containing these words must not change the
+ * disposition of an unrelated qmd exit.
+ */
+function isExpectedQmdCallerFailure(args, stderr) {
+    const subcommand = args[0];
+    if (subcommand === 'get') {
+        return /^Document not found:\s+[^\r\n]+$/m.test(stderr);
+    }
+    if (subcommand === 'collection') {
+        return /(?:^|\b)Failed to parse\s+[^\r\n]+:\s*.+$/m.test(stderr);
+    }
+    return false;
+}
 /** Normalise a spawn result and raise the typed qmd failures. */
 function finishRunQmd(result, bin, args, attribution) {
     const normalized = {
@@ -1212,7 +1237,26 @@ function finishRunQmd(result, bin, args, attribution) {
     if (alreadyExists) {
         throw new QmdCollectionExistsError(message, args, normalized.status, normalized.stdout, normalized.stderr, alreadyExists[1]);
     }
-    throw new QmdExitError(message, args, normalized.status, normalized.stdout, normalized.stderr);
+    const exitError = new QmdExitError(message, args, normalized.status, normalized.stdout, normalized.stderr);
+    if (isExpectedQmdCallerFailure(args, normalized.stderr)) {
+        throw markExpectedUserError(exitError);
+    }
+    throw exitError;
+}
+function finishRunQmdWithDiagnostics(result, bin, args, options, attribution) {
+    try {
+        return finishRunQmd(result, bin, args, attribution);
+    }
+    catch (error) {
+        if (error instanceof QmdExitError) {
+            if (args[0] === 'update' && options.entryPath)
+                error.entryPath = options.entryPath;
+            const bundledBins = [packageLocalBin(), packageLocalNodeEntry()].filter((candidate) => Boolean(candidate));
+            if (bundledBins.includes(bin))
+                error.qmdVersion = resolveQmdVersion();
+        }
+        throw error;
+    }
 }
 /** Run qmd with captured output and typed failures. */
 export function runQmd(args, options = {}) {
@@ -1221,7 +1265,7 @@ export function runQmd(args, options = {}) {
     if (options.runner) {
         const bin = options.bin ?? resolveQmdBin({ env: options.env });
         const result = options.runner(bin, args, { cwd: options.cwd, env: options.env });
-        return finishRunQmd(result, bin, args);
+        return finishRunQmdWithDiagnostics(result, bin, args, options);
     }
     // Default path: resolve the full invocation (shell-free Node launcher preferred)
     // and spawn it through the shared Windows-aware plan. An explicit string bin is
@@ -1254,7 +1298,7 @@ export function runQmd(args, options = {}) {
     // genuinely missing qmd — instead of blaming the launcher for all three
     // (HQ-CLI-1A). `command` is the process actually spawned; `launcher` is qmd's
     // file identity.
-    return finishRunQmd(result, launcher, args, {
+    return finishRunQmdWithDiagnostics(result, launcher, args, options, {
         command: invocation.command,
         launcher,
         cwd: options.cwd,
@@ -1328,9 +1372,90 @@ export function deriveCollections(hqRoot) {
     }
     return collections;
 }
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function qmdConfigPath(hqRoot) {
+    const env = {
+        ...process.env,
+        HOME: process.env.HOME ?? process.env.USERPROFILE ?? os.homedir(),
+    };
+    return resolveQmdConfigPath({ env, startDir: hqRoot });
+}
+/** Read qmd's configured collection metadata from the same config file its CLI uses. */
+function configuredCollections(hqRoot) {
+    const configPath = qmdConfigPath(hqRoot);
+    if (!configPath || !fs.existsSync(configPath))
+        return new Map();
+    const document = load(fs.readFileSync(configPath, 'utf8'));
+    if (!isRecord(document) || !isRecord(document.collections))
+        return new Map();
+    return new Map(Object.entries(document.collections).flatMap(([name, config]) => isRecord(config) && typeof config.path === 'string' ? [[name, config]] : []));
+}
+/** Restore existing collection options after qmd's add command rewrites the entry. */
+function restoreCollectionMetadata(hqRoot, collection, previousConfig) {
+    const configPath = qmdConfigPath(hqRoot);
+    if (!configPath || !fs.existsSync(configPath)) {
+        throw new Error(`QMD config disappeared while repairing collection '${collection.name}'`);
+    }
+    const document = load(fs.readFileSync(configPath, 'utf8'));
+    if (!isRecord(document) || !isRecord(document.collections)) {
+        throw new Error(`QMD config has no collections map while repairing '${collection.name}'`);
+    }
+    const currentConfig = document.collections[collection.name];
+    document.collections[collection.name] = {
+        ...(isRecord(currentConfig) ? currentConfig : {}),
+        ...previousConfig,
+        path: collection.path,
+    };
+    fs.writeFileSync(configPath, dump(document, { lineWidth: 0 }));
+}
+function resolvedPath(value) {
+    const absolutePath = path.resolve(value);
+    try {
+        return fs.realpathSync(absolutePath);
+    }
+    catch {
+        return absolutePath;
+    }
+}
+function comparablePath(value) {
+    return process.platform === 'win32' ? value.toLowerCase() : value;
+}
+/** Repair a known HQ-managed path, including the former company knowledge mirror layout. */
+function isPreviousHqManagedPath(hqRoot, collection, configuredPath) {
+    const root = resolvedPath(hqRoot);
+    const expectedPath = resolvedPath(collection.path);
+    const managedRelativePath = path.relative(root, expectedPath);
+    if (!managedRelativePath ||
+        path.isAbsolute(managedRelativePath) ||
+        managedRelativePath === '..' ||
+        managedRelativePath.startsWith(`..${path.sep}`)) {
+        return false;
+    }
+    const actualPath = resolvedPath(path.resolve(hqRoot, configuredPath));
+    const suffix = `${path.sep}${managedRelativePath}`;
+    const actualForComparison = comparablePath(actualPath);
+    const suffixForComparison = comparablePath(suffix);
+    const prefixLength = actualForComparison.length - suffixForComparison.length;
+    if (prefixLength > path.parse(actualPath).root.length && actualForComparison.endsWith(suffixForComparison)) {
+        return true;
+    }
+    const expectedParts = managedRelativePath.split(path.sep);
+    if (expectedParts.length !== 3 || expectedParts[0] !== 'companies' || expectedParts[2] !== 'knowledge') {
+        return false;
+    }
+    const slug = expectedParts[1];
+    if (!slug)
+        return false;
+    const formerMirrorPath = resolvedPath(path.join(root, 'repos', 'private', `knowledge-${slug}`));
+    return comparablePath(actualPath) === comparablePath(formerMirrorPath);
+}
 /**
  * Register expected collections that qmd does not yet know about, returning the
  * collections this call actually created (a `collection add` that exited 0).
+ * When the default-off hq-flags rollout is enabled, it also replaces a registered
+ * collection whose path matches a known prior HQ-managed layout.
  *
  * A same-name idempotent duplicate — qmd already owns the exact requested name
  * in its YAML config (`Collection '<name>' already exists.`), while the
@@ -1346,11 +1471,29 @@ export function deriveCollections(hqRoot) {
 export function reconcileCollections(hqRoot, options = {}) {
     const runOptions = { bin: options.bin, runner: options.runner, cwd: hqRoot };
     const registered = listRegisteredCollections(hqRoot, runOptions);
-    const missing = deriveCollections(hqRoot).filter((collection) => !registered.has(collection.name));
+    const expected = deriveCollections(hqRoot);
+    const repairPathDrift = options.repairPathDrift ?? qmdCollectionPathRepairEnabled();
+    const configured = repairPathDrift ? configuredCollections(hqRoot) : new Map();
+    const stale = repairPathDrift
+        ? expected.filter((collection) => {
+            const previousConfig = configured.get(collection.name);
+            return previousConfig !== undefined
+                && comparablePath(resolvedPath(path.resolve(hqRoot, previousConfig.path))) !== comparablePath(resolvedPath(collection.path))
+                && isPreviousHqManagedPath(hqRoot, collection, previousConfig.path);
+        })
+        : [];
+    for (const collection of stale) {
+        runQmd(['collection', 'remove', collection.name], runOptions);
+        registered.delete(collection.name);
+    }
+    const missing = expected.filter((collection) => !registered.has(collection.name));
     const created = [];
     for (const collection of missing) {
         try {
             runQmd(['collection', 'add', collection.path, '--name', collection.name, '--mask', collection.mask], runOptions);
+            const previousConfig = configured.get(collection.name);
+            if (previousConfig)
+                restoreCollectionMetadata(hqRoot, collection, previousConfig);
             created.push(collection);
         }
         catch (error) {
@@ -1359,6 +1502,9 @@ export function reconcileCollections(hqRoot, options = {}) {
             // different collection — stays fatal.
             if (!(error instanceof QmdCollectionExistsError) || error.collectionName !== collection.name)
                 throw error;
+            const previousConfig = configured.get(collection.name);
+            if (previousConfig)
+                restoreCollectionMetadata(hqRoot, collection, previousConfig);
         }
         runQmd(['context', 'add', `qmd://${collection.name}`, collection.context], runOptions);
     }

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

@@ -0,0 +1,57 @@
+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

package/dist/lib/search-index/load-gate.js

@@ -0,0 +1,270 @@
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { lockRoot } from './embed-lock.js';
+export 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 const MAX_CONSECUTIVE_DEFERRED_EMBEDS = 12;
+/** Six hours bounds deferral even when indexing requests are infrequent. */
+export const MAX_EMBED_DEFERRAL_SECONDS = 6 * 60 * 60;
+const LOAD_GATE_STATE_NAME = 'qmd-embed-load-state';
+const PROC_STAT = '/proc/stat';
+const PROC_MEMINFO = '/proc/meminfo';
+export class LoadGateConfigurationError extends Error {
+    constructor(value) {
+        super(`HQ_INDEX_MAX_LOAD_PERCENT must be an integer from 1 to 100, 0, or off; received ${JSON.stringify(value)}.`);
+        this.name = 'LoadGateConfigurationError';
+    }
+}
+function synchronousSleep(milliseconds) {
+    const slot = new Int32Array(new SharedArrayBuffer(4));
+    Atomics.wait(slot, 0, 0, milliseconds);
+}
+export function defaultLoadGateDependencies(env = process.env) {
+    return {
+        env,
+        now: () => Math.floor(Date.now() / 1_000),
+        readFile: (file) => fs.readFileSync(file, 'utf8'),
+        writeFile: (file, contents) => fs.writeFileSync(file, contents),
+        rename: (source, destination) => fs.renameSync(source, destination),
+        mkdir: (directory) => fs.mkdirSync(directory, { recursive: true }),
+        sleep: synchronousSleep,
+        cpus: () => os.cpus(),
+        // os.freemem() reports MemFree on Linux, which excludes reclaimable cache.
+        // Use it only where /proc/meminfo does not exist.
+        freemem: () => os.freemem(),
+        totalmem: () => os.totalmem(),
+    };
+}
+function errorCode(error) {
+    return error?.code;
+}
+function missing(error) {
+    return errorCode(error) === 'ENOENT';
+}
+function parseProcStatAggregate(contents) {
+    const line = contents.split('\n').find((candidate) => /^cpu\s+/.test(candidate));
+    if (!line)
+        return undefined;
+    const values = line.trim().split(/\s+/).slice(1).map(Number);
+    if (values.length < 5 || values.some((value) => !Number.isFinite(value) || value < 0))
+        return undefined;
+    // Linux reports guest and guest_nice inside user and nice respectively.
+    const total = values.slice(0, 8).reduce((sum, value) => sum + value, 0);
+    const idle = values[3] + values[4];
+    return total > 0 && Number.isFinite(idle) ? { total, idle } : undefined;
+}
+function cpuBusyPercent(before, after) {
+    const totalDelta = after.total - before.total;
+    const idleDelta = after.idle - before.idle;
+    if (totalDelta <= 0 || idleDelta < 0)
+        return undefined;
+    return Math.max(0, Math.min(100, (1 - idleDelta / totalDelta) * 100));
+}
+function cpuCountersFromCpus(cpus) {
+    let total = 0;
+    let idle = 0;
+    if (cpus.length === 0)
+        return undefined;
+    for (const cpu of cpus) {
+        const { user, nice, sys, idle: cpuIdle, irq } = cpu.times;
+        const values = [user, nice, sys, cpuIdle, irq];
+        if (values.some((value) => !Number.isFinite(value) || value < 0))
+            return undefined;
+        total += values.reduce((sum, value) => sum + value, 0);
+        idle += cpuIdle;
+    }
+    return total > 0 ? { total, idle } : undefined;
+}
+function fallbackCpuPercent(dependencies) {
+    const before = cpuCountersFromCpus(dependencies.cpus());
+    dependencies.sleep(200);
+    const after = cpuCountersFromCpus(dependencies.cpus());
+    const busy = before && after ? cpuBusyPercent(before, after) : undefined;
+    if (busy === undefined)
+        throw new Error('Cannot determine CPU busy time from os.cpus().');
+    return busy;
+}
+/** Sample aggregate CPU busy time over 200 ms, falling back only without /proc/stat. */
+export function measureCpuPercent(dependencies) {
+    let first;
+    try {
+        first = dependencies.readFile(PROC_STAT);
+    }
+    catch (error) {
+        if (missing(error))
+            return fallbackCpuPercent(dependencies);
+        throw error;
+    }
+    dependencies.sleep(200);
+    let second;
+    try {
+        second = dependencies.readFile(PROC_STAT);
+    }
+    catch (error) {
+        if (missing(error))
+            return fallbackCpuPercent(dependencies);
+        throw error;
+    }
+    const before = parseProcStatAggregate(first);
+    const after = parseProcStatAggregate(second);
+    const busy = before && after ? cpuBusyPercent(before, after) : undefined;
+    if (busy === undefined)
+        throw new Error('Cannot determine CPU busy time from /proc/stat.');
+    return busy;
+}
+function memAvailableFraction(contents) {
+    const fields = new Map();
+    for (const line of contents.split('\n')) {
+        const match = /^(MemTotal|MemAvailable):\s+(\d+)\s+kB$/.exec(line.trim());
+        if (match)
+            fields.set(match[1], Number(match[2]));
+    }
+    const total = fields.get('MemTotal');
+    const available = fields.get('MemAvailable');
+    if (total === undefined || available === undefined || total <= 0 || available < 0 || available > total)
+        return undefined;
+    return 1 - available / total;
+}
+/** Prefer Linux MemAvailable, because MemFree alone treats reclaimable cache as used memory. */
+export function measureMemoryPercent(dependencies) {
+    try {
+        const fraction = memAvailableFraction(dependencies.readFile(PROC_MEMINFO));
+        if (fraction === undefined)
+            throw new Error('Cannot determine memory use from /proc/meminfo.');
+        return fraction * 100;
+    }
+    catch (error) {
+        if (!missing(error))
+            throw error;
+    }
+    const total = dependencies.totalmem();
+    const free = dependencies.freemem();
+    if (total <= 0 || free < 0 || free > total)
+        throw new Error('Cannot determine memory use.');
+    return (1 - free / total) * 100;
+}
+export function parseLoadThreshold(env) {
+    const value = env.HQ_INDEX_MAX_LOAD_PERCENT?.trim() || String(DEFAULT_MAX_LOAD_PERCENT);
+    if (value === '0' || value.toLowerCase() === 'off')
+        return undefined;
+    if (!/^[1-9]\d{0,2}$/.test(value) || Number(value) > 100)
+        throw new LoadGateConfigurationError(value);
+    return Number(value);
+}
+export function loadGateStatePath(home) {
+    return path.join(lockRoot(home), LOAD_GATE_STATE_NAME);
+}
+function readFields(file, dependencies) {
+    try {
+        const fields = {};
+        for (const line of dependencies.readFile(file).split('\n')) {
+            if (line === '')
+                continue;
+            const index = line.indexOf('=');
+            const key = line.slice(0, index);
+            if (index < 1 || !['skips', 'firstDeferredAt', 'lastSuccessfulEmbedAt'].includes(key) || fields[key] !== undefined)
+                return undefined;
+            fields[key] = line.slice(index + 1);
+        }
+        return fields;
+    }
+    catch (error) {
+        if (missing(error))
+            return undefined;
+        throw error;
+    }
+}
+function nonnegativeInteger(value) {
+    return value !== undefined && /^\d+$/.test(value) ? Number(value) : undefined;
+}
+function readState(home, dependencies) {
+    const fields = readFields(loadGateStatePath(home), dependencies);
+    if (!fields)
+        return { skips: 0 };
+    const skips = nonnegativeInteger(fields.skips);
+    const firstDeferredAt = nonnegativeInteger(fields.firstDeferredAt);
+    const lastSuccessfulEmbedAt = nonnegativeInteger(fields.lastSuccessfulEmbedAt);
+    if (skips === undefined
+        || (fields.firstDeferredAt !== undefined && firstDeferredAt === undefined)
+        || (fields.lastSuccessfulEmbedAt !== undefined && lastSuccessfulEmbedAt === undefined)
+        || (skips > 0 && firstDeferredAt === undefined)
+        || (skips === 0 && firstDeferredAt !== undefined))
+        return { skips: 0 };
+    return {
+        skips,
+        ...(firstDeferredAt === undefined ? {} : { firstDeferredAt }),
+        ...(lastSuccessfulEmbedAt === undefined ? {} : { lastSuccessfulEmbedAt }),
+    };
+}
+function writeState(home, state, dependencies) {
+    dependencies.mkdir(lockRoot(home));
+    const statePath = loadGateStatePath(home);
+    const temporaryPath = `${statePath}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
+    dependencies.writeFile(temporaryPath, [
+        `skips=${state.skips}`,
+        ...(state.firstDeferredAt === undefined ? [] : [`firstDeferredAt=${state.firstDeferredAt}`]),
+        ...(state.lastSuccessfulEmbedAt === undefined ? [] : [`lastSuccessfulEmbedAt=${state.lastSuccessfulEmbedAt}`]),
+        '',
+    ].join('\n'));
+    dependencies.rename(temporaryPath, statePath);
+}
+function rounded(percent) {
+    return Math.round(percent);
+}
+function trippedSignal(cpuPercent, memoryPercent, limit) {
+    if (cpuPercent >= limit)
+        return { signal: 'cpu', percent: rounded(cpuPercent) };
+    if (memoryPercent >= limit)
+        return { signal: 'memory', percent: rounded(memoryPercent) };
+    return undefined;
+}
+/**
+ * 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 function checkEmbedLoad(home, dependencies) {
+    const limit = parseLoadThreshold(dependencies.env);
+    if (limit === undefined)
+        return { action: 'embed', forced: false };
+    const cpuPercent = measureCpuPercent(dependencies);
+    const memoryPercent = measureMemoryPercent(dependencies);
+    const tripped = trippedSignal(cpuPercent, memoryPercent, limit);
+    if (!tripped)
+        return { action: 'embed', forced: false };
+    const now = dependencies.now();
+    const state = readState(home, dependencies);
+    const skips = state.skips + 1;
+    const deferredSince = state.firstDeferredAt ?? now;
+    const exceededSkipBound = skips > MAX_CONSECUTIVE_DEFERRED_EMBEDS;
+    const exceededTimeBound = now - deferredSince >= MAX_EMBED_DEFERRAL_SECONDS;
+    if (exceededSkipBound || exceededTimeBound) {
+        return {
+            action: 'embed',
+            forced: true,
+            notice: `hq: proceeding with qmd embed despite ${tripped.signal} ${tripped.percent}% (limit ${limit}%) because embeddings have been deferred too long.\n`,
+        };
+    }
+    writeState(home, {
+        skips,
+        firstDeferredAt: state.firstDeferredAt ?? now,
+        ...(state.lastSuccessfulEmbedAt === undefined ? {} : { lastSuccessfulEmbedAt: state.lastSuccessfulEmbedAt }),
+    }, dependencies);
+    return {
+        action: 'skip',
+        signal: tripped.signal,
+        percent: tripped.percent,
+        limit,
+        notice: `hq: skipping qmd embed — ${tripped.signal} ${tripped.percent}% (limit ${limit}%).\n`,
+    };
+}
+/** Reset the starvation counter only after qmd embed has actually returned successfully. */
+export function recordSuccessfulEmbed(home, dependencies) {
+    writeState(home, { skips: 0, lastSuccessfulEmbedAt: dependencies.now() }, dependencies);
+}
+//# sourceMappingURL=load-gate.js.map