@indigoai-us/hq-cli 5.314.0 → 5.316.0

package/dist/lib/lanes/hooks-install.js

@@ -0,0 +1,555 @@
+/**
+ * Install and register the lane-resolving drain hook in a provider home.
+ *
+ * Copying the hook files into `<home>/hooks/` is only half of an install. Each
+ * provider discovers hooks differently, and a file the provider never reads
+ * registers nothing:
+ *
+ * - grok reads every `*.json` under `$GROK_HOME/hooks/`, so the registration
+ *   file in that directory is the registration.
+ * - claude reads `$CLAUDE_CONFIG_DIR/settings.json` and nothing under
+ *   `hooks/`. The registration is merged into the `hooks.PreToolUse` array of
+ *   that file.
+ * - codex reads `$CODEX_HOME/config.toml` (`[[hooks.PreToolUse]]`, gated by
+ *   `[features] hooks = true`). The registration is appended to that file.
+ *
+ * Every registration merge keeps what the operator already has and is a
+ * no-op when the entry is present, because this runs on every spawn.
+ * Never merges into hq-hq-bridge.json / hq-hq-bridge.sh.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { parse as parseToml, TomlError } from "smol-toml";
+import { LanesError } from "./errors.js";
+import { parseLaneProvider } from "./types.js";
+export const DRAIN_HOOK_BASENAME = "hq-lanes-drain";
+export const DRAIN_HOOK_TIMEOUT_SECONDS = 30;
+function shellQuote(value) {
+    return `'${value.replaceAll("'", "'\\''")}'`;
+}
+export function drainHookEntryPath() {
+    return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../../dist/lanes-drain-hook.js");
+}
+export function lanesHookAssetsDir() {
+    return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../../assets/lanes-hooks");
+}
+export const DRAIN_HOOK_REGISTRATION_KINDS = [
+    "hooks_dir",
+    "settings_json",
+    "config_toml",
+];
+export const PROVIDER_REGISTRATION_KIND = {
+    claude: "settings_json",
+    codex: "config_toml",
+    grok: "hooks_dir",
+};
+export function drainHookCommand(_shPath) {
+    return `${shellQuote(process.execPath)} ${shellQuote(drainHookEntryPath())}`;
+}
+function legacyDrainHookCommand(shPath) {
+    return `bash ${shPath}`;
+}
+export function drainHookShPath(providerHome) {
+    return path.join(providerHome, "hooks", `${DRAIN_HOOK_BASENAME}.sh`);
+}
+function writeIfChanged(dest, contents, mode) {
+    try {
+        const existing = fs.readFileSync(dest);
+        const next = Buffer.isBuffer(contents) ? contents : Buffer.from(contents);
+        if (existing.equals(next))
+            return false;
+    }
+    catch (err) {
+        const code = err.code;
+        if (code !== "ENOENT")
+            throw err;
+    }
+    const tmp = `${dest}.${process.pid}.${Date.now()}.tmp`;
+    fs.writeFileSync(tmp, contents);
+    if (mode !== undefined)
+        fs.chmodSync(tmp, mode);
+    fs.renameSync(tmp, dest);
+    return true;
+}
+function readTextIfExists(filePath) {
+    try {
+        return fs.readFileSync(filePath, "utf8");
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT")
+            return null;
+        throw err;
+    }
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** One `{ hooks: [{ type: "command", command }] }` group carries the drain command. */
+function groupsContainCommand(groups, command) {
+    if (!Array.isArray(groups))
+        return false;
+    return groups.some((group) => {
+        if (!isPlainObject(group) || !Array.isArray(group.hooks))
+            return false;
+        return group.hooks.some((hook) => isPlainObject(hook) && hook.type === "command" && hook.command === command);
+    });
+}
+/** Parse the single-quoted argv form emitted by shellQuote without invoking a shell. */
+function parseShellQuotedArguments(command) {
+    const args = [];
+    let index = 0;
+    while (index < command.length) {
+        while (/\s/.test(command[index] ?? ""))
+            index += 1;
+        if (index >= command.length)
+            break;
+        if (command[index] !== "'")
+            return null;
+        index += 1;
+        let value = "";
+        let closed = false;
+        while (index < command.length) {
+            if (command.startsWith("'\\''", index)) {
+                value += "'";
+                index += 4;
+            }
+            else if (command[index] === "'") {
+                index += 1;
+                closed = true;
+                break;
+            }
+            else {
+                value += command[index];
+                index += 1;
+            }
+        }
+        if (!closed)
+            return null;
+        args.push(value);
+        if (index < command.length && !/\s/.test(command[index]))
+            return null;
+    }
+    return args;
+}
+function isInstalledDrainEntry(entryPath) {
+    if (!path.isAbsolute(entryPath))
+        return false;
+    const segments = path.resolve(entryPath).split(path.sep);
+    return segments.slice(-5).join(path.sep) ===
+        ["node_modules", "@indigoai-us", "hq-cli", "dist", "lanes-drain-hook.js"].join(path.sep);
+}
+/**
+ * The provider settings can outlive a CLI worktree or global package update.
+ * Both paths target the same hq-cli drain entry, so recognize an installed
+ * package entry alongside the exact entry belonging to this CLI invocation.
+ */
+function drainCommandsMatch(candidate, expected) {
+    if (candidate === expected)
+        return true;
+    const argv = parseShellQuotedArguments(candidate);
+    if (argv === null || argv.length !== 2)
+        return false;
+    if (path.parse(argv[0]).name.toLowerCase() !== "node")
+        return false;
+    if (!isInstalledDrainEntry(argv[1]))
+        return false;
+    return fs.existsSync(argv[0]) && fs.existsSync(argv[1]);
+}
+function groupsContainDrainCommand(groups, expected) {
+    if (!Array.isArray(groups))
+        return false;
+    return groups.some((group) => {
+        if (!isPlainObject(group) || !Array.isArray(group.hooks))
+            return false;
+        return group.hooks.some((hook) => isPlainObject(hook) &&
+            hook.type === "command" &&
+            typeof hook.command === "string" &&
+            drainCommandsMatch(hook.command, expected));
+    });
+}
+function tomlHasDrainCommand(parsed, expected) {
+    return isPlainObject(parsed.hooks) && groupsContainDrainCommand(parsed.hooks.PreToolUse, expected);
+}
+function removeCommandFromGroups(groups, command) {
+    let changed = false;
+    const next = groups.flatMap((group) => {
+        if (!isPlainObject(group) || !Array.isArray(group.hooks))
+            return [group];
+        const hooks = group.hooks.filter((hook) => !(isPlainObject(hook) &&
+            hook.type === "command" &&
+            hook.command === command));
+        if (hooks.length === group.hooks.length)
+            return [group];
+        changed = true;
+        return hooks.length === 0 ? [] : [{ ...group, hooks }];
+    });
+    return { groups: next, changed };
+}
+export function renderDrainHookJson(shPath) {
+    return `${JSON.stringify({
+        hooks: {
+            PreToolUse: [
+                {
+                    hooks: [
+                        {
+                            type: "command",
+                            command: drainHookCommand(shPath),
+                            timeout: DRAIN_HOOK_TIMEOUT_SECONDS,
+                        },
+                    ],
+                },
+            ],
+        },
+    }, null, 2)}\n`;
+}
+/**
+ * Claude Code: `settings.json` is the one file it reads hooks from. Merge the
+ * drain into `hooks.PreToolUse`, keep every other key and every other hook,
+ * and do nothing when a command hook with this exact command string is
+ * already in the list. No `matcher` means every tool call.
+ */
+export function mergeClaudeSettingsHook(existingText, command, settingsPath, legacyCommand) {
+    let root = {};
+    if (existingText !== null && existingText.trim() !== "") {
+        try {
+            root = JSON.parse(existingText);
+        }
+        catch (err) {
+            throw new LanesError("settings_unparseable", `${settingsPath} is not valid JSON; refusing to rewrite it: ${err instanceof Error ? err.message : String(err)}`, { path: settingsPath });
+        }
+    }
+    if (!isPlainObject(root)) {
+        throw new LanesError("settings_unparseable", `${settingsPath} must hold a JSON object; refusing to rewrite it`, { path: settingsPath });
+    }
+    const hooks = root.hooks === undefined ? {} : root.hooks;
+    if (!isPlainObject(hooks)) {
+        throw new LanesError("settings_unparseable", `${settingsPath} has a non-object "hooks" key; refusing to rewrite it`, { path: settingsPath });
+    }
+    const pre = hooks.PreToolUse === undefined ? [] : hooks.PreToolUse;
+    if (!Array.isArray(pre)) {
+        throw new LanesError("settings_unparseable", `${settingsPath} has a non-array "hooks.PreToolUse"; refusing to rewrite it`, { path: settingsPath });
+    }
+    const migration = legacyCommand && legacyCommand !== command
+        ? removeCommandFromGroups(pre, legacyCommand)
+        : { groups: pre, changed: false };
+    if (groupsContainCommand(migration.groups, command) && !migration.changed) {
+        return { text: existingText ?? "", changed: false };
+    }
+    const nextPre = groupsContainCommand(migration.groups, command)
+        ? migration.groups
+        : [
+            ...migration.groups,
+            {
+                hooks: [
+                    { type: "command", command, timeout: DRAIN_HOOK_TIMEOUT_SECONDS },
+                ],
+            },
+        ];
+    const nextRoot = { ...root, hooks: { ...hooks, PreToolUse: nextPre } };
+    return { text: `${JSON.stringify(nextRoot, null, 2)}\n`, changed: true };
+}
+function tomlBasicString(value) {
+    // JSON string escapes are a subset of TOML basic-string escapes for the
+    // characters a filesystem path can contain.
+    return JSON.stringify(value);
+}
+function tomlHooksFeatureEnabled(parsed) {
+    return isPlainObject(parsed.features) && parsed.features.hooks === true;
+}
+function tomlHasCommand(parsed, command) {
+    return isPlainObject(parsed.hooks) && groupsContainCommand(parsed.hooks.PreToolUse, command);
+}
+function tomlHeader(line) {
+    const match = /^\s*(\[\[|\[)([^\]]+)(\]\]|\])\s*(?:#.*)?$/.exec(line);
+    if (!match) {
+        const trimmed = line.trimStart();
+        return trimmed.startsWith("[")
+            ? { path: "", array: trimmed.startsWith("[[") }
+            : undefined;
+    }
+    const array = match[1] === "[[";
+    if ((array && match[3] !== "]]") ||
+        (!array && match[3] !== "]")) {
+        return { path: "", array };
+    }
+    return { path: match[2].trim(), array };
+}
+function tomlCommandValue(line) {
+    const match = /^\s*command\s*=\s*(.+)$/.exec(line);
+    if (!match)
+        return undefined;
+    try {
+        const parsed = parseToml(`command = ${match[1]}\n`);
+        return isPlainObject(parsed) && typeof parsed.command === "string"
+            ? parsed.command
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Remove old installer-created Codex command tables while retaining TOML text and operator hooks. */
+function removeLegacyCodexHook(text, parsed, legacyCommand, configPath) {
+    if (!legacyCommand || legacyCommand === "")
+        return { text, changed: false };
+    const hooks = isPlainObject(parsed.hooks) ? parsed.hooks.PreToolUse : undefined;
+    const groups = Array.isArray(hooks) ? hooks : [];
+    const expectedCount = groups.reduce((total, group) => {
+        if (!isPlainObject(group) || !Array.isArray(group.hooks))
+            return total;
+        return total + group.hooks.filter((hook) => isPlainObject(hook) &&
+            hook.type === "command" &&
+            hook.command === legacyCommand).length;
+    }, 0);
+    if (expectedCount === 0)
+        return { text, changed: false };
+    const lines = text.split("\n");
+    const parentHeaders = lines.flatMap((line, index) => {
+        const header = tomlHeader(line);
+        return header?.array && header.path === "hooks.PreToolUse" ? [index] : [];
+    });
+    const wholeGroupIndexes = new Set();
+    if (parentHeaders.length === groups.length) {
+        groups.forEach((group, index) => {
+            if (isPlainObject(group) &&
+                Array.isArray(group.hooks) &&
+                group.hooks.length === 1 &&
+                isPlainObject(group.hooks[0]) &&
+                group.hooks[0].type === "command" &&
+                group.hooks[0].command === legacyCommand) {
+                wholeGroupIndexes.add(index);
+            }
+        });
+    }
+    const spans = [];
+    let parentGroupIndex = -1;
+    for (let index = 0; index < lines.length; index += 1) {
+        const header = tomlHeader(lines[index]);
+        if (header?.array && header.path === "hooks.PreToolUse") {
+            parentGroupIndex += 1;
+            if (!wholeGroupIndexes.has(parentGroupIndex))
+                continue;
+            let end = index + 1;
+            for (; end < lines.length; end += 1) {
+                const nextHeader = tomlHeader(lines[end]);
+                if (!nextHeader)
+                    continue;
+                if (nextHeader.array && nextHeader.path === "hooks.PreToolUse")
+                    break;
+                if (nextHeader.path.startsWith("hooks.PreToolUse."))
+                    continue;
+                break;
+            }
+            spans.push({ start: index, end });
+            index = end - 1;
+            continue;
+        }
+        if (!header?.array || header.path !== "hooks.PreToolUse.hooks")
+            continue;
+        let end = index + 1;
+        let foundLegacyCommand = false;
+        for (; end < lines.length; end += 1) {
+            const nextHeader = tomlHeader(lines[end]);
+            if (!nextHeader) {
+                if (tomlCommandValue(lines[end]) === legacyCommand) {
+                    foundLegacyCommand = true;
+                }
+                continue;
+            }
+            if (nextHeader.array &&
+                nextHeader.path === "hooks.PreToolUse.hooks") {
+                break;
+            }
+            if (nextHeader.path.startsWith("hooks.PreToolUse.hooks."))
+                continue;
+            break;
+        }
+        if (foundLegacyCommand)
+            spans.push({ start: index, end });
+        index = end - 1;
+    }
+    if (spans.length !== expectedCount) {
+        throw new LanesError("config_toml_migration_failed", `Could not safely remove all legacy lane drain hooks from ${configPath}; refusing to add a second drain`, { path: configPath, expected: expectedCount, found: spans.length });
+    }
+    for (const span of spans.reverse())
+        lines.splice(span.start, span.end - span.start);
+    const migrated = lines.join("\n");
+    const migratedConfig = parseTomlOrThrow(migrated, configPath, "after legacy hook removal");
+    if (tomlHasCommand(migratedConfig, legacyCommand)) {
+        throw new LanesError("config_toml_migration_failed", `Legacy lane drain hook remains in ${configPath}; refusing to add a second drain`, { path: configPath });
+    }
+    return { text: migrated, changed: true };
+}
+function parseTomlOrThrow(text, configPath, stage) {
+    let parsed;
+    try {
+        parsed = parseToml(text);
+    }
+    catch (err) {
+        const detail = err instanceof TomlError || err instanceof Error ? err.message : String(err);
+        throw new LanesError("config_toml_unparseable", `${configPath} is not valid TOML (${stage}); refusing to rewrite it: ${detail}`, { path: configPath, stage });
+    }
+    if (!isPlainObject(parsed)) {
+        throw new LanesError("config_toml_unparseable", `${configPath} did not parse to a table (${stage}); refusing to rewrite it`, { path: configPath, stage });
+    }
+    return parsed;
+}
+/**
+ * Set `hooks = true` inside `[features]` by editing lines, so the operator's
+ * comments and layout survive. A `[features]` header that exists gets the
+ * key inserted (or an existing `hooks =` line replaced); a missing header is
+ * appended. An inline `features = { ... }` table cannot be edited this way;
+ * the re-parse post-condition in the caller reports that case.
+ */
+function enableTomlHooksFeature(text) {
+    const lines = text.split("\n");
+    const header = lines.findIndex((line) => /^\s*\[features\]\s*(#.*)?$/.test(line));
+    if (header === -1) {
+        const sep = text === "" || text.endsWith("\n") ? "" : "\n";
+        return `${text}${sep}\n[features]\nhooks = true\n`;
+    }
+    for (let i = header + 1; i < lines.length; i += 1) {
+        const line = lines[i];
+        if (/^\s*\[/.test(line))
+            break;
+        if (/^\s*hooks\s*=/.test(line)) {
+            lines[i] = "hooks = true";
+            return lines.join("\n");
+        }
+    }
+    lines.splice(header + 1, 0, "hooks = true");
+    return lines.join("\n");
+}
+/**
+ * Codex: hooks come from `config.toml` in the codex home. The drain is
+ * appended as one `[[hooks.PreToolUse]]` table and `[features] hooks = true`
+ * is ensured. Edits are textual so comments and unrelated tables are kept
+ * byte for byte; the result is re-parsed and must contain the registration,
+ * otherwise nothing is written.
+ */
+export function mergeCodexConfigHook(existingText, command, configPath, legacyCommand) {
+    const original = existingText ?? "";
+    const parsed = parseTomlOrThrow(original, configPath, "before merge");
+    const migration = removeLegacyCodexHook(original, parsed, legacyCommand, configPath);
+    const textAfterMigration = migration.text;
+    const current = parseTomlOrThrow(textAfterMigration, configPath, "after legacy hook removal");
+    const hasCommand = tomlHasCommand(current, command);
+    const featureOn = tomlHooksFeatureEnabled(current);
+    if (hasCommand && featureOn && !migration.changed) {
+        return { text: original, changed: false };
+    }
+    let text = textAfterMigration;
+    if (!featureOn)
+        text = enableTomlHooksFeature(text);
+    if (!hasCommand) {
+        const sep = text === "" || text.endsWith("\n") ? "" : "\n";
+        text =
+            `${text}${sep}\n` +
+                `# hq lanes: drop-box drain for lane workers (no-op unless HQ_LANE_ID is set)\n` +
+                `[[hooks.PreToolUse]]\n` +
+                `matcher = ".*"\n\n` +
+                `[[hooks.PreToolUse.hooks]]\n` +
+                `type = "command"\n` +
+                `command = ${tomlBasicString(command)}\n` +
+                `timeout = ${DRAIN_HOOK_TIMEOUT_SECONDS}\n`;
+    }
+    const check = parseTomlOrThrow(text, configPath, "after merge");
+    if (!tomlHasCommand(check, command) || !tomlHooksFeatureEnabled(check)) {
+        throw new LanesError("config_toml_merge_failed", `Merged ${configPath} does not carry the drain registration; refusing to write it`, { path: configPath, command });
+    }
+    return { text, changed: true };
+}
+export function drainHookRegistrationPath(provider, providerHome) {
+    switch (PROVIDER_REGISTRATION_KIND[provider]) {
+        case "hooks_dir":
+            return path.join(providerHome, "hooks", `${DRAIN_HOOK_BASENAME}.json`);
+        case "settings_json":
+            return path.join(providerHome, "settings.json");
+        case "config_toml":
+            return path.join(providerHome, "config.toml");
+    }
+}
+/**
+ * Read the registration back the way the provider CLI would find it. Reports
+ * the state of the file only; it does not prove the provider honours it.
+ */
+export function probeDrainHookRegistration(provider, providerHome) {
+    const parsed = parseLaneProvider(provider);
+    const kind = PROVIDER_REGISTRATION_KIND[parsed];
+    const regPath = drainHookRegistrationPath(parsed, providerHome);
+    const command = drainHookCommand(drainHookShPath(providerHome));
+    const text = readTextIfExists(regPath);
+    const base = { kind, path: regPath, command, file_present: text !== null };
+    if (text === null)
+        return { ...base, registered: false };
+    try {
+        if (kind === "config_toml") {
+            const toml = parseToml(text);
+            return {
+                ...base,
+                registered: isPlainObject(toml) && tomlHasDrainCommand(toml, command) && tomlHooksFeatureEnabled(toml),
+            };
+        }
+        const json = JSON.parse(text);
+        return {
+            ...base,
+            registered: isPlainObject(json) &&
+                isPlainObject(json.hooks) &&
+                groupsContainDrainCommand(json.hooks.PreToolUse, command),
+        };
+    }
+    catch (err) {
+        process.stderr.write(`hq lanes: registration file ${regPath} is unreadable as ${kind}: ${err instanceof Error ? err.message : String(err)}\n`);
+        return { ...base, registered: false };
+    }
+}
+function registerDrainHook(provider, providerHome, shPath) {
+    const kind = PROVIDER_REGISTRATION_KIND[provider];
+    const regPath = drainHookRegistrationPath(provider, providerHome);
+    const command = drainHookCommand(shPath);
+    if (kind === "hooks_dir") {
+        const changed = writeIfChanged(regPath, renderDrainHookJson(shPath), 0o644);
+        return { kind, path: regPath, command, changed };
+    }
+    const existing = readTextIfExists(regPath);
+    const merged = kind === "settings_json"
+        ? mergeClaudeSettingsHook(existing, command, regPath, legacyDrainHookCommand(shPath))
+        : mergeCodexConfigHook(existing, command, regPath, legacyDrainHookCommand(shPath));
+    if (!merged.changed) {
+        return { kind, path: regPath, command, changed: false };
+    }
+    const tmp = `${regPath}.${process.pid}.${Date.now()}.tmp`;
+    fs.writeFileSync(tmp, merged.text, { mode: 0o600 });
+    try {
+        if (existing !== null)
+            fs.chmodSync(tmp, fs.statSync(regPath).mode & 0o777);
+        fs.renameSync(tmp, regPath);
+    }
+    catch (err) {
+        fs.rmSync(tmp, { force: true });
+        throw err;
+    }
+    return { kind, path: regPath, command, changed: true };
+}
+export function installDrainHook(provider, providerHome, assetsDir = lanesHookAssetsDir()) {
+    const parsed = parseLaneProvider(provider);
+    const hooksDir = path.join(providerHome, "hooks");
+    fs.mkdirSync(hooksDir, { recursive: true });
+    const shDest = drainHookShPath(providerHome);
+    const mjsDest = path.join(hooksDir, `${DRAIN_HOOK_BASENAME}.mjs`);
+    writeIfChanged(shDest, fs.readFileSync(path.join(assetsDir, `${DRAIN_HOOK_BASENAME}.sh`)), 0o755);
+    writeIfChanged(mjsDest, fs.readFileSync(path.join(assetsDir, `${DRAIN_HOOK_BASENAME}.mjs`)), 0o755);
+    const registration = registerDrainHook(parsed, providerHome, shDest);
+    const files = [shDest, mjsDest];
+    if (registration.kind === "hooks_dir") {
+        files.push(registration.path);
+    }
+    else {
+        // A registration-shaped file the provider never reads is how this bug hid.
+        fs.rmSync(path.join(hooksDir, `${DRAIN_HOOK_BASENAME}.json`), { force: true });
+    }
+    return { provider: parsed, home: providerHome, hooksDir, files, registration };
+}
+//# sourceMappingURL=hooks-install.js.map

package/dist/lib/lanes/host-capacity.d.ts

@@ -0,0 +1,69 @@
+import { type AuthState } from "./accounts.js";
+import type { LaneHost, LaneProvider, LaneRecord, LanesConfig } from "./types.js";
+export interface HostCapacityAccount {
+    enabled: boolean;
+    logged_in: boolean | null;
+    /** Absent on snapshots from older CLIs. */
+    auth_state?: AuthState;
+    max_running: number;
+    running: number;
+    queued: number;
+    /** Exact lane states used for Claude account balancing; absent on older Outposts. */
+    lane_counts?: {
+        running: number;
+        queued: number;
+        awaiting_input: number;
+        live: number;
+    };
+    /** Provider-reported usage, when a host can read a recent sample. */
+    usage?: {
+        five_hour_percent?: number;
+        weekly_percent?: number;
+        sampled_at?: string;
+    };
+}
+export interface HostCapacityProvider {
+    max_running: number;
+    max_queued: number;
+    running: number;
+    queued: number;
+    accounts: Record<string, HostCapacityAccount>;
+}
+export interface HostCapacitySnapshot {
+    schema_version: "hq-lanes-host-capacity.v1";
+    host: LaneHost;
+    sampled_at: string;
+    providers: Record<LaneProvider, HostCapacityProvider>;
+}
+export interface HostPlacementChoice {
+    host: LaneHost;
+    account: string;
+    queued: boolean;
+}
+/** Snapshot the same per-host running-slot predicate used by lane admission. */
+export declare function buildHostCapacitySnapshot(input: {
+    host: LaneHost;
+    lanes: readonly LaneRecord[];
+    config: LanesConfig;
+    existsSync: (path: string) => boolean;
+    probe?: (command: string, args: string[], env: NodeJS.ProcessEnv) => {
+        status: number | null;
+        stdout: string;
+        stderr: string;
+    };
+    env?: NodeJS.ProcessEnv;
+    hostname?: string;
+    now: Date;
+}): HostCapacitySnapshot;
+/** Reject malformed remote snapshots before they can influence host selection. */
+export declare function parseHostCapacitySnapshot(raw: unknown): HostCapacitySnapshot;
+/**
+ * Choose the least-loaded eligible host/account from advisory snapshots. The
+ * selected host still runs the shared admission check under its own lock.
+ */
+export declare function chooseHostForLane(snapshots: readonly HostCapacitySnapshot[], request: {
+    provider: LaneProvider;
+    account?: string;
+    allowedAccounts?: readonly string[];
+}): HostPlacementChoice;
+//# sourceMappingURL=host-capacity.d.ts.map