@indigoai-us/hq-cli 5.345.104 → 5.345.106

package/dist/lib/bot/runtime/claude.js

@@ -19,6 +19,7 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { messagesStreamEvents, messagesStreamFailure, messagesStreamResult } from "./messages-stream.js";
+import { hqAppToolchainBin } from "../toolchain.js";
 import { resolveRuntimeBinary } from "./windows.js";
 export const CLAUDE_PERMISSION_MODE_ENV = "HQ_BOT_CLAUDE_PERMISSION_MODE";
 export const DEFAULT_CLAUDE_PERMISSION_MODE = "bypassPermissions";
@@ -104,18 +105,59 @@ export function bundledClaudeBin(homeDir = os.homedir()) {
     });
     return candidates.at(-1)?.bin ?? null;
 }
-export function resolveClaudeBinary(env, homeDir, platform = process.platform, cwd = process.cwd()) {
+/**
+ * Where a bot looks for `claude`, in order, outside the PATH walk. The HQ
+ * desktop app's toolchain comes first: on a clean Mac it is the only copy, and
+ * it is the one the app keeps updated. Then the usual install prefixes, so a
+ * bot under launchd (no shell profile) still finds a Homebrew or npm global
+ * install even when its PATH is thin.
+ */
+export const CLAUDE_SYSTEM_BIN_DIRS = ["/usr/local/bin", "/opt/homebrew/bin", "/usr/bin"];
+function executableAt(file) {
+    try {
+        fs.accessSync(file, fs.constants.X_OK);
+        return fs.statSync(file).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The `claude` a bot spawns. Order (contract "Claude resolution for bots"):
+ *
+ *   1. `~/Library/Application Support/Indigo HQ/toolchain/npm-global/bin/claude`
+ *      (the HQ app's own install; macOS only)
+ *   2. /usr/local/bin, /opt/homebrew/bin, /usr/bin
+ *   3. PATH (returned as the bare name, so the spawn uses the same lookup)
+ *   4. the Claude desktop app's bundled Claude Code
+ *   5. the bare name, so the failure reads "claude is not installed".
+ *
+ * Absolute paths come back for 1, 2 and 4 so the bot log can say which one
+ * ran.
+ */
+export function resolveClaudeBinary(env, homeDir, platform = process.platform, cwd = process.cwd(), systemBinDirs = CLAUDE_SYSTEM_BIN_DIRS) {
     if (platform === "win32")
         return resolveRuntimeBinary("claude", env, platform, fs.existsSync, cwd);
+    const home = homeDir ?? env.HOME ?? os.homedir();
+    if (platform === "darwin") {
+        const toolchain = hqAppToolchainBin("claude", home);
+        if (executableAt(toolchain))
+            return toolchain;
+    }
+    for (const dir of systemBinDirs) {
+        const candidate = path.join(dir, "claude");
+        if (executableAt(candidate))
+            return candidate;
+    }
     if (onPath("claude", env))
         return "claude";
-    return bundledClaudeBin(homeDir ?? env.HOME ?? os.homedir()) ?? "claude";
+    return bundledClaudeBin(home) ?? "claude";
 }
-export function createClaudeRuntime(env = process.env) {
+export function createClaudeRuntime(env = process.env, opts = {}) {
     return {
         id: "claude",
         binary: "claude",
-        resolveBinary: (turnEnv, cwd, platform) => resolveClaudeBinary(turnEnv, undefined, platform ?? process.platform, cwd),
+        resolveBinary: (turnEnv, cwd, platform) => resolveClaudeBinary(turnEnv, undefined, platform ?? process.platform, cwd, opts.systemBinDirs ?? CLAUDE_SYSTEM_BIN_DIRS),
         buildArgs(input, scratch) {
             const usesWindowsStdin = input.platform === "win32";
             const args = [
@@ -142,6 +184,9 @@ export function createClaudeRuntime(env = process.env) {
             }
             if (input.model)
                 args.push("--model", input.model);
+            if (input.leanSettingsFile) {
+                args.push("--strict-mcp-config", "--setting-sources", "", "--settings", input.leanSettingsFile);
+            }
             if (input.sessionId)
                 args.push("--resume", input.sessionId);
             else

package/dist/lib/bot/runtime/types.d.ts

@@ -33,6 +33,11 @@ export interface RuntimeTurnInput {
     sessionId?: string;
     /** Optional model override. */
     model?: string;
+    /**
+     * Claude only: a lean turn. The settings file holds HQ's tool hooks; the turn
+     * loads no other settings, plugins or MCP servers (BotConfig.lean).
+     */
+    leanSettingsFile?: string;
     /** Thinking level for the CLI (runtimes fall back to medium). */
     effort?: string;
     /**

package/dist/lib/bot/runtime-failure.d.ts

@@ -89,7 +89,7 @@ export interface RuntimeRepairNotice {
     cls: RuntimeFailureClass;
     /** The plain DM body. */
     text: string;
-    /** Absent for `not-installed` and `unknown`: those get the plain text only. */
+    /** Absent for `not-installed` and `unknown`: those get the plain text (plus a Retry suggestion in a DM). */
     richContent?: RuntimeRichContent;
 }
 export declare function runtimeRepairBlock(args: {
@@ -99,7 +99,23 @@ export declare function runtimeRepairBlock(args: {
     retryOf?: string;
     suggestedModel?: string;
 }): RuntimeRepairBlock;
-/** The plain body plus, for a repairable class, the repair block. */
+/** The tap-to-answer button under a failure that carries no repair card. */
+export declare const RETRY_SUGGESTION = "Retry";
+/**
+ * The `hq-block` suggestions envelope the desktop draws as buttons (the same
+ * one the setup bot uses for its questions). Tapping sends the text back as
+ * the person's next message, so a failed turn is never a dead end.
+ */
+export declare function suggestionsBlock(items: string[]): string;
+/** `text` followed by a one-button Retry envelope. */
+export declare function withRetrySuggestion(text: string): string;
+/**
+ * The plain body plus, for a repairable class, the repair block. Classes
+ * without a card (`not-installed`, `unknown`) get the plain text; the DM post
+ * path adds a Retry suggestion under it (see run.ts postRepair): on 2026-10-11
+ * a fresh bot whose Claude Code was missing left the person with nothing to
+ * press.
+ */
 export declare function runtimeRepairNotice(args: {
     cls: RuntimeFailureClass;
     runtime: BotRuntimeId | string;

package/dist/lib/bot/runtime-failure.js

@@ -155,7 +155,27 @@ export function runtimeRepairBlock(args) {
         ...(args.suggestedModel ? { suggestedModel: args.suggestedModel.slice(0, 128) } : {}),
     };
 }
-/** The plain body plus, for a repairable class, the repair block. */
+/** The tap-to-answer button under a failure that carries no repair card. */
+export const RETRY_SUGGESTION = "Retry";
+/**
+ * The `hq-block` suggestions envelope the desktop draws as buttons (the same
+ * one the setup bot uses for its questions). Tapping sends the text back as
+ * the person's next message, so a failed turn is never a dead end.
+ */
+export function suggestionsBlock(items) {
+    return "```hq-block\n" + JSON.stringify({ v: 1, blocks: [{ kind: "suggestions", items }] }) + "\n```";
+}
+/** `text` followed by a one-button Retry envelope. */
+export function withRetrySuggestion(text) {
+    return `${text}\n\n${suggestionsBlock([RETRY_SUGGESTION])}`;
+}
+/**
+ * The plain body plus, for a repairable class, the repair block. Classes
+ * without a card (`not-installed`, `unknown`) get the plain text; the DM post
+ * path adds a Retry suggestion under it (see run.ts postRepair): on 2026-10-11
+ * a fresh bot whose Claude Code was missing left the person with nothing to
+ * press.
+ */
 export function runtimeRepairNotice(args) {
     const text = args.text ?? runtimeFailureText(args.cls, args.runtime, args.context);
     if (!isRuntimeRepairClass(args.cls))

package/dist/lib/bot/toolchain.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The HQ desktop app's managed toolchain.
+ *
+ * The app installs node, hq-cli and @anthropic-ai/claude-code under one
+ * prefix so a clean Mac can run bots without the person installing anything:
+ *
+ *   ~/Library/Application Support/Indigo HQ/toolchain/
+ *     node/bin/node
+ *     npm-global/bin/hq
+ *     npm-global/bin/claude
+ *
+ * The bot daemon's PATH, the hq-cli update watcher and the Claude Code
+ * resolver all key on the same root, so it lives here once.
+ */
+/** Path segments under the home directory. macOS only; other platforms have no app toolchain. */
+export declare const HQ_APP_TOOLCHAIN_SEGMENTS: readonly ["Library", "Application Support", "Indigo HQ", "toolchain"];
+/** The npm prefix the app installs CLIs into, relative to the toolchain root. */
+export declare const HQ_APP_TOOLCHAIN_NPM_GLOBAL_BIN: string;
+/** `~/Library/Application Support/Indigo HQ/toolchain`. */
+export declare function hqAppToolchainRoot(homeDir?: string): string;
+/** `<toolchain>/npm-global/bin`, where `hq` and `claude` live. */
+export declare function hqAppToolchainBinDir(homeDir?: string): string;
+/** `<toolchain>/npm-global/bin/<name>`: where the app puts a CLI it manages. */
+export declare function hqAppToolchainBin(name: string, homeDir?: string): string;
+//# sourceMappingURL=toolchain.d.ts.map

package/dist/lib/bot/toolchain.js

@@ -0,0 +1,33 @@
+/**
+ * The HQ desktop app's managed toolchain.
+ *
+ * The app installs node, hq-cli and @anthropic-ai/claude-code under one
+ * prefix so a clean Mac can run bots without the person installing anything:
+ *
+ *   ~/Library/Application Support/Indigo HQ/toolchain/
+ *     node/bin/node
+ *     npm-global/bin/hq
+ *     npm-global/bin/claude
+ *
+ * The bot daemon's PATH, the hq-cli update watcher and the Claude Code
+ * resolver all key on the same root, so it lives here once.
+ */
+import * as os from "node:os";
+import * as path from "node:path";
+/** Path segments under the home directory. macOS only; other platforms have no app toolchain. */
+export const HQ_APP_TOOLCHAIN_SEGMENTS = ["Library", "Application Support", "Indigo HQ", "toolchain"];
+/** The npm prefix the app installs CLIs into, relative to the toolchain root. */
+export const HQ_APP_TOOLCHAIN_NPM_GLOBAL_BIN = path.join("npm-global", "bin");
+/** `~/Library/Application Support/Indigo HQ/toolchain`. */
+export function hqAppToolchainRoot(homeDir = os.homedir()) {
+    return path.join(homeDir, ...HQ_APP_TOOLCHAIN_SEGMENTS);
+}
+/** `<toolchain>/npm-global/bin`, where `hq` and `claude` live. */
+export function hqAppToolchainBinDir(homeDir = os.homedir()) {
+    return path.join(hqAppToolchainRoot(homeDir), HQ_APP_TOOLCHAIN_NPM_GLOBAL_BIN);
+}
+/** `<toolchain>/npm-global/bin/<name>`: where the app puts a CLI it manages. */
+export function hqAppToolchainBin(name, homeDir = os.homedir()) {
+    return path.join(hqAppToolchainBinDir(homeDir), name);
+}
+//# sourceMappingURL=toolchain.js.map

package/dist/lib/bot/worker-source.d.ts

@@ -48,6 +48,7 @@ export interface WorkerSourceFs {
     }) => Array<{
         name: string;
         isDirectory: () => boolean;
+        isSymbolicLink?: () => boolean;
     }>;
 }
 /** Collapse whitespace and take the first sentence, capped at `max` chars. */

package/dist/lib/bot/worker-source.js

@@ -111,7 +111,13 @@ function scanCoreWorkerDirs(hqRoot, io) {
             return;
         }
         for (const e of entries) {
-            if (!e.isDirectory() || e.name.startsWith(".") || SKIP_DIRS.has(e.name))
+            if (e.name.startsWith(".") || SKIP_DIRS.has(e.name))
+                continue;
+            // A pack worker is a symlink (core/workers/public/<id> ->
+            // core/packages/<pack>/workers/<id>); a Dirent reports it as a link, not a
+            // directory, so follow it when it holds a worker.yaml.
+            const linkedWorker = !e.isDirectory() && e.isSymbolicLink?.() === true && io.existsSync(path.join(hqRoot, rel, e.name, "worker.yaml"));
+            if (!e.isDirectory() && !linkedWorker)
                 continue;
             walk(path.join(rel, e.name), depth + 1);
         }

package/dist/lib/daemon/catalog.d.ts

@@ -11,6 +11,7 @@
  */
 import type { MachineType } from "./machine-type.js";
 import type { SyncOwner } from "./config.js";
+import type { RemoteControlPoolsConfig } from "./remote-control-pools.js";
 import { type SyncRunnerProcess } from "./sync-runner.js";
 export declare const SERVICE_NAMES: readonly ["sync", "mesh", "heartbeat", "inbox", "bots", "remote-control", "codex-remote-control", "session-host", "lanes-reconcile", "search-index", "jobs-reconcile", "updater", "housekeeping"];
 export type ServiceName = (typeof SERVICE_NAMES)[number];
@@ -125,6 +126,20 @@ export interface PlanContext {
     tmuxPath: string | null;
     /** Short host name, used to name this machine's remote-control session. */
     hostName: string;
+    /** Main A Claude config dir shared by the pool's control plane. */
+    claudeConfigDir?: string;
+    /** Optional host-local RC pool desired state; absent/empty keeps legacy behavior. */
+    remoteControlPools?: RemoteControlPoolsConfig;
+    /** Invalid host-local desired state remains visible instead of disappearing. */
+    remoteControlPoolsError?: string;
+    /** Secret names whose presence was verified through HQ Secrets. */
+    availablePoolSecrets?: ReadonlySet<string>;
+    /** Secret names whose presence check failed for a reason other than absence. */
+    unverifiablePoolSecrets?: ReadonlySet<string>;
+    /** Pool accounts whose configured personal service-session capability is invalid or missing. */
+    invalidPoolServiceSessions?: ReadonlySet<string>;
+    availablePoolFrontends?: ReadonlySet<string>;
+    unverifiablePoolFrontends?: ReadonlySet<string>;
     /** The session name the box's own runner used (`--name` in its script), kept when the daemon takes over. */
     remoteControlName: string | null;
     /** Absolute path of the login user's codex binary, or null. */

package/dist/lib/daemon/catalog.js

@@ -364,6 +364,55 @@ export function planUnits(services, ctx) {
             units.push(unit);
         }
     }
+    // Pool units are desired-state instances rather than service-name toggles.
+    // This leaves the existing A unit and no-pools plan byte-for-byte unchanged.
+    for (const pool of ctx.remoteControlPools?.pools ?? []) {
+        units.push(base("remote-control", {
+            id: `remote-control-pool-forwarder:${pool.accountId}`,
+            description: `keeps the account ${pool.accountId} inference forwarder on 127.0.0.1:${pool.forwarderPort}`,
+            command: { type: "hq", args: ["daemon", "service", "remote-control-pool-forwarder-host", "--account-id", pool.accountId] },
+            env: { ...(ctx.hqRoot ? { HQ_ROOT: ctx.hqRoot } : {}), HQ_POOL_CONFIG: JSON.stringify([pool, ctx.remoteControlPools?.frontendCaPath, ctx.remoteControlPools?.serviceSessionId]) },
+            keepAcrossCliUpdates: true,
+            blocked: firstBlock([
+                [ctx.platform !== "linux", "Remote Control account pools require Linux mount namespaces"],
+                [!ctx.hqRoot, NO_HQ_ROOT],
+                [ctx.invalidPoolServiceSessions?.has(pool.accountId) === true, "configured serviceSessionId must reference an existing personal-only scope capability"],
+                [ctx.unverifiablePoolSecrets?.has(pool.secretName) === true, "could not verify the configured HQ Secret"],
+                [ctx.availablePoolSecrets?.has(pool.secretName) !== true, "the configured HQ Secret is missing"],
+            ]),
+        }));
+        const unit = base("remote-control", {
+            id: `remote-control-pool:${pool.accountId}`,
+            description: `keeps Claude remote control running for account ${pool.accountId}`,
+            command: { type: "hq", args: ["daemon", "service", "remote-control-pool", "--account-id", pool.accountId] },
+            env: {
+                ...(ctx.hqRoot ? { HQ_ROOT: ctx.hqRoot } : {}),
+                ...(ctx.claudeConfigDir ? { CLAUDE_CONFIG_DIR: ctx.claudeConfigDir } : {}),
+                HQ_POOL_CONFIG: JSON.stringify([pool, ctx.remoteControlPools?.frontendCaPath, ctx.remoteControlPools?.serviceSessionId]),
+            },
+            keepAcrossCliUpdates: true,
+            blocked: firstBlock([
+                [ctx.platform !== "linux", "Remote Control account pools require Linux mount namespaces"],
+                [!ctx.claudePath, "the claude CLI is not installed"],
+                [!ctx.tmuxPath, "tmux is not installed (remote control runs Claude inside tmux)"],
+                [!ctx.hqRoot, NO_HQ_ROOT],
+                [ctx.invalidPoolServiceSessions?.has(pool.accountId) === true, "configured serviceSessionId must reference an existing personal-only scope capability"],
+                [ctx.unverifiablePoolSecrets?.has(pool.secretName) === true, "could not verify the configured HQ Secret"],
+                [ctx.availablePoolSecrets?.has(pool.secretName) !== true, "the configured HQ Secret is missing"],
+                [ctx.unverifiablePoolFrontends?.has(pool.accountId) === true, "could not verify the configured nginx frontend"],
+                [ctx.availablePoolFrontends?.has(pool.accountId) !== true, "the configured nginx frontend is not responding on HTTPS port 443"],
+            ]),
+        });
+        units.push(unit);
+    }
+    if (ctx.remoteControlPoolsError) {
+        units.push(base("remote-control", {
+            id: "remote-control-pools:config",
+            description: "validates Claude Remote Control account pool desired state",
+            command: null,
+            blocked: { state: "unavailable", reason: `invalid remote-control pool config: ${ctx.remoteControlPoolsError}` },
+        }));
+    }
     return units;
 }
 //# sourceMappingURL=catalog.js.map

package/dist/lib/daemon/paths.d.ts

@@ -6,6 +6,7 @@
 export interface DaemonPaths {
     root: string;
     configPath: string;
+    remoteControlPoolsPath: string;
     statePath: string;
     lockPath: string;
     logsDir: string;

package/dist/lib/daemon/paths.js

@@ -12,6 +12,7 @@ export function daemonPaths(home = os.homedir(), env = process.env) {
     return {
         root,
         configPath: path.join(root, "config.json"),
+        remoteControlPoolsPath: path.join(root, "remote-control-pools.json"),
         statePath: path.join(root, "state.json"),
         lockPath: path.join(root, "daemon.pid"),
         logsDir,

package/dist/lib/daemon/remote-control-forwarder.d.ts

@@ -0,0 +1,14 @@
+/** A narrow, loopback-only Anthropic inference proxy for one RC account pool. */
+import * as https from "node:https";
+import { type IncomingMessage, type Server } from "node:http";
+export declare const POOL_UPSTREAM_TIMEOUT_MS = 600000;
+export declare const POOL_UPSTREAM_CONNECT_TIMEOUT_MS = 30000;
+export declare function inferenceForwardHeaders(incoming: IncomingMessage["headers"], secret: string): Record<string, string | string[]>;
+export declare function poolInferencePathAllowed(method: string | undefined, requestUrl: string | undefined): boolean;
+export declare function createInferenceForwarder(options: {
+    port: number;
+    secret: () => string | undefined;
+    upstream?: typeof https.request;
+    upstreamTimeoutMs?: number;
+}): Server;
+//# sourceMappingURL=remote-control-forwarder.d.ts.map

package/dist/lib/daemon/remote-control-forwarder.js

@@ -0,0 +1,104 @@
+/** A narrow, loopback-only Anthropic inference proxy for one RC account pool. */
+import * as https from "node:https";
+import * as dns from "node:dns";
+import { createServer } from "node:http";
+const STRIPPED_HEADERS = new Set([
+    "authorization", "x-api-key", "proxy-authorization", "proxy-authenticate", "proxy-connection", "host", "content-length",
+    "connection", "keep-alive", "te", "trailer", "transfer-encoding", "upgrade",
+]);
+export const POOL_UPSTREAM_TIMEOUT_MS = 600_000;
+export const POOL_UPSTREAM_CONNECT_TIMEOUT_MS = 30_000;
+export function inferenceForwardHeaders(incoming, secret) {
+    if (!secret)
+        throw new Error("the configured HQ Secret is empty");
+    const headers = {};
+    const hopByHop = new Set(STRIPPED_HEADERS);
+    const connection = incoming.connection;
+    for (const value of Array.isArray(connection) ? connection : connection ? [connection] : []) {
+        for (const name of value.split(","))
+            if (name.trim())
+                hopByHop.add(name.trim().toLowerCase());
+    }
+    for (const [name, value] of Object.entries(incoming)) {
+        if (value === undefined || hopByHop.has(name.toLowerCase()))
+            continue;
+        headers[name] = value;
+    }
+    headers.host = "api.anthropic.com";
+    headers.authorization = `Bearer ${secret}`;
+    return headers;
+}
+export function poolInferencePathAllowed(method, requestUrl) {
+    if (method !== "POST")
+        return false;
+    const pathname = new URL(requestUrl ?? "/", "http://127.0.0.1").pathname;
+    return pathname === "/v1/messages" || pathname.startsWith("/v1/messages/");
+}
+function sendJson(response, status, message) {
+    response.writeHead(status, { "content-type": "application/json", connection: "close" });
+    response.end(JSON.stringify({ error: { type: "proxy_error", message } }));
+}
+export function createInferenceForwarder(options) {
+    const requestUpstream = options.upstream ?? https.request;
+    const server = createServer((incoming, response) => {
+        if (!poolInferencePathAllowed(incoming.method, incoming.url)) {
+            sendJson(response, 404, "only POST /v1/messages is available through this inference forwarder");
+            incoming.resume();
+            return;
+        }
+        const secret = options.secret();
+        if (!secret) {
+            sendJson(response, 503, "the pool inference secret is unavailable");
+            incoming.resume();
+            return;
+        }
+        const headers = inferenceForwardHeaders(incoming.headers, secret);
+        const upstream = requestUpstream({
+            protocol: "https:",
+            hostname: "api.anthropic.com",
+            lookup: (hostname, _options, callback) => {
+                // The host can map this name to A's local proxy in /etc/hosts. DNS
+                // resolution bypasses that mapping for the pool's outbound request.
+                dns.resolve4(hostname, (error, addresses) => {
+                    if (_options.all)
+                        callback(error, addresses?.map((address) => ({ address, family: 4 })) ?? []);
+                    else
+                        callback(error, addresses?.[0] ?? "", 4);
+                });
+            },
+            port: 443,
+            method: "POST",
+            path: incoming.url,
+            headers,
+        }, (upstreamResponse) => {
+            response.writeHead(upstreamResponse.statusCode ?? 502, upstreamResponse.headers);
+            upstreamResponse.pipe(response);
+        });
+        const connectTimeout = setTimeout(() => {
+            upstream.destroy(new Error("pool inference upstream connection timed out"));
+        }, POOL_UPSTREAM_CONNECT_TIMEOUT_MS);
+        upstream.once("socket", (socket) => {
+            socket.once("secureConnect", () => clearTimeout(connectTimeout));
+        });
+        upstream.setTimeout(options.upstreamTimeoutMs ?? POOL_UPSTREAM_TIMEOUT_MS, () => {
+            upstream.destroy(new Error("pool inference upstream timed out"));
+        });
+        upstream.on("error", () => {
+            clearTimeout(connectTimeout);
+            if (!response.headersSent && !response.destroyed)
+                sendJson(response, 502, "the pool inference backend is unavailable");
+            else
+                response.destroy();
+        });
+        upstream.once("close", () => clearTimeout(connectTimeout));
+        response.once("close", () => {
+            clearTimeout(connectTimeout);
+            if (!response.writableEnded)
+                upstream.destroy();
+        });
+        incoming.pipe(upstream);
+    });
+    server.listen(options.port, "127.0.0.1");
+    return server;
+}
+//# sourceMappingURL=remote-control-forwarder.js.map

package/dist/lib/daemon/remote-control-pools.d.ts

@@ -0,0 +1,44 @@
+/** Host-local desired state for opt-in Claude Remote Control account pools. */
+export interface RemoteControlPool {
+    accountId: string;
+    capacity: number;
+    /** Private loopback address bound by the external nginx TLS listener. */
+    frontendAddress: string;
+    /** The Anthropic API hostname is HTTPS and the hosts overlay cannot set a port. */
+    frontendPort: 443;
+    /** Loopback-only inference forwarder owned by hq daemon. */
+    forwarderPort: number;
+    /** A real mount-point path, not a symlink, populated in a private namespace. */
+    mountPath: string;
+    /** HQ Secrets name; the secret value is never part of this file. */
+    secretName: string;
+}
+export interface RemoteControlPoolsConfig {
+    version: 1;
+    /** CA certificate trusted by Claude and used to verify the external nginx TLS listener. */
+    frontendCaPath?: string;
+    /** Stable HQ session whose scope capability is locked to personal for Secrets access. */
+    serviceSessionId?: string;
+    pools: RemoteControlPool[];
+}
+/** Parse and validate the complete desired state; unknown keys fail closed. */
+export declare function parseRemoteControlPoolsConfig(value: unknown, knownAccountIds?: Iterable<string>, home?: string): RemoteControlPoolsConfig;
+/** Override ambient session selection only for a Secrets child process. */
+export declare function remoteControlPoolSecretsEnv(env: NodeJS.ProcessEnv, serviceSessionId: string): NodeJS.ProcessEnv;
+/** Require an explicit, existing capability; never inherit the mutable .current session. */
+export declare function assertPersonalServiceSessionCapability(root: string, serviceSessionId: string): void;
+/** Hosts file overlay consumed inside this pool's private mount namespace. */
+export declare function remoteControlPoolHostsOverlay(pool: RemoteControlPool): string;
+export declare function poolHostsFile(baseHosts: string, pool: RemoteControlPool): string;
+export declare function readRemoteControlPoolsConfig(file: string, knownAccountIds?: Iterable<string>, home?: string): RemoteControlPoolsConfig;
+export declare function writeRemoteControlPoolsConfig(file: string, config: RemoteControlPoolsConfig, home?: string): void;
+export declare function remoteControlPoolArgs(pool: RemoteControlPool): string[];
+/** Reject an existing symlink anywhere in the requested path. */
+export declare function assertNoSymlinkPathComponents(target: string): void;
+/** Compare paths after resolving their real filesystem identities. */
+export declare function assertDistinctRealMountPath(mountPath: string, hqRoot: string): void;
+/** Validate the private readiness marker against the live forwarder process identity. */
+export declare function isOwnedPoolForwarder(readyFile: string, accountId: string, isAlive: (pid: number) => boolean, commandLine: (pid: number) => string | null): boolean;
+/** Fail the pool host when its separately supervised inference process disappears. */
+export declare function monitorOwnedPoolForwarder(isOwned: () => boolean, signal: AbortSignal, sleep?: () => Promise<void>): Promise<void>;
+//# sourceMappingURL=remote-control-pools.d.ts.map