@borgee/agents-host 0.2.1 → 0.2.26

package/dist/managed-daemon.js

@@ -0,0 +1,1601 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { promises as fs } from 'node:fs';
+import { spawn } from 'node:child_process';
+import { createConnection, createServer } from 'node:net';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { AgentsHostSupervisor } from './agents-host-supervisor.js';
+import { COMPATIBILITY_GATES_ENV, createManagedRuntimeSettingsFingerprint, INTERNAL_POLICY_MODE_ENV, INTERNAL_PROVIDER_IMPLEMENTATIONS_ENV, MANAGED_RUNTIME_CONVERGENCE_COMPATIBILITY_GATE, MANAGED_RUNTIME_SETTINGS_SCHEMA_VERSION, resolveManagedRuntimeSettingsSnapshot, normalizeInternalProviderImplementationOverrides, } from './compatibility-gates.js';
+import { loadConfigFromEnv } from './config.js';
+import { loadLocalConfigGenerateSpec, materializeLocalConfig, parseGenerateConfigSpec, resolveLocalConfigLayout, } from './local-config.js';
+import { normalizeManagedRuntimeKey, resolveManagedBootstrapLockPath, resolveManagedDaemonLogPath, resolveManagedDaemonSocketPath, resolveManagedRuntimeRoot, resolveManagedRuntimeSettingsPath, } from './state-paths.js';
+const MANAGED_ROOT_MODE = 0o700;
+const MANAGED_CONFIG_MODE = 0o600;
+const BOOTSTRAP_LOCK_WAIT_MS = 10_000;
+const BOOTSTRAP_LOCK_RETRY_MS = 50;
+const HOLDER_METADATA_FILENAME = '.holder.json';
+const HOLDER_MAX_AGE_MS = 5 * 60_000;
+// Managed daemon startup includes the full supervisor bootstrap for every
+// persisted agent in the runtime root. On a cold local restart that can take
+// materially longer than a bare socket bind, so the bootstrap/resume path needs
+// a longer wait window than the original 10s probe to avoid false failures.
+const DAEMON_READY_WAIT_MS = 60_000;
+const DAEMON_RECONCILE_WAIT_MS = 60_000;
+const DAEMON_READY_RETRY_MS = 100;
+const CONTROL_SOCKET_CONNECT_TIMEOUT_MS = 1_000;
+const DAEMON_EXIT_WAIT_MS = 2_000;
+const DAEMON_FORCE_KILL_WAIT_MS = 1_000;
+export const MANAGED_DAEMON_ERROR_CODES = [
+    'MANAGED_BINDING_MISMATCH',
+    'MANAGED_RUNTIME_NOT_PRESENT',
+    'MANAGED_SPEC_INVALID',
+    'MANAGED_BOOTSTRAP_LOCK_TIMEOUT',
+    'MANAGED_DAEMON_START_FAILED',
+    'MANAGED_DAEMON_NOT_READY',
+    'MANAGED_RELOAD_FAILED',
+    'MANAGED_CONVERGENCE_FAILED',
+];
+const MANAGED_DAEMON_NOT_READY_MESSAGE = 'Managed daemon is still starting';
+function isNodeErrorWithCode(error, code) {
+    return typeof error === 'object' && error !== null && 'code' in error && error.code === code;
+}
+function isNotFoundError(error) {
+    return isNodeErrorWithCode(error, 'ENOENT');
+}
+function isAlreadyExistsError(error) {
+    return isNodeErrorWithCode(error, 'EEXIST');
+}
+function isSocketBusyError(error) {
+    return isNodeErrorWithCode(error, 'EADDRINUSE');
+}
+function delay(milliseconds) {
+    return new Promise((resolveDelay) => {
+        setTimeout(resolveDelay, milliseconds);
+    });
+}
+function toErrorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function isManagedDaemonErrorCode(value) {
+    return MANAGED_DAEMON_ERROR_CODES.includes(value);
+}
+function resolveLegacyManagedErrorCode(message, fallbackCode) {
+    return message === MANAGED_DAEMON_NOT_READY_MESSAGE ? 'MANAGED_DAEMON_NOT_READY' : fallbackCode;
+}
+class ManagedDaemonOperationError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'ManagedDaemonOperationError';
+        this.code = code;
+    }
+}
+function managedOperationError(code, message) {
+    return new ManagedDaemonOperationError(code, message);
+}
+function isManagedOperationError(error) {
+    return error instanceof ManagedDaemonOperationError;
+}
+function toManagedErrorPayload(error, fallbackCode = 'MANAGED_RELOAD_FAILED') {
+    if (isManagedOperationError(error)) {
+        return {
+            code: error.code,
+            message: error.message,
+        };
+    }
+    if (typeof error === 'string') {
+        return {
+            code: resolveLegacyManagedErrorCode(error, fallbackCode),
+            message: error,
+        };
+    }
+    if (typeof error === 'object' &&
+        error !== null &&
+        'message' in error &&
+        typeof error.message === 'string') {
+        const code = 'code' in error && typeof error.code === 'string' && isManagedDaemonErrorCode(error.code)
+            ? error.code
+            : resolveLegacyManagedErrorCode(error.message, fallbackCode);
+        return {
+            code,
+            message: error.message,
+        };
+    }
+    return {
+        code: fallbackCode,
+        message: toErrorMessage(error),
+    };
+}
+function toManagedErrorResponse(error, fallbackCode = 'MANAGED_RELOAD_FAILED') {
+    return {
+        ok: false,
+        error: toManagedErrorPayload(error, fallbackCode),
+    };
+}
+function isManagedErrorResponse(response) {
+    return response.ok === false;
+}
+function normalizeManagedErrorResponse(response) {
+    return {
+        ok: false,
+        error: toManagedErrorPayload(response.error),
+    };
+}
+function getManagedErrorPayload(response) {
+    return normalizeManagedErrorResponse(response).error;
+}
+function isExpectedManagedFailure(error) {
+    return isManagedOperationError(error);
+}
+function combineManagedRollbackFailure(applyError, rollbackError) {
+    const original = toManagedErrorPayload(applyError, 'MANAGED_RELOAD_FAILED');
+    const rollback = toManagedErrorPayload(rollbackError, 'MANAGED_RELOAD_FAILED');
+    return managedOperationError(original.code, `${original.message}; rollback failed: ${rollback.message}`);
+}
+function toApplyManagedColdStartErrorResponse(error) {
+    if (isManagedOperationError(error)) {
+        return toManagedErrorResponse(error);
+    }
+    return toManagedErrorResponse(managedOperationError('MANAGED_RELOAD_FAILED', toErrorMessage(error)));
+}
+function resolveDesiredManagedRuntimeSettings(env = process.env) {
+    const snapshot = resolveManagedRuntimeSettingsSnapshot(env);
+    return {
+        snapshot,
+        fingerprint: createManagedRuntimeSettingsFingerprint(snapshot),
+        convergenceEnabled: snapshot.compatibilityGates.includes(MANAGED_RUNTIME_CONVERGENCE_COMPATIBILITY_GATE),
+    };
+}
+function normalizeManagedRuntimeSettingsSnapshot(snapshot) {
+    const compatibilityGates = [...new Set(snapshot.compatibilityGates.map((gate) => gate.trim()))]
+        .filter((gate) => gate.length > 0)
+        .sort((left, right) => left.localeCompare(right));
+    const providerImplementationOverrides = normalizeInternalProviderImplementationOverrides(snapshot.providerImplementationOverrides.join(','));
+    return {
+        schemaVersion: MANAGED_RUNTIME_SETTINGS_SCHEMA_VERSION,
+        compatibilityGates,
+        providerImplementationOverrides,
+        internalPolicyMode: snapshot.internalPolicyMode,
+    };
+}
+function parseManagedRuntimeSettingsSnapshotRecord(value, sourceLabel) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new Error(`Invalid ${sourceLabel}: expected an object`);
+    }
+    const record = value;
+    if (record.schemaVersion !== MANAGED_RUNTIME_SETTINGS_SCHEMA_VERSION) {
+        throw new Error(`Invalid ${sourceLabel}: expected schemaVersion ${MANAGED_RUNTIME_SETTINGS_SCHEMA_VERSION}`);
+    }
+    if (!Array.isArray(record.compatibilityGates)
+        || !record.compatibilityGates.every((entry) => typeof entry === 'string')) {
+        throw new Error(`Invalid ${sourceLabel}: expected compatibilityGates to be a string array`);
+    }
+    if (!Array.isArray(record.providerImplementationOverrides)
+        || !record.providerImplementationOverrides.every((entry) => typeof entry === 'string')) {
+        throw new Error(`Invalid ${sourceLabel}: expected providerImplementationOverrides to be a string array`);
+    }
+    if (record.internalPolicyMode !== 'audit-only' && record.internalPolicyMode !== 'enforce') {
+        throw new Error(`Invalid ${sourceLabel}: expected internalPolicyMode to be "audit-only" or "enforce"`);
+    }
+    return normalizeManagedRuntimeSettingsSnapshot({
+        schemaVersion: MANAGED_RUNTIME_SETTINGS_SCHEMA_VERSION,
+        compatibilityGates: [...record.compatibilityGates],
+        providerImplementationOverrides: [...record.providerImplementationOverrides],
+        internalPolicyMode: record.internalPolicyMode,
+    });
+}
+async function loadManagedRuntimeSettingsSnapshot(rootPath) {
+    const settingsPath = resolveManagedRuntimeSettingsPath(rootPath);
+    try {
+        const raw = await fs.readFile(settingsPath, 'utf8');
+        return parseManagedRuntimeSettingsSnapshotRecord(JSON.parse(raw), `managed runtime settings snapshot ${settingsPath}`);
+    }
+    catch (error) {
+        if (isNotFoundError(error)) {
+            return undefined;
+        }
+        if (error instanceof SyntaxError) {
+            throw new Error(`Invalid managed runtime settings snapshot ${settingsPath}: ${error.message}`);
+        }
+        throw error;
+    }
+}
+async function writeManagedRuntimeSettingsSnapshot(rootPath, snapshot) {
+    await ensureDirectory(rootPath, MANAGED_ROOT_MODE);
+    const settingsPath = resolveManagedRuntimeSettingsPath(rootPath);
+    const normalizedSnapshot = normalizeManagedRuntimeSettingsSnapshot(snapshot);
+    await fs.writeFile(settingsPath, `${JSON.stringify(normalizedSnapshot)}\n`, {
+        encoding: 'utf8',
+        mode: MANAGED_CONFIG_MODE,
+    });
+    await fs.chmod(settingsPath, MANAGED_CONFIG_MODE);
+}
+async function restoreManagedRuntimeSettingsSnapshot(rootPath, snapshot) {
+    const settingsPath = resolveManagedRuntimeSettingsPath(rootPath);
+    if (!snapshot) {
+        await fs.rm(settingsPath, { force: true });
+        return;
+    }
+    await writeManagedRuntimeSettingsSnapshot(rootPath, snapshot);
+}
+function buildManagedRuntimeSettingsEnv(baseEnv, snapshot) {
+    return {
+        ...baseEnv,
+        [COMPATIBILITY_GATES_ENV]: snapshot.compatibilityGates.join(','),
+        [INTERNAL_PROVIDER_IMPLEMENTATIONS_ENV]: snapshot.providerImplementationOverrides.join(','),
+        [INTERNAL_POLICY_MODE_ENV]: snapshot.internalPolicyMode,
+    };
+}
+function getManagedRuntimeFingerprintMismatch(status, desiredSettings) {
+    if (!desiredSettings.convergenceEnabled) {
+        return status.managedRuntimeFingerprint != null;
+    }
+    return status.managedRuntimeFingerprint !== desiredSettings.fingerprint;
+}
+function cloneLocalAgentConfig(agent) {
+    return {
+        ...agent,
+        claudeArgs: agent.claudeArgs ? [...agent.claudeArgs] : undefined,
+        codexArgs: agent.codexArgs ? [...agent.codexArgs] : undefined,
+        copilotArgs: agent.copilotArgs ? [...agent.copilotArgs] : undefined,
+    };
+}
+function cloneLocalHostGenerateConfig(spec) {
+    return {
+        ...spec,
+        defaults: spec.defaults
+            ? {
+                ...spec.defaults,
+                claudeArgs: spec.defaults.claudeArgs ? [...spec.defaults.claudeArgs] : undefined,
+                codexArgs: spec.defaults.codexArgs ? [...spec.defaults.codexArgs] : undefined,
+                copilotArgs: spec.defaults.copilotArgs ? [...spec.defaults.copilotArgs] : undefined,
+            }
+            : undefined,
+    };
+}
+function cloneLocalConfigGenerateSpec(spec) {
+    return {
+        host: cloneLocalHostGenerateConfig(spec.host),
+        agents: spec.agents.map((agent) => cloneLocalAgentConfig(agent)),
+    };
+}
+function normalizeRequestedManagedBinding(serverUrl) {
+    return normalizeManagedRuntimeKey(serverUrl);
+}
+function countEnabledManagedAgents(agents) {
+    return agents.filter((agent) => agent.enabled !== false).length;
+}
+function listEnabledManagedAgentKeys(agents) {
+    return agents
+        .filter((agent) => agent.enabled !== false)
+        .map((agent) => agent.key)
+        .sort((left, right) => left.localeCompare(right));
+}
+function hashApiKey(apiKey) {
+    return createHash('sha256').update(apiKey).digest('hex').slice(0, 16);
+}
+export function resolveManagedAgentKey(apiKey) {
+    return `agent-${hashApiKey(apiKey)}`;
+}
+export function buildManagedLocalAgentConfig(options) {
+    if (!options.apiKey) {
+        throw new Error('Managed bootstrap requires an apiKey');
+    }
+    const processEnv = options.processEnv ?? process.env;
+    const effectiveEnv = {
+        ...processEnv,
+        ...options.env,
+        BORGEE_BASE_URL: options.serverUrl,
+        BORGEE_AGENT_API_KEY: options.apiKey,
+    };
+    const config = loadConfigFromEnv(effectiveEnv);
+    const rootPath = resolveManagedRuntimeRoot(config.borgeeBaseUrl, effectiveEnv);
+    const hostConfigPath = resolveLocalConfigLayout(rootPath).hostConfigPath;
+    return {
+        rootPath,
+        hostConfigPath,
+        borgeeBaseUrl: config.borgeeBaseUrl,
+        agent: {
+            key: resolveManagedAgentKey(config.agent.agentApiKey),
+            name: config.agent.agentName,
+            apiKey: config.agent.agentApiKey,
+            provider: config.agent.provider,
+            enabled: true,
+            claudeCommand: config.claudeCommand,
+            claudeArgs: [...config.claudeArgs],
+            codexCommand: config.codexCommand,
+            codexArgs: [...config.codexArgs],
+            copilotCommand: config.copilotCommand,
+            copilotArgs: [...config.copilotArgs],
+            copilotSessionTtlMinutes: config.copilotSessionTtlMinutes,
+        },
+    };
+}
+function resolveManagedRuntimeLayoutForServerUrl(serverUrl, processEnv = process.env) {
+    const rootPath = resolveManagedRuntimeRoot(serverUrl, processEnv);
+    return {
+        rootPath,
+        hostConfigPath: resolveLocalConfigLayout(rootPath).hostConfigPath,
+        borgeeBaseUrl: normalizeRequestedManagedBinding(serverUrl),
+    };
+}
+function createMissingManagedAgentError(serverUrl) {
+    return managedOperationError('MANAGED_RUNTIME_NOT_PRESENT', `No managed agents have been bootstrapped for ${normalizeManagedRuntimeKey(serverUrl)}; run agents-host start-managed <serverUrl> <apiKey> first`);
+}
+function assertManagedRuntimeBinding(runtimeServerUrl, requestedServerUrl) {
+    if (normalizeManagedRuntimeKey(runtimeServerUrl) !==
+        normalizeRequestedManagedBinding(requestedServerUrl)) {
+        throw managedOperationError('MANAGED_BINDING_MISMATCH', 'Managed runtime root is bound to a different Borgee base URL');
+    }
+}
+function assertManagedSpecBinding(spec, requestedServerUrl) {
+    assertManagedRuntimeBinding(spec.host.borgeeBaseUrl, requestedServerUrl);
+}
+async function loadManagedSpecOrUndefined(hostConfigPath, loadSpec) {
+    try {
+        return await loadSpec(hostConfigPath);
+    }
+    catch (error) {
+        if (isNotFoundError(error)) {
+            return undefined;
+        }
+        throw error;
+    }
+}
+function buildDescribeSpecResponse(spec) {
+    if (!spec) {
+        return {
+            ok: true,
+            type: 'describeSpec',
+            present: false,
+        };
+    }
+    return {
+        ok: true,
+        type: 'describeSpec',
+        present: true,
+        spec,
+    };
+}
+function ensureCurrentManagedSpec(spec) {
+    if (!spec) {
+        throw managedOperationError('MANAGED_RUNTIME_NOT_PRESENT', 'Managed runtime config is not present for this managed root');
+    }
+    return spec;
+}
+async function ensurePersistedManagedAgentsExist(serverUrl, hostConfigPath, loadSpec) {
+    let spec;
+    try {
+        spec = await loadSpec(hostConfigPath);
+    }
+    catch (error) {
+        if (isNotFoundError(error)) {
+            throw createMissingManagedAgentError(serverUrl);
+        }
+        throw error;
+    }
+    assertManagedRuntimeBinding(spec.host.borgeeBaseUrl, serverUrl);
+    if (spec.agents.length === 0) {
+        throw createMissingManagedAgentError(serverUrl);
+    }
+}
+async function ensureDirectory(path, mode) {
+    await fs.mkdir(path, { recursive: true, mode });
+    await fs.chmod(path, mode);
+}
+async function readHolderMetadata(holderPath) {
+    try {
+        const raw = await fs.readFile(`${holderPath}/${HOLDER_METADATA_FILENAME}`, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed !== 'object' || parsed === null) {
+            return undefined;
+        }
+        const pid = 'pid' in parsed ? parsed.pid : undefined;
+        const createdAt = 'createdAt' in parsed ? parsed.createdAt : undefined;
+        const token = 'token' in parsed ? parsed.token : undefined;
+        if (typeof pid !== 'number' ||
+            !Number.isSafeInteger(pid) ||
+            pid <= 0 ||
+            typeof createdAt !== 'number' ||
+            !Number.isFinite(createdAt) ||
+            typeof token !== 'string' ||
+            token.length === 0) {
+            return undefined;
+        }
+        return { pid, createdAt, token };
+    }
+    catch (error) {
+        if (isNotFoundError(error)) {
+            return undefined;
+        }
+        throw error;
+    }
+}
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        if (isNodeErrorWithCode(error, 'ESRCH')) {
+            return false;
+        }
+        return undefined;
+    }
+}
+async function isStaleHolderDirectory(holderPath, stats) {
+    const metadata = await readHolderMetadata(holderPath);
+    if (!metadata) {
+        return Date.now() - stats.mtimeMs >= HOLDER_MAX_AGE_MS;
+    }
+    const alive = isProcessAlive(metadata.pid);
+    return (alive === false || (alive === undefined && Date.now() - metadata.createdAt >= HOLDER_MAX_AGE_MS));
+}
+export async function acquireBootstrapLock(rootPath) {
+    await ensureDirectory(rootPath, MANAGED_ROOT_MODE);
+    const lockPath = resolveManagedBootstrapLockPath(rootPath);
+    const deadline = Date.now() + BOOTSTRAP_LOCK_WAIT_MS;
+    while (true) {
+        const metadata = {
+            pid: process.pid,
+            createdAt: Date.now(),
+            token: randomUUID(),
+        };
+        try {
+            await fs.mkdir(lockPath, { mode: MANAGED_ROOT_MODE });
+            try {
+                await fs.writeFile(`${lockPath}/${HOLDER_METADATA_FILENAME}`, `${JSON.stringify(metadata)}\n`, {
+                    encoding: 'utf8',
+                    mode: MANAGED_CONFIG_MODE,
+                });
+                await fs.chmod(lockPath, MANAGED_ROOT_MODE);
+            }
+            catch (error) {
+                await fs.rm(lockPath, { recursive: true, force: true }).catch(() => undefined);
+                throw error;
+            }
+            return async () => {
+                const currentMetadata = await readHolderMetadata(lockPath).catch(() => undefined);
+                if (currentMetadata?.token === metadata.token) {
+                    await fs.rm(lockPath, { recursive: true, force: true });
+                }
+            };
+        }
+        catch (error) {
+            if (!isAlreadyExistsError(error)) {
+                throw error;
+            }
+            const stats = await fs.lstat(lockPath).catch((lstatError) => {
+                if (isNotFoundError(lstatError)) {
+                    return undefined;
+                }
+                throw lstatError;
+            });
+            if (stats && (!stats.isDirectory() || stats.isSymbolicLink())) {
+                throw new Error(`Managed bootstrap lock has an unexpected value: ${lockPath}`);
+            }
+            if (stats && (await isStaleHolderDirectory(lockPath, stats))) {
+                await fs.rm(lockPath, { recursive: true, force: true });
+                continue;
+            }
+            if (Date.now() >= deadline) {
+                throw managedOperationError('MANAGED_BOOTSTRAP_LOCK_TIMEOUT', `Timed out waiting for managed bootstrap lock: ${lockPath}`);
+            }
+            await delay(BOOTSTRAP_LOCK_RETRY_MS);
+        }
+    }
+}
+async function canConnectToSocket(socketPath) {
+    return new Promise((resolveConnection) => {
+        const socket = createConnection(socketPath);
+        const finalize = (value) => {
+            socket.removeAllListeners();
+            socket.destroy();
+            resolveConnection(value);
+        };
+        socket.setTimeout(CONTROL_SOCKET_CONNECT_TIMEOUT_MS);
+        socket.once('connect', () => finalize(true));
+        socket.once('timeout', () => finalize(false));
+        socket.once('error', () => finalize(false));
+    });
+}
+async function removeStaleControlSocket(socketPath) {
+    const stats = await fs.lstat(socketPath).catch((error) => {
+        if (isNotFoundError(error)) {
+            return undefined;
+        }
+        throw error;
+    });
+    if (!stats) {
+        return false;
+    }
+    if (stats.isDirectory() || stats.isSymbolicLink()) {
+        throw new Error(`Managed control socket path has an unexpected value: ${socketPath}`);
+    }
+    if (await canConnectToSocket(socketPath)) {
+        return false;
+    }
+    if (!stats.isSocket() && !stats.isFile()) {
+        throw new Error(`Managed control socket path has an unexpected value: ${socketPath}`);
+    }
+    await fs.rm(socketPath, { force: true });
+    return true;
+}
+function parseDaemonResponse(raw) {
+    const parsed = JSON.parse(raw);
+    if (typeof parsed !== 'object' ||
+        parsed === null ||
+        typeof parsed.ok !== 'boolean') {
+        throw new Error('Invalid daemon response payload');
+    }
+    if (parsed.ok === false) {
+        return normalizeManagedErrorResponse(parsed);
+    }
+    return parsed;
+}
+function parseDaemonRequest(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw managedOperationError('MANAGED_SPEC_INVALID', `Invalid managed daemon request JSON: ${toErrorMessage(error)}`);
+    }
+    if (typeof parsed !== 'object' ||
+        parsed === null ||
+        typeof parsed.type !== 'string') {
+        throw managedOperationError('MANAGED_SPEC_INVALID', 'Invalid managed daemon request payload');
+    }
+    return parsed;
+}
+function isManagedDaemonConnectionError(error) {
+    return (isNodeErrorWithCode(error, 'ECONNREFUSED') ||
+        isNodeErrorWithCode(error, 'ENOENT') ||
+        isNodeErrorWithCode(error, 'ENOTSOCK') ||
+        isNodeErrorWithCode(error, 'ECONNRESET'));
+}
+export async function sendManagedDaemonRequest(rootPath, request) {
+    const socketPath = resolveManagedDaemonSocketPath(rootPath);
+    const requestTimeoutMs = request.type === 'upsertAgent' || request.type === 'applySpec'
+        ? DAEMON_RECONCILE_WAIT_MS
+        : DAEMON_READY_WAIT_MS;
+    return new Promise((resolveRequest, rejectRequest) => {
+        const socket = createConnection(socketPath);
+        let settled = false;
+        let responseBuffer = '';
+        const rejectOnce = (error) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            socket.destroy();
+            rejectRequest(error);
+        };
+        const resolveOnce = (response) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            socket.destroy();
+            resolveRequest(response);
+        };
+        socket.setEncoding('utf8');
+        socket.setTimeout(requestTimeoutMs);
+        socket.once('timeout', () => rejectOnce(new Error(`Timed out talking to managed daemon: ${socketPath}`)));
+        socket.once('error', rejectOnce);
+        socket.on('data', (chunk) => {
+            responseBuffer += chunk;
+            const newlineIndex = responseBuffer.indexOf('\n');
+            if (newlineIndex === -1) {
+                return;
+            }
+            try {
+                resolveOnce(parseDaemonResponse(responseBuffer.slice(0, newlineIndex)));
+            }
+            catch (error) {
+                rejectOnce(error);
+            }
+        });
+        socket.once('connect', () => {
+            socket.write(`${JSON.stringify(request)}\n`);
+        });
+        socket.once('end', () => {
+            if (!settled) {
+                rejectOnce(new Error('Managed daemon closed the control socket before sending a response'));
+            }
+        });
+    });
+}
+export async function waitForManagedDaemonReady(rootPath, sendRequest, child) {
+    const deadline = Date.now() + DAEMON_READY_WAIT_MS;
+    let childExited = false;
+    let childExitSummary = 'unknown exit';
+    const onExit = (code, signal) => {
+        childExited = true;
+        childExitSummary = `code=${code ?? 'null'} signal=${signal ?? 'null'}`;
+    };
+    child.once('exit', onExit);
+    try {
+        while (Date.now() < deadline) {
+            if (childExited) {
+                throw managedOperationError('MANAGED_DAEMON_START_FAILED', `Managed daemon exited before becoming ready (${childExitSummary})`);
+            }
+            try {
+                const response = await sendRequest(rootPath, { type: 'status' });
+                if (response.ok && response.type === 'status') {
+                    return;
+                }
+                if (isManagedErrorResponse(response)) {
+                    const managedError = getManagedErrorPayload(response);
+                    if (managedError.code !== 'MANAGED_DAEMON_NOT_READY') {
+                        throw managedOperationError(managedError.code, managedError.message);
+                    }
+                }
+            }
+            catch (error) {
+                if (isManagedOperationError(error)) {
+                    throw error;
+                }
+                // Retry until the deadline or an early child exit.
+            }
+            await delay(DAEMON_READY_RETRY_MS);
+        }
+        throw managedOperationError('MANAGED_DAEMON_NOT_READY', `Timed out waiting for managed daemon readiness: ${rootPath}`);
+    }
+    finally {
+        child.off('exit', onExit);
+    }
+}
+async function waitForExistingManagedDaemonReady(rootPath, sendRequest) {
+    const deadline = Date.now() + DAEMON_READY_WAIT_MS;
+    while (Date.now() < deadline) {
+        let response;
+        try {
+            response = await sendRequest(rootPath, { type: 'status' });
+        }
+        catch {
+            await delay(DAEMON_READY_RETRY_MS);
+            continue;
+        }
+        if (response.ok && response.type === 'status') {
+            return response;
+        }
+        if (isManagedErrorResponse(response)) {
+            const managedError = getManagedErrorPayload(response);
+            if (managedError.code !== 'MANAGED_DAEMON_NOT_READY') {
+                throw managedOperationError(managedError.code, managedError.message);
+            }
+        }
+        await delay(DAEMON_READY_RETRY_MS);
+    }
+    throw managedOperationError('MANAGED_DAEMON_NOT_READY', `Timed out waiting for managed daemon readiness: ${rootPath}`);
+}
+async function readReadyManagedDaemonStatus(rootPath, sendRequest) {
+    try {
+        const status = await sendRequest(rootPath, { type: 'status' });
+        if (status.ok && status.type === 'status') {
+            return status;
+        }
+        if (isManagedErrorResponse(status)) {
+            return waitForExistingManagedDaemonReady(rootPath, sendRequest);
+        }
+        return undefined;
+    }
+    catch (error) {
+        if (isManagedDaemonConnectionError(error)) {
+            return undefined;
+        }
+        throw error;
+    }
+}
+async function waitForManagedDaemonShutdown(rootPath, canConnect) {
+    const deadline = Date.now() + DAEMON_READY_WAIT_MS;
+    const socketPath = resolveManagedDaemonSocketPath(rootPath);
+    while (Date.now() < deadline) {
+        const listening = await canConnect(socketPath).catch((error) => {
+            if (isNodeErrorWithCode(error, 'ENOENT')) {
+                return false;
+            }
+            throw error;
+        });
+        if (!listening) {
+            return;
+        }
+        await delay(DAEMON_READY_RETRY_MS);
+    }
+    throw managedOperationError('MANAGED_RELOAD_FAILED', `Timed out waiting for managed daemon shutdown: ${rootPath}`);
+}
+async function shutdownManagedDaemon(rootPath, sendRequest, waitForShutdown) {
+    const response = await sendRequest(rootPath, { type: 'shutdown' });
+    if (!response.ok) {
+        const managedError = getManagedErrorPayload(response);
+        throw managedOperationError(managedError.code, managedError.message);
+    }
+    if (response.type !== 'shutdown') {
+        throw new Error('Unexpected managed daemon response for shutdown');
+    }
+    await waitForShutdown(rootPath);
+}
+export async function cleanupManagedRuntime(options, deps = {}) {
+    const sendRequest = deps.sendRequest ?? sendManagedDaemonRequest;
+    const removeRuntimeRoot = deps.removeRuntimeRoot ??
+        (async (rootPath) => {
+            await fs.rm(rootPath, { recursive: true, force: true });
+        });
+    const confirmSocket = deps.canConnectToSocket ?? canConnectToSocket;
+    const resolved = resolveManagedRuntimeLayoutForServerUrl(options.serverUrl, options.processEnv);
+    const waitForShutdown = deps.waitForShutdown ??
+        (async (rootPath) => {
+            await waitForManagedDaemonShutdown(rootPath, confirmSocket);
+        });
+    let requestedShutdown = false;
+    try {
+        const response = await sendRequest(resolved.rootPath, { type: 'shutdown' });
+        if (!response.ok) {
+            const managedError = getManagedErrorPayload(response);
+            throw managedOperationError(managedError.code, managedError.message);
+        }
+        if (response.type !== 'shutdown') {
+            throw new Error('Unexpected managed daemon response for shutdown');
+        }
+        requestedShutdown = true;
+    }
+    catch (error) {
+        if (!isManagedDaemonConnectionError(error)) {
+            if (isExpectedManagedFailure(error)) {
+                throw error;
+            }
+            throw error;
+        }
+    }
+    if (requestedShutdown) {
+        await waitForShutdown(resolved.rootPath);
+    }
+    if (options.purge === true) {
+        await removeRuntimeRoot(resolved.rootPath);
+    }
+}
+export async function openManagedDaemonLogFile(rootPath) {
+    await ensureDirectory(rootPath, MANAGED_ROOT_MODE);
+    const logPath = resolveManagedDaemonLogPath(rootPath);
+    const logFileHandle = await fs.open(logPath, 'a', MANAGED_CONFIG_MODE);
+    try {
+        await logFileHandle.chmod(MANAGED_CONFIG_MODE);
+        return {
+            logPath,
+            fd: logFileHandle.fd,
+            async close() {
+                await logFileHandle.close();
+            },
+        };
+    }
+    catch (error) {
+        await logFileHandle.close().catch(() => undefined);
+        throw error;
+    }
+}
+export async function spawnDetachedManagedProcess(options, deps = {}) {
+    const openLogFile = deps.openLogFile ?? openManagedDaemonLogFile;
+    const spawnProcess = deps.spawnProcess ?? spawn;
+    const logFile = await openLogFile(options.rootPath);
+    try {
+        return spawnProcess(options.command, options.args, {
+            detached: true,
+            env: options.env,
+            stdio: ['ignore', logFile.fd, logFile.fd],
+        });
+    }
+    finally {
+        await logFile.close().catch(() => undefined);
+    }
+}
+export async function spawnManagedDaemonProcess(options, deps = {}) {
+    const spawnDetachedProcess = deps.spawnDetachedProcess ?? spawnDetachedManagedProcess;
+    const managedRuntimeSettingsSnapshot = await loadManagedRuntimeSettingsSnapshot(options.rootPath);
+    if (!managedRuntimeSettingsSnapshot) {
+        throw new Error(`Managed runtime settings snapshot is missing for ${resolveManagedRuntimeSettingsPath(options.rootPath)}`);
+    }
+    const thisPath = fileURLToPath(import.meta.url);
+    const cliEntrypointPath = join(dirname(thisPath), thisPath.endsWith('.ts') ? 'cli.ts' : 'cli.js');
+    return spawnDetachedProcess({
+        rootPath: options.rootPath,
+        command: process.execPath,
+        env: {
+            ...buildManagedRuntimeSettingsEnv({
+                ...process.env,
+                ...(options.processEnv ?? {}),
+            }, managedRuntimeSettingsSnapshot),
+            AGENTS_HOST_MANAGED_DAEMON_LOG_PATH: resolveManagedDaemonLogPath(options.rootPath),
+            AGENTS_HOST_INTERNAL_TASK_WORKSPACE_ROOT_DIR: options.rootPath,
+        },
+        args: [
+            ...process.execArgv,
+            cliEntrypointPath,
+            'daemon',
+            '--root',
+            options.rootPath,
+            ...(options.debug ? ['--debug'] : []),
+        ],
+    });
+}
+async function startManagedDaemonWithPersistedSettings(options) {
+    const previousSettingsSnapshot = await loadManagedRuntimeSettingsSnapshot(options.rootPath);
+    await writeManagedRuntimeSettingsSnapshot(options.rootPath, options.desiredSettings.snapshot);
+    let child;
+    try {
+        child = await options.spawnDaemonProcess({
+            rootPath: options.rootPath,
+            debug: options.debug,
+            processEnv: options.processEnv,
+        });
+        child.unref();
+        await options.waitForDaemon(options.rootPath, options.sendRequest, child);
+    }
+    catch (error) {
+        if (child) {
+            await terminateChildProcessAndWait(child);
+        }
+        await restoreManagedRuntimeSettingsSnapshot(options.rootPath, previousSettingsSnapshot);
+        throw error;
+    }
+}
+async function recycleManagedDaemonWithDesiredSettings(options) {
+    const previousSettingsSnapshot = await loadManagedRuntimeSettingsSnapshot(options.rootPath);
+    await shutdownManagedDaemon(options.rootPath, options.sendRequest, options.waitForShutdown);
+    try {
+        await startManagedDaemonWithPersistedSettings({
+            rootPath: options.rootPath,
+            debug: options.debug,
+            processEnv: options.processEnv,
+            desiredSettings: options.desiredSettings,
+            spawnDaemonProcess: options.spawnDaemonProcess,
+            waitForDaemon: options.waitForDaemon,
+            sendRequest: options.sendRequest,
+        });
+    }
+    catch (error) {
+        if (!previousSettingsSnapshot) {
+            throw error;
+        }
+        try {
+            await writeManagedRuntimeSettingsSnapshot(options.rootPath, previousSettingsSnapshot);
+            await startManagedDaemonWithPersistedSettings({
+                rootPath: options.rootPath,
+                debug: options.debug,
+                processEnv: options.processEnv,
+                desiredSettings: {
+                    snapshot: previousSettingsSnapshot,
+                    fingerprint: createManagedRuntimeSettingsFingerprint(previousSettingsSnapshot),
+                    convergenceEnabled: previousSettingsSnapshot.compatibilityGates.includes(MANAGED_RUNTIME_CONVERGENCE_COMPATIBILITY_GATE),
+                },
+                spawnDaemonProcess: options.spawnDaemonProcess,
+                waitForDaemon: options.waitForDaemon,
+                sendRequest: options.sendRequest,
+            });
+        }
+        catch (rollbackError) {
+            throw combineManagedRollbackFailure(error, rollbackError);
+        }
+        throw error;
+    }
+}
+export async function bootstrapManagedDaemonStart(options, deps = {}) {
+    const effectiveProcessEnv = {
+        ...(options.processEnv ?? process.env),
+        ...options.env,
+    };
+    const loadSpec = deps.loadSpec
+        ?? ((hostConfigPath) => loadLocalConfigGenerateSpec(hostConfigPath, { env: effectiveProcessEnv }));
+    const materialize = deps.materialize ?? materializeLocalConfig;
+    const sendRequest = deps.sendRequest ?? sendManagedDaemonRequest;
+    const spawnDaemonProcess = deps.spawnDaemon ?? spawnManagedDaemonProcess;
+    const waitForDaemon = deps.waitForDaemonReady ?? waitForManagedDaemonReady;
+    const acquireLock = deps.acquireBootstrapLock ?? acquireBootstrapLock;
+    const waitForShutdown = deps.waitForShutdown
+        ?? (async (rootPath) => {
+            await waitForManagedDaemonShutdown(rootPath, canConnectToSocket);
+        });
+    const desiredSettings = resolveDesiredManagedRuntimeSettings(effectiveProcessEnv);
+    const resolvedManagedAgent = options.apiKey === undefined ? null : buildManagedLocalAgentConfig(options);
+    const resolved = resolvedManagedAgent ??
+        resolveManagedRuntimeLayoutForServerUrl(options.serverUrl, options.processEnv);
+    const releaseBootstrapLock = await acquireLock(resolved.rootPath);
+    try {
+        let statusResponse = await readReadyManagedDaemonStatus(resolved.rootPath, sendRequest);
+        if (statusResponse && getManagedRuntimeFingerprintMismatch(statusResponse, desiredSettings)) {
+            await recycleManagedDaemonWithDesiredSettings({
+                rootPath: resolved.rootPath,
+                debug: options.debug === true,
+                processEnv: effectiveProcessEnv,
+                desiredSettings,
+                sendRequest,
+                waitForShutdown,
+                spawnDaemonProcess,
+                waitForDaemon,
+            });
+            statusResponse = await readReadyManagedDaemonStatus(resolved.rootPath, sendRequest);
+        }
+        if (!statusResponse) {
+            if (options.apiKey === undefined) {
+                await ensurePersistedManagedAgentsExist(options.serverUrl, resolved.hostConfigPath, loadSpec);
+            }
+            else {
+                try {
+                    await loadSpec(resolved.hostConfigPath);
+                }
+                catch (error) {
+                    if (isNotFoundError(error)) {
+                        await materialize(resolved.rootPath, {
+                            host: { borgeeBaseUrl: resolved.borgeeBaseUrl },
+                            agents: [],
+                        });
+                    }
+                    else {
+                        throw error;
+                    }
+                }
+            }
+            await startManagedDaemonWithPersistedSettings({
+                rootPath: resolved.rootPath,
+                debug: options.debug === true,
+                processEnv: effectiveProcessEnv,
+                desiredSettings,
+                spawnDaemonProcess,
+                waitForDaemon,
+                sendRequest,
+            });
+            statusResponse = undefined;
+        }
+        if (options.apiKey === undefined) {
+            if (!statusResponse) {
+                await ensurePersistedManagedAgentsExist(options.serverUrl, resolved.hostConfigPath, loadSpec);
+            }
+            else {
+                assertManagedRuntimeBinding(statusResponse.borgeeBaseUrl, options.serverUrl);
+                if (statusResponse.agentCount === 0) {
+                    throw createMissingManagedAgentError(options.serverUrl);
+                }
+            }
+            return;
+        }
+        if (!resolvedManagedAgent) {
+            return;
+        }
+        const upsertResponse = await sendRequest(resolved.rootPath, {
+            type: 'upsertAgent',
+            borgeeBaseUrl: resolvedManagedAgent.borgeeBaseUrl,
+            agent: resolvedManagedAgent.agent,
+        });
+        if (!upsertResponse.ok) {
+            const managedError = getManagedErrorPayload(upsertResponse);
+            throw managedOperationError(managedError.code, managedError.message);
+        }
+    }
+    finally {
+        await releaseBootstrapLock();
+    }
+}
+function buildApplySpecSuccessResponse(hostConfigPath, logPath, spec) {
+    return {
+        ok: true,
+        type: 'applySpec',
+        hostConfigPath,
+        ...(logPath ? { logPath } : {}),
+        agentCount: spec.agents.length,
+        enabledAgentCount: countEnabledManagedAgents(spec.agents),
+    };
+}
+function assertManagedSupervisorConvergence(supervisor, previousSpec, nextSpec) {
+    const nextEnabledKeys = new Set(listEnabledManagedAgentKeys(nextSpec.agents));
+    const missingEnabledKeys = [...nextEnabledKeys]
+        .filter((key) => !supervisor.hasActiveAgent(key))
+        .sort();
+    const staleDisabledOrDeletedKeys = listEnabledManagedAgentKeys(previousSpec.agents)
+        .filter((key) => !nextEnabledKeys.has(key) && supervisor.hasActiveAgent(key))
+        .sort();
+    if (missingEnabledKeys.length === 0 && staleDisabledOrDeletedKeys.length === 0) {
+        return;
+    }
+    const parts = [];
+    if (missingEnabledKeys.length > 0) {
+        parts.push(`missing active enabled agents: ${missingEnabledKeys.join(', ')}`);
+    }
+    if (staleDisabledOrDeletedKeys.length > 0) {
+        parts.push(`stale active deleted/disabled agents: ${staleDisabledOrDeletedKeys.join(', ')}`);
+    }
+    throw managedOperationError('MANAGED_CONVERGENCE_FAILED', `Managed runtime did not converge exactly after reload (${parts.join('; ')})`);
+}
+async function clearManagedRuntime(rootPath) {
+    const normalizedRootPath = resolve(rootPath);
+    const lockPath = resolveManagedBootstrapLockPath(normalizedRootPath);
+    const entries = await fs.readdir(normalizedRootPath, { withFileTypes: true }).catch((error) => {
+        if (isNotFoundError(error)) {
+            return [];
+        }
+        throw error;
+    });
+    await Promise.all(entries.map(async (entry) => {
+        const entryPath = join(normalizedRootPath, entry.name);
+        if (entryPath === lockPath) {
+            return;
+        }
+        await fs.rm(entryPath, { recursive: true, force: true });
+    }));
+}
+function sendSignalToChildProcess(child, signal) {
+    if (typeof child.pid !== 'number' || child.pid <= 0) {
+        return false;
+    }
+    try {
+        process.kill(child.pid, signal);
+        return true;
+    }
+    catch (error) {
+        if (!isNodeErrorWithCode(error, 'ESRCH')) {
+            throw error;
+        }
+        return false;
+    }
+}
+function hasChildExited(child) {
+    return child.exitCode != null || child.signalCode != null;
+}
+async function waitForChildExit(child, timeoutMs) {
+    if (hasChildExited(child)) {
+        return true;
+    }
+    return new Promise((resolveWait) => {
+        const onExit = () => {
+            cleanup();
+            resolveWait(true);
+        };
+        const timer = setTimeout(() => {
+            cleanup();
+            resolveWait(false);
+        }, timeoutMs);
+        const cleanup = () => {
+            clearTimeout(timer);
+            child.off('exit', onExit);
+        };
+        child.once('exit', onExit);
+        if (hasChildExited(child)) {
+            cleanup();
+            resolveWait(true);
+        }
+    });
+}
+async function terminateChildProcessAndWait(child) {
+    if (hasChildExited(child)) {
+        return;
+    }
+    if (!sendSignalToChildProcess(child, 'SIGTERM')) {
+        return;
+    }
+    if (await waitForChildExit(child, DAEMON_EXIT_WAIT_MS)) {
+        return;
+    }
+    if (!sendSignalToChildProcess(child, 'SIGKILL')) {
+        return;
+    }
+    await waitForChildExit(child, DAEMON_FORCE_KILL_WAIT_MS);
+}
+async function rollbackManagedApplyFailure(rootPath, previousSpec, materialize, clearRuntimeImpl, applyError) {
+    const original = toManagedErrorPayload(applyError, 'MANAGED_RELOAD_FAILED');
+    try {
+        if (previousSpec) {
+            await materialize(rootPath, cloneLocalConfigGenerateSpec(previousSpec));
+        }
+        else {
+            await clearRuntimeImpl(rootPath);
+        }
+    }
+    catch (rollbackError) {
+        return toManagedErrorResponse(combineManagedRollbackFailure(applyError, rollbackError));
+    }
+    return {
+        ok: false,
+        error: original,
+    };
+}
+function assertManagedFullSetSpecHasAgents(spec, sourceLabel) {
+    if (spec.agents.length === 0) {
+        throw managedOperationError('MANAGED_SPEC_INVALID', `Invalid managed spec in ${sourceLabel}: full-set managed specs must include at least one agent`);
+    }
+}
+function validateApplyManagedInput(spec, serverUrl, env = process.env) {
+    const parsed = parseGenerateConfigSpec(spec, '<apply-managed>', env);
+    assertManagedSpecBinding(parsed, serverUrl);
+    assertManagedFullSetSpecHasAgents(parsed, '<apply-managed>');
+    return parsed;
+}
+function validateDaemonApplySpecInput(spec, serverUrl, env = process.env) {
+    try {
+        const parsed = parseGenerateConfigSpec(spec, '<managed-daemon applySpec>', env);
+        assertManagedSpecBinding(parsed, serverUrl);
+        assertManagedFullSetSpecHasAgents(parsed, '<managed-daemon applySpec>');
+        return parsed;
+    }
+    catch (error) {
+        if (isManagedOperationError(error)) {
+            throw error;
+        }
+        throw managedOperationError('MANAGED_SPEC_INVALID', toErrorMessage(error));
+    }
+}
+function validateDaemonUpsertAgentInput(currentSpec, serverUrl, agent, env = process.env) {
+    try {
+        assertManagedRuntimeBinding(currentSpec.host.borgeeBaseUrl, serverUrl);
+        return parseGenerateConfigSpec({
+            host: cloneLocalHostGenerateConfig(currentSpec.host),
+            agents: [agent],
+        }, '<managed-daemon upsertAgent>', env).agents[0];
+    }
+    catch (error) {
+        if (isManagedOperationError(error)) {
+            throw error;
+        }
+        throw managedOperationError('MANAGED_SPEC_INVALID', toErrorMessage(error));
+    }
+}
+export async function describeManagedSpec(options, deps = {}) {
+    const effectiveProcessEnv = options.processEnv ?? process.env;
+    const loadSpec = deps.loadSpec
+        ?? ((hostConfigPath) => loadLocalConfigGenerateSpec(hostConfigPath, { env: effectiveProcessEnv }));
+    const sendRequest = deps.sendRequest ?? sendManagedDaemonRequest;
+    const resolved = resolveManagedRuntimeLayoutForServerUrl(options.serverUrl, options.processEnv);
+    try {
+        const response = await sendRequest(resolved.rootPath, {
+            type: 'describeSpec',
+            borgeeBaseUrl: resolved.borgeeBaseUrl,
+        });
+        if (response.ok && response.type === 'describeSpec') {
+            return response.present && response.spec
+                ? { ok: true, present: true, spec: response.spec }
+                : { ok: true, present: false };
+        }
+        if (isManagedErrorResponse(response)) {
+            return normalizeManagedErrorResponse(response);
+        }
+        throw new Error('Unexpected managed daemon response for describeSpec');
+    }
+    catch (error) {
+        if (!isManagedDaemonConnectionError(error)) {
+            if (isExpectedManagedFailure(error)) {
+                return toManagedErrorResponse(error);
+            }
+            throw error;
+        }
+    }
+    try {
+        const persistedSpec = await loadManagedSpecOrUndefined(resolved.hostConfigPath, loadSpec);
+        if (!persistedSpec) {
+            return { ok: true, present: false };
+        }
+        assertManagedSpecBinding(persistedSpec, options.serverUrl);
+        return {
+            ok: true,
+            present: true,
+            spec: persistedSpec,
+        };
+    }
+    catch (error) {
+        if (isExpectedManagedFailure(error)) {
+            return toManagedErrorResponse(error);
+        }
+        throw error;
+    }
+}
+async function applySpecToRunningManagedDaemon(rootPath, borgeeBaseUrl, spec, sendRequest) {
+    const response = await sendRequest(rootPath, {
+        type: 'applySpec',
+        borgeeBaseUrl,
+        spec: cloneLocalConfigGenerateSpec(spec),
+    });
+    if (!response.ok) {
+        return normalizeManagedErrorResponse(response);
+    }
+    if (response.type !== 'applySpec') {
+        throw new Error('Unexpected managed daemon response for applySpec');
+    }
+    return {
+        ok: true,
+        daemon: 'reused',
+        agentCount: response.agentCount,
+        enabledAgentCount: response.enabledAgentCount,
+        ...(response.logPath ? { logPath: response.logPath } : {}),
+    };
+}
+export async function applyManagedSpec(options, deps = {}) {
+    const effectiveProcessEnv = options.processEnv ?? process.env;
+    const loadSpec = deps.loadSpec
+        ?? ((hostConfigPath) => loadLocalConfigGenerateSpec(hostConfigPath, { env: effectiveProcessEnv }));
+    const materialize = deps.materialize
+        ?? ((rootPath, spec) => materializeLocalConfig(rootPath, spec, { env: effectiveProcessEnv }));
+    const sendRequest = deps.sendRequest ?? sendManagedDaemonRequest;
+    const spawnDaemonProcess = deps.spawnDaemon ?? spawnManagedDaemonProcess;
+    const waitForDaemon = deps.waitForDaemonReady ?? waitForManagedDaemonReady;
+    const acquireLock = deps.acquireBootstrapLock ?? acquireBootstrapLock;
+    const clearManagedRuntimeImpl = deps.clearManagedRuntime ?? clearManagedRuntime;
+    const resolved = resolveManagedRuntimeLayoutForServerUrl(options.serverUrl, options.processEnv);
+    let spec;
+    try {
+        spec = validateApplyManagedInput(options.spec, options.serverUrl, effectiveProcessEnv);
+    }
+    catch (error) {
+        if (isManagedOperationError(error)) {
+            return toManagedErrorResponse(error);
+        }
+        return toManagedErrorResponse(managedOperationError('MANAGED_SPEC_INVALID', `Invalid managed spec: ${toErrorMessage(error)}`));
+    }
+    const desiredSettings = resolveDesiredManagedRuntimeSettings(effectiveProcessEnv);
+    const waitForShutdown = deps.waitForShutdown
+        ?? (async (rootPath) => {
+            await waitForManagedDaemonShutdown(rootPath, canConnectToSocket);
+        });
+    let releaseBootstrapLock;
+    try {
+        releaseBootstrapLock = await acquireLock(resolved.rootPath);
+    }
+    catch (error) {
+        return toApplyManagedColdStartErrorResponse(error);
+    }
+    try {
+        let statusResponse;
+        try {
+            statusResponse = await readReadyManagedDaemonStatus(resolved.rootPath, sendRequest);
+        }
+        catch (error) {
+            if (isExpectedManagedFailure(error)) {
+                return toManagedErrorResponse(error);
+            }
+            throw error;
+        }
+        if (statusResponse && getManagedRuntimeFingerprintMismatch(statusResponse, desiredSettings)) {
+            try {
+                await recycleManagedDaemonWithDesiredSettings({
+                    rootPath: resolved.rootPath,
+                    debug: options.debug === true,
+                    processEnv: effectiveProcessEnv,
+                    desiredSettings,
+                    sendRequest,
+                    waitForShutdown,
+                    spawnDaemonProcess,
+                    waitForDaemon,
+                });
+            }
+            catch (error) {
+                return toManagedErrorResponse(error);
+            }
+            statusResponse = await readReadyManagedDaemonStatus(resolved.rootPath, sendRequest);
+        }
+        if (statusResponse) {
+            return applySpecToRunningManagedDaemon(resolved.rootPath, resolved.borgeeBaseUrl, spec, sendRequest);
+        }
+        let previousSpec;
+        try {
+            previousSpec = await loadManagedSpecOrUndefined(resolved.hostConfigPath, loadSpec);
+            if (previousSpec) {
+                assertManagedSpecBinding(previousSpec, options.serverUrl);
+            }
+        }
+        catch (error) {
+            return toApplyManagedColdStartErrorResponse(error);
+        }
+        try {
+            await materialize(resolved.rootPath, cloneLocalConfigGenerateSpec(spec));
+        }
+        catch (error) {
+            return rollbackManagedApplyFailure(resolved.rootPath, previousSpec, materialize, clearManagedRuntimeImpl, error);
+        }
+        try {
+            await startManagedDaemonWithPersistedSettings({
+                rootPath: resolved.rootPath,
+                debug: options.debug === true,
+                processEnv: effectiveProcessEnv,
+                desiredSettings,
+                spawnDaemonProcess,
+                waitForDaemon,
+                sendRequest,
+            });
+            const status = await sendRequest(resolved.rootPath, { type: 'status' });
+            if (!status.ok) {
+                const managedError = getManagedErrorPayload(status);
+                return rollbackManagedApplyFailure(resolved.rootPath, previousSpec, materialize, clearManagedRuntimeImpl, managedOperationError(managedError.code, managedError.message));
+            }
+            if (status.type !== 'status') {
+                throw new Error('Unexpected managed daemon response for status');
+            }
+            return {
+                ok: true,
+                daemon: 'started',
+                agentCount: status.agentCount,
+                enabledAgentCount: status.enabledAgentCount,
+                ...(status.logPath ? { logPath: status.logPath } : {}),
+            };
+        }
+        catch (error) {
+            return rollbackManagedApplyFailure(resolved.rootPath, previousSpec, materialize, clearManagedRuntimeImpl, error);
+        }
+    }
+    finally {
+        await releaseBootstrapLock?.();
+    }
+}
+export class ManagedAgentsHostDaemon {
+    rootPath;
+    hostConfigPath;
+    socketPath;
+    createSupervisor;
+    supervisor;
+    loadSpec;
+    materialize;
+    managedRuntimeFingerprint;
+    logger;
+    logPath;
+    server;
+    requestQueue = Promise.resolve();
+    started = false;
+    ready = false;
+    ownsSocket = false;
+    shutdownRequested = false;
+    ownedSocketInode = null;
+    constructor(rootPath, debug = false, deps = {}) {
+        const layout = resolveLocalConfigLayout(rootPath);
+        this.rootPath = layout.root;
+        this.hostConfigPath = layout.hostConfigPath;
+        this.socketPath = resolveManagedDaemonSocketPath(this.rootPath);
+        this.createSupervisor =
+            deps.createSupervisor ??
+                ((configPath, daemonDebug) => new AgentsHostSupervisor(configPath, { debug: daemonDebug }));
+        this.loadSpec = deps.loadSpec ?? loadLocalConfigGenerateSpec;
+        this.materialize = deps.materialize ?? materializeLocalConfig;
+        const managedRuntimeSettings = resolveDesiredManagedRuntimeSettings(process.env);
+        this.managedRuntimeFingerprint = managedRuntimeSettings.convergenceEnabled
+            ? managedRuntimeSettings.fingerprint
+            : null;
+        this.logger = deps.logger ?? console;
+        this.logPath = deps.logPath ?? null;
+        this.server = createServer((socket) => {
+            void this.handleSocket(socket);
+        });
+        this.server.on('error', (error) => {
+            this.logger.error('[agents-host] managed daemon control socket error', {
+                rootPath: this.rootPath,
+                error,
+            });
+        });
+        this.supervisor = this.createSupervisor(this.hostConfigPath, debug);
+    }
+    async start() {
+        if (this.started) {
+            return;
+        }
+        this.started = true;
+        this.ready = false;
+        await ensureDirectory(this.rootPath, MANAGED_ROOT_MODE);
+        try {
+            await this.listen();
+            await this.supervisor.start();
+            this.ready = true;
+            this.logger.log('[agents-host] managed daemon ready', {
+                rootPath: this.rootPath,
+                hostConfigPath: this.hostConfigPath,
+                socketPath: this.socketPath,
+            });
+        }
+        catch (error) {
+            this.started = false;
+            this.ready = false;
+            await this.stop().catch(() => undefined);
+            throw error;
+        }
+    }
+    async stop() {
+        this.ready = false;
+        try {
+            await this.supervisor.stop();
+        }
+        finally {
+            await new Promise((resolveStop) => {
+                if (!this.server.listening) {
+                    resolveStop();
+                    return;
+                }
+                this.server.close(() => resolveStop());
+            });
+            if (this.ownsSocket) {
+                const socketStats = await fs.lstat(this.socketPath).catch(() => undefined);
+                if (socketStats && socketStats.ino === this.ownedSocketInode) {
+                    await fs.rm(this.socketPath, { force: true }).catch(() => undefined);
+                }
+                this.ownsSocket = false;
+                this.ownedSocketInode = null;
+            }
+            this.started = false;
+            this.shutdownRequested = false;
+        }
+    }
+    async listen() {
+        for (let attempt = 0; attempt < 2; attempt++) {
+            try {
+                await new Promise((resolveListen, rejectListen) => {
+                    const onError = (error) => {
+                        this.server.off('listening', onListening);
+                        rejectListen(error);
+                    };
+                    const onListening = () => {
+                        this.server.off('error', onError);
+                        resolveListen();
+                    };
+                    this.server.once('error', onError);
+                    this.server.once('listening', onListening);
+                    this.server.listen(this.socketPath);
+                });
+                await fs.chmod(this.socketPath, MANAGED_CONFIG_MODE);
+                this.ownedSocketInode = (await fs.lstat(this.socketPath)).ino;
+                this.ownsSocket = true;
+                return;
+            }
+            catch (error) {
+                if (!isSocketBusyError(error) || !(await removeStaleControlSocket(this.socketPath))) {
+                    throw error;
+                }
+            }
+        }
+        throw new Error(`Unable to bind managed daemon control socket: ${this.socketPath}`);
+    }
+    async handleSocket(socket) {
+        let buffer = '';
+        socket.setEncoding('utf8');
+        socket.on('data', (chunk) => {
+            buffer += chunk;
+            const newlineIndex = buffer.indexOf('\n');
+            if (newlineIndex === -1) {
+                return;
+            }
+            const rawRequest = buffer.slice(0, newlineIndex);
+            void this.respond(socket, rawRequest);
+            buffer = '';
+        });
+        socket.on('error', (error) => {
+            this.logger.error('[agents-host] managed daemon client socket error', {
+                rootPath: this.rootPath,
+                error,
+            });
+        });
+    }
+    async respond(socket, rawRequest) {
+        try {
+            const request = parseDaemonRequest(rawRequest);
+            const response = await this.handleRequest(request);
+            if (request.type === 'shutdown') {
+                socket.end(`${JSON.stringify(response)}\n`, () => {
+                    if (this.shutdownRequested) {
+                        return;
+                    }
+                    this.shutdownRequested = true;
+                    void this.stop().catch((error) => {
+                        this.logger.error('[agents-host] managed daemon shutdown failed', {
+                            rootPath: this.rootPath,
+                            error,
+                        });
+                    });
+                });
+                return;
+            }
+            socket.end(`${JSON.stringify(response)}\n`);
+        }
+        catch (error) {
+            socket.end(`${JSON.stringify(toManagedErrorResponse(error, 'MANAGED_RELOAD_FAILED'))}\n`);
+        }
+    }
+    async handleRequest(request) {
+        if (request.type === 'shutdown') {
+            return { ok: true, type: 'shutdown' };
+        }
+        if (!this.ready) {
+            return toManagedErrorResponse(managedOperationError('MANAGED_DAEMON_NOT_READY', MANAGED_DAEMON_NOT_READY_MESSAGE));
+        }
+        if (request.type === 'status') {
+            const spec = ensureCurrentManagedSpec(await loadManagedSpecOrUndefined(this.hostConfigPath, this.loadSpec));
+            return {
+                ok: true,
+                type: 'status',
+                borgeeBaseUrl: spec.host.borgeeBaseUrl,
+                hostConfigPath: this.hostConfigPath,
+                ...(this.logPath ? { logPath: this.logPath } : {}),
+                agentCount: spec.agents.length,
+                enabledAgentCount: countEnabledManagedAgents(spec.agents),
+                ...(this.managedRuntimeFingerprint
+                    ? { managedRuntimeFingerprint: this.managedRuntimeFingerprint }
+                    : {}),
+            };
+        }
+        if (request.type === 'describeSpec') {
+            const spec = await loadManagedSpecOrUndefined(this.hostConfigPath, this.loadSpec);
+            if (spec) {
+                assertManagedRuntimeBinding(spec.host.borgeeBaseUrl, request.borgeeBaseUrl);
+            }
+            return buildDescribeSpecResponse(spec);
+        }
+        if (request.type === 'upsertAgent') {
+            return this.enqueue(async () => {
+                const currentSpec = ensureCurrentManagedSpec(await loadManagedSpecOrUndefined(this.hostConfigPath, this.loadSpec));
+                const validatedAgent = validateDaemonUpsertAgentInput(currentSpec, request.borgeeBaseUrl, request.agent, process.env);
+                const agentsByKey = new Map(currentSpec.agents.map((agent) => [agent.key, cloneLocalAgentConfig(agent)]));
+                agentsByKey.set(validatedAgent.key, cloneLocalAgentConfig(validatedAgent));
+                const nextSpec = {
+                    host: cloneLocalHostGenerateConfig(currentSpec.host),
+                    agents: [...agentsByKey.values()].sort((left, right) => left.key.localeCompare(right.key)),
+                };
+                await this.publishSpecWithRollback(currentSpec, nextSpec, () => `Managed daemon reconcile finished without starting agent ${validatedAgent.key}`);
+                return {
+                    ok: true,
+                    type: 'upsertAgent',
+                    agentKey: validatedAgent.key,
+                    hostConfigPath: this.hostConfigPath,
+                    ...(this.logPath ? { logPath: this.logPath } : {}),
+                    agentCount: nextSpec.agents.length,
+                };
+            });
+        }
+        if (request.type === 'applySpec') {
+            return this.enqueue(async () => {
+                const currentSpec = ensureCurrentManagedSpec(await loadManagedSpecOrUndefined(this.hostConfigPath, this.loadSpec));
+                assertManagedRuntimeBinding(currentSpec.host.borgeeBaseUrl, request.borgeeBaseUrl);
+                const nextSpec = validateDaemonApplySpecInput(request.spec, request.borgeeBaseUrl, process.env);
+                await this.publishSpecWithRollback(currentSpec, nextSpec);
+                return buildApplySpecSuccessResponse(this.hostConfigPath, this.logPath, nextSpec);
+            });
+        }
+        throw managedOperationError('MANAGED_SPEC_INVALID', 'Unsupported managed daemon request');
+    }
+    async enqueue(operation) {
+        const next = this.requestQueue.then(operation, operation);
+        this.requestQueue = next.then(() => undefined, () => undefined);
+        return next;
+    }
+    async publishSpecWithRollback(previousSpec, nextSpec, convergenceMessage) {
+        let publishedNextSpec = false;
+        try {
+            await this.materialize(this.rootPath, cloneLocalConfigGenerateSpec(nextSpec));
+            publishedNextSpec = true;
+            try {
+                await this.supervisor.reloadNow(true);
+            }
+            catch (error) {
+                throw managedOperationError('MANAGED_RELOAD_FAILED', `Managed daemon reload failed: ${toErrorMessage(error)}`);
+            }
+            try {
+                assertManagedSupervisorConvergence(this.supervisor, previousSpec, nextSpec);
+            }
+            catch (error) {
+                if (convergenceMessage &&
+                    isManagedOperationError(error) &&
+                    error.code === 'MANAGED_CONVERGENCE_FAILED') {
+                    throw managedOperationError('MANAGED_CONVERGENCE_FAILED', convergenceMessage());
+                }
+                throw error;
+            }
+        }
+        catch (error) {
+            if (!publishedNextSpec) {
+                throw error;
+            }
+            try {
+                await this.materialize(this.rootPath, cloneLocalConfigGenerateSpec(previousSpec));
+                try {
+                    await this.supervisor.reloadNow(true);
+                }
+                catch (rollbackReloadError) {
+                    throw managedOperationError('MANAGED_RELOAD_FAILED', `Managed daemon rollback reload failed: ${toErrorMessage(rollbackReloadError)}`);
+                }
+                assertManagedSupervisorConvergence(this.supervisor, nextSpec, previousSpec);
+            }
+            catch (rollbackError) {
+                throw combineManagedRollbackFailure(error, rollbackError);
+            }
+            throw error;
+        }
+    }
+}