@songsid/agend 2.1.6-beta.1 → 2.1.6-beta.10

package/dist/fleet-manager.js

@@ -5,7 +5,6 @@ import { freemem, totalmem, cpus } from "node:os";
 import { createServer } from "node:http";
 import { join, dirname, basename } from "node:path";
 import { fileURLToPath } from "node:url";
-import { isDeepStrictEqual } from "node:util";
 import { getAgendHome, ensureWorkspaceGit } from "./paths.js";
 import { beginFullRestartProgress as persistFullRestartProgress, beginUpdateProgress as persistUpdateProgress, clearUpdateMarker, isUpdateInProgress, readUpdateProgress, setUpdateProgressStage, updateProgressOperation, } from "./update-marker.js";
 import { formatUpdateProgress } from "./update-progress.js";
@@ -45,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 { filterUsageProviders, 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";
@@ -53,15 +52,30 @@ import { runBeforeDeadline } from "./deadline.js";
 import { LoginWindowLock } from "./login-window-lock.js";
 import { handleSettingsRequest } from "./settings-api.js";
 import { setLocale, detectLocale, getLocale, t } from "./locale.js";
-import { handleAgentRequest } from "./agent-endpoint.js";
+import { handleAgentRequest, ToolNotPermittedError } from "./agent-endpoint.js";
 import { ClassicChannelManager, getClassicBackendChoices, isSelectableClassicBackend, readClassicLastActivityAt } from "./classic-channel-manager.js";
 import { assertExplicitInstanceRemoval } from "./instance-removal.js";
 import { validateFleetConfig } from "./config-validator.js";
 import { readLastInboundAt } from "./daemon.js";
 import { clearPausedMarker } from "./pause-marker.js";
-import { releaseProcessFleetLock } from "./fleet-lock.js";
+import { isFleetStartCommandLine, readProcessCommandLine, releaseProcessFleetLock } from "./fleet-lock.js";
+import { isSetupComplete, markSetupComplete } from "./setup-marker.js";
+import { manualCleanupMessage, reapStaleTunnel } from "./tunnel/lease.js";
+import { buildToolPermissionsNotice } from "./tool-permissions-notice.js";
 import { GENERAL_PAUSE_ERROR, isGeneralInstance } from "./general-instance.js";
-import { loadOrCreateWebToken, WEB_TOKEN_INVALID_MESSAGE } from "./web-auth.js";
+import { mayUseTool, resolveToolSet, scheduleOpRefusal, toolForIpcType, toolRefusedMessage, } from "./tool-permissions.js";
+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";
+import { instanceCredentialProfile } from "./backend/credential-profile.js";
+import { classifyInstanceChange, CLASSIC_HOT_CONFIG_KEYS, HOT_INSTANCE_CONFIG_KEYS, hotConfigUpdate, } from "./instance-config-impact.js";
 import { formatRestartProgressCompletion, RESTART_PROGRESS_TERMINAL_TIMEOUT_MS, RestartProgress, } from "./restart-progress.js";
 import { launchFullRestartHelper } from "./full-restart.js";
 import { collectRedundantInstanceDefaultPaths } from "./fleet-yaml-slim.js";
@@ -179,31 +193,6 @@ const DELIVERY_STATUS_EMOJIS = new Set(["👀", "⏳", "✅", "❌"]);
  * emoji never changes the documented delivery-state protocol.
  */
 const IGNORED_REACTION_EMOJIS = new Set(["📷"]);
-const HOT_INSTANCE_CONFIG_KEYS = new Set([
-    "tool_progress",
-    "reply_completion_guard",
-    "mcp_proxy_reply",
-    "auto_pause_after",
-    "warm_cap",
-    "display_name",
-    "description",
-    "tags",
-    "log_level",
-]);
-function splitHotColdConfig(config) {
-    const hot = {};
-    const cold = {};
-    for (const [key, value] of Object.entries(config)) {
-        (HOT_INSTANCE_CONFIG_KEYS.has(key) ? hot : cold)[key] = value;
-    }
-    return { hot, cold };
-}
-function hotConfigUpdate(config) {
-    const update = {};
-    for (const key of HOT_INSTANCE_CONFIG_KEYS)
-        update[key] = config[key] ?? null;
-    return update;
-}
 /**
  * How long a delivery waits out a disconnected instance IPC before giving up.
  *
@@ -232,6 +221,8 @@ const CLEAR_CONFIRM_TIMEOUT_MS = 15_000;
 /** Default lifetime for long-lived nonce prompts (clear overrides this to 15s). */
 const NONCE_BUTTON_TIMEOUT_MS = 15 * 60_000;
 const TIP_BUTTON_TIMEOUT_MS = 24 * 60 * 60_000;
+/** How long shutdown will spend retiring still-armed button prompts. */
+const NONCE_RETIRE_BUDGET_MS = 5_000;
 const CLI_ENV_TTL_MS = 24 * 60 * 60 * 1000; // hard validity bound for the cached CLI env
 /**
  * How old the cached CLI env may be before `/model` re-probes it live.
@@ -449,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;
@@ -462,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;
@@ -472,7 +500,29 @@ export class FleetManager {
     mirrorTimer = null;
     // Web UI: SSE clients + auth token
     sseClients = new Set();
-    webToken = null;
+    /**
+     * Read from disk on every access rather than cached at startup: `agend
+     * web-token rotate` runs in a separate process, and a cached copy would keep
+     * authorizing revoked links and cookies until the fleet restarted.
+     */
+    get webToken() { return readWebToken(this.dataDir); }
+    /**
+     * Set while a Settings apply job is driving the reconcile. The reconcile
+     * stays the single doer; it just says out loud what it is doing to whom, so
+     * the job's rows are the work rather than a prediction of it.
+     */
+    applyJobStoreCache = null;
+    /** The apply that currently owns the reconcile slot, reserved synchronously
+     * so a second request cannot slip in before the first one starts working. */
+    activeApplyJobId = null;
+    /** The fleet-level signature this process actually came up on. */
+    appliedFleetLevel = null;
+    /** The config behind that signature, kept so a "needs restart" log can name
+     * which keys moved rather than just asserting that something did. */
+    startupFleetConfig = null;
+    /** Set when the file on disk and the in-memory config disagree on a
+     * startup-only key at startup. See checkStartupSignatureConsistency(). */
+    fleetSignatureMismatch = null;
     viewToken = null;
     healthServerListening = false;
     constructor(dataDir) {
@@ -548,26 +598,48 @@ export class FleetManager {
         this.scheduleReconcile();
     }
     scheduleReconcile() {
-        if (this.reconcileInFlight) {
+        const started = this.startExclusiveReconcile();
+        if (!started) {
             this.reloadPending = true;
             this.logger.info("Config reconciliation already running — coalesced reload request");
             return;
         }
-        this.reloadPending = false;
-        this.reconcileInFlight = this.reconcileInstances()
-            .catch(err => {
+        started.catch(err => {
             // Almost always a YAML parse error. Log-only meant the user edited
             // fleet.yaml, sent SIGHUP, and got no reaction and no explanation.
             this.logger.error({ err }, "SIGHUP config reload failed");
             const message = err instanceof Error ? err.message : String(err);
             this.notifyFleetError(t("fleet.reload_failed", message));
-        })
+        });
+    }
+    /**
+     * Take the reconcile slot, or refuse.
+     *
+     * Only one reconcile may touch lifecycle and config at a time — two of them
+     * stop and start the same instance in parallel. SIGHUP and a Settings apply
+     * are the same operation from two entrances, so they share the one slot: the
+     * signal coalesces into a pending replay, the apply is told the fleet is busy.
+     *
+     * The returned promise is the caller's to handle; the stored one is already
+     * handled, so a rejection never escapes as an unhandled rejection.
+     */
+    startExclusiveReconcile(observer) {
+        if (this.reconcileInFlight)
+            return null;
+        this.reloadPending = false;
+        let settle;
+        const caller = new Promise((resolve, reject) => {
+            settle = (err, outcome) => (err ? reject(err instanceof Error ? err : new Error(String(err))) : resolve(outcome ?? {}));
+        });
+        this.reconcileInFlight = this.reconcileInstances(observer)
+            .then(outcome => settle(null, outcome), err => settle(err))
             .finally(() => {
             this.reconcileInFlight = null;
             if (this.reloadPending && this.startupComplete) {
                 this.scheduleReconcile();
             }
         });
+        return caller;
     }
     /**
      * Is the fleet going down (or coming back up) on purpose?
@@ -583,6 +655,39 @@ export class FleetManager {
     }
     finishStartup() {
         this.startupComplete = true;
+        // Resolve whatever a previous run — or a setup host that crashed — left
+        // behind. A tunnel nobody is tracking is a public entrance nobody is
+        // watching, and the fleet starting is the moment there is finally a process
+        // around to notice. Never throws: a lease that cannot be resolved blocks
+        // the next tunnel and says so, it does not block the fleet.
+        this.announceToolPermissionsChange();
+        void reapStaleTunnel(this.dataDir)
+            .then(outcome => {
+            if (outcome.kind === "manual")
+                this.logger.warn({ tunnel: outcome }, manualCleanupMessage(outcome));
+            else if (outcome.kind === "reaped")
+                this.logger.info({ how: outcome.how, pid: outcome.pid }, "Reaped a leftover tunnel");
+        })
+            .catch(err => this.logger.warn({ err }, "Tunnel reaper failed"));
+        // An existing installation has never written the setup marker — it predates
+        // it — so `agend setup` would open a pre-fleet form for a fleet that plainly
+        // exists. A fleet that just came up on a config with agents in it is proof
+        // enough that setup happened.
+        if (Object.keys(this.fleetConfig?.instances ?? {}).length > 0 && !isSetupComplete(this.dataDir)) {
+            markSetupComplete(this.dataDir);
+        }
+        // After slimFleetConfigAtStartup() and the general/topic fixups, all of
+        // which may rewrite fleet.yaml — the baseline has to be what this process
+        // is actually running, compared against what a reconcile would load.
+        this.appliedFleetLevel = this.fleetLevelSignature();
+        this.startupFleetConfig = this.fleetConfig ? structuredClone(this.fleetConfig) : null;
+        this.checkStartupSignatureConsistency();
+        // A job from the process that just died cannot still be running here. The
+        // restart applied the saved config to every instance, so its open rows are
+        // finished — by the restart, which is what the user needs told.
+        for (const settled of this.applyJobs.settleAfterRestart()) {
+            this.logger.info({ jobId: settled.id }, "Settings apply job settled by fleet restart");
+        }
         // We are the post-update fleet: the update is over by definition. Clearing
         // it here (rather than in the update command, which exits before the new
         // fleet is up) is what keeps the quiet window from outliving the restart.
@@ -708,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);
@@ -1116,31 +1240,56 @@ export class FleetManager {
      */
     getActiveUsageProviderIds() {
         const providers = new Set();
-        for (const backend of this.getActiveBackendIds()) {
+        // Per instance, not per backend: two agents on two kiro subscriptions are
+        // two rows, and filtering by the bare backend id would hide both.
+        for (const [name, backend, profile] of this.activeBackendBindings()) {
+            void name;
             const provider = usageProviderIdForBackend(backend);
-            if (provider)
-                providers.add(provider);
+            if (!provider)
+                continue;
+            providers.add(profile ? `${provider}:${profile}` : provider);
         }
         return providers;
     }
-    /** Effective backends with a running or persisted-paused fleet/Classic instance. */
-    getActiveBackendIds() {
-        const backends = new Set();
-        const add = (name, backend) => {
+    /** Subscription providers used by the running/paused instances owned by one adapter. */
+    getUsageProviderIdsForAdapter(adapterId) {
+        const providers = new Set();
+        for (const [name, backend, profile] of this.activeBackendBindings()) {
+            if (this.getInstanceAdapterId(name) !== adapterId)
+                continue;
+            const provider = usageProviderIdForBackend(backend);
+            if (!provider)
+                continue;
+            providers.add(profile ? `${provider}:${profile}` : provider);
+        }
+        return providers;
+    }
+    /** `[instance, effective backend, credential profile]` for everything that is
+     * running or paused — the one place both usage views agree on who is live. */
+    activeBackendBindings() {
+        const bindings = [];
+        const add = (name, backend, profile) => {
             const status = this.getInstanceStatus(name);
             if (status !== "running" && status !== "paused")
                 return;
             if (backend)
-                backends.add(backend);
+                bindings.push([name, backend, profile]);
         };
         for (const [name, config] of Object.entries(this.fleetConfig?.instances ?? {})) {
             // loadFleetConfig() has already merged the fleet default into each row.
-            add(name, config.backend ?? this.fleetConfig?.defaults?.backend ?? "claude-code");
+            const backend = config.backend ?? this.fleetConfig?.defaults?.backend ?? "claude-code";
+            add(name, backend, instanceCredentialProfile(config, this.fleetConfig?.defaults, backend));
         }
         for (const channel of this.classicChannels?.getAll() ?? []) {
-            add(channel.instanceName, this.classicChannels?.getBackendByInstance(channel.instanceName, this.fleetConfig?.defaults?.backend));
+            const backend = this.classicChannels?.getBackendByInstance(channel.instanceName, this.fleetConfig?.defaults?.backend);
+            // Classic channels carry no backend_options, so they run the shared login.
+            add(channel.instanceName, backend, null);
         }
-        return backends;
+        return bindings;
+    }
+    /** Effective backends with a running or persisted-paused fleet/Classic instance. */
+    getActiveBackendIds() {
+        return new Set(this.activeBackendBindings().map(([, backend]) => backend));
     }
     isClassicInstance(name) {
         return this.classicChannels?.getAll().some(channel => channel.instanceName === name) ?? false;
@@ -1548,7 +1697,7 @@ export class FleetManager {
         if (!wasRunning)
             return;
         const hotOnly = changedFields.length > 0
-            && changedFields.every(field => field === "tool_progress" || field === "reply_completion_guard");
+            && changedFields.every(field => CLASSIC_HOT_CONFIG_KEYS.has(field));
         if (hotOnly) {
             this.applyHotConfigUpdate(instanceName, this.classicBehaviorUpdate(instanceName));
             this.logger.info({ instanceName, fields: changedFields }, "Classic instance hot config reloaded");
@@ -1945,6 +2094,22 @@ export class FleetManager {
             names.add(channel.instanceName);
         return [...names];
     }
+    /**
+     * Probe the same executable set exposed by the web backend catalog.
+     *
+     * This deliberately has no cache: an `/install-cli` completion can add a
+     * binary to PATH while the fleet process remains alive, and the next bare
+     * `/login` must see it without requiring a restart or an explicit cache
+     * invalidation call.
+     */
+    probeInstalledBackends() {
+        const installed = new Set();
+        for (const [backend, info] of Object.entries(BACKEND_INSTALLATION_INFO)) {
+            if (checkBinaryInstalled(info.binary))
+                installed.add(backend);
+        }
+        return installed;
+    }
     /**
      * One fleet-level notice per burst, not one per instance: a post-update herd
      * fails many instances within the same second. Two notices per incident at
@@ -2174,7 +2339,9 @@ export class FleetManager {
     }
     /** Initialize auth before any adapter can answer /dashboard. */
     initializeWebAuthTokens() {
-        this.webToken = loadOrCreateWebToken(this.dataDir);
+        // Creates web.token if absent; the value is then read back per request by
+        // the `webToken` getter, so nothing is cached here.
+        loadOrCreateWebToken(this.dataDir);
         this.viewToken = randomBytes(24).toString("hex");
         const viewTokenPath = join(this.dataDir, "view.token");
         writeFileSync(viewTokenPath, this.viewToken, { encoding: "utf8", mode: 0o600 });
@@ -2738,6 +2905,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.
@@ -2886,6 +3054,53 @@ 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 {
+                // Fetch the shared snapshot once, then scope the projection to each
+                // adapter's own fleet/Classic instances.  Passing the fleet-wide active
+                // set here would make every bot advertise providers owned by a sibling
+                // bot (notably ClassicBot's Grok/Antigravity rows).
+                const payload = await getUsageSnapshot(false);
+                for (const adapter of targets) {
+                    try {
+                        const scoped = filterUsageProviders(payload, this.getUsageProviderIdsForAdapter(adapter.id));
+                        adapter.setActivity?.(formatDiscordUsageActivity(scoped));
+                    }
+                    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");
+            }
+        })();
+        const done = run.finally(() => {
+            if (this.discordPresenceInFlight === done)
+                this.discordPresenceInFlight = null;
+        });
+        this.discordPresenceInFlight = done;
+        return done;
+    }
     /**
      * Delete inbox files older than retentionDays (by mtime). Cleans the shared
      * inbox (`<dataDir>/inbox`) and every workspace inbox
@@ -3003,6 +3218,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"
@@ -3083,7 +3303,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");
@@ -3091,7 +3311,9 @@ export class FleetManager {
         }
         const accessDir = join(this.dataDir, "access");
         mkdirSync(accessDir, { recursive: true });
-        const accessManager = new AccessManager(channelConfig.access ?? DEFAULT_OPEN_ACCESS, join(accessDir, "access.json"));
+        const accessStatePath = join(accessDir, "access.json");
+        const accessManager = new AccessManager(channelConfig.access ?? DEFAULT_OPEN_ACCESS, accessStatePath);
+        this.warnIfAccessModeOverridden(accessManager, accessStatePath);
         this.accessManager = accessManager;
         const inboxDir = join(this.dataDir, "inbox");
         mkdirSync(inboxDir, { recursive: true });
@@ -3107,13 +3329,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))
@@ -3154,6 +3383,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);
             }
@@ -3433,6 +3664,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.
@@ -3444,6 +3677,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`);
@@ -3452,10 +3686,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.
@@ -3467,6 +3705,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(() => {
@@ -3474,7 +3715,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) {
@@ -3483,7 +3724,9 @@ export class FleetManager {
         }
         const accessDir = join(this.dataDir, "access");
         mkdirSync(accessDir, { recursive: true });
-        const accessManager = new AccessManager(channelConfig.access ?? DEFAULT_OPEN_ACCESS, join(accessDir, `access-${adapterId}.json`));
+        const accessStatePath = join(accessDir, `access-${adapterId}.json`);
+        const accessManager = new AccessManager(channelConfig.access ?? DEFAULT_OPEN_ACCESS, accessStatePath);
+        this.warnIfAccessModeOverridden(accessManager, accessStatePath);
         const inboxDir = join(this.dataDir, "inbox");
         mkdirSync(inboxDir, { recursive: true });
         const adapter = await createAdapter(channelConfig, {
@@ -3497,14 +3740,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))
@@ -3545,6 +3795,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);
             }
@@ -3768,6 +4020,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) {
@@ -3775,14 +4029,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(() => { });
         });
@@ -3791,6 +4050,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 */
@@ -3861,22 +4123,15 @@ export class FleetManager {
                     }
                     await this.handleOutboundFromInstance(name, msg);
                 }
-                else if (msg.type === "fleet_schedule_create" || msg.type === "fleet_schedule_list" ||
-                    msg.type === "fleet_schedule_update" || msg.type === "fleet_schedule_delete") {
-                    this.handleScheduleCrud(name, msg);
-                }
-                else if (msg.type === "fleet_decision_create" || msg.type === "fleet_decision_list" ||
-                    msg.type === "fleet_decision_update") {
-                    this.handleDecisionCrud(name, msg);
-                }
-                else if (msg.type === "fleet_task") {
-                    this.handleTaskCrud(name, msg);
-                }
-                else if (msg.type === "fleet_set_display_name") {
-                    this.handleSetDisplayName(name, msg);
-                }
-                else if (msg.type === "fleet_set_description") {
-                    this.handleSetDescription(name, msg);
+                else if (toolForIpcType(msg.type) !== null) {
+                    // Sink 2 of 3. Each of these types IS a tool and reaches its own
+                    // handler without passing through the outbound path — which is how
+                    // `update_decision`, a coordinator-only tool, kept a way through.
+                    const typed = this.checkToolPermission("ipc-typed", name, toolForIpcType(msg.type));
+                    if (typed.allowed)
+                        this.dispatchTypedIpc(name, msg);
+                    else
+                        this.refuseTypedIpc(name, msg, typed.message);
                 }
                 else if (msg.type === "instance_process_state") {
                     this.cacheInstanceProcessStatus(name, msg.status);
@@ -4040,6 +4295,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) {
@@ -4065,6 +4323,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) {
@@ -4245,13 +4506,36 @@ export class FleetManager {
         const target = this.routing.resolve(threadId);
         if (!target)
             return "fleet topic: no instance routed for this thread";
-        // Fleet topic: allow if collab enabled OR access mode is open
+        // Fleet topic: this gate lets the copy through when the adapter is open OR
+        // collab is on for the instance. "Through" is not "delivered" — access
+        // control runs next, and the two arms are not symmetric there:
+        //
+        //   open adapter   → isAllowed() returns true outright: really admitted.
+        //   locked + collab → the bot's user id still has to be on the allowlist,
+        //                     so the message is normally refused a few lines later
+        //                     under "Access DENIED for non-allowed user".
+        //
+        // Collab alone therefore does not admit a bot on a locked adapter; it only
+        // declines to drop the copy here and leaves the decision to access control.
         const isOpen = this.getChannelConfig(msg.adapterId)?.access?.mode === "open";
         if (!isOpen && !this.collabInstances.has(target.name)) {
             return `fleet topic: adapter not open and collab off for ${target.name}`;
         }
         return null;
     }
+    /**
+     * Say so when an adapter's access mode is coming from its state file rather
+     * than from fleet.yaml. The state file wins by design — a pairing done at
+     * runtime has to survive a restart — but that also means an edit to
+     * `access.mode` silently does nothing, which is indistinguishable from the
+     * fleet not having reloaded. Naming the file is what makes it fixable.
+     */
+    warnIfAccessModeOverridden(accessManager, statePath) {
+        const configured = accessManager.overriddenConfigMode();
+        if (!configured)
+            return;
+        this.logger.warn({ statePath, configured, inEffect: accessManager.getMode() }, `access mode "${accessManager.getMode()}" comes from the state file and overrides "${configured}" in fleet.yaml; delete ${statePath} to go back to the configured value`);
+    }
     async handleInboundMessage(msg) {
         const threadId = msg.threadId || undefined;
         this.logger.debug({ source: msg.source, chatId: msg.chatId, threadId, userId: msg.userId, isBotMessage: msg.isBotMessage, textLen: (msg.text ?? "").length, text: (msg.text ?? "").slice(0, 80) }, "handleInboundMessage entry");
@@ -4818,6 +5102,55 @@ export class FleetManager {
         }
     }
     /** Handle outbound tool calls from a daemon instance */
+    /**
+     * Would this instance be allowed to use this tool?
+     *
+     * Stage 1 asks and records; nothing is refused yet. The recording is not only
+     * an observation window: `logActivity("tool_call")` sits on the outbound path
+     * only, so today the fleet has no idea what the agent endpoint or the typed
+     * IPC handlers are being asked to do — the one face with no authorization is
+     * also the one face with no telemetry.
+     *
+     * The profile comes from the instance the socket belongs to. Deliberately not
+     * `senderSessionName`, which arrives inside the message: a caller that fills
+     * in its own identity has not been identified.
+     */
+    /**
+     * Say once, at startup, what the new default means for this fleet.
+     *
+     * Nothing is rewritten: an explicit `tool_set: full` is a choice somebody
+     * made, and marking an instance as a coordinator is a judgement about how
+     * their fleet is organised. Both stay theirs — this only makes sure they are
+     * not discovered by an agent failing at three in the morning.
+     */
+    announceToolPermissionsChange() {
+        try {
+            const thirtyDaysAgo = new Date(Date.now() - 30 * 864e5).toISOString().slice(0, 19).replace("T", " ");
+            const recent = [...(this.eventLog?.toolUseByInstance(thirtyDaysAgo) ?? new Map())]
+                .map(([instance, tools]) => ({ instance, tools }));
+            const notice = buildToolPermissionsNotice({
+                defaultsToolSet: this.fleetConfig?.defaults?.tool_set,
+                instances: (this.fleetConfig?.instances ?? {}),
+                recent,
+            });
+            if (notice)
+                this.logger.warn({ notice }, notice);
+        }
+        catch (err) {
+            // Advice is not worth failing a startup over.
+            this.logger.debug({ err }, "tool-permissions: could not build the migration notice");
+        }
+    }
+    checkToolPermission(sink, instanceName, tool) {
+        const profile = resolveToolSet(this.fleetConfig?.instances[instanceName], instanceName);
+        const allowed = mayUseTool(profile, tool);
+        if (!allowed) {
+            this.logger.warn({ sink, instance: instanceName, profile, tool, enforced: true }, "tool-permissions: refused");
+            return { allowed: false, message: toolRefusedMessage(profile, tool) };
+        }
+        this.logger.debug({ sink, instance: instanceName, profile, tool, enforced: true }, "tool-permissions: allowed");
+        return { allowed: true, message: "" };
+    }
     async handleOutboundFromInstance(instanceName, msg) {
         this.touchActivity(instanceName);
         this.setTopicIcon(instanceName, "green");
@@ -4839,6 +5172,19 @@ export class FleetManager {
                 this.logger.warn({ instanceName, tool, requestId, fleetRequestId, error }, "Fleet outbound result could not be returned — instance IPC is disconnected");
             }
         };
+        // Sink 1 of 3, and the first thing decided. Every MCP call and every direct
+        // write to channel.sock lands here, whether or not mcp-server was ever
+        // involved — which is why this is the boundary and the tool list the model
+        // was shown is not.
+        //
+        // Above the adapter check on purpose: "retry shortly" is the wrong answer
+        // to a call that will never be allowed, and an agent that believes it is a
+        // timing problem will keep trying.
+        const permitted = this.checkToolPermission("ipc-outbound", instanceName, tool);
+        if (!permitted.allowed) {
+            respond(null, permitted.message);
+            return;
+        }
         if (this.worlds.size === 0) {
             respond(null, "Channel adapters are not ready — retry shortly");
             return;
@@ -5096,6 +5442,15 @@ export class FleetManager {
      */
     scheduleSourceAdapter(schedule) {
         const chatId = String(schedule.reply_chat_id);
+        // New schedules carry the adapter that owned the source chat at creation.
+        // Keep that persona across source-instance rebinding, but never trust a
+        // stale adapter after the chat has moved to another world.
+        const persistedWorld = schedule.reply_adapter_id
+            ? this.worlds.get(schedule.reply_adapter_id)
+            : undefined;
+        if (persistedWorld && String(persistedWorld.groupId) === chatId) {
+            return persistedWorld.adapter;
+        }
         const sourceAdapterId = schedule.source ? this.getInstanceAdapterId(schedule.source) : undefined;
         const sourceWorld = sourceAdapterId ? this.worlds.get(sourceAdapterId) : undefined;
         if (sourceWorld && String(sourceWorld.groupId) === chatId)
@@ -5127,6 +5482,58 @@ export class FleetManager {
             threadId: schedule.reply_thread_id ?? undefined,
         }).catch((err) => this.logger.error({ err }, "Failed to send schedule failure notification"));
     }
+    /**
+     * The typed IPC messages, all through one door.
+     *
+     * They used to be five sibling branches on the dispatch, which is why the
+     * permission question had five places to be forgotten. Routing them together
+     * means the check above happens once and cannot be skipped by adding a
+     * sixth — a new type has to appear in `IPC_TYPE_TOOLS` to be dispatched at
+     * all.
+     */
+    /**
+     * Answer a refused typed message the way its handler would have.
+     *
+     * These are request/response over IPC: dropping the message silently leaves
+     * the caller waiting for a reply that never comes, and a hung agent is a
+     * worse failure than a refused one.
+     */
+    refuseTypedIpc(name, msg, message) {
+        const ipc = this.instanceIpcClients.get(name);
+        const fleetRequestId = msg.fleetRequestId;
+        if (!ipc || !fleetRequestId)
+            return;
+        const type = String(msg.type);
+        const responseType = type.startsWith("fleet_schedule_") ? "fleet_schedule_response"
+            : type.startsWith("fleet_decision_") ? "fleet_decision_response"
+                : type === "fleet_task" ? "fleet_task_response"
+                    : type === "fleet_set_display_name" ? "fleet_display_name_response"
+                        : "fleet_description_response";
+        ipc.send({ type: responseType, fleetRequestId, error: message });
+    }
+    dispatchTypedIpc(name, msg) {
+        const type = String(msg.type);
+        if (type.startsWith("fleet_schedule_")) {
+            this.handleScheduleCrud(name, msg);
+            return;
+        }
+        if (type.startsWith("fleet_decision_")) {
+            this.handleDecisionCrud(name, msg);
+            return;
+        }
+        if (type === "fleet_task") {
+            this.handleTaskCrud(name, msg);
+            return;
+        }
+        if (type === "fleet_set_display_name") {
+            this.handleSetDisplayName(name, msg);
+            return;
+        }
+        if (type === "fleet_set_description") {
+            this.handleSetDescription(name, msg);
+            return;
+        }
+    }
     handleScheduleCrud(instanceName, msg) {
         const fleetRequestId = msg.fleetRequestId;
         const payload = (msg.payload ?? {});
@@ -5134,36 +5541,27 @@ export class FleetManager {
         const ipc = this.instanceIpcClients.get(instanceName);
         if (!ipc)
             return;
+        if (!this.scheduler) {
+            // It did answer before, with whatever TypeError fell out of the try
+            // block — "Cannot read properties of null (reading 'list')" is a stack
+            // trace wearing an error message, and the agent reading it cannot tell
+            // that the fleet simply has no scheduler.
+            ipc.send({ type: "fleet_schedule_response", fleetRequestId, error: "Schedules are unavailable — the fleet scheduler is not running" });
+            return;
+        }
         try {
-            let result;
-            switch (msg.type) {
-                case "fleet_schedule_create": {
-                    const params = {
-                        cron: payload.cron,
-                        at: payload.at,
-                        message: payload.message,
-                        source: instanceName,
-                        target: payload.target || instanceName,
-                        reply_chat_id: meta.chat_id,
-                        reply_thread_id: meta.thread_id || null,
-                        label: payload.label,
-                        timezone: payload.timezone,
-                        silent: !!(payload.silent),
-                    };
-                    result = this.scheduler.create(params);
-                    break;
-                }
-                case "fleet_schedule_list":
-                    result = this.scheduler.list(payload.target);
-                    break;
-                case "fleet_schedule_update":
-                    result = this.scheduler.update(payload.id, payload);
-                    break;
-                case "fleet_schedule_delete":
-                    this.scheduler.delete(payload.id);
-                    result = "ok";
-                    break;
-            }
+            const op = String(msg.type).replace("fleet_schedule_", "");
+            const result = this.performScheduleOp(instanceName, op, payload, {
+                // The daemon sends its last chat id, which is unset until the instance
+                // has had a chat message — and cross-instance traffic never sets it. So
+                // a worker that only takes delegated tasks, the very instance #895 lets
+                // self-schedule, hit "NOT NULL constraint failed: schedules.reply_chat_id".
+                // No chat means no reply chat, exactly as on the agent endpoint.
+                chatId: meta.chat_id ?? "",
+                threadId: meta.thread_id || null,
+                adapterId: meta.adapter_id || null,
+                silent: !!(payload.silent),
+            });
             ipc.send({ type: "fleet_schedule_response", fleetRequestId, result });
         }
         catch (err) {
@@ -5175,8 +5573,15 @@ export class FleetManager {
         const payload = (msg.payload ?? {});
         const meta = (msg.meta ?? {});
         const ipc = this.instanceIpcClients.get(instanceName);
-        if (!ipc || !this.scheduler)
+        if (!ipc)
             return;
+        if (!this.scheduler) {
+            // Returning silently left the caller waiting for a response that was
+            // never coming. Over IPC that is a hang, and a hang is a worse answer
+            // than an error.
+            ipc.send({ type: "fleet_decision_response", fleetRequestId, error: "Decisions are unavailable — the fleet scheduler is not running" });
+            return;
+        }
         const db = this.scheduler.db;
         const projectRoot = meta.working_directory || this.fleetConfig?.instances[instanceName]?.working_directory || "";
         try {
@@ -5292,23 +5697,76 @@ export class FleetManager {
     async handleScheduleCrudHttp(instance, op, args) {
         if (!this.scheduler)
             return { error: "Scheduler not available" };
+        if (op !== "create" && op !== "list" && op !== "update" && op !== "delete") {
+            return { error: `Unknown schedule op: ${op}` };
+        }
+        // No bound chat on this path, as before: a schedule made through the agent
+        // endpoint has nowhere of its own to reply.
+        return this.performScheduleOp(instance, op, args, { chatId: "", threadId: null });
+    }
+    /**
+     * The only place an agent's request creates, changes or removes a schedule
+     * (#895). The IPC handler (MCP calls, direct channel.sock writes) and the
+     * agent endpoint (agent-cli, HTTP agent mode) are adapters over this, so the
+     * target check cannot be present on one face and missing on the other — the
+     * shape #804 had to close twice.
+     *
+     * `caller` is the instance the server resolved for the request; any
+     * `source` in `args` is ignored, and a schedule's source is always its caller.
+     * A refusal is a ToolNotPermittedError: 403 on the agent endpoint, the error
+     * of the schedule response on IPC.
+     */
+    performScheduleOp(caller, op, args, reply) {
+        const scheduler = this.scheduler;
+        // Shape first, so the value the permission decision reads is the value the
+        // scheduler gets. `target` used to be filtered through typeof for the
+        // decision and passed raw to the scheduler, whose `target.startsWith`
+        // then threw a TypeError for `target: 123` (#897). A non-string is refused
+        // — never coerced: turning 123 into "123" would decide an identity
+        // question on a value the caller did not send. `null` means absent, as
+        // omitting it always did, and is removed before the scheduler sees it.
+        if (args.target === null) {
+            args = { ...args };
+            delete args.target;
+        }
+        if (args.target !== undefined && typeof args.target !== "string") {
+            throw new Error(`${op}_schedule: "target" must be an instance name (a string), not ${typeof args.target}.`);
+        }
+        if ((op === "update" || op === "delete") && typeof args.id !== "string") {
+            throw new Error(`${op}_schedule: "id" must be a schedule id (a string) — get one from list_schedules.`);
+        }
+        const requestedTarget = args.target;
+        if (op !== "list") {
+            const profile = resolveToolSet(this.fleetConfig?.instances[caller], caller);
+            const existing = op === "create" ? null : scheduler.get(args.id);
+            const refusal = scheduleOpRefusal(profile, caller, op, { requestedTarget, existing });
+            if (refusal) {
+                this.logger.warn({ instance: caller, profile, op, target: requestedTarget ?? existing?.target, scheduleId: args.id }, "tool-permissions: schedule op refused");
+                throw new ToolNotPermittedError(refusal);
+            }
+        }
         switch (op) {
             case "create":
-                return this.scheduler.create({
+                return scheduler.create({
                     cron: args.cron,
                     at: args.at,
                     message: args.message,
-                    source: instance, target: args.target || instance,
-                    reply_chat_id: "", reply_thread_id: null,
+                    source: caller,
+                    target: requestedTarget || caller,
+                    reply_chat_id: reply.chatId,
+                    reply_thread_id: reply.threadId,
+                    ...(reply.adapterId !== undefined ? { reply_adapter_id: reply.adapterId } : {}),
                     label: args.label,
                     timezone: args.timezone,
+                    ...(reply.silent !== undefined ? { silent: reply.silent } : {}),
                 });
-            case "list": return this.scheduler.list(args.target);
-            case "update": return this.scheduler.update(args.id, args);
+            case "list":
+                return scheduler.list(requestedTarget);
+            case "update":
+                return scheduler.update(args.id, args);
             case "delete":
-                this.scheduler.delete(args.id);
+                scheduler.delete(args.id);
                 return "ok";
-            default: return { error: `Unknown schedule op: ${op}` };
         }
     }
     async handleDecisionCrudHttp(instance, op, args) {
@@ -5450,8 +5908,15 @@ export class FleetManager {
         const payload = (msg.payload ?? {});
         const meta = (msg.meta ?? {});
         const ipc = this.instanceIpcClients.get(instanceName);
-        if (!ipc || !this.scheduler)
+        if (!ipc)
+            return;
+        if (!this.scheduler) {
+            // Returning silently left the caller waiting for a response that was
+            // never coming. Over IPC that is a hang, and a hang is a worse answer
+            // than an error.
+            ipc.send({ type: "fleet_task_response", fleetRequestId, error: "The task board is unavailable — the fleet scheduler is not running" });
             return;
+        }
         const db = this.scheduler.db;
         const action = payload.action;
         try {
@@ -6799,6 +7264,39 @@ export class FleetManager {
      * (or an assist for one they stopped) must not stay clickable for the rest
      * of its 15 minutes.
      */
+    /**
+     * Collapse every still-armed button prompt, for a fleet that is going away.
+     *
+     * The map is in memory; the buttons are in the chat for up to 24 hours. A
+     * restart therefore leaves them looking live — pressing one takes the stale
+     * branch, which acknowledges the click and drops the dismissal without
+     * saying so. Retiring them here means the user meets a spent prompt instead
+     * of a live-looking dead one.
+     *
+     * Best effort and bounded. Each collapse is a platform call, a day of tips
+     * can be many of them, and shutdown still has instances to stop. Whatever
+     * has not finished by the deadline is abandoned — that is exactly today's
+     * behaviour, so the budget can only leave things no worse than before.
+     */
+    async retirePendingNoncePrompts(budgetMs = NONCE_RETIRE_BUDGET_MS) {
+        const entries = [...this.pendingNonceButtons.values()];
+        this.pendingNonceButtons.clear();
+        for (const entry of entries)
+            if (entry.timer)
+                clearTimeout(entry.timer);
+        const collapses = entries
+            .filter(entry => entry.messageId && entry.adapter.editMessageRemoveButtons)
+            .map(entry => entry.adapter.editMessageRemoveButtons(entry.chatId, entry.messageId, entry.expiredText, entry.threadId).catch(err => this.logger.debug({ err, instanceName: entry.instanceName, prefix: entry.prefix }, "Failed to retire button prompt during shutdown")));
+        if (!collapses.length)
+            return;
+        await Promise.race([
+            Promise.allSettled(collapses),
+            new Promise(resolve => {
+                const timer = setTimeout(resolve, budgetMs);
+                timer.unref?.();
+            }),
+        ]);
+    }
     clearNoncePromptsForInstance(instanceName) {
         for (const [nonce, entry] of this.pendingNonceButtons) {
             if (entry.instanceName !== instanceName)
@@ -7739,11 +8237,39 @@ export class FleetManager {
         for (const name of this.configuredBackendInstanceNames()) {
             configured.add(this.backendNameOf(name));
         }
-        const choices = Object.keys(LOGIN_FLOWS)
-            .filter(backend => configured.size === 0 || configured.has(backend))
-            .map(backend => ({ action: backend, label: backend }));
+        const installed = this.probeInstalledBackends();
+        const candidates = new Set([...installed, ...configured]);
+        const unsupported = [];
+        const choices = [...candidates].sort().flatMap(backend => {
+            const flow = LOGIN_FLOWS[backend];
+            const remoteLogin = !!flow && flow.remoteLogin !== "unsupported";
+            const status = [];
+            if (installed.has(backend))
+                status.push(t("login.status_installed"));
+            if (configured.has(backend))
+                status.push(t("login.status_configured"));
+            if (remoteLogin)
+                status.push(t("login.status_auth"));
+            else
+                status.push(t("login.status_unsupported"));
+            if (!remoteLogin) {
+                unsupported.push({ backend, flow, status });
+                return [];
+            }
+            return [{ action: backend, label: `${backend} · ${status.join(" · ")}` }];
+        });
+        if (unsupported.length) {
+            const guidance = unsupported.map(({ backend, flow, status }) => `${backend} · ${status.join(" · ")} — ${flow?.remoteLogin === "unsupported"
+                ? t("login.remote_unsupported_agent_cli", backend, flow.command)
+                : backend === "opencode" ? t("login.unsupported", backend) : t("login.no_remote_flow", backend)}`).join("\n");
+            await chat.adapter.sendText(chat.chatId, guidance, { threadId: chat.threadId })
+                .catch(err => this.logger.warn({ err }, "Failed to post unsupported login guidance"));
+        }
         if (choices.length === 0) {
-            await chat.adapter.sendText(chat.chatId, t("login.unsupported", [...configured].join(", ")), { threadId: chat.threadId });
+            if (!unsupported.length) {
+                await chat.adapter.sendText(chat.chatId, t("login.none_available"), { threadId: chat.threadId })
+                    .catch(err => this.logger.warn({ err }, "Failed to post empty login chooser guidance"));
+            }
             return;
         }
         await this.postNonceButtonPrompt({
@@ -8332,6 +8858,12 @@ export class FleetManager {
                     await chat.adapter.sendText(chat.chatId, t("install.success_no_login", backend), { threadId: chat.threadId }).catch(() => { });
                     return;
                 }
+                // The button is deliberately best-effort: it is a short-lived
+                // capability and can be lost during an adapter reconnect.  Always
+                // publish a durable completion line first so a successful install can
+                // never look like it silently disappeared.  Include the binary that
+                // passed the fresh-login-shell verification and the exact next step.
+                await chat.adapter.sendText(chat.chatId, t("install.success", backend, info.binary), { threadId: chat.threadId }).catch(err => this.logger.warn({ err, backend }, "Failed to send durable install success notification"));
                 await this.postNonceButtonPrompt({
                     prefix: INSTALL_LOGIN_CALLBACK_PREFIX,
                     alertType: "login",
@@ -8583,6 +9115,8 @@ export class FleetManager {
         // Grok reads AGENTS.md project docs; agy reads .agents/agents.md — the
         // same files their writeConfig() appends fleet instructions to.
         "grok": "AGENTS.md",
+        // muse init scaffolds AGENTS.md and the binary reads it as project rules.
+        "muse": "AGENTS.md",
         "antigravity": ".agents/agents.md",
         "mock": "CLAUDE.md",
     };
@@ -8658,6 +9192,9 @@ Plus the operational skills (fleet-health, instance-lifecycle, scheduling, sessi
         // vendor-canonical location is .grok/skills.
         "opencode": [".agents", "skills"],
         "grok": [".grok", "skills"],
+        // Live-verified on muse 1.3.0: `muse skills list --source project` sees
+        // .agents/skills and ignores .muse/skills.
+        "muse": [".agents", "skills"],
         "antigravity": [".agents", "skills"],
     };
     /** Copy general-knowledge steering + all role-eligible skills to General. */
@@ -9242,8 +9779,8 @@ Plus the operational skills (fleet-health, instance-lifecycle, scheduling, sessi
      * A model list is an aid: a vendor that stops answering must degrade to the
      * previous list, never stall the command that asked for it.
      */
-    async probeBackendBounded(backend) {
-        const work = this.probeBackend(backend);
+    async probeBackendBounded(backend, opts = {}) {
+        const work = this.probeBackend(backend, opts);
         work.catch(() => { });
         let timer;
         const deadline = new Promise(resolve => {
@@ -9307,12 +9844,23 @@ Plus the operational skills (fleet-health, instance-lifecycle, scheduling, sessi
         const label = option.description ? `${option.label} — ${option.description}` : option.label;
         return option.id === currentModel ? `✓ ${label}` : label;
     }
-    /** Probe one backend's CLI env and cache it. Best-effort; never throws. */
-    async probeBackend(backend) {
+    /**
+     * Probe one backend's CLI env and cache it. Best-effort; never throws.
+     *
+     * `refreshVendorCatalog` is the "🔄 Refresh models" path only (#886): first
+     * ask the CLI to refetch its own catalog, for backends whose probe merely
+     * reads a file the CLI maintains. Every other caller leaves it off, so the
+     * startup and /model probes behave exactly as before. A failed vendor
+     * refresh fails the probe (null), which the menu reports instead of passing
+     * the old list off as fresh.
+     */
+    async probeBackend(backend, opts = {}) {
         try {
             const be = createBackend(backend, join(getAgendHome(), "cli-env"));
             if (!be.probeCLIEnv)
                 return null;
+            if (opts.refreshVendorCatalog && be.refreshModelCatalog)
+                await be.refreshModelCatalog();
             const probed = await be.probeCLIEnv({ workingDirectory: "", instanceDir: join(getAgendHome(), "cli-env"), instanceName: `probe-${backend}`, mcpServers: {} });
             const env = { backend, probedAt: Date.now(), ...probed };
             // An empty result must never overwrite a catalog we already have. Some
@@ -9361,22 +9909,48 @@ Plus the operational skills (fleet-health, instance-lifecycle, scheduling, sessi
     }
     /** Best-effort model list for `/model`: cached CLI env first, else live probe. Never throws. */
     async getModelOptions(instanceName, refresh = false, onLiveProbe) {
+        return (await this.getModelOptionsWithSource(instanceName, { refresh, onLiveProbe })).models;
+    }
+    /**
+     * The model list plus where it came from. `source` is "live" only when a probe
+     * actually ran and answered; a refresh that failed or ran out of time reports
+     * "cache" with the previous list, so a menu can say "could not refresh"
+     * instead of presenting an old list as a fresh one.
+     */
+    async getModelOptionsWithSource(instanceName, opts = {}) {
         const backendName = this.backendNameForInstance(instanceName);
         const cached = this.readCliEnv(backendName);
-        if (!refresh && cached?.models.length && !this.cliEnvNeedsRefresh(cached))
-            return cached.models;
+        if (!opts.refresh && cached?.models.length && !this.cliEnvNeedsRefresh(cached)) {
+            return { models: cached.models, source: "cache" };
+        }
         // About to go to the vendor: let the caller say so. A silent 1–10s pause on
         // an interactive command reads as another hang, which is the wrong lesson to
         // teach a user who has just been bitten by one.
-        onLiveProbe?.();
+        opts.onLiveProbe?.();
         // Stale, missing, or a forced refresh → probe live (also refreshes the cache).
         // A newly released model is invisible until this runs, which is why staleness
         // triggers it rather than waiting for the 24h hard expiry or a cold start.
-        const env = await this.probeBackendBounded(backendName);
+        const env = await this.probeBackendBounded(backendName, { refreshVendorCatalog: opts.refreshVendorCatalog });
         if (env?.models.length)
-            return env.models;
+            return { models: env.models, source: "live" };
         // Probe failed or timed out: the previous list is still the best answer.
-        return cached?.models ?? [];
+        return { models: cached?.models ?? [], source: "cache" };
+    }
+    /**
+     * The /model menu's choices, in the one order all three pickers share:
+     * 🔄 Refresh first, then models, then (claude) "More models…". Refresh takes
+     * a slot inside Discord's 25-option select cap, so it is paid for from the
+     * model rows, never from "More models…".
+     */
+    modelMenuChoices(instanceName, nonce, options, currentModel) {
+        const isClaude = this.backendNameForInstance(instanceName) === "claude-code";
+        const choices = [{ id: `${MODEL_SELECT_CALLBACK_PREFIX}${nonce}:__refresh__`, label: t("model.refresh") }];
+        for (const o of options.slice(0, isClaude ? 23 : 24)) {
+            choices.push({ id: `${MODEL_SELECT_CALLBACK_PREFIX}${nonce}:${o.id}`, label: this.modelChoiceLabel(o, currentModel) });
+        }
+        if (isClaude)
+            choices.push({ id: `${MODEL_SELECT_CALLBACK_PREFIX}${nonce}:__more__`, label: t("model.more") });
+        return choices;
     }
     /**
      * Model catalog behind the `list_models` tool.
@@ -9677,14 +10251,7 @@ Plus the operational skills (fleet-health, instance-lifecycle, scheduling, sessi
         // Raw id for ✓-matching options; display resolves an inherited CLI default.
         const { model: currentModel, display: currentDisplay } = this.resolveInstanceModel(name);
         const nonce = randomBytes(6).toString("hex");
-        const isClaude = this.backendNameForInstance(name) === "claude-code";
-        const choices = options.slice(0, isClaude ? 24 : 25).map(o => ({
-            id: `${MODEL_SELECT_CALLBACK_PREFIX}${nonce}:${o.id}`,
-            label: this.modelChoiceLabel(o, currentModel),
-        }));
-        if (isClaude) {
-            choices.push({ id: `${MODEL_SELECT_CALLBACK_PREFIX}${nonce}:__more__`, label: t("model.more") });
-        }
+        const choices = this.modelMenuChoices(name, nonce, options, currentModel);
         const timer = setTimeout(() => this.pendingModelSelects.delete(nonce), CLASSIC_BACKEND_SELECTION_TIMEOUT_MS);
         timer.unref?.();
         this.pendingModelSelects.set(nonce, { instanceName: name, model: "", userId: data.userId, channelId: data.channelId, timer, respond: data.respond, respondChoices: data.respondChoices });
@@ -9710,15 +10277,7 @@ Plus the operational skills (fleet-health, instance-lifecycle, scheduling, sessi
         }
         const { model: currentModel, display: currentDisplay } = this.resolveInstanceModel(instanceName);
         const nonce = randomBytes(6).toString("hex");
-        const isClaude = this.backendNameForInstance(instanceName) === "claude-code";
-        // Keep the more-models entry inside Discord's 25-option select cap.
-        const choices = options.slice(0, isClaude ? 24 : 25).map(o => ({
-            id: `${MODEL_SELECT_CALLBACK_PREFIX}${nonce}:${o.id}`,
-            label: this.modelChoiceLabel(o, currentModel),
-        }));
-        if (isClaude) {
-            choices.push({ id: `${MODEL_SELECT_CALLBACK_PREFIX}${nonce}:__more__`, label: t("model.more") });
-        }
+        const choices = this.modelMenuChoices(instanceName, nonce, options, currentModel);
         const respond = async (text) => {
             await adapter.sendText(chatId, text, { threadId });
             return undefined;
@@ -9802,6 +10361,64 @@ Plus the operational skills (fleet-health, instance-lifecycle, scheduling, sessi
             await pending.respond(t("model.more_unavailable")).catch(() => { });
         }
     }
+    /**
+     * "🔄 Refresh models" (#886): probe live past both caches and redraw the menu.
+     *
+     * Past AgEnD's cli-env cache (refresh=true) and, where the backend supports
+     * it, past the CLI's own catalog cache too (codex: `codex debug models`).
+     * Without the second half, a codex refresh re-read the same models_cache.json
+     * and showed the old list as new.
+     *
+     * A failed refresh keeps the previous list and says so. It never blanks the
+     * menu, because a picker with no rows cannot even offer another refresh.
+     */
+    async refreshModelMenu(pending) {
+        const { models, source } = await this.getModelOptionsWithSource(pending.instanceName, {
+            refresh: true, refreshVendorCatalog: true,
+        });
+        if (models.length === 0) {
+            await pending.respond(t("model.list_unavailable", pending.instanceName)).catch(() => { });
+            return;
+        }
+        const { model: currentModel, display: currentDisplay } = this.resolveInstanceModel(pending.instanceName);
+        const nonce = randomBytes(6).toString("hex");
+        const choices = this.modelMenuChoices(pending.instanceName, nonce, models, currentModel);
+        const status = source === "live" ? t("model.refreshed") : t("model.refresh_failed");
+        const timer = setTimeout(() => {
+            const p = this.pendingModelSelects.get(nonce);
+            if (p) {
+                this.pendingModelSelects.delete(nonce);
+                p.respond(t("model.selection_expired")).catch(() => { });
+            }
+        }, CLASSIC_BACKEND_SELECTION_TIMEOUT_MS);
+        timer.unref?.();
+        this.pendingModelSelects.set(nonce, { ...pending, model: "", timer });
+        try {
+            if (pending.respondChoices) {
+                // Discord select menu: edit the same interaction reply in place.
+                await pending.respondChoices(`${status}\n${t("model.menu", `**${currentDisplay}**`)}`, choices);
+                return;
+            }
+            if (pending.adapter && pending.adapterChatId) {
+                // Telegram: retire the consumed keyboard, then post the redrawn menu.
+                if (pending.menuMessageId && pending.adapter.editMessageRemoveButtons) {
+                    await pending.adapter.editMessageRemoveButtons(pending.adapterChatId, pending.menuMessageId, t("model.refresh"), pending.adapterThreadId).catch(() => { });
+                }
+                const menuMessageId = await pending.adapter.promptUser(pending.adapterChatId, `${status}\n${t("model.menu", currentDisplay)}`, choices, { threadId: pending.adapterThreadId });
+                const fresh = this.pendingModelSelects.get(nonce);
+                if (fresh)
+                    fresh.menuMessageId = menuMessageId;
+                return;
+            }
+            await pending.respond(t("model.usage")).catch(() => { });
+        }
+        catch (err) {
+            this.pendingModelSelects.delete(nonce);
+            clearTimeout(timer);
+            this.logger.warn({ err, instanceName: pending.instanceName }, "Refreshed model menu failed");
+            await pending.respond(t("model.usage")).catch(() => { });
+        }
+    }
     /** Consume a `/model` selection callback. Returns true for all model-select ids (incl. stale). */
     async handleModelSelection(data) {
         if (!data.callbackData.startsWith(MODEL_SELECT_CALLBACK_PREFIX))
@@ -9827,6 +10444,12 @@ Plus the operational skills (fleet-health, instance-lifecycle, scheduling, sessi
             await this.expandClaudeModelMenu(pending);
             return true;
         }
+        // "🔄 Refresh models" is navigation too: re-probe past every cache and
+        // redraw the same menu with what came back.
+        if (model === "__refresh__") {
+            await this.refreshModelMenu(pending);
+            return true;
+        }
         // Send immediate "⏳ Switching..." feedback, then apply in background.
         const progressText = t("model.switching", pending.instanceName, model);
         let progressMsgId;
@@ -10360,6 +10983,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.
@@ -10397,11 +11024,9 @@ Plus the operational skills (fleet-health, instance-lifecycle, scheduling, sessi
         for (const pending of this.pendingClassicStarts.values())
             clearTimeout(pending.timer);
         this.pendingClassicStarts.clear();
-        for (const pending of this.pendingNonceButtons.values()) {
-            if (pending.timer)
-                clearTimeout(pending.timer);
-        }
-        this.pendingNonceButtons.clear();
+        // Adapters are still connected here — they are stopped further down — so
+        // this is the last moment the prompts can be collapsed.
+        await this.retirePendingNoncePrompts();
         this.topicArchiver.stop();
         this.scheduler?.shutdown();
         // Stop instances in parallel batches to avoid long sequential waits.
@@ -10586,9 +11211,9 @@ Plus the operational skills (fleet-health, instance-lifecycle, scheduling, sessi
      * Whitelisted runtime fields are pushed into live daemons; all other instance
      * fields, plus cold fleet-level settings, retain restart semantics.
      */
-    async reconcileInstances() {
+    async reconcileInstances(observe) {
         if (!this.configPath)
-            return;
+            return {};
         const oldConfig = this.fleetConfig;
         const previousRawConfig = this.rawFleetConfig;
         const previousRawDocument = this.rawFleetDocument;
@@ -10631,7 +11256,9 @@ Plus the operational skills (fleet-health, instance-lifecycle, scheduling, sessi
                     ? t("fleet.reload_removed_all", oldCount)
                     : t("fleet.reload_removed_half", oldCount, newCount);
             this.notifyFleetError(t("fleet.reload_rejected", why));
-            return;
+            // Reported, not swallowed: an apply job whose config was refused used to
+            // mark every row done and tell the user "changes applied".
+            return { rejected: why };
         }
         // Classic behavior settings share the fleet defaults but are not entries
         // in fleet.yaml. Snapshot the old effective chain before reloading the
@@ -10662,29 +11289,31 @@ Plus the operational skills (fleet-health, instance-lifecycle, scheduling, sessi
         this.scheduler?.reload();
         const newInstances = this.fleetConfig.instances;
         const topicMode = this.fleetConfig?.channel?.mode === "topic";
-        // Detect fleet-level changes which still need a restart. Hot defaults are
-        // reconciled below and must not produce a misleading restart warning.
-        const oldDefaultColdWithFleetFields = oldConfig?.defaults
-            ? splitHotColdConfig(oldConfig.defaults).cold
-            : {};
-        const newDefaultColdWithFleetFields = this.fleetConfig?.defaults
-            ? splitHotColdConfig(this.fleetConfig.defaults).cold
-            : {};
-        // `tips` is a fleet-owned hot switch; it is read at post time and never
-        // belongs in a daemon config or a "restart required" warning.
-        const { tips: _oldTips, ...oldDefaultCold } = oldDefaultColdWithFleetFields;
-        const { tips: _newTips, ...newDefaultCold } = newDefaultColdWithFleetFields;
-        const oldFleetLevel = JSON.stringify({ channel: oldConfig?.channel, defaults: oldDefaultCold });
-        const newFleetLevel = JSON.stringify({ channel: this.fleetConfig?.channel, defaults: newDefaultCold });
-        if (oldFleetLevel !== newFleetLevel) {
-            this.logger.warn("Fleet-level config changed (channel/defaults) — use /restart for full effect");
+        // Only what a fresh process can adopt, and only relative to the signature
+        // this process came up on: a Settings edit mutates this.fleetConfig in place
+        // before the reload, so comparing the pre-load copy sees nothing at all.
+        const newFleetLevel = this.fleetLevelSignature();
+        if (this.appliedFleetLevel !== null && this.appliedFleetLevel !== newFleetLevel) {
+            this.logger.warn({
+                keys: fleetLevelDifferences(this.startupFleetConfig, this.fleetConfig),
+            }, "Fleet-level config changed — restart AgEnD for it to take effect");
+            // Terminal, and deliberately not "done": this reconcile cannot adopt a
+            // fleet-level change, and saying otherwise would claim AgEnD is running
+            // on a configuration it is not running on.
+            observe?.(APPLY_FLEET_TARGET, "restart", "restart-required");
         }
         // Stop removed instances (skip classic bot instances — they're managed by classicBot.yaml)
         const classicNames = new Set(this.classicChannels?.getAll().map(ch => ch.instanceName) ?? []);
         for (const name of this.daemons.keys()) {
             if (!(name in newInstances) && !classicNames.has(name)) {
                 this.logger.info({ name }, "Instance removed from config — stopping");
-                await this.stopInstance(name).catch(err => this.logger.error({ err, name }, "Failed to stop removed instance"));
+                observe?.(name, "restart", "running");
+                await this.stopInstance(name)
+                    .then(() => observe?.(name, "restart", "done"))
+                    .catch(err => {
+                    observe?.(name, "restart", "failed", err.message);
+                    this.logger.error({ err, name }, "Failed to stop removed instance");
+                });
             }
         }
         // Start new + reconcile modified instances. Hot values are always sent as a
@@ -10694,20 +11323,23 @@ Plus the operational skills (fleet-health, instance-lifecycle, scheduling, sessi
             if (!this.daemons.has(name)) {
                 // New instance — startInstance already calls connectIpcToInstance
                 this.logger.info({ name }, "New instance in config — starting");
+                observe?.(name, "restart", "running");
                 await this.startInstanceUnattended(name, config, topicMode, "new instance");
+                observe?.(name, "restart", "done");
             }
             else if (oldConfig?.instances[name]) {
                 const daemon = this.daemons.get(name);
                 const runtimeConfig = daemon.getConfigSnapshot?.() ?? oldConfig.instances[name];
-                const oldParts = splitHotColdConfig(runtimeConfig);
-                const newParts = splitHotColdConfig(config);
-                // Every field not explicitly classified hot is cold by default.
-                if (!isDeepStrictEqual(oldParts.cold, newParts.cold)) {
+                const change = classifyInstanceChange(runtimeConfig, config);
+                if (change === "restart") {
                     this.logger.info({ name }, "Instance config changed — restarting");
+                    observe?.(name, "restart", "running");
                     await this.stopInstance(name).catch(() => { });
                     await this.startInstanceUnattended(name, config, topicMode, "modified instance");
+                    observe?.(name, "restart", "done");
                 }
-                else if (!isDeepStrictEqual(oldParts.hot, newParts.hot)) {
+                else if (change === "hot") {
+                    observe?.(name, "hot", "running");
                     const update = hotConfigUpdate(config);
                     const ipc = this.instanceIpcClients.get(name);
                     const sent = ipc?.connected === true && ipc.send({ type: "config_update", config: update });
@@ -10718,6 +11350,7 @@ Plus the operational skills (fleet-health, instance-lifecycle, scheduling, sessi
                         this.logger.warn({ name }, "Config-update IPC unavailable — applied hot config in-process");
                     }
                     this.logger.info({ name, fields: [...HOT_INSTANCE_CONFIG_KEYS] }, "Instance hot config reloaded");
+                    observe?.(name, "hot", "done");
                 }
             }
         }
@@ -10735,25 +11368,1155 @@ Plus the operational skills (fleet-health, instance-lifecycle, scheduling, sessi
                 const autoPauseAfter = this.classicChannels.getAutoPauseAfter(ch.channelId, ch.adapterId, this.fleetConfig?.defaults?.auto_pause_after);
                 if (old.backend !== backend || old.model !== model || old.autoPauseAfter !== autoPauseAfter) {
                     this.logger.info({ instanceName: ch.instanceName }, "Classic cold config changed — restarting");
+                    observe?.(ch.instanceName, "restart", "running");
                     await this.stopInstance(ch.instanceName).catch(() => { });
                     await this.startClassicInstanceUnattended(ch, "classic instance after fleet reload");
+                    observe?.(ch.instanceName, "restart", "done");
                     continue;
                 }
                 const toolProgress = this.classicChannels.getToolProgress(ch.channelId, ch.adapterId, this.fleetConfig?.defaults?.tool_progress);
                 const replyCompletionGuard = this.classicChannels.getReplyCompletionGuard(ch.channelId, ch.adapterId, this.fleetConfig?.defaults?.reply_completion_guard);
                 if (old.toolProgress !== toolProgress || old.replyCompletionGuard !== replyCompletionGuard) {
+                    observe?.(ch.instanceName, "hot", "running");
                     this.applyHotConfigUpdate(ch.instanceName, {
                         tool_progress: toolProgress,
                         reply_completion_guard: replyCompletionGuard,
                     });
                     this.logger.info({ instanceName: ch.instanceName }, "Classic inherited hot config reloaded");
+                    observe?.(ch.instanceName, "hot", "done");
                 }
             }
         }
         // warm_cap is fleet-owned; enforce the reloaded value immediately against
         // currently idle instances instead of waiting for a future state edge.
         this.enforceWarmCap();
+        // appliedFleetLevel is deliberately NOT updated here. It means "the
+        // fleet-level config this process started on"; a reconcile does not restart
+        // the process, so moving it would erase the fact that a restart is still
+        // owed and silence every later reminder.
         this.logger.info({ running: this.daemons.size, configured: Object.keys(newInstances).length }, "Reconcile complete");
+        return {};
+    }
+    /**
+     * `{channel, cold defaults}` as one comparable string — the part of the config
+     * a running fleet process cannot adopt without restarting.
+     */
+    fleetLevelSignature(config = this.fleetConfig) {
+        return fleetLevelSignature(config);
+    }
+    /**
+     * The config a reconcile is about to load, not the one held in memory.
+     *
+     * Settings mutates the in-memory object and writes the file; only the file
+     * goes back through defaults expansion. Forecasting from memory therefore
+     * misses every instance that a changed fleet default will restart — the user
+     * is told "restart AgEnD" and not told that five agents are about to go down.
+     */
+    nextFleetConfig() {
+        if (!this.configPath)
+            return this.fleetConfig;
+        try {
+            return loadFleetConfig(this.configPath);
+        }
+        catch (err) {
+            // An unparseable file is the reconcile's problem to report; the forecast
+            // falls back to what is running rather than failing the request.
+            this.logger.debug({ err }, "Apply plan fell back to the in-memory config");
+            return this.fleetConfig;
+        }
+    }
+    /**
+     * Does the config this process is running match the one a reconcile would
+     * load off disk?
+     *
+     * If not, every apply reports a fleet-level change that a restart cannot
+     * clear — restart, recompute, disagree again — a self-sustaining loop that
+     * the rate limit can only slow to three naggings an hour. Startup rewrites
+     * the file in three places before this point (slimFleetConfigAtStartup, the
+     * general auto-create, the general fixup), so the two can genuinely diverge.
+     *
+     * An offer to restart that cannot possibly succeed is worse than no offer, so
+     * the panel shows the mismatch instead of a button.
+     */
+    checkStartupSignatureConsistency() {
+        if (!this.configPath) {
+            this.fleetSignatureMismatch = null;
+            return;
+        }
+        let onDisk;
+        try {
+            onDisk = loadFleetConfig(this.configPath);
+        }
+        catch (err) {
+            this.logger.warn({ err }, "Could not re-read fleet.yaml to check the startup signature");
+            this.fleetSignatureMismatch = null;
+            return;
+        }
+        if (fleetLevelSignature(onDisk) === this.appliedFleetLevel) {
+            this.fleetSignatureMismatch = null;
+            return;
+        }
+        this.fleetSignatureMismatch = fleetLevelDifferences(this.fleetConfig, onDisk);
+        this.logger.warn({
+            keys: this.fleetSignatureMismatch,
+            configPath: this.configPath,
+        }, "fleet.yaml and the running configuration disagree on startup-only keys — every apply will ask for a restart that cannot clear it");
+    }
+    /**
+     * Is a live adapter already long-polling this bot token?
+     *
+     * Telegram's `getUpdates` has exactly one consumer: a second poller takes
+     * turns with the first and both miss messages. The setup wizard's "post in
+     * the group and I'll detect it" step is a second poller, so it has to know
+     * when the answer is "not against this token, not while I'm running".
+     */
+    isBotTokenInUse(token) {
+        if (!token)
+            return false;
+        const configured = this.fleetConfig?.channels
+            ?? (this.fleetConfig?.channel ? [this.fleetConfig.channel] : []);
+        for (const channel of configured) {
+            const envVar = channel?.bot_token_env;
+            if (!envVar)
+                continue;
+            // Compare the value, not the variable name: the same token can be
+            // reached through a differently named variable.
+            if (process.env[envVar] === token)
+                return true;
+        }
+        return false;
+    }
+    /** Non-null when startup found the running config and fleet.yaml disagreeing. */
+    fleetSignatureMismatchKeys() {
+        return this.fleetSignatureMismatch;
+    }
+    /**
+     * Restart AgEnD itself on behalf of a Settings apply.
+     *
+     * Deliberately a separate action from Apply: the panel is reachable from
+     * outside the LAN, and "restart the whole fleet" must never be something a
+     * single Apply click can carry along with it.
+     *
+     * The order below is the safety envelope, and the order matters:
+     * concurrency and consistency first (cheap, and a restart during a reconcile
+     * is the dangerous one), then the state checks, then the rate limit, then the
+     * audit notice — and only once all of that holds is the attempt written to
+     * disk and fsynced, before anything spawns.
+     */
+    async requestSettingsSelfRestart(jobId, key) {
+        // A retry after a lost response must not restart a second time. The key is
+        // recorded on the job, which survives the restart it triggers.
+        const already = this.applyJobs.findByRestartKey(key);
+        if (already)
+            return { ok: true, jobId: already.id, reused: true };
+        if (this.reconcileInFlight || this.activeApplyJobId) {
+            return { ok: false, status: 409, error: "a configuration reload is running — try again once it finishes" };
+        }
+        if (this.fleetSignatureMismatch) {
+            // Restarting cannot clear this, so offering it would be a loop.
+            return {
+                ok: false,
+                status: 409,
+                error: `fleet.yaml and the running configuration disagree on ${this.fleetSignatureMismatch.join(", ")} — check fleet.log before restarting`,
+            };
+        }
+        const job = this.applyJobs.get(jobId);
+        const row = job?.targets.find(item => item.target === APPLY_FLEET_TARGET);
+        if (!job || !row || row.status !== "restart-required") {
+            return { ok: false, status: 409, error: "that apply has no pending fleet-level change" };
+        }
+        // The row alone is not enough: an old job keeps its row for the whole
+        // retention window, so a change made and then reverted would still leave a
+        // job that looks restartable. The live signature is the authority — and it
+        // must be the same view of the config the plan uses.
+        if (this.appliedFleetLevel === null || this.appliedFleetLevel === this.fleetLevelSignature(this.nextFleetConfig())) {
+            return { ok: false, status: 409, error: "no fleet-level change is pending any more" };
+        }
+        const allowance = checkSelfRestartAllowance(this.dataDir);
+        if (!allowance.allowed) {
+            if (allowance.reason === "unreadable") {
+                // Fail closed: with the limit's own state in doubt, "no attempts yet"
+                // is the one reading that must not be assumed.
+                return {
+                    ok: false,
+                    status: 503,
+                    error: "the restart rate-limit file cannot be read — remove self-restart.json from the data dir on the host, or run `agend restart` there",
+                };
+            }
+            return {
+                ok: false,
+                status: 429,
+                error: allowance.reason === "too-soon"
+                    ? "AgEnD was restarted from Settings very recently"
+                    : "too many Settings-triggered restarts in the last hour",
+                retryAfterSeconds: allowance.retryAfterSeconds,
+            };
+        }
+        // Recorded before the notice, not after. If recording keeps failing (a
+        // read-only data dir), posting first would let whoever holds the token spam
+        // the channel with "restarting…" notices for restarts that never happen.
+        // The cost is that a failed announcement still spends an attempt, which is
+        // the right way round for a rate limit.
+        if (!recordSelfRestartAttempt(this.dataDir)) {
+            this.logger.error("Self-restart attempt could not be recorded — refusing to restart unmetered");
+            return { ok: false, status: 503, error: "could not record the restart attempt" };
+        }
+        // Out-of-band notice before the restart, so a panel restart is visible where
+        // the admins are. Refusing when it cannot be posted is the same rule as
+        // refusing when the progress marker cannot be written: no untraceable
+        // restarts.
+        const notice = await this.postSelfRestartNotice();
+        if (!notice) {
+            return {
+                ok: false,
+                status: 409,
+                error: "no chat channel is available to announce the restart — run `agend restart` on the host instead",
+            };
+        }
+        // Consume the row: it moves to running, which is also what lets the next
+        // process settle it (settleAfterRestart only touches non-terminal rows).
+        this.applyJobs.update(jobId, current => {
+            const target = current.targets.find(item => item.target === APPLY_FLEET_TARGET);
+            if (target)
+                target.status = "running";
+            current.restart_key = key;
+            current.deadlineMs = SELF_RESTART_DEADLINE_MS;
+        });
+        this.emitSseEvent("apply_progress", viewOf(this.applyJobs.get(jobId)));
+        const launched = await this.requestFullRestart(notice.adapter, notice.chatId, notice.threadId, notice.messageId)
+            .catch(err => {
+            this.logger.error({ err }, "Settings-triggered self restart failed to launch");
+            return false;
+        });
+        if (!launched) {
+            this.applyJobs.setTargetStatus(jobId, APPLY_FLEET_TARGET, "failed", "restart could not be launched");
+            this.applyJobs.finish(jobId, "restart could not be launched");
+            this.emitSseEvent("apply_progress", viewOf(this.applyJobs.get(jobId)));
+            return { ok: false, status: 409, error: "the restart could not be launched — see fleet.log" };
+        }
+        return { ok: true, jobId };
+    }
+    /** The audit notice, and the message the restart progress will edit. */
+    async postSelfRestartNotice() {
+        const groupId = this.fleetConfig?.channel?.group_id;
+        const adapter = this.adapter;
+        if (!groupId || !adapter)
+            return null;
+        const generalName = this.findGeneralInstance();
+        const rawThreadId = generalName ? this.fleetConfig?.instances[generalName]?.topic_id : undefined;
+        const threadId = rawThreadId != null ? String(rawThreadId) : undefined;
+        try {
+            const sent = await adapter.sendText(String(groupId), t("restart.settings_triggered"), { threadId });
+            if (!sent?.messageId)
+                return null;
+            return { adapter, chatId: sent.chatId, threadId: sent.threadId, messageId: sent.messageId };
+        }
+        catch (err) {
+            this.logger.error({ err }, "Could not announce the Settings-triggered restart — refusing to restart silently");
+            return null;
+        }
+    }
+    /** Jobs outlive this process on purpose; see apply-job.ts. */
+    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.
+     *
+     * A forecast, not the record: it is built from the same `classifyInstanceChange`
+     * the reconcile decides with, but the rows that end up in the job are the ones
+     * the reconcile reports as it works. A target the forecast missed (a Classic
+     * instance inheriting a changed default) is added when it is first touched.
+     */
+    planConfigApply() {
+        const rows = [];
+        const nextConfig = this.nextFleetConfig();
+        const next = nextConfig?.instances ?? {};
+        const classicNames = new Set(this.classicChannels?.getAll().map(ch => ch.instanceName) ?? []);
+        for (const [name, config] of Object.entries(next)) {
+            const daemon = this.daemons.get(name);
+            if (!daemon) {
+                rows.push({ target: name, kind: "restart" });
+                continue;
+            }
+            const runtime = daemon.getConfigSnapshot?.();
+            if (!runtime)
+                continue;
+            const change = classifyInstanceChange(runtime, config);
+            if (change !== "none")
+                rows.push({ target: name, kind: change === "restart" ? "restart" : "hot" });
+        }
+        for (const name of this.daemons.keys()) {
+            if (!(name in next) && !classicNames.has(name))
+                rows.push({ target: name, kind: "restart" });
+        }
+        if (this.appliedFleetLevel !== null && this.appliedFleetLevel !== this.fleetLevelSignature(nextConfig)) {
+            rows.push({ target: APPLY_FLEET_TARGET, kind: "restart" });
+        }
+        return rows;
+    }
+    /**
+     * Start (or re-join) a Settings apply.
+     *
+     * The key is the client's. Handing back the existing job for a repeated key is
+     * the whole point: the retry after a lost response must not apply everything a
+     * second time.
+     */
+    startSettingsApply(key) {
+        // The key is checked first on purpose: a retry of the apply that is running
+        // right now must get its own job back, not "busy".
+        const existing = this.applyJobs.findByKey(key);
+        if (existing)
+            return { job: existing, reused: true };
+        if (this.reconcileInFlight || this.activeApplyJobId) {
+            return { busy: this.activeApplyJobId ? this.applyJobs.get(this.activeApplyJobId) : null };
+        }
+        const job = this.applyJobs.create(key, this.planConfigApply());
+        // Reserved synchronously: the work starts a microtask later, and a second
+        // request arriving in that gap must see the slot taken.
+        this.activeApplyJobId = job.id;
+        // Start after the caller has its answer, so the first thing the page renders
+        // is the whole plan with every row still pending — not a job the reconcile
+        // has already half-finished synchronously.
+        queueMicrotask(() => void this.runSettingsApply(job.id));
+        return { job, reused: false };
+    }
+    async runSettingsApply(jobId) {
+        const emit = () => {
+            const job = this.applyJobs.get(jobId);
+            // An accelerator only: these frames carry no event id, so a client that
+            // reconnects cannot ask for what it missed. GET is the authority.
+            if (job)
+                this.emitSseEvent("apply_progress", viewOf(job));
+        };
+        // Passed in rather than parked on `this`: a shared field would let a second
+        // reconcile redirect this job's reporting into another job's rows.
+        const observer = (target, kind, status, error) => {
+            this.applyJobs.update(jobId, job => {
+                let row = job.targets.find(item => item.target === target);
+                if (!row) {
+                    row = { target, kind, status: "pending" };
+                    job.targets.push(row);
+                }
+                row.kind = kind;
+                row.status = status;
+                if (error)
+                    row.error = error;
+            });
+            emit();
+        };
+        emit();
+        try {
+            const started = this.startExclusiveReconcile(observer);
+            if (!started) {
+                // The slot was reserved before the microtask, so this means a SIGHUP
+                // reconcile started in between. Report it instead of applying twice.
+                this.applyJobs.finish(jobId, "a config reload was already running");
+                return;
+            }
+            const outcome = await started;
+            this.applyJobs.finish(jobId, outcome.rejected);
+        }
+        catch (err) {
+            this.applyJobs.finish(jobId, err instanceof Error ? err.message : String(err));
+        }
+        finally {
+            this.activeApplyJobId = null;
+            emit();
+        }
     }
     async restartInstances() {
         if (!this.configPath) {
@@ -11046,6 +12809,12 @@ Plus the operational skills (fleet-health, instance-lifecycle, scheduling, sessi
             this.initializeWebAuthTokens();
         this.healthServer = createServer((req, res) => {
             res.setHeader("Content-Type", "application/json");
+            // No Referer to a tunnel host, an upstream proxy, or any page linked from
+            // the panel — the dashboard URL is itself a credential-bearing address.
+            res.setHeader("Referrer-Policy", "no-referrer");
+            // Authorization now depends on a cookie, so a shared cache (a tunnel, a
+            // corporate proxy) must not serve one visitor's response to another.
+            res.setHeader("Vary", "Cookie");
             const requestPath = new URL(req.url ?? "/", `http://localhost:${port}`).pathname;
             // Browsers request this automatically and AgEnD does not ship an icon.
             // It is neither user data nor an API route, so do not turn the harmless
@@ -11071,15 +12840,25 @@ Plus the operational skills (fleet-health, instance-lifecycle, scheduling, sessi
                 // like the other /view data routes (usage-api.ts rejects non-GET).
             }
             else {
-                // All other endpoints require a valid token (query ?token= or X-Agend-Token header).
+                // All other endpoints require a session cookie or an X-Agend-Token
+                // header; a `?token=` in the URL is only redeemed for a cookie on a GET.
                 // /ui/* will also re-check in web-api.ts, which is harmless.
                 const parsedUrl = new URL(req.url ?? "/", `http://localhost:${port}`);
-                const headerToken = req.headers["x-agend-token"];
-                const providedToken = parsedUrl.searchParams.get("token")
-                    ?? (typeof headerToken === "string" ? headerToken : null);
-                if (!this.webToken || providedToken !== this.webToken) {
-                    res.writeHead(401);
-                    res.end(JSON.stringify({ error: WEB_TOKEN_INVALID_MESSAGE }));
+                const decision = decideWebGate(req, parsedUrl, this.webToken);
+                if (decision.kind === "reject") {
+                    res.writeHead(decision.status);
+                    res.end(JSON.stringify({ error: decision.message }));
+                    return;
+                }
+                if (decision.kind === "exchange") {
+                    res.setHeader("Set-Cookie", decision.setCookie);
+                    res.setHeader("Location", decision.location);
+                    // A cached redirect would replay a Set-Cookie for a rotated token.
+                    res.setHeader("Cache-Control", "no-store");
+                    res.writeHead(302);
+                    // Browsers follow the Location; a script that does not gets told why
+                    // its URL token stopped being echoed back as data.
+                    res.end(JSON.stringify({ redirect: decision.location }));
                     return;
                 }
             }
@@ -11317,8 +13096,11 @@ Plus the operational skills (fleet-health, instance-lifecycle, scheduling, sessi
             this.logger.info({ port }, afterTakeover
                 ? "Health endpoint listening (after takeover)"
                 : "Health endpoint listening");
-            this.logger.info({ url: `http://localhost:${port}/ui?token=${this.webToken}` }, "Web UI available");
-            this.logger.info({ url: `http://localhost:${port}/view?token=${this.viewToken}` }, "Web View available");
+            // Never the token: fleet.log is readable by anything that can read the
+            // data dir, is copied into bug reports, and is tailed in shared terminals.
+            // `/dashboard` and `agend web` are the ways to get an authorized link.
+            this.logger.info({ url: `http://localhost:${port}/ui` }, "Web UI available (open it with /dashboard or `agend web`)");
+            this.logger.info({ url: `http://localhost:${port}/view` }, "Web View available");
         };
         this.healthServer.on("error", (err) => {
             this.healthServerListening = false;
@@ -11335,8 +13117,25 @@ Plus the operational skills (fleet-health, instance-lifecycle, scheduling, sessi
                     if (existsSync(pidPath)) {
                         const oldPid = parseInt(readFileSync(pidPath, "utf-8").trim(), 10);
                         if (oldPid && oldPid !== process.pid) {
-                            process.kill(oldPid, "SIGTERM");
-                            this.logger.info({ oldPid }, "Killed old fleet process");
+                            // fleet.pid is a claim, not proof. A stale or wrong entry points
+                            // at whatever now holds that pid, and this used to SIGTERM it —
+                            // an unrelated process killed because a port was busy. Confirm
+                            // the target really is an AgEnD fleet, and when that cannot be
+                            // confirmed, do not signal: not killing costs a dashboard, and
+                            // killing costs somebody else's process.
+                            const commandLine = readProcessCommandLine(oldPid);
+                            if (isFleetStartCommandLine(commandLine)) {
+                                process.kill(oldPid, "SIGTERM");
+                                this.logger.info({ oldPid }, "Killed old fleet process");
+                            }
+                            else {
+                                this.logger.warn({
+                                    oldPid,
+                                    // Truncated: this is an unrelated process's command line, and
+                                    // fleet.log is copied into bug reports.
+                                    commandLine: commandLine ? `${commandLine.slice(0, 60)}${commandLine.length > 60 ? "…" : ""}` : "(unreadable)",
+                                }, "fleet.pid does not name an AgEnD fleet process — not signalling it");
+                            }
                         }
                     }
                 }