@songsid/agend 2.1.6-beta.6 → 2.1.6-beta.8

package/dist/fleet-manager.js

@@ -44,7 +44,7 @@ import { StatuslineWatcher } from "./statusline-watcher.js";
 import { outboundHandlers } from "./outbound-handlers.js";
 import { handleWebRequest, broadcastSseEvent } from "./web-api.js";
 import { handleViewRequest, isViewPath } from "./view-api.js";
-import { handleUsageRequest, isUsagePath, usageProviderIdForBackend } from "./usage/usage-api.js";
+import { formatDiscordUsageActivity, getUsageSnapshot, handleUsageRequest, isUsagePath, usageProviderIdForBackend } from "./usage/usage-api.js";
 import { LOGIN_FLOWS, LOGIN_BACKEND_ALIASES, checkAuthStatus } from "./login-flows.js";
 import { LoginSession } from "./login-manager.js";
 import { LoginController, LOGIN_TOKEN_RESEND_PREFIX, POST_LOGIN_RECOVERY_DEADLINE_MS, announcePostLoginRecovery } from "./login-controller.js";
@@ -67,6 +67,10 @@ import { mayUseTool, resolveToolSet, toolForIpcType, toolRefusedMessage, } from
 import { decideWebGate, loadOrCreateWebToken, readWebToken } from "./web-auth.js";
 import { fleetLevelDifferences, fleetLevelSignature } from "./fleet-level-config.js";
 import { checkSelfRestartAllowance, recordSelfRestartAttempt } from "./self-restart-limit.js";
+import { SecretStore } from "./secret-store.js";
+import { opaqueId, safeSecretError, SECRET_CHALLENGE_TTL_MS, } from "./connection-secrets.js";
+import { verifyDiscordToken, verifyTelegramToken } from "./provider-probe.js";
+import { PROVIDER_SECRET_SPECS, providerSecretSpec, providerRegistryEnvKeys, isReservedProviderEnvKey, verifyProviderSecret, } from "./provider-secret-registry.js";
 /** A self-restart is a whole service restart; 120s is the apply budget, not this. */
 const SELF_RESTART_DEADLINE_MS = 300_000;
 import { APPLY_FLEET_TARGET, ApplyJobStore, viewOf, } from "./apply-job.js";
@@ -436,6 +440,40 @@ export class FleetManager {
     adapterRestarting = new Set();
     // Adapter isolation: track state per adapter for retry + visibility
     adapterState = new Map();
+    /** Web Settings secret rotation is deliberately separate from reconnect
+     * recovery: a rotation must build a fresh provider client with the new token,
+     * and stale callbacks from the old client must not win. */
+    connectionSecretChallenges = new Map();
+    connectionSecretChallengesByKey = new Map();
+    connectionSecretJobs = new Map();
+    connectionSecretJobSession = new Map();
+    connectionSecretInFlight = new Map();
+    connectionSecretGenerations = new Map();
+    /** Local epoch that fences a challenge across adapter replacement and
+     * provider reconnect generations. The adapter's own generation can reset
+     * when a new adapter object is constructed, so keep an independent epoch. */
+    connectionSecretAdapterRefs = new Map();
+    connectionSecretHealthGenerations = new Map();
+    /** Generic API-key verifier/apply state.  The challenge scope contains the
+     * resolved spec/env key, so a request can never retarget another provider. */
+    providerSecretChallenges = new Map();
+    providerSecretChallengesByKey = new Map();
+    providerSecretJobs = new Map();
+    providerSecretJobSession = new Map();
+    providerSecretInFlight = new Map();
+    providerSecretGenerations = new Map();
+    /** Test seam only; production always uses the fixed HTTPS client. */
+    providerSecretHttpClient;
+    /** Code-owned activation hooks; never populated from a request. */
+    providerSecretReloadHooks = new Map();
+    /** In-memory snapshots for narrow hot consumers (currently Groq voice). */
+    providerSecretHotSnapshots = new Map();
+    /** Web Settings connection-binding step-up challenges and apply jobs. */
+    connectionBindingChallenges = new Map();
+    connectionBindingChallengesByKey = new Map();
+    connectionBindingJobs = new Map();
+    connectionBindingJobSession = new Map();
+    connectionBindingInFlight = new Map();
     collabInstances = new Set();
     // Health endpoint
     healthServer = null;
@@ -449,6 +487,9 @@ export class FleetManager {
     fullRestartLauncher = launchFullRestartHelper;
     eventLogPruneTimer = null;
     logRotateTimer = null;
+    discordPresenceTimer = null;
+    discordPresenceInFlight = null;
+    static DISCORD_PRESENCE_REFRESH_MS = 15 * 60_000;
     /** Days of event/activity history to keep. */
     static EVENT_LOG_RETENTION_DAYS = 30;
     watchdogTimer = null;
@@ -772,11 +813,30 @@ export class FleetManager {
         if (this.rawFleetDocument.errors.length > 0) {
             throw new Error(`Invalid fleet.yaml: ${this.rawFleetDocument.errors[0].message}`);
         }
-        this.rawFleetConfig = loadRawFleetConfig(configPath);
-        this.fleetConfig = loadFleetConfig(configPath);
+        const raw = loadRawFleetConfig(configPath);
+        const loaded = loadFleetConfig(configPath);
+        this.assertProviderSecretEnvKeys(loaded);
+        this.rawFleetConfig = raw;
+        this.fleetConfig = loaded;
         this.savedFleetConfigSnapshot = structuredClone(this.fleetConfig);
         return this.fleetConfig;
     }
+    /**
+     * A channel's configurable bot_token_env is an env-key writer too.  Refuse
+     * an overlap with a registry API key (or a process-reserved key) before the
+     * config becomes live; otherwise a Discord token could be written into
+     * GROQ_API_KEY by a perfectly valid-looking rotation request.
+     */
+    assertProviderSecretEnvKeys(config) {
+        const registryKeys = providerRegistryEnvKeys();
+        const channels = config.channels ?? (config.channel ? [config.channel] : []);
+        for (const channel of channels) {
+            const key = channel.bot_token_env;
+            if (registryKeys.has(key) || isReservedProviderEnvKey(key)) {
+                throw new Error(`bot_token_env ${key} conflicts with a protected provider secret key`);
+            }
+        }
+    }
     /** User-authored fleet.yaml, before defaults are merged into instances. */
     getRawFleetConfig() {
         return structuredClone(this.rawFleetConfig);
@@ -2832,6 +2892,7 @@ export class FleetManager {
         }
         if (topicMode && (fleet.channel || fleet.channels?.length)) {
             await adapterStartup;
+            this.startDiscordUsagePresence();
             // Bind every fleet instance deterministically. Explicit channel_id wins;
             // otherwise channels[0] is authoritative. Do not infer identity from
             // concurrent adapter startup or whichever bot receives a message first.
@@ -2980,6 +3041,48 @@ export class FleetManager {
             this.logger.warn({ health }, "Fleet started with problems — see /health");
         }
     }
+    /** Keep Discord profile activity aligned with the same cached usage source as /usage. */
+    startDiscordUsagePresence() {
+        if (this.discordPresenceTimer)
+            clearInterval(this.discordPresenceTimer);
+        void this.refreshDiscordUsagePresence();
+        this.discordPresenceTimer = setInterval(() => {
+            void this.refreshDiscordUsagePresence();
+        }, FleetManager.DISCORD_PRESENCE_REFRESH_MS);
+        this.discordPresenceTimer.unref?.();
+    }
+    refreshDiscordUsagePresence() {
+        if (this.discordPresenceInFlight)
+            return this.discordPresenceInFlight;
+        const run = (async () => {
+            const targets = [...this.adapters.values()]
+                .filter(adapter => adapter.type === "discord" && typeof adapter.setActivity === "function");
+            if (targets.length === 0)
+                return;
+            try {
+                const payload = await getUsageSnapshot(false, this.getActiveUsageProviderIds());
+                const text = formatDiscordUsageActivity(payload);
+                for (const adapter of targets) {
+                    try {
+                        adapter.setActivity?.(text);
+                    }
+                    catch {
+                        // Presence is cosmetic; a failed update must not affect delivery.
+                    }
+                }
+            }
+            catch {
+                // Usage providers are best-effort and may be offline. Keep the last
+                // activity rather than replacing it with an untruthful blank state.
+                this.logger.debug("Discord usage presence refresh skipped");
+            }
+        })();
+        this.discordPresenceInFlight = run.finally(() => {
+            if (this.discordPresenceInFlight === run)
+                this.discordPresenceInFlight = null;
+        });
+        return this.discordPresenceInFlight;
+    }
     /**
      * Delete inbox files older than retentionDays (by mtime). Cleans the shared
      * inbox (`<dataDir>/inbox`) and every workspace inbox
@@ -3097,6 +3200,11 @@ export class FleetManager {
     }
     bindAdapterHealth(adapter, adapterId) {
         adapter.on("gateway_health", (snapshot) => {
+            // A token rotation tears down the old EventEmitter before constructing
+            // the replacement. A late health frame from that old client must never
+            // make a failed/new-generation adapter look connected.
+            if (this.adapters.get(adapterId) !== adapter)
+                return;
             const previous = this.adapterState.get(adapterId);
             const status = snapshot.status === "connected" ? "connected"
                 : snapshot.status === "stopped" ? "failed"
@@ -3177,7 +3285,7 @@ export class FleetManager {
         };
     }
     /** Start the primary adapter (backward-compatible, sets this.adapter) */
-    async startSingleAdapter(fleet, channelConfig) {
+    async startSingleAdapter(fleet, channelConfig, onStarted) {
         const botToken = process.env[channelConfig.bot_token_env];
         if (!botToken) {
             this.logger.warn({ env: channelConfig.bot_token_env }, "Bot token env not set, skipping shared adapter");
@@ -3203,13 +3311,20 @@ export class FleetManager {
         this.worlds.set(adapterId, world);
         this.adapters.set(adapterId, adapter);
         this.bindAdapterHealth(adapter, adapterId);
+        const isCurrentAdapter = () => this.adapters.get(adapterId) === adapter;
         this.adapter.on("message", safeHandler(async (msg) => {
+            if (!isCurrentAdapter())
+                return;
             await this.handleInboundMessage(msg);
         }, this.logger, "adapter.message"));
         this.adapter.on("reaction", safeHandler(async (r) => {
+            if (!isCurrentAdapter())
+                return;
             await this.handleInboundReaction(r);
         }, this.logger, "adapter.reaction"));
         this.adapter.on("callback_query", safeHandler(async (data) => {
+            if (!isCurrentAdapter())
+                return;
             if (await this.handleTipDismiss(data, adapterId, this.adapter ?? undefined))
                 return;
             if (await this.handleTipUnlock(data, adapterId, this.adapter ?? undefined))
@@ -3250,6 +3365,8 @@ export class FleetManager {
         this.bindTopicClosedHandler(adapter, adapterId, "adapter.topic_closed");
         // Handle classic bot slash commands (/start, /stop, /chat, /compact, /save, /load)
         this.adapter.on("slash_command", safeHandler(async (data) => {
+            if (!isCurrentAdapter())
+                return;
             if (data.command === "start") {
                 await this.handleClassicStartSlash(data, adapterId);
             }
@@ -3529,6 +3646,8 @@ export class FleetManager {
         // Non-blocking: /model & status views read the cache; never delays startup.
         this.probeCliEnvs();
         this.adapter.on("started", safeHandler((username, userId) => {
+            if (!isCurrentAdapter())
+                return;
             this.logger.info(`Bot @${username} polling started. Ensure no other service is polling this bot token.`);
             // Concurrent startup can insert a secondary world first. Update the
             // configured primary world, not Map insertion order.
@@ -3540,6 +3659,7 @@ export class FleetManager {
             }
             if (userId)
                 this.botUserId = userId;
+            onStarted?.();
         }, this.logger, "adapter.started"));
         this.adapter.on("polling_conflict", safeHandler(({ attempt, delay }) => {
             this.logger.warn(`409 Conflict (attempt ${attempt}), retry in ${delay / 1000}s`);
@@ -3548,10 +3668,14 @@ export class FleetManager {
             this.logger.warn({ err: err instanceof Error ? err.message : String(err) }, "Adapter handler error");
         }, this.logger, "adapter.handler_error"));
         this.adapter.on("error", (err) => {
+            if (!isCurrentAdapter())
+                return;
             this.logger.error({ err }, "Primary adapter fatal error");
             this.restartAdapter(this.adapter, adapterId).catch(() => { });
         });
         this.adapter.on("new_group_detected", safeHandler(async (data) => {
+            if (!isCurrentAdapter())
+                return;
             const adminMsg = t("alert.bot_added", data.groupTitle, data.groupId, data.source);
             const generalId = this.findGeneralInstance();
             // No user to promote: the bot was just added, nobody has run /start yet.
@@ -3563,6 +3687,9 @@ export class FleetManager {
         if (fleet.channel?.group_id) {
             this.adapter.setChatId(String(fleet.channel.group_id));
         }
+        if (this.discordPresenceTimer && this.adapter.type === "discord") {
+            void this.refreshDiscordUsagePresence();
+        }
         this.startTopicCleanupPoller();
         // Prune stale external sessions every 5 minutes
         this.sessionPruneTimer = setInterval(() => {
@@ -3570,7 +3697,7 @@ export class FleetManager {
         }, 5 * 60 * 1000);
     }
     /** Start an additional (non-primary) adapter */
-    async startAdditionalAdapter(channelConfig, registerCommands = true) {
+    async startAdditionalAdapter(channelConfig, registerCommands = true, onStarted) {
         const adapterId = channelConfig.id ?? channelConfig.type;
         const botToken = process.env[channelConfig.bot_token_env];
         if (!botToken) {
@@ -3595,14 +3722,21 @@ export class FleetManager {
         this.worlds.set(adapterId, world);
         this.adapters.set(adapterId, adapter);
         this.bindAdapterHealth(adapter, adapterId);
+        const isCurrentAdapter = () => this.adapters.get(adapterId) === adapter;
         // Wire up event handlers (same as primary, routes through shared handleInboundMessage)
         adapter.on("message", safeHandler(async (msg) => {
+            if (!isCurrentAdapter())
+                return;
             await this.handleInboundMessage(msg);
         }, this.logger, `adapter[${adapterId}].message`));
         adapter.on("reaction", safeHandler(async (r) => {
+            if (!isCurrentAdapter())
+                return;
             await this.handleInboundReaction(r);
         }, this.logger, `adapter[${adapterId}].reaction`));
         adapter.on("callback_query", safeHandler(async (data) => {
+            if (!isCurrentAdapter())
+                return;
             if (await this.handleTipDismiss(data, adapterId, adapter))
                 return;
             if (await this.handleTipUnlock(data, adapterId, adapter))
@@ -3643,6 +3777,8 @@ export class FleetManager {
         this.bindTopicClosedHandler(adapter, adapterId, `adapter[${adapterId}].topic_closed`);
         // Slash commands: classic bot + admin commands
         adapter.on("slash_command", safeHandler(async (data) => {
+            if (!isCurrentAdapter())
+                return;
             if (data.command === "start") {
                 await this.handleClassicStartSlash(data, adapterId);
             }
@@ -3866,6 +4002,8 @@ export class FleetManager {
             }
         }, this.logger, `adapter[${adapterId}].slash_command`));
         adapter.on("started", safeHandler((username, userId) => {
+            if (!isCurrentAdapter())
+                return;
             this.logger.info(`[${adapterId}] Bot @${username} polling started.`);
             const world = this.worlds.get(adapterId);
             if (world) {
@@ -3873,14 +4011,19 @@ export class FleetManager {
                 if (userId)
                     world.botUserId = userId;
             }
+            onStarted?.();
         }, this.logger, `adapter[${adapterId}].started`));
         adapter.on("new_group_detected", safeHandler(async (data) => {
+            if (!isCurrentAdapter())
+                return;
             const adminMsg = t("alert.bot_added", data.groupTitle, data.groupId, data.source);
             const generalId = this.findGeneralInstance(adapterId);
             if (generalId)
                 await this.promptClassicApproval({ generalName: generalId, message: adminMsg, groupId: data.groupId, scope: data.source === "telegram" ? "group" : "guild" });
         }, this.logger, `adapter[${adapterId}].new_group_detected`));
         adapter.on("error", (err) => {
+            if (!isCurrentAdapter())
+                return;
             this.logger.error({ err, adapterId }, "Additional adapter fatal error");
             this.restartAdapter(adapter, adapterId).catch(() => { });
         });
@@ -3889,6 +4032,9 @@ export class FleetManager {
         if (channelConfig.group_id) {
             adapter.setChatId(String(channelConfig.group_id));
         }
+        if (this.discordPresenceTimer && adapter.type === "discord") {
+            void this.refreshDiscordUsagePresence();
+        }
         this.logger.info({ adapterId, type: channelConfig.type }, "Additional adapter started");
     }
     /** Connect IPC to a single instance with all handlers */
@@ -4131,6 +4277,9 @@ export class FleetManager {
                     // watchdog/manual/error triggers must converge here instead of stop/start.
                     await adapter.reconnectGateway(previous?.lastError ?? "fleet adapter restart");
                     this.adapterState.set(id, { status: "connected", retryCount: 0 });
+                    if (this.discordPresenceTimer && adapter.type === "discord") {
+                        void this.refreshDiscordUsagePresence();
+                    }
                     this.logger.info({ id }, "Adapter gateway rebuilt successfully");
                 }
                 catch (err) {
@@ -4156,6 +4305,9 @@ export class FleetManager {
                     await adapter.start();
                     this.logger.info({ id, attempt }, "Adapter restarted successfully");
                     this.adapterState.set(id, { status: "connected", retryCount: 0 });
+                    if (this.discordPresenceTimer && adapter.type === "discord") {
+                        void this.refreshDiscordUsagePresence();
+                    }
                     return;
                 }
                 catch (err) {
@@ -10692,6 +10844,10 @@ Plus the operational skills (fleet-health, instance-lifecycle, scheduling, sessi
             clearInterval(this.logRotateTimer);
             this.logRotateTimer = null;
         }
+        if (this.discordPresenceTimer) {
+            clearInterval(this.discordPresenceTimer);
+            this.discordPresenceTimer = null;
+        }
         // Cancel-button timers were never cleared here. The idle-check interval is not
         // unref'd, so it held the event loop open past shutdown and kept retrying
         // deletes against an adapter that was already gone.
@@ -11325,6 +11481,799 @@ Plus the operational skills (fleet-health, instance-lifecycle, scheduling, sessi
     get applyJobs() {
         return (this.applyJobStoreCache ??= new ApplyJobStore(this.dataDir, Date.now, this.logger));
     }
+    /** The only channel metadata exposed to the Settings secret UI. */
+    listSecureConnections() {
+        const channels = this.fleetConfig?.channels
+            ?? (this.fleetConfig?.channel ? [this.fleetConfig.channel] : []);
+        return channels.map((channel, index) => {
+            const id = channel.id ?? channel.type ?? `channel-${index}`;
+            const world = this.worlds.get(id);
+            const state = this.adapterState.get(id);
+            return {
+                id,
+                type: channel.type,
+                token_env: channel.bot_token_env,
+                token_present: !!process.env[channel.bot_token_env],
+                group_id: channel.group_id != null ? String(channel.group_id) : null,
+                general_channel_id: channel.options?.general_channel_id != null
+                    ? String(channel.options.general_channel_id)
+                    : null,
+                status: state?.status ?? (world ? "starting" : "stopped"),
+                ...(world ? { identity: { id: world.botUserId ?? null, username: world.botUsername ?? null } } : {}),
+            };
+        });
+    }
+    secureConnectionChannel(connectionId) {
+        const channels = this.fleetConfig?.channels
+            ?? (this.fleetConfig?.channel ? [this.fleetConfig.channel] : []);
+        const matches = channels.filter((channel, index) => (channel.id ?? channel.type ?? `channel-${index}`) === connectionId);
+        // Ambiguous fallback IDs (for example two unlabelled Discord channels)
+        // must fail closed rather than rotating the first matching token.
+        return matches.length === 1 ? matches[0] : undefined;
+    }
+    secureConnectionGeneration(connectionId) {
+        const adapter = this.adapters.get(connectionId);
+        const healthGeneration = adapter?.getHealthSnapshot?.().generation ?? 0;
+        let generation = this.connectionSecretGenerations.get(connectionId) ?? 0;
+        const previousAdapter = this.connectionSecretAdapterRefs.get(connectionId);
+        const previousHealthGeneration = this.connectionSecretHealthGenerations.get(connectionId);
+        if (this.connectionSecretAdapterRefs.has(connectionId) && previousAdapter !== adapter)
+            generation++;
+        if (this.connectionSecretHealthGenerations.has(connectionId) && previousHealthGeneration !== healthGeneration)
+            generation++;
+        this.connectionSecretAdapterRefs.set(connectionId, adapter);
+        this.connectionSecretHealthGenerations.set(connectionId, healthGeneration);
+        this.connectionSecretGenerations.set(connectionId, generation);
+        return generation;
+    }
+    /** Provider API-key rows exposed to Settings (never the env key or secret). */
+    providerSecretsEnabled() {
+        return this.fleetConfig?.web?.provider_secrets === true;
+    }
+    listProviderSecrets() {
+        return PROVIDER_SECRET_SPECS.map(spec => ({
+            id: spec.id,
+            display_name: spec.displayName,
+            kind: spec.kind,
+            token_present: !!process.env[spec.envKey],
+            verifier: spec.verifier ? "available" : "unsupported",
+            activation: spec.activation,
+            stale_consumers: this.providerSecretStaleConsumers(spec.envKey),
+        }));
+    }
+    providerSecretStaleConsumers(envKey) {
+        // A child inherits the manager's environment at spawn.  We cannot inspect
+        // a child process's private environment safely, so report the conservative
+        // set of already-running children; the UI can then say "restart these"
+        // rather than claiming an existing process reloaded.
+        if (envKey === "GROQ_API_KEY")
+            return [];
+        return [...this.children.keys()].sort();
+    }
+    providerSecretGeneration(envKey) {
+        return this.providerSecretGenerations.get(envKey) ?? 0;
+    }
+    providerSecretEnvAllowed(envKey) {
+        const configured = new Set((this.fleetConfig?.channels
+            ?? (this.fleetConfig?.channel ? [this.fleetConfig.channel] : []))
+            .map(channel => channel.bot_token_env));
+        return !configured.has(envKey) && providerRegistryEnvKeys().has(envKey);
+    }
+    async verifyProviderSecret(input) {
+        const spec = providerSecretSpec(input.specId);
+        if (!spec || !this.providerSecretEnvAllowed(spec.envKey)) {
+            return { ok: false, status: "invalid", error: "provider secret is not configured" };
+        }
+        if (!spec.verifier)
+            return { ok: false, status: "unsupported_verifier", error: "this provider has no supported verifier" };
+        if (!input.secret || input.secret.length > 4096 || /[\r\n\0]/.test(input.secret) || /[^\x20-\x7e]/.test(input.secret)) {
+            return { ok: false, status: "invalid", error: "secret is invalid" };
+        }
+        const challengeKey = `${input.sessionBinding}:api_key:${spec.id}:${spec.envKey}:${input.idempotencyKey}`;
+        const existingId = this.providerSecretChallengesByKey.get(challengeKey);
+        const existing = existingId ? this.providerSecretChallenges.get(existingId) : undefined;
+        if (existing && existing.expiresAt > Date.now()) {
+            return { ok: true, verification_id: existing.id, expires_at: existing.expiresAt, spec_id: spec.id, activation: spec.activation };
+        }
+        if (existingId)
+            this.providerSecretChallengesByKey.delete(challengeKey);
+        const result = await verifyProviderSecret(spec, input.secret, this.providerSecretHttpClient);
+        if (!result.ok) {
+            // Do not log provider detail: the HTTP verifier already redacted it and
+            // this endpoint has no need to disclose whether a key was close to valid.
+            this.logger.warn({ specId: spec.id, status: result.status }, "Provider API-key verification failed");
+            return { ok: false, status: result.status, error: result.status === "unsupported_verifier" ? "this provider has no supported verifier" : "provider rejected or unavailable" };
+        }
+        const expiresAt = Date.now() + SECRET_CHALLENGE_TTL_MS;
+        const challenge = {
+            id: opaqueId("provider_verify"),
+            specId: spec.id,
+            envKey: spec.envKey,
+            kind: "api_key",
+            sessionBinding: input.sessionBinding,
+            generation: this.providerSecretGeneration(spec.envKey),
+            operation: "provider-secret.apply",
+            idempotencyKey: input.idempotencyKey,
+            expiresAt,
+            secret: input.secret,
+        };
+        this.providerSecretChallenges.set(challenge.id, challenge);
+        this.providerSecretChallengesByKey.set(challengeKey, challenge.id);
+        const expiryTimer = setTimeout(() => {
+            if (this.providerSecretChallenges.get(challenge.id) !== challenge)
+                return;
+            this.providerSecretChallenges.delete(challenge.id);
+            if (this.providerSecretChallengesByKey.get(challengeKey) === challenge.id)
+                this.providerSecretChallengesByKey.delete(challengeKey);
+        }, SECRET_CHALLENGE_TTL_MS);
+        expiryTimer.unref?.();
+        return { ok: true, verification_id: challenge.id, expires_at: expiresAt, spec_id: spec.id, activation: spec.activation };
+    }
+    /** Naming aliases used by integrations that call this an API-key operation. */
+    verifyProviderApiKey(input) {
+        return this.verifyProviderSecret(input);
+    }
+    startProviderSecretApply(input) {
+        for (const [jobId, job] of this.providerSecretJobs) {
+            if (job.specId === input.specId && job.idempotencyKey === input.idempotencyKey
+                && this.providerSecretJobSession.get(jobId) === input.sessionBinding)
+                return { job, reused: true };
+        }
+        const challenge = this.providerSecretChallenges.get(input.verificationId);
+        const spec = providerSecretSpec(input.specId);
+        if (!challenge || challenge.expiresAt <= Date.now()) {
+            if (challenge)
+                this.providerSecretChallenges.delete(input.verificationId);
+            return { error: "verification expired; verify the secret again" };
+        }
+        if (!spec || challenge.specId !== spec.id || challenge.envKey !== spec.envKey || challenge.kind !== "api_key"
+            || challenge.sessionBinding !== input.sessionBinding || challenge.operation !== "provider-secret.apply"
+            || challenge.idempotencyKey !== input.idempotencyKey || challenge.generation !== this.providerSecretGeneration(challenge.envKey)) {
+            return { error: "verification does not match this provider or session" };
+        }
+        const existingId = this.providerSecretInFlight.get(challenge.envKey);
+        if (existingId) {
+            const existing = this.providerSecretJobs.get(existingId) ?? null;
+            if (existing?.idempotencyKey === input.idempotencyKey)
+                return { job: existing, reused: true };
+            return { busy: existing };
+        }
+        this.providerSecretChallenges.delete(input.verificationId);
+        this.providerSecretChallengesByKey.delete(`${input.sessionBinding}:api_key:${spec.id}:${spec.envKey}:${input.idempotencyKey}`);
+        const job = {
+            id: opaqueId("provider_apply"), specId: spec.id, envKey: spec.envKey,
+            idempotencyKey: input.idempotencyKey, result: "applying", status: "running", startedAt: Date.now(),
+            stale_consumers: this.providerSecretStaleConsumers(spec.envKey),
+        };
+        this.providerSecretJobs.set(job.id, job);
+        this.providerSecretJobSession.set(job.id, input.sessionBinding);
+        this.providerSecretInFlight.set(spec.envKey, job.id);
+        queueMicrotask(() => void this.runProviderSecretApply(job, challenge.secret));
+        return { job, reused: false };
+    }
+    startProviderApiKeyApply(input) {
+        return this.startProviderSecretApply(input);
+    }
+    getProviderSecretApply(jobId, sessionBinding) {
+        if (this.providerSecretJobSession.get(jobId) !== sessionBinding)
+            return null;
+        return this.providerSecretJobs.get(jobId) ?? null;
+    }
+    getProviderApiKeyApply(jobId, sessionBinding) {
+        return this.getProviderSecretApply(jobId, sessionBinding);
+    }
+    async runProviderSecretApply(job, secret) {
+        const spec = providerSecretSpec(job.specId);
+        const allowed = new Set([
+            ...PROVIDER_SECRET_SPECS.map(item => item.envKey),
+            ...(this.fleetConfig?.channels ?? (this.fleetConfig?.channel ? [this.fleetConfig.channel] : [])).map(channel => channel.bot_token_env),
+        ]);
+        let store = null;
+        let before = null;
+        const previousProcessValue = process.env[job.envKey];
+        let wrote = false;
+        try {
+            if (!spec || !this.providerSecretEnvAllowed(job.envKey))
+                throw new Error("provider secret is not configured");
+            // Construct inside the transaction: symlink/permission refusal must
+            // settle the job as a safe failure, not escape the queued microtask.
+            store = new SecretStore(join(this.dataDir, ".env"), allowed);
+            before = store.write(job.envKey, secret);
+            wrote = true;
+            process.env[job.envKey] = secret;
+            if (spec.activation === "reload_hook" && spec.reloadHookId) {
+                await this.runProviderSecretReloadHook(spec.reloadHookId, secret, previousProcessValue);
+                job.result = "reloaded";
+            }
+            else {
+                job.result = "applied_next_use";
+            }
+            this.providerSecretGenerations.set(job.envKey, this.providerSecretGeneration(job.envKey) + 1);
+            job.status = "done";
+            job.finishedAt = Date.now();
+        }
+        catch (err) {
+            const safe = safeSecretError(err, secret);
+            this.logger.warn({ specId: job.specId, reason: safe }, "Provider API-key apply failed");
+            try {
+                if (wrote && before && store)
+                    store.restore(before);
+                if (previousProcessValue === undefined)
+                    delete process.env[job.envKey];
+                else
+                    process.env[job.envKey] = previousProcessValue;
+                // SecretStore.write is itself transactional; when it fails before a
+                // snapshot is returned there is no new value to roll back. Report the
+                // truthful no-op rather than claiming rollback_failed.
+                job.result = "rolled_back";
+                if (!wrote || !before)
+                    job.error = "provider secret was not applied";
+            }
+            catch (rollbackErr) {
+                this.logger.error({ specId: job.specId, reason: safeSecretError(rollbackErr, secret, previousProcessValue ? [previousProcessValue] : []) }, "Provider API-key rollback failed");
+                job.result = "rollback_failed";
+                job.error = "provider secret rollback failed; operator attention required";
+            }
+            job.status = "done";
+            job.finishedAt = Date.now();
+        }
+        finally {
+            this.providerSecretInFlight.delete(job.envKey);
+            secret = "";
+        }
+    }
+    /** Groq is currently read from process.env per voice request, so the hook is
+     * intentionally a no-op. Keeping it as a named code-owned hook makes the
+     * hot activation contract explicit and gives tests a failure seam; no generic
+     * SIGHUP or caller-provided hook is ever executed. */
+    async runProviderSecretReloadHook(hookId, _next, _previous) {
+        if (hookId !== "groq.voice")
+            throw new Error("unknown provider secret reload hook");
+        const before = this.providerSecretHotSnapshots.get(hookId);
+        this.providerSecretHotSnapshots.set(hookId, _next);
+        const hook = this.providerSecretReloadHooks.get(hookId);
+        try {
+            if (hook)
+                await hook(_next, before);
+        }
+        catch (err) {
+            if (before === undefined)
+                this.providerSecretHotSnapshots.delete(hookId);
+            else
+                this.providerSecretHotSnapshots.set(hookId, before);
+            throw err;
+        }
+    }
+    normalizeConnectionBinding(input) {
+        // IDs arrive from JSON and may be Discord snowflakes.  Do not accept a
+        // number here: JSON.parse may already have rounded it before verification.
+        if (typeof input.group_id !== "string")
+            return null;
+        const groupId = input.group_id.trim();
+        if (!groupId || groupId.length > 128 || /[\r\n\0]/.test(groupId))
+            return null;
+        let general;
+        if (input.general_channel_id === null || input.general_channel_id === undefined || input.general_channel_id === "") {
+            general = input.general_channel_id === null ? null : undefined;
+        }
+        else if (typeof input.general_channel_id === "string") {
+            general = input.general_channel_id.trim();
+            if (!general || general.length > 128 || /[\r\n\0]/.test(general))
+                return null;
+        }
+        else {
+            return null;
+        }
+        return general === undefined ? { group_id: groupId } : { group_id: groupId, general_channel_id: general };
+    }
+    connectionBindingChannelConfig(channel, binding) {
+        const candidate = structuredClone(channel);
+        // IDs are intentionally normalized to strings at this boundary. Discord
+        // snowflakes must never become YAML numbers (precision loss is silent).
+        candidate.group_id = String(binding.group_id);
+        if (binding.general_channel_id !== undefined) {
+            const options = { ...(candidate.options ?? {}) };
+            if (binding.general_channel_id === null)
+                delete options.general_channel_id;
+            else
+                options.general_channel_id = String(binding.general_channel_id);
+            if (Object.keys(options).length === 0)
+                delete candidate.options;
+            else
+                candidate.options = options;
+        }
+        return candidate;
+    }
+    /** Verify a prospective group/guild binding without mutating fleet state. */
+    async verifyConnectionBinding(input) {
+        const channel = this.secureConnectionChannel(input.connectionId);
+        const binding = this.normalizeConnectionBinding(input.binding);
+        const adapter = this.adapters.get(input.connectionId);
+        if (!channel || !binding || !adapter?.verifyBinding) {
+            return { ok: false, error: "connection binding is unsupported or invalid" };
+        }
+        const key = `${input.sessionBinding}:${input.connectionId}:${input.idempotencyKey}`;
+        const existingId = this.connectionBindingChallengesByKey.get(key);
+        const existing = existingId ? this.connectionBindingChallenges.get(existingId) : undefined;
+        if (existing && existing.expiresAt > Date.now()) {
+            return { ok: true, verification_id: existing.id, expires_at: existing.expiresAt, binding: existing.binding, probe: existing.probe };
+        }
+        if (existingId)
+            this.connectionBindingChallengesByKey.delete(key);
+        const beforeGeneration = this.secureConnectionGeneration(input.connectionId);
+        let probe;
+        try {
+            probe = await adapter.verifyBinding(binding.group_id, binding.general_channel_id ?? undefined);
+        }
+        catch (err) {
+            this.logger.warn({ connectionId: input.connectionId, reason: safeSecretError(err) }, "Settings connection binding verification failed");
+            return { ok: false, error: "binding verification failed" };
+        }
+        const afterGeneration = this.secureConnectionGeneration(input.connectionId);
+        if (beforeGeneration !== afterGeneration || this.adapters.get(input.connectionId) !== adapter) {
+            return { ok: false, error: "connection changed while binding was verified" };
+        }
+        if (probe.group_id !== binding.group_id || !probe.can_view || !probe.can_send) {
+            return { ok: false, error: "provider did not confirm the requested binding" };
+        }
+        const expiresAt = Date.now() + SECRET_CHALLENGE_TTL_MS;
+        const challenge = {
+            id: opaqueId("binding_verify"),
+            connectionId: input.connectionId,
+            sessionBinding: input.sessionBinding,
+            generation: afterGeneration,
+            operation: "binding.apply",
+            idempotencyKey: input.idempotencyKey,
+            expiresAt,
+            binding,
+            probe,
+        };
+        this.connectionBindingChallenges.set(challenge.id, challenge);
+        this.connectionBindingChallengesByKey.set(key, challenge.id);
+        const expiryTimer = setTimeout(() => {
+            if (this.connectionBindingChallenges.get(challenge.id) !== challenge)
+                return;
+            this.connectionBindingChallenges.delete(challenge.id);
+            if (this.connectionBindingChallengesByKey.get(key) === challenge.id)
+                this.connectionBindingChallengesByKey.delete(key);
+        }, SECRET_CHALLENGE_TTL_MS);
+        expiryTimer.unref?.();
+        return { ok: true, verification_id: challenge.id, expires_at: expiresAt, binding, probe };
+    }
+    startConnectionBindingApply(input) {
+        for (const [jobId, job] of this.connectionBindingJobs) {
+            if (job.connectionId === input.connectionId && job.idempotencyKey === input.idempotencyKey
+                && this.connectionBindingJobSession.get(jobId) === input.sessionBinding)
+                return { job, reused: true };
+        }
+        const challenge = this.connectionBindingChallenges.get(input.verificationId);
+        if (!challenge || challenge.expiresAt <= Date.now()) {
+            this.connectionBindingChallenges.delete(input.verificationId);
+            return { error: "binding verification expired; verify the binding again" };
+        }
+        if (challenge.connectionId !== input.connectionId || challenge.sessionBinding !== input.sessionBinding
+            || challenge.operation !== "binding.apply" || challenge.idempotencyKey !== input.idempotencyKey
+            || challenge.generation !== this.secureConnectionGeneration(input.connectionId)) {
+            return { error: "binding verification does not match this connection or session" };
+        }
+        const existingId = this.connectionBindingInFlight.get(input.connectionId);
+        if (existingId) {
+            const existing = this.connectionBindingJobs.get(existingId) ?? null;
+            if (existing?.idempotencyKey === input.idempotencyKey)
+                return { job: existing, reused: true };
+            return { busy: existing };
+        }
+        this.connectionBindingChallenges.delete(input.verificationId);
+        this.connectionBindingChallengesByKey.delete(`${input.sessionBinding}:${input.connectionId}:${input.idempotencyKey}`);
+        const job = {
+            id: opaqueId("binding_apply"), connectionId: input.connectionId, idempotencyKey: input.idempotencyKey,
+            result: "applying", status: "running", startedAt: Date.now(),
+        };
+        this.connectionBindingJobs.set(job.id, job);
+        this.connectionBindingJobSession.set(job.id, input.sessionBinding);
+        this.connectionBindingInFlight.set(input.connectionId, job.id);
+        queueMicrotask(() => void this.runConnectionBindingApply(job, challenge.binding));
+        return { job, reused: false };
+    }
+    getConnectionBindingApply(jobId, sessionBinding) {
+        if (this.connectionBindingJobSession.get(jobId) !== sessionBinding)
+            return null;
+        return this.connectionBindingJobs.get(jobId) ?? null;
+    }
+    async runConnectionBindingApply(job, binding) {
+        try {
+            await this.rebuildAdapterForBinding(job.connectionId, binding);
+            job.result = "applied";
+        }
+        catch (err) {
+            const reason = safeSecretError(err);
+            job.result = /rollback failed/i.test(reason) ? "rollback_failed" : "rolled_back";
+            job.error = job.result === "rollback_failed"
+                ? "binding rollback failed; adapter requires operator attention"
+                : "binding was not applied; previous binding was restored";
+            this.logger.warn({ connectionId: job.connectionId, reason: safeSecretError(err) }, "Settings connection binding apply failed");
+        }
+        finally {
+            job.status = "done";
+            job.finishedAt = Date.now();
+            this.connectionBindingInFlight.delete(job.connectionId);
+        }
+    }
+    /** Stop, rebuild and wait for a new adapter before committing YAML binding. */
+    async rebuildAdapterForBinding(connectionId, binding) {
+        const channel = this.secureConnectionChannel(connectionId);
+        if (!channel || !this.fleetConfig)
+            throw new Error("connection not found");
+        const candidate = this.connectionBindingChannelConfig(channel, binding);
+        const oldAdapter = this.adapters.get(connectionId);
+        const oldWorld = this.worlds.get(connectionId);
+        const oldPrimary = this.adapter;
+        const oldAccess = this.accessManager;
+        const oldState = this.adapterState.get(connectionId);
+        const oldChannel = structuredClone(channel);
+        const primary = this.getPrimaryAdapterId() === connectionId;
+        if (primary && this.sessionPruneTimer) {
+            clearInterval(this.sessionPruneTimer);
+            this.sessionPruneTimer = null;
+        }
+        let fresh;
+        let persistedBinding = false;
+        try {
+            this.adapterState.set(connectionId, { status: "retrying", retryCount: oldState?.retryCount ?? 0 });
+            if (oldAdapter) {
+                oldAdapter.removeAllListeners();
+                await oldAdapter.stop().catch(() => { });
+                if (this.adapters.get(connectionId) === oldAdapter)
+                    this.adapters.delete(connectionId);
+                if (this.worlds.get(connectionId)?.adapter === oldAdapter)
+                    this.worlds.delete(connectionId);
+                if (primary && this.adapter === oldAdapter)
+                    this.adapter = null;
+            }
+            let startedResolve = null;
+            const started = new Promise(resolve => { startedResolve = resolve; });
+            const onStarted = () => { startedResolve?.(); };
+            if (primary)
+                await this.startSingleAdapter(this.fleetConfig, candidate, onStarted);
+            else
+                await this.startAdditionalAdapter(candidate, true, onStarted);
+            fresh = this.adapters.get(connectionId);
+            if (!fresh)
+                throw new Error("new adapter did not start");
+            const deadline = Date.now() + 15_000;
+            if (!fresh.getHealthSnapshot) {
+                let timer;
+                const timeout = new Promise((_, reject) => {
+                    timer = setTimeout(() => reject(new Error("new adapter did not become ready")), Math.max(1, deadline - Date.now()));
+                    timer.unref?.();
+                });
+                try {
+                    await Promise.race([started, timeout]);
+                }
+                finally {
+                    if (timer)
+                        clearTimeout(timer);
+                }
+            }
+            else {
+                while (Date.now() < deadline) {
+                    const health = fresh.getHealthSnapshot?.();
+                    if (health?.status === "connected" || this.adapterState.get(connectionId)?.status === "connected")
+                        break;
+                    await new Promise(resolve => setTimeout(resolve, 100));
+                }
+                const health = fresh.getHealthSnapshot?.();
+                if (health && health.status !== "connected" && this.adapterState.get(connectionId)?.status !== "connected") {
+                    throw new Error("new adapter did not become connected");
+                }
+            }
+            if (fresh.setChatId)
+                fresh.setChatId(String(candidate.group_id));
+            // Commit only after the replacement adapter is ready. No allowlist,
+            // topic, instance or schedule fields are touched here.
+            channel.group_id = String(binding.group_id);
+            if (binding.general_channel_id !== undefined) {
+                const options = { ...(channel.options ?? {}) };
+                if (binding.general_channel_id === null)
+                    delete options.general_channel_id;
+                else
+                    options.general_channel_id = String(binding.general_channel_id);
+                if (Object.keys(options).length === 0)
+                    delete channel.options;
+                else
+                    channel.options = options;
+            }
+            this.saveFleetConfig();
+            persistedBinding = true;
+            this.routing.rebuild(this.fleetConfig);
+            this.reregisterClassicChannels();
+            this.adapterState.set(connectionId, { status: "connected", retryCount: 0 });
+        }
+        catch (err) {
+            if (fresh && fresh !== oldAdapter)
+                await fresh.stop().catch(() => { });
+            // Restore only the binding object in memory; unrelated connection and
+            // instance state remains exactly as it was before the attempt.
+            for (const key of Object.keys(channel)) {
+                if (!(key in oldChannel))
+                    delete channel[key];
+            }
+            Object.assign(channel, oldChannel);
+            this.adapters.delete(connectionId);
+            this.worlds.delete(connectionId);
+            this.adapterState.delete(connectionId);
+            if (oldAdapter) {
+                try {
+                    const onStarted = () => { };
+                    if (primary)
+                        await this.startSingleAdapter(this.fleetConfig, oldChannel, onStarted);
+                    else
+                        await this.startAdditionalAdapter(oldChannel, true, onStarted);
+                    this.adapterState.set(connectionId, oldState ?? { status: "connected", retryCount: 0 });
+                }
+                catch (restoreErr) {
+                    throw new Error(`binding rollback failed: ${safeSecretError(restoreErr)}`);
+                }
+            }
+            else {
+                if (primary)
+                    this.adapter = oldPrimary;
+                if (oldWorld)
+                    this.worlds.set(connectionId, oldWorld);
+                if (oldAdapter)
+                    this.adapters.set(connectionId, oldAdapter);
+                this.accessManager = oldAccess;
+            }
+            // The binding is committed to YAML before routing is rebuilt.  If the
+            // post-commit rebuild fails, restore the durable document as well as the
+            // in-memory channel; otherwise a reload would resurrect the failed
+            // binding that the running fleet just rolled back.
+            if (persistedBinding)
+                this.saveFleetConfig();
+            this.routing.rebuild(this.fleetConfig);
+            this.reregisterClassicChannels();
+            throw err;
+        }
+    }
+    async verifyConnectionSecret(input) {
+        const channel = this.secureConnectionChannel(input.connectionId);
+        if (!channel || (channel.type !== "discord" && channel.type !== "telegram")) {
+            return { ok: false, error: "connection not found or unsupported" };
+        }
+        if (!input.secret || input.secret.length > 4096 || /[\r\n\0]/.test(input.secret)) {
+            return { ok: false, error: "secret is invalid" };
+        }
+        const challengeKey = `${input.sessionBinding}:${input.connectionId}:${input.idempotencyKey}`;
+        const existingId = this.connectionSecretChallengesByKey.get(challengeKey);
+        const existing = existingId ? this.connectionSecretChallenges.get(existingId) : undefined;
+        if (existing && existing.expiresAt > Date.now()) {
+            return { ok: true, verification_id: existing.id, expires_at: existing.expiresAt };
+        }
+        if (existingId)
+            this.connectionSecretChallengesByKey.delete(challengeKey);
+        // Fixed provider endpoints only. Never use a user-supplied URL and never
+        // call Telegram getUpdates (the running adapter owns that long poll).
+        const identity = channel.type === "discord"
+            ? await verifyDiscordToken(input.secret)
+            : await verifyTelegramToken(input.secret);
+        if (!identity.valid) {
+            this.logger.warn({ connectionId: input.connectionId, provider: channel.type }, "Settings connection secret verification failed");
+            return { ok: false, error: "provider rejected the secret" };
+        }
+        const expiresAt = Date.now() + SECRET_CHALLENGE_TTL_MS;
+        const challenge = {
+            id: opaqueId("verify"),
+            connectionId: input.connectionId,
+            sessionBinding: input.sessionBinding,
+            generation: this.secureConnectionGeneration(input.connectionId),
+            operation: "secret.apply",
+            idempotencyKey: input.idempotencyKey,
+            expiresAt,
+            secret: input.secret,
+        };
+        this.connectionSecretChallenges.set(challenge.id, challenge);
+        this.connectionSecretChallengesByKey.set(challengeKey, challenge.id);
+        const expiryTimer = setTimeout(() => {
+            if (this.connectionSecretChallenges.get(challenge.id) !== challenge)
+                return;
+            this.connectionSecretChallenges.delete(challenge.id);
+            if (this.connectionSecretChallengesByKey.get(challengeKey) === challenge.id) {
+                this.connectionSecretChallengesByKey.delete(challengeKey);
+            }
+        }, SECRET_CHALLENGE_TTL_MS);
+        expiryTimer.unref?.();
+        return {
+            ok: true,
+            verification_id: challenge.id,
+            expires_at: expiresAt,
+            identity: { id: identity.id, username: identity.username },
+        };
+    }
+    startConnectionSecretApply(input) {
+        for (const [jobId, job] of this.connectionSecretJobs) {
+            if (job.connectionId === input.connectionId
+                && job.idempotencyKey === input.idempotencyKey
+                && this.connectionSecretJobSession.get(jobId) === input.sessionBinding) {
+                return { job, reused: true };
+            }
+        }
+        const challenge = this.connectionSecretChallenges.get(input.verificationId);
+        if (!challenge || challenge.expiresAt <= Date.now()) {
+            this.connectionSecretChallenges.delete(input.verificationId);
+            return { error: "verification expired; verify the secret again" };
+        }
+        if (challenge.connectionId !== input.connectionId
+            || challenge.sessionBinding !== input.sessionBinding
+            || challenge.operation !== "secret.apply"
+            || challenge.idempotencyKey !== input.idempotencyKey
+            || challenge.generation !== this.secureConnectionGeneration(input.connectionId)) {
+            return { error: "verification does not match this connection or session" };
+        }
+        const existingId = this.connectionSecretInFlight.get(input.connectionId);
+        if (existingId) {
+            const existing = this.connectionSecretJobs.get(existingId) ?? null;
+            if (existing?.idempotencyKey === input.idempotencyKey)
+                return { job: existing, reused: true };
+            return { busy: existing };
+        }
+        // Consume the challenge before scheduling work. A lost HTTP response can
+        // retry with the same idempotency key and rejoin the job, but a second
+        // request cannot replay the secret into a second adapter.
+        this.connectionSecretChallenges.delete(input.verificationId);
+        this.connectionSecretChallengesByKey.delete(`${input.sessionBinding}:${input.connectionId}:${input.idempotencyKey}`);
+        const job = {
+            id: opaqueId("secret_apply"),
+            connectionId: input.connectionId,
+            idempotencyKey: input.idempotencyKey,
+            result: "applying",
+            status: "running",
+            startedAt: Date.now(),
+        };
+        this.connectionSecretJobs.set(job.id, job);
+        this.connectionSecretJobSession.set(job.id, input.sessionBinding);
+        this.connectionSecretInFlight.set(input.connectionId, job.id);
+        queueMicrotask(() => void this.runConnectionSecretApply(job, challenge.secret));
+        return { job, reused: false };
+    }
+    getConnectionSecretApply(jobId, sessionBinding) {
+        if (this.connectionSecretJobSession.get(jobId) !== sessionBinding)
+            return null;
+        return this.connectionSecretJobs.get(jobId) ?? null;
+    }
+    async runConnectionSecretApply(job, secret) {
+        const channel = this.secureConnectionChannel(job.connectionId);
+        const envKey = channel?.bot_token_env;
+        const allowed = new Set((this.fleetConfig?.channels
+            ?? (this.fleetConfig?.channel ? [this.fleetConfig.channel] : []))
+            .map(item => item.bot_token_env));
+        let before = null;
+        let oldToken;
+        let replaced = false;
+        try {
+            if (!channel || !envKey || !allowed.has(envKey))
+                throw new Error("connection is not configured for secret rotation");
+            const owners = (this.fleetConfig?.channels
+                ?? (this.fleetConfig?.channel ? [this.fleetConfig.channel] : []))
+                .filter(item => item.bot_token_env === envKey);
+            if (owners.length !== 1)
+                throw new Error("secret key is shared by multiple connections");
+            const store = new SecretStore(join(this.dataDir, ".env"), allowed);
+            before = store.write(envKey, secret);
+            replaced = true;
+            oldToken = process.env[envKey];
+            process.env[envKey] = secret;
+            const generation = this.secureConnectionGeneration(job.connectionId) + 1;
+            this.connectionSecretGenerations.set(job.connectionId, generation);
+            const applied = await this.rebuildAdapterForSecret(job.connectionId, channel);
+            if (!applied) {
+                job.result = "restart_required";
+                job.status = "done";
+                job.finishedAt = Date.now();
+                return;
+            }
+            job.result = "applied";
+            job.status = "done";
+            job.finishedAt = Date.now();
+        }
+        catch (err) {
+            const message = safeSecretError(err, secret);
+            this.logger.warn({ connectionId: job.connectionId, reason: message }, "Settings connection secret apply failed");
+            if (!replaced || !before || !envKey) {
+                job.result = "rollback_failed";
+                job.error = "secret was not applied";
+            }
+            else {
+                try {
+                    const store = new SecretStore(join(this.dataDir, ".env"), new Set([envKey]));
+                    store.restore(before);
+                    if (oldToken === undefined)
+                        delete process.env[envKey];
+                    else
+                        process.env[envKey] = oldToken;
+                    // Build a fresh adapter from the restored token. If the old adapter
+                    // was stopped already, this is the only safe way to return to the
+                    // previous runtime without claiming a disk-only rollback succeeded.
+                    const restored = await this.rebuildAdapterForSecret(job.connectionId, channel, true);
+                    if (!restored)
+                        throw new Error("adapter rollback did not become connected");
+                    job.result = "rolled_back";
+                }
+                catch (rollbackErr) {
+                    this.logger.error({ connectionId: job.connectionId, reason: safeSecretError(rollbackErr, oldToken, [secret]) }, "Settings connection secret rollback failed");
+                    job.result = "rollback_failed";
+                    job.error = "secret rollback failed; adapter is disabled";
+                }
+            }
+            job.status = "done";
+            job.finishedAt = Date.now();
+        }
+        finally {
+            this.connectionSecretInFlight.delete(job.connectionId);
+            // Do not retain the token after the apply (success or rollback).
+            secret = "";
+        }
+    }
+    /** Stop the old provider client and construct a new one from process.env. */
+    async rebuildAdapterForSecret(connectionId, channel, force = false) {
+        const old = this.adapters.get(connectionId);
+        if (!old && !force)
+            return false; // The secret is valid on disk; the next start adopts it.
+        const primary = this.getPrimaryAdapterId() === connectionId;
+        const previousState = this.adapterState.get(connectionId);
+        this.adapterState.set(connectionId, { status: "retrying", retryCount: previousState?.retryCount ?? 0 });
+        if (primary && this.sessionPruneTimer) {
+            clearInterval(this.sessionPruneTimer);
+            this.sessionPruneTimer = null;
+        }
+        if (old) {
+            old.removeAllListeners();
+            await old.stop().catch(() => { });
+            if (this.adapters.get(connectionId) === old)
+                this.adapters.delete(connectionId);
+            if (this.worlds.get(connectionId)?.adapter === old)
+                this.worlds.delete(connectionId);
+            if (primary && this.adapter === old)
+                this.adapter = null;
+        }
+        let startedResolve = null;
+        const started = new Promise(resolve => { startedResolve = resolve; });
+        const onStarted = () => { startedResolve?.(); };
+        if (primary)
+            await this.startSingleAdapter(this.fleetConfig, channel, onStarted);
+        else
+            await this.startAdditionalAdapter(channel, true, onStarted);
+        const fresh = this.adapters.get(connectionId);
+        if (!fresh)
+            throw new Error("new adapter did not start");
+        const deadline = Date.now() + 15_000;
+        // Telegram has no gateway health snapshot. Its start() method launches the
+        // grammY polling loop in the background, so completion of start() is not a
+        // connected signal. The adapter's `started` event is emitted only after the
+        // first provider getMe succeeds; require that event before claiming apply.
+        if (!fresh.getHealthSnapshot) {
+            let timer;
+            const timeout = new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new Error("new adapter did not emit started before deadline")), Math.max(1, deadline - Date.now()));
+                timer.unref?.();
+            });
+            try {
+                await Promise.race([started, timeout]);
+            }
+            finally {
+                if (timer)
+                    clearTimeout(timer);
+            }
+            this.adapterState.set(connectionId, { status: "connected", retryCount: 0 });
+            return true;
+        }
+        while (Date.now() < deadline) {
+            const health = fresh.getHealthSnapshot?.();
+            if (health?.status === "connected" || this.adapterState.get(connectionId)?.status === "connected")
+                return true;
+            await new Promise(resolve => setTimeout(resolve, 100));
+        }
+        throw new Error("new adapter did not become connected");
+    }
     /**
      * What a reconcile is about to do, per target.
      *