@borgee/agents-host 0.2.28 → 0.2.29

package/README.md

@@ -54,6 +54,7 @@ agents-host start-managed <serverUrl> <apiKey> [agent-options]
 agents-host describe-managed <serverUrl>
 agents-host apply-managed <serverUrl> --stdin
 agents-host apply-managed <serverUrl> --spec-json <json>
+agents-host cleanup-managed <serverUrl> [--purge]
 agents-host log <serverUrl> [--lines <n>] [--follow]
 agents-host log <serverUrl> --path
 agents-host start --config <path-to-host-config> [--debug]
@@ -77,7 +78,28 @@ RUNTIME_PROVIDER=claude \
 pnpm --filter @borgee/agents-host dev
 ```
 
-Codex remains opt-in. Select `RUNTIME_PROVIDER=codex` only when `AGENTS_HOST_INTERNAL_COMPATIBILITY_GATES` includes `codex-provider`.
+Codex now ships on the same default hosted-provider surface as Claude and Copilot. Select `RUNTIME_PROVIDER=codex` directly unless you are explicitly rolling that path back with `AGENTS_HOST_INTERNAL_DISABLED_COMPATIBILITY_GATES=codex-provider`.
+
+### Shipped internal compatibility defaults and rollback controls
+
+The current shipped internal compatibility surface resolves gates in this order:
+
+1. start from the shipped defaults: `claude-provider-v2`, `copilot-provider-v2`, `codex-provider`, `managed-runtime-convergence`, and `policy-audit-enforcement`
+2. add any explicit entries from `AGENTS_HOST_INTERNAL_COMPATIBILITY_GATES`
+3. subtract any explicit entries from `AGENTS_HOST_INTERNAL_DISABLED_COMPATIBILITY_GATES`
+
+The shipped default set now also includes `connections-state-layer`, `context-injection`, `skill-runtime`, `localhost-gateway`, `token-binding`, `collaboration-outcome-model`, `task-thread-collaboration-contract`, and `collaboration-capabilities-diagnostics`. `attention-follow-semantics`, `collaboration-skill-first`, and hosted `praestoclaw-provider` still remain opt-in.
+
+Managed-runtime settings still preserve the managed rollback rule for `connections-state-layer` plus `token-binding`: when `managed-runtime-convergence` remains enabled, the managed surface forces that pair on; explicitly disabling `managed-runtime-convergence` removes that pair from the managed surface again unless you also explicitly re-enable them.
+
+Managed runtime precedence stays intentional: detached daemon respawns always reuse the persisted `managed-runtime-settings.json` snapshot, bare `start-managed <serverUrl>` and `apply-managed` treat the caller's current env as an explicit request to update that managed runtime surface, and full `start-managed <serverUrl> <apiKey> ...` validates the agent upsert against the existing managed-root snapshot before ambient rollback env can reject an otherwise valid existing surface.
+Legacy managed roots created before `managed-runtime-settings.json` existed need one bare `agents-host start-managed <serverUrl>` migration pass before full per-agent updates can rely on that snapshot-backed precedence.
+
+Rollback and hardening controls stay explicit:
+
+- `AGENTS_HOST_INTERNAL_DISABLED_COMPATIBILITY_GATES=<comma-list>` disables shipped gates for rollback
+- `AGENTS_HOST_INTERNAL_PROVIDER_IMPLEMENTATIONS=claude:v1,copilot:v1` forces Claude and/or Copilot back to the v1 adapters while their v2 gates stay enabled
+- `AGENTS_HOST_INTERNAL_POLICY_MODE=enforce` hardens the shipped `policy-audit-enforcement` gate beyond its default `audit-only` mode
 
 Or with the CLI:
 
@@ -117,6 +139,7 @@ and resumable in that case.
 Each managed runtime root keeps:
 
 - `agents-host.yaml` and `agents/` as the stable generated local-config entrypoints
+- `managed-runtime-settings.json` as the persisted managed runtime surface snapshot
 - `daemon.log` as the detached managed daemon stdout/stderr log file
 - `.state/` as the per-agent runtime state base
 - `ctl.sock` as the local control socket
@@ -210,8 +233,8 @@ Notes:
 | `BORGEE_AGENT_API_KEY`             | positional `<apiKey>`                  | yes      | —                                             | Agent API key from the web UI                                                                    |
 | `AGENTS_HOST_DEBUG`                | `--debug`                              | no       | off                                           | Extra host/provider lifecycle logs. Set `AGENTS_HOST_DEBUG=1` to enable without the CLI flag.   |
 | `BORGEE_AGENT_NAME`                | `--name`                               | no       | `Assistant`                                   | Display name used in prompts                                                                     |
-| `RUNTIME_PROVIDER`                 | `--provider`                           | no       | `claude`                                      | `claude`, `copilot`, or `codex` when `codex-provider` is enabled                                 |
-| `CLAUDE_COMMAND` / `CLAUDE_ARGS`   | `--claude-command` / `--claude-args`   | no       | `claude` / `--print`                          | Local Claude CLI command + args                                                                  |
+| `RUNTIME_PROVIDER`                 | `--provider`                           | no       | `claude`                                      | `claude`, `copilot`, or `codex`                                                                  |
+| `CLAUDE_COMMAND` / `CLAUDE_ARGS`   | `--claude-command` / `--claude-args`   | no       | `claude` / `--print --permission-mode bypassPermissions` | Local Claude CLI command + args                                                                  |
 | `CODEX_COMMAND` / `CODEX_ARGS`     | `--codex-command` / `--codex-args`     | no       | `codex-acp` / empty                           | Local Codex ACP adapter command + args. The default launch resolves the bundled `@agentclientprotocol/codex-acp` entrypoint. |
 | `COPILOT_COMMAND` / `COPILOT_ARGS` | `--copilot-command` / `--copilot-args` | no       | `copilot` / parsed but ignored by ACP runtime | Local Copilot CLI command. The persistent Copilot ACP prototype always launches `copilot --acp`. |
 | `COPILOT_SESSION_TTL_MINUTES`      | `--copilot-session-ttl-minutes`        | no       | `2880`                                        | Idle TTL for per-channel Copilot ACP sessions                                                    |
@@ -414,7 +437,7 @@ Agent config fields:
 - `key` (**required**): stable identity used for diffing and reload decisions
 - `name` (**required**)
 - `apiKey` (**required**)
-- `provider` (**required**): `claude`, `copilot`, or gated `codex`
+- `provider` (**required**): `claude`, `copilot`, or `codex` (roll back Codex only with `AGENTS_HOST_INTERNAL_DISABLED_COMPATIBILITY_GATES=codex-provider`)
 - `enabled` (optional, default `true`)
 - optional overrides for `claudeCommand`, `claudeArgs`, `codexCommand`,
   `codexArgs`, `copilotCommand`, `copilotArgs`, and

package/dist/compatibility-gates.d.ts

@@ -14,6 +14,7 @@ export declare const TOKEN_BINDING_COMPATIBILITY_GATE = "token-binding";
 export declare const POLICY_AUDIT_ENFORCEMENT_COMPATIBILITY_GATE = "policy-audit-enforcement";
 export declare const MANAGED_RUNTIME_CONVERGENCE_COMPATIBILITY_GATE = "managed-runtime-convergence";
 export declare const COMPATIBILITY_GATES_ENV = "AGENTS_HOST_INTERNAL_COMPATIBILITY_GATES";
+export declare const INTERNAL_DISABLED_COMPATIBILITY_GATES_ENV = "AGENTS_HOST_INTERNAL_DISABLED_COMPATIBILITY_GATES";
 export declare const INTERNAL_POLICY_MODE_ENV = "AGENTS_HOST_INTERNAL_POLICY_MODE";
 export declare const INTERNAL_PROVIDER_IMPLEMENTATIONS_ENV = "AGENTS_HOST_INTERNAL_PROVIDER_IMPLEMENTATIONS";
 export declare const MANAGED_RUNTIME_SETTINGS_SCHEMA_VERSION = 1;
@@ -27,8 +28,10 @@ export interface ManagedRuntimeSettingsSnapshot {
     providerImplementationOverrides: string[];
     internalPolicyMode: InternalPolicyMode;
 }
+export declare const DEFAULT_INTERNAL_COMPATIBILITY_GATES: readonly string[];
 export declare function parseCompatibilityGates(rawValue: string | undefined): ReadonlySet<string>;
-export declare function resolveInternalCompatibilityGates(): ReadonlySet<string>;
+export declare function resolveInternalCompatibilityGates(env?: NodeJS.ProcessEnv): ReadonlySet<string>;
+export declare function resolveDisabledDefaultCompatibilityGates(compatibilityGates: Iterable<string>): string[];
 export declare function normalizeInternalProviderImplementationOverrides(rawValue: string | undefined): string[];
 export declare function parseInternalProviderImplementationOverrides(rawValue: string | undefined): InternalProviderImplementationOverrides;
 export declare function resolveManagedRuntimeProviderImplementationOverrides(env?: NodeJS.ProcessEnv, compatibilityGates?: string[]): string[];

package/dist/compatibility-gates.js

@@ -15,10 +15,26 @@ export const TOKEN_BINDING_COMPATIBILITY_GATE = 'token-binding';
 export const POLICY_AUDIT_ENFORCEMENT_COMPATIBILITY_GATE = 'policy-audit-enforcement';
 export const MANAGED_RUNTIME_CONVERGENCE_COMPATIBILITY_GATE = 'managed-runtime-convergence';
 export const COMPATIBILITY_GATES_ENV = 'AGENTS_HOST_INTERNAL_COMPATIBILITY_GATES';
+export const INTERNAL_DISABLED_COMPATIBILITY_GATES_ENV = 'AGENTS_HOST_INTERNAL_DISABLED_COMPATIBILITY_GATES';
 export const INTERNAL_POLICY_MODE_ENV = 'AGENTS_HOST_INTERNAL_POLICY_MODE';
 export const INTERNAL_PROVIDER_IMPLEMENTATIONS_ENV = 'AGENTS_HOST_INTERNAL_PROVIDER_IMPLEMENTATIONS';
 export const MANAGED_RUNTIME_SETTINGS_SCHEMA_VERSION = 1;
 const VALID_PROVIDER_IMPLEMENTATION_ENTRIES = '"claude:v1", "claude:v2", "copilot:v1", or "copilot:v2"';
+export const DEFAULT_INTERNAL_COMPATIBILITY_GATES = Object.freeze([
+    CLAUDE_PROVIDER_V2_COMPATIBILITY_GATE,
+    COLLABORATION_CAPABILITIES_DIAGNOSTICS_COMPATIBILITY_GATE,
+    COLLABORATION_OUTCOME_MODEL_COMPATIBILITY_GATE,
+    CONNECTIONS_STATE_LAYER_COMPATIBILITY_GATE,
+    CONTEXT_INJECTION_COMPATIBILITY_GATE,
+    CODEX_PROVIDER_COMPATIBILITY_GATE,
+    COPILOT_PROVIDER_V2_COMPATIBILITY_GATE,
+    LOCALHOST_GATEWAY_COMPATIBILITY_GATE,
+    MANAGED_RUNTIME_CONVERGENCE_COMPATIBILITY_GATE,
+    POLICY_AUDIT_ENFORCEMENT_COMPATIBILITY_GATE,
+    SKILL_RUNTIME_COMPATIBILITY_GATE,
+    TASK_THREAD_COLLABORATION_CONTRACT_COMPATIBILITY_GATE,
+    TOKEN_BINDING_COMPATIBILITY_GATE,
+]);
 const PROVIDER_IMPLEMENTATION_COMPATIBILITY_GATES = {
     claude: CLAUDE_PROVIDER_V2_COMPATIBILITY_GATE,
     copilot: COPILOT_PROVIDER_V2_COMPATIBILITY_GATE,
@@ -50,8 +66,19 @@ export function parseCompatibilityGates(rawValue) {
     }
     return gates;
 }
-export function resolveInternalCompatibilityGates() {
-    return parseCompatibilityGates(process.env[COMPATIBILITY_GATES_ENV]);
+export function resolveInternalCompatibilityGates(env = process.env) {
+    const compatibilityGates = new Set(DEFAULT_INTERNAL_COMPATIBILITY_GATES);
+    for (const gate of parseCompatibilityGates(env[COMPATIBILITY_GATES_ENV])) {
+        compatibilityGates.add(gate);
+    }
+    for (const gate of parseCompatibilityGates(env[INTERNAL_DISABLED_COMPATIBILITY_GATES_ENV])) {
+        compatibilityGates.delete(gate);
+    }
+    return compatibilityGates;
+}
+export function resolveDisabledDefaultCompatibilityGates(compatibilityGates) {
+    const enabledGates = new Set(compatibilityGates);
+    return DEFAULT_INTERNAL_COMPATIBILITY_GATES.filter((gate) => !enabledGates.has(gate));
 }
 export function normalizeInternalProviderImplementationOverrides(rawValue) {
     if (!rawValue || rawValue.trim().length === 0) {
@@ -95,11 +122,20 @@ export function resolveManagedRuntimeProviderImplementationOverrides(env = proce
     });
 }
 export function resolveManagedRuntimeCompatibilityGates(env = process.env) {
-    const compatibilityGates = new Set(parseCompatibilityGates(env[COMPATIBILITY_GATES_ENV]));
+    const compatibilityGates = new Set(resolveInternalCompatibilityGates(env));
+    const explicitlyEnabledGates = parseCompatibilityGates(env[COMPATIBILITY_GATES_ENV]);
     if (compatibilityGates.has(MANAGED_RUNTIME_CONVERGENCE_COMPATIBILITY_GATE)) {
         compatibilityGates.add(CONNECTIONS_STATE_LAYER_COMPATIBILITY_GATE);
         compatibilityGates.add(TOKEN_BINDING_COMPATIBILITY_GATE);
     }
+    else {
+        if (!explicitlyEnabledGates.has(CONNECTIONS_STATE_LAYER_COMPATIBILITY_GATE)) {
+            compatibilityGates.delete(CONNECTIONS_STATE_LAYER_COMPATIBILITY_GATE);
+        }
+        if (!explicitlyEnabledGates.has(TOKEN_BINDING_COMPATIBILITY_GATE)) {
+            compatibilityGates.delete(TOKEN_BINDING_COMPATIBILITY_GATE);
+        }
+    }
     return sortUniqueStrings(compatibilityGates);
 }
 export function resolveInternalPolicyMode(gateEnabled, env = process.env) {

package/dist/config.js

@@ -1,5 +1,5 @@
 import { resolveSingleAgentStateRoot } from './state-paths.js';
-import { CODEX_PROVIDER_COMPATIBILITY_GATE, COMPATIBILITY_GATES_ENV, parseCompatibilityGates, } from './compatibility-gates.js';
+import { CODEX_PROVIDER_COMPATIBILITY_GATE, resolveInternalCompatibilityGates, } from './compatibility-gates.js';
 const MAX_TIMER_DELAY_MS = 2_147_483_647;
 export const MAX_COPILOT_SESSION_TTL_MINUTES = MAX_TIMER_DELAY_MS / 60_000;
 export const DEFAULT_COPILOT_SESSION_TTL_MINUTES = 2 * 24 * 60;
@@ -69,9 +69,9 @@ export function assertProviderCompatibility(provider, sourceLabel, env = process
     if (provider !== 'codex') {
         return;
     }
-    const compatibilityGates = parseCompatibilityGates(env[COMPATIBILITY_GATES_ENV]);
+    const compatibilityGates = resolveInternalCompatibilityGates(env);
     if (!compatibilityGates.has(CODEX_PROVIDER_COMPATIBILITY_GATE)) {
-        throw new Error(`${sourceLabel}: provider "codex" requires ${COMPATIBILITY_GATES_ENV} to include ${CODEX_PROVIDER_COMPATIBILITY_GATE}`);
+        throw new Error(`${sourceLabel}: provider "codex" requires the shipped ${CODEX_PROVIDER_COMPATIBILITY_GATE} path to remain enabled`);
     }
 }
 export function resolveProviderCommandConfig(overrides = {}) {

package/dist/managed-daemon.js

@@ -5,7 +5,7 @@ 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 { COMPATIBILITY_GATES_ENV, createManagedRuntimeSettingsFingerprint, INTERNAL_DISABLED_COMPATIBILITY_GATES_ENV, INTERNAL_POLICY_MODE_ENV, INTERNAL_PROVIDER_IMPLEMENTATIONS_ENV, MANAGED_RUNTIME_CONVERGENCE_COMPATIBILITY_GATE, MANAGED_RUNTIME_SETTINGS_SCHEMA_VERSION, resolveDisabledDefaultCompatibilityGates, 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';
@@ -222,15 +222,45 @@ function buildManagedRuntimeSettingsEnv(baseEnv, snapshot) {
     return {
         ...baseEnv,
         [COMPATIBILITY_GATES_ENV]: snapshot.compatibilityGates.join(','),
+        [INTERNAL_DISABLED_COMPATIBILITY_GATES_ENV]: resolveDisabledDefaultCompatibilityGates(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;
+function buildDesiredManagedRuntimeSettingsFromSnapshot(snapshot) {
+    return {
+        snapshot,
+        fingerprint: createManagedRuntimeSettingsFingerprint(snapshot),
+        convergenceEnabled: snapshot.compatibilityGates.includes(MANAGED_RUNTIME_CONVERGENCE_COMPATIBILITY_GATE),
+    };
+}
+async function getManagedRuntimeFingerprintMismatch(rootPath, status, desiredSettings) {
+    if (status.managedRuntimeFingerprint != null) {
+        return status.managedRuntimeFingerprint !== desiredSettings.fingerprint;
+    }
+    if (desiredSettings.convergenceEnabled) {
+        return true;
+    }
+    const persistedSettingsSnapshot = await loadManagedRuntimeSettingsSnapshot(rootPath);
+    if (!persistedSettingsSnapshot) {
+        return true;
+    }
+    return createManagedRuntimeSettingsFingerprint(persistedSettingsSnapshot) !== desiredSettings.fingerprint;
+}
+async function resolveAuthoritativeManagedRuntimeSettings(rootPath, effectiveProcessEnv) {
+    const persistedSettingsSnapshot = await loadManagedRuntimeSettingsSnapshot(rootPath);
+    if (!persistedSettingsSnapshot) {
+        return {
+            desiredSettings: resolveDesiredManagedRuntimeSettings(effectiveProcessEnv),
+            processEnv: effectiveProcessEnv,
+            persistedSettingsSnapshot: null,
+        };
     }
-    return status.managedRuntimeFingerprint !== desiredSettings.fingerprint;
+    return {
+        desiredSettings: buildDesiredManagedRuntimeSettingsFromSnapshot(persistedSettingsSnapshot),
+        processEnv: buildManagedRuntimeSettingsEnv(effectiveProcessEnv, persistedSettingsSnapshot),
+        persistedSettingsSnapshot,
+    };
 }
 function cloneLocalAgentConfig(agent) {
     return {
@@ -311,6 +341,57 @@ export function buildManagedLocalAgentConfig(options) {
         },
     };
 }
+function mergeManagedLocalAgentConfig(existingAgent, generatedAgent, envOverrides) {
+    const overrides = envOverrides ?? {};
+    const hasOverride = (key) => Object.prototype.hasOwnProperty.call(overrides, key);
+    return {
+        ...cloneLocalAgentConfig(existingAgent),
+        key: generatedAgent.key,
+        apiKey: generatedAgent.apiKey,
+        enabled: true,
+        name: hasOverride('BORGEE_AGENT_NAME') ? generatedAgent.name : existingAgent.name,
+        provider: hasOverride('RUNTIME_PROVIDER') ? generatedAgent.provider : existingAgent.provider,
+        claudeCommand: hasOverride('CLAUDE_COMMAND') ? generatedAgent.claudeCommand : existingAgent.claudeCommand,
+        claudeArgs: hasOverride('CLAUDE_ARGS')
+            ? [...(generatedAgent.claudeArgs ?? [])]
+            : [...(existingAgent.claudeArgs ?? [])],
+        codexCommand: hasOverride('CODEX_COMMAND') ? generatedAgent.codexCommand : existingAgent.codexCommand,
+        codexArgs: hasOverride('CODEX_ARGS')
+            ? [...(generatedAgent.codexArgs ?? [])]
+            : [...(existingAgent.codexArgs ?? [])],
+        copilotCommand: hasOverride('COPILOT_COMMAND')
+            ? generatedAgent.copilotCommand
+            : existingAgent.copilotCommand,
+        copilotArgs: hasOverride('COPILOT_ARGS')
+            ? [...(generatedAgent.copilotArgs ?? [])]
+            : [...(existingAgent.copilotArgs ?? [])],
+        copilotSessionTtlMinutes: hasOverride('COPILOT_SESSION_TTL_MINUTES')
+            ? generatedAgent.copilotSessionTtlMinutes
+            : existingAgent.copilotSessionTtlMinutes,
+    };
+}
+function collectExplicitManagedAgentEnvOverrides(processEnv, optionEnv) {
+    const explicitOverrides = {};
+    for (const key of [
+        'BORGEE_AGENT_NAME',
+        'RUNTIME_PROVIDER',
+        'CLAUDE_COMMAND',
+        'CLAUDE_ARGS',
+        'CODEX_COMMAND',
+        'CODEX_ARGS',
+        'COPILOT_COMMAND',
+        'COPILOT_ARGS',
+        'COPILOT_SESSION_TTL_MINUTES',
+    ]) {
+        if (processEnv[key] !== undefined) {
+            explicitOverrides[key] = processEnv[key];
+        }
+        if (optionEnv && Object.prototype.hasOwnProperty.call(optionEnv, key)) {
+            explicitOverrides[key] = optionEnv[key];
+        }
+    }
+    return explicitOverrides;
+}
 function resolveManagedRuntimeLayoutForServerUrl(serverUrl, processEnv = process.env) {
     const rootPath = resolveManagedRuntimeRoot(serverUrl, processEnv);
     return {
@@ -884,8 +965,6 @@ export async function bootstrapManagedDaemonStart(options, deps = {}) {
         ...(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;
@@ -895,19 +974,51 @@ export async function bootstrapManagedDaemonStart(options, deps = {}) {
         ?? (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 requestedSettings = resolveDesiredManagedRuntimeSettings(effectiveProcessEnv);
+    const resolved = resolveManagedRuntimeLayoutForServerUrl(options.serverUrl, options.processEnv);
     const releaseBootstrapLock = await acquireLock(resolved.rootPath);
     try {
+        const currentRuntimeSettings = await resolveAuthoritativeManagedRuntimeSettings(resolved.rootPath, effectiveProcessEnv);
+        const loadManagedSpecWithCurrentRuntimeEnv = (hostConfigPath) => deps.loadSpec
+            ? deps.loadSpec(hostConfigPath)
+            : loadLocalConfigGenerateSpec(hostConfigPath, {
+                env: currentRuntimeSettings.processEnv,
+            });
+        if (options.apiKey !== undefined
+            && currentRuntimeSettings.persistedSettingsSnapshot == null
+            && await fs.access(resolved.hostConfigPath).then(() => true).catch(() => false)) {
+            throw new Error(`Managed runtime root ${resolved.rootPath} predates managed-runtime-settings.json; run \`agents-host start-managed ${options.serverUrl}\` once to migrate it before updating an individual agent`);
+        }
+        const explicitManagedAgentOverrides = collectExplicitManagedAgentEnvOverrides(options.processEnv ?? process.env, options.env);
+        const currentManagedSpec = options.apiKey === undefined
+            ? undefined
+            : await loadManagedSpecOrUndefined(resolved.hostConfigPath, loadManagedSpecWithCurrentRuntimeEnv);
+        const resolvedManagedAgent = options.apiKey === undefined
+            ? null
+            : (() => {
+                const generatedManagedAgent = buildManagedLocalAgentConfig({
+                    ...options,
+                    processEnv: currentRuntimeSettings.processEnv,
+                    env: options.env,
+                });
+                const existingAgent = currentManagedSpec?.agents.find((agent) => agent.key === generatedManagedAgent.agent.key);
+                return existingAgent
+                    ? {
+                        ...generatedManagedAgent,
+                        agent: mergeManagedLocalAgentConfig(existingAgent, generatedManagedAgent.agent, explicitManagedAgentOverrides),
+                    }
+                    : generatedManagedAgent;
+            })();
+        const desiredBootstrapSettings = options.apiKey === undefined ? requestedSettings : currentRuntimeSettings.desiredSettings;
+        const desiredBootstrapProcessEnv = options.apiKey === undefined ? effectiveProcessEnv : currentRuntimeSettings.processEnv;
         let statusResponse = await readReadyManagedDaemonStatus(resolved.rootPath, sendRequest);
-        if (statusResponse && getManagedRuntimeFingerprintMismatch(statusResponse, desiredSettings)) {
+        if (statusResponse
+            && await getManagedRuntimeFingerprintMismatch(resolved.rootPath, statusResponse, desiredBootstrapSettings)) {
             await recycleManagedDaemonWithDesiredSettings({
                 rootPath: resolved.rootPath,
                 debug: options.debug === true,
-                processEnv: effectiveProcessEnv,
-                desiredSettings,
+                processEnv: desiredBootstrapProcessEnv,
+                desiredSettings: desiredBootstrapSettings,
                 sendRequest,
                 waitForShutdown,
                 spawnDaemonProcess,
@@ -917,11 +1028,17 @@ export async function bootstrapManagedDaemonStart(options, deps = {}) {
         }
         if (!statusResponse) {
             if (options.apiKey === undefined) {
-                await ensurePersistedManagedAgentsExist(options.serverUrl, resolved.hostConfigPath, loadSpec);
+                await ensurePersistedManagedAgentsExist(options.serverUrl, resolved.hostConfigPath, (hostConfigPath) => options.apiKey === undefined
+                    ? (deps.loadSpec
+                        ? deps.loadSpec(hostConfigPath)
+                        : loadLocalConfigGenerateSpec(hostConfigPath, {
+                            env: desiredBootstrapProcessEnv,
+                        }))
+                    : loadManagedSpecWithCurrentRuntimeEnv(hostConfigPath));
             }
             else {
                 try {
-                    await loadSpec(resolved.hostConfigPath);
+                    await loadManagedSpecWithCurrentRuntimeEnv(resolved.hostConfigPath);
                 }
                 catch (error) {
                     if (isNotFoundError(error)) {
@@ -938,8 +1055,8 @@ export async function bootstrapManagedDaemonStart(options, deps = {}) {
             await startManagedDaemonWithPersistedSettings({
                 rootPath: resolved.rootPath,
                 debug: options.debug === true,
-                processEnv: effectiveProcessEnv,
-                desiredSettings,
+                processEnv: desiredBootstrapProcessEnv,
+                desiredSettings: desiredBootstrapSettings,
                 spawnDaemonProcess,
                 waitForDaemon,
                 sendRequest,
@@ -948,7 +1065,11 @@ export async function bootstrapManagedDaemonStart(options, deps = {}) {
         }
         if (options.apiKey === undefined) {
             if (!statusResponse) {
-                await ensurePersistedManagedAgentsExist(options.serverUrl, resolved.hostConfigPath, loadSpec);
+                await ensurePersistedManagedAgentsExist(options.serverUrl, resolved.hostConfigPath, (hostConfigPath) => deps.loadSpec
+                    ? deps.loadSpec(hostConfigPath)
+                    : loadLocalConfigGenerateSpec(hostConfigPath, {
+                        env: desiredBootstrapProcessEnv,
+                    }));
             }
             else {
                 assertManagedRuntimeBinding(statusResponse.borgeeBaseUrl, options.serverUrl);
@@ -1079,10 +1200,11 @@ async function terminateChildProcessAndWait(child) {
     }
     await waitForChildExit(child, DAEMON_FORCE_KILL_WAIT_MS);
 }
-async function rollbackManagedApplyFailure(rootPath, previousSpec, materialize, clearRuntimeImpl, applyError) {
+async function rollbackManagedApplyFailure(rootPath, previousSpec, previousSettingsSnapshot, materialize, clearRuntimeImpl, applyError) {
     const original = toManagedErrorPayload(applyError, 'MANAGED_RELOAD_FAILED');
     try {
         if (previousSpec) {
+            await restoreManagedRuntimeSettingsSnapshot(rootPath, previousSettingsSnapshot);
             await materialize(rootPath, cloneLocalConfigGenerateSpec(previousSpec));
         }
         else {
@@ -1139,8 +1261,6 @@ function validateDaemonUpsertAgentInput(currentSpec, serverUrl, agent, env = pro
 }
 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 {
@@ -1167,7 +1287,12 @@ export async function describeManagedSpec(options, deps = {}) {
         }
     }
     try {
-        const persistedSpec = await loadManagedSpecOrUndefined(resolved.hostConfigPath, loadSpec);
+        const currentRuntimeSettings = await resolveAuthoritativeManagedRuntimeSettings(resolved.rootPath, effectiveProcessEnv);
+        const persistedSpec = await loadManagedSpecOrUndefined(resolved.hostConfigPath, (hostConfigPath) => deps.loadSpec
+            ? deps.loadSpec(hostConfigPath)
+            : loadLocalConfigGenerateSpec(hostConfigPath, {
+                env: currentRuntimeSettings.processEnv,
+            }));
         if (!persistedSpec) {
             return { ok: true, present: false };
         }
@@ -1207,27 +1332,13 @@ async function applySpecToRunningManagedDaemon(rootPath, borgeeBaseUrl, spec, se
 }
 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 desiredSettings = resolveDesiredManagedRuntimeSettings(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);
@@ -1240,6 +1351,32 @@ export async function applyManagedSpec(options, deps = {}) {
         return toApplyManagedColdStartErrorResponse(error);
     }
     try {
+        const currentRuntimeSettings = await resolveAuthoritativeManagedRuntimeSettings(resolved.rootPath, effectiveProcessEnv);
+        const loadSpecWithCurrentRuntimeEnv = (hostConfigPath) => deps.loadSpec
+            ? deps.loadSpec(hostConfigPath)
+            : loadLocalConfigGenerateSpec(hostConfigPath, {
+                env: currentRuntimeSettings.processEnv,
+            });
+        const materializeWithDesiredEnv = (rootPath, nextSpec) => deps.materialize
+            ? deps.materialize(rootPath, nextSpec)
+            : materializeLocalConfig(rootPath, nextSpec, {
+                env: effectiveProcessEnv,
+            });
+        const materializeWithCurrentRuntimeEnv = (rootPath, nextSpec) => deps.materialize
+            ? deps.materialize(rootPath, nextSpec)
+            : materializeLocalConfig(rootPath, nextSpec, {
+                env: currentRuntimeSettings.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)}`));
+        }
         let statusResponse;
         try {
             statusResponse = await readReadyManagedDaemonStatus(resolved.rootPath, sendRequest);
@@ -1250,7 +1387,8 @@ export async function applyManagedSpec(options, deps = {}) {
             }
             throw error;
         }
-        if (statusResponse && getManagedRuntimeFingerprintMismatch(statusResponse, desiredSettings)) {
+        if (statusResponse
+            && await getManagedRuntimeFingerprintMismatch(resolved.rootPath, statusResponse, desiredSettings)) {
             try {
                 await recycleManagedDaemonWithDesiredSettings({
                     rootPath: resolved.rootPath,
@@ -1273,7 +1411,7 @@ export async function applyManagedSpec(options, deps = {}) {
         }
         let previousSpec;
         try {
-            previousSpec = await loadManagedSpecOrUndefined(resolved.hostConfigPath, loadSpec);
+            previousSpec = await loadManagedSpecOrUndefined(resolved.hostConfigPath, loadSpecWithCurrentRuntimeEnv);
             if (previousSpec) {
                 assertManagedSpecBinding(previousSpec, options.serverUrl);
             }
@@ -1282,10 +1420,10 @@ export async function applyManagedSpec(options, deps = {}) {
             return toApplyManagedColdStartErrorResponse(error);
         }
         try {
-            await materialize(resolved.rootPath, cloneLocalConfigGenerateSpec(spec));
+            await materializeWithDesiredEnv(resolved.rootPath, cloneLocalConfigGenerateSpec(spec));
         }
         catch (error) {
-            return rollbackManagedApplyFailure(resolved.rootPath, previousSpec, materialize, clearManagedRuntimeImpl, error);
+            return rollbackManagedApplyFailure(resolved.rootPath, previousSpec, currentRuntimeSettings.persistedSettingsSnapshot ?? undefined, materializeWithCurrentRuntimeEnv, clearManagedRuntimeImpl, error);
         }
         try {
             await startManagedDaemonWithPersistedSettings({
@@ -1300,7 +1438,7 @@ export async function applyManagedSpec(options, deps = {}) {
             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));
+                return rollbackManagedApplyFailure(resolved.rootPath, previousSpec, currentRuntimeSettings.persistedSettingsSnapshot ?? undefined, materializeWithCurrentRuntimeEnv, clearManagedRuntimeImpl, managedOperationError(managedError.code, managedError.message));
             }
             if (status.type !== 'status') {
                 throw new Error('Unexpected managed daemon response for status');
@@ -1314,7 +1452,7 @@ export async function applyManagedSpec(options, deps = {}) {
             };
         }
         catch (error) {
-            return rollbackManagedApplyFailure(resolved.rootPath, previousSpec, materialize, clearManagedRuntimeImpl, error);
+            return rollbackManagedApplyFailure(resolved.rootPath, previousSpec, currentRuntimeSettings.persistedSettingsSnapshot ?? undefined, materializeWithCurrentRuntimeEnv, clearManagedRuntimeImpl, error);
         }
     }
     finally {
@@ -1350,9 +1488,7 @@ export class ManagedAgentsHostDaemon {
         this.loadSpec = deps.loadSpec ?? loadLocalConfigGenerateSpec;
         this.materialize = deps.materialize ?? materializeLocalConfig;
         const managedRuntimeSettings = resolveDesiredManagedRuntimeSettings(process.env);
-        this.managedRuntimeFingerprint = managedRuntimeSettings.convergenceEnabled
-            ? managedRuntimeSettings.fingerprint
-            : null;
+        this.managedRuntimeFingerprint = managedRuntimeSettings.fingerprint;
         this.logger = deps.logger ?? console;
         this.logPath = deps.logPath ?? null;
         this.server = createServer((socket) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@borgee/agents-host",
-  "version": "0.2.28",
+  "version": "0.2.29",
   "private": false,
   "publishConfig": {
     "access": "public"