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

package/dist/fleet-manager.js

@@ -1,9 +1,10 @@
-import { existsSync, readFileSync, mkdirSync, writeFileSync, unlinkSync, rmSync, readdirSync, renameSync, copyFileSync, chmodSync, statSync } from "node:fs";
+import { existsSync, readFileSync, mkdirSync, writeFileSync, unlinkSync, rmSync, readdirSync, renameSync, copyFileSync, chmodSync, statSync, accessSync, constants as fsConstants } from "node:fs";
 import { randomBytes, randomUUID } from "node:crypto";
 import { spawnSync } from "node:child_process";
 import { freemem, totalmem, cpus } from "node:os";
 import { createServer } from "node:http";
-import { join, dirname, basename } from "node:path";
+import { Worker } from "node:worker_threads";
+import { join, dirname, basename, delimiter, isAbsolute } from "node:path";
 import { fileURLToPath } from "node:url";
 import { getAgendHome, ensureWorkspaceGit } from "./paths.js";
 import { beginFullRestartProgress as persistFullRestartProgress, beginUpdateProgress as persistUpdateProgress, clearUpdateMarker, isUpdateInProgress, readUpdateProgress, setUpdateProgressStage, updateProgressOperation, } from "./update-marker.js";
@@ -16,7 +17,7 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 /** Fallback access policy for a channel with no `access:` block — open (no gate). */
 const DEFAULT_OPEN_ACCESS = { mode: "open", allowed_users: [], max_pending_codes: 0, code_expiry_minutes: 0 };
-import { STATUS_EMOJI_KEYS, builtinStatusEmojis, reactionForm, reactionMatchKey, resolveStatusEmojis, statusAvoidList, statusMatchKey, statusMatchKeys, textForm, } from "./status-emojis.js";
+import { STATUS_EMOJI_CONFIG_KEYS, STATUS_EMOJI_KEYS, STATUS_EMOJI_SUGGESTIONS, TELEGRAM_REACTION_EMOJIS, builtinStatusEmojis, customEmojiValue, emojiImageUrl, normalizeEmoji, previewStatusEmojis, reactionForm, reactionMatchKey, resolveStatusEmojis, statusAvoidList, statusEmojiProblem, statusMatchKey, statusMatchKeys, textForm, } from "./status-emojis.js";
 import { isProbeableRouteTarget } from "./fleet-context.js";
 import { loadFleetConfig, loadRawFleetConfig, DEFAULT_COST_GUARD, DEFAULT_DAILY_SUMMARY, DEFAULT_INSTANCE_CONFIG } from "./config.js";
 import { EventLog } from "./event-log.js";
@@ -28,7 +29,7 @@ import { IpcClient } from "./channel/ipc-bridge.js";
 import { createAdapter } from "./channel/factory.js";
 import { TelegramAdapter } from "./channel/adapters/telegram.js";
 import { createBackend } from "./backend/factory.js";
-import { isModelCompatible } from "./backend/types.js";
+import { isModelCompatible, SYSINFO_BACKEND_IDS } from "./backend/types.js";
 import { createLogger, rotateLogIfNeeded } from "./logger.js";
 import { processAttachments } from "./channel/attachment-handler.js";
 import { routeToolCall } from "./channel/tool-router.js";
@@ -40,7 +41,7 @@ import { WebhookEmitter } from "./webhook-emitter.js";
 import { TmuxControlClient } from "./tmux-control.js";
 import { safeHandler } from "./safe-async.js";
 import { RoutingEngine } from "./routing-engine.js";
-import { InstanceLifecycle, BACKEND_INSTALLATION_INFO, checkBinaryInstalled, } from "./instance-lifecycle.js";
+import { InstanceLifecycle, SupersededStartError, BACKEND_INSTALLATION_INFO, checkBinaryInstalled, } from "./instance-lifecycle.js";
 import { TopicArchiver } from "./topic-archiver.js";
 import { StatuslineWatcher } from "./statusline-watcher.js";
 import { outboundHandlers } from "./outbound-handlers.js";
@@ -65,7 +66,9 @@ import { ClassicChannelManager, getClassicBackendChoices, isSelectableClassicBac
 import { assertExplicitInstanceRemoval } from "./instance-removal.js";
 import { validateFleetConfig } from "./config-validator.js";
 import { readLastInboundAt } from "./daemon.js";
-import { clearPausedMarker } from "./pause-marker.js";
+import { clearPausedMarker, readPausedAt, readPauseReason, writePausedMarker } from "./pause-marker.js";
+import { DEFAULT_WARM_OVERFLOW, WakeCoordinator } from "./wake-coordinator.js";
+import { resolveDeliveryWorkerMode } from "./types.js";
 import { isFleetStartCommandLine, readProcessCommandLine, releaseProcessFleetLock } from "./fleet-lock.js";
 import { isSetupComplete, markSetupComplete } from "./setup-marker.js";
 import { manualCleanupMessage, reapStaleTunnel } from "./tunnel/lease.js";
@@ -285,6 +288,8 @@ export class FleetManager {
     managerBootId = randomUUID();
     deliveryOutbox = null;
     deliveryOutboxRecovered = false;
+    /** Phase 2b: wakes paused targets for queued durable work (delivery_worker ≠ off). */
+    wakeCoordinator = null;
     deliveryPumpScheduled = false;
     deliveryPumpRunning = false;
     deliveryPumpTimer = null;
@@ -569,9 +574,15 @@ export class FleetManager {
             this.logger.info({ ...recovered }, "Recovered durable delivery outbox for this process boot");
             this.deliveryOutboxRecovered = true;
         }
-        outbox.on("admitted", () => this.scheduleDeliveryOutboxPump());
+        outbox.on("admitted", () => { this.scheduleDeliveryOutboxPump(); this.wakeCoordinator?.kick(); });
         outbox.on("state", (event) => {
             this.scheduleDeliveryOutboxPump();
+            this.wakeCoordinator?.kick();
+            if (event.deliveryId && event.state === "delivered") {
+                const target = outbox.get(event.deliveryId)?.targetInstance;
+                if (target)
+                    this.wakeCoordinator?.noteDelivered(target);
+            }
             if (event.deliveryId && (event.state === "failed" || event.state === "uncertain")) {
                 const row = outbox.get(event.deliveryId);
                 if (row && row.kind !== "delivery_outcome_notice" && row.kind !== "post_restart_outcome_notice") {
@@ -590,8 +601,11 @@ export class FleetManager {
         outbox.on("content_digest_mismatch", (event) => {
             this.logger.warn(event, "Delivered text differs from the admitted text (content digest mismatch)");
         });
+        this.wakeCoordinator = this.createWakeCoordinator();
+        this.wakeCoordinator.start();
         outbox.on("expired", (event) => {
             this.scheduleDeliveryOutboxPump();
+            this.wakeCoordinator?.kick();
             if (event.count)
                 this.notifyFleetError(`${event.count} durable delivery row(s) reached the 24-hour outbox bound; ${event.uncertain ?? 0} unresolved submissions are uncertain and sender notices were queued.`);
         });
@@ -618,6 +632,9 @@ export class FleetManager {
                 kind: input.kind,
             }, "Durable cross-instance delivery accepted");
         this.scheduleDeliveryOutboxPump();
+        // Phase 2b: a paused wake_only target is woken by the coordinator, never by
+        // the pump; admission must tell it, or the work waits for the watchdog.
+        this.wakeCoordinator?.kick();
         return {
             deliveryId: admitted.delivery.deliveryId,
             state: admitted.delivery.state,
@@ -680,7 +697,7 @@ export class FleetManager {
         }
     }
     scheduleDeliveryOutboxPump(delayMs = 0) {
-        if (!this.deliveryOutbox || this.shuttingDown)
+        if (!this.deliveryOutbox || this.shuttingDown || !this.deliveryOutbox.isOpen)
             return;
         if (this.deliveryPumpTimer) {
             if (delayMs > 0)
@@ -700,14 +717,25 @@ export class FleetManager {
     }
     async runDeliveryOutboxPump() {
         const outbox = this.deliveryOutbox;
-        if (!outbox || this.shuttingDown || this.deliveryPumpRunning)
+        // A closed database is never queried: this runs from timers, where a throw
+        // is an unhandled rejection. Checking here covers the finally block too:
+        // the body below never awaits, so the database cannot close in between.
+        if (!outbox || this.shuttingDown || this.deliveryPumpRunning || !outbox.isOpen)
             return;
         this.deliveryPumpRunning = true;
         this.deliveryPumpScheduled = false;
         try {
-            outbox.expireStale();
+            outbox.expireStale(undefined, undefined, target => {
+                const failure = this.wakeCoordinator?.wakeFailure(target);
+                return failure ? `target could not be woken (${failure})` : undefined;
+            });
             while (this.activeDurableTargets.size < 8) {
-                const claimed = outbox.claimNext(this.managerBootId, target => this.isInstanceRestarting(target) ? null : this.daemons.get(target)?.bootId ?? null, this.activeDurableTargets);
+                const claimed = outbox.claimNext(this.managerBootId, 
+                // Phase 2b: a wake_only target is claimed only once it is awake; the
+                // wake coordinator, not this pump, wakes it (no claim, no attempt).
+                target => this.isInstanceRestarting(target) || this.wakeCoordinator?.blocksClaim(target)
+                    ? null
+                    : this.daemons.get(target)?.bootId ?? null, this.activeDurableTargets);
                 if (!claimed)
                     break;
                 this.activeDurableTargets.add(claimed.targetInstance);
@@ -761,7 +789,7 @@ export class FleetManager {
                     content: payload.content,
                     delivery_id: claimed.deliveryId,
                     delivery_attempt: String(claimed.attemptNo),
-                }, { waitForIdle: false });
+                }, { waitForIdle: false, noInlineWake: this.deliveryWorkerMode(target) !== "off" });
             }
             else {
                 payload.meta = {
@@ -776,6 +804,7 @@ export class FleetManager {
                 sent = await this.deliverToInstance(target, payload, {
                     isCrossInstance: true,
                     waitForIdle: claimed.kind !== "steer",
+                    noInlineWake: this.deliveryWorkerMode(target) !== "off",
                 });
             }
             if (!sent) {
@@ -1687,13 +1716,15 @@ export class FleetManager {
             exclude,
             isEvicting: name => this.warmCapEvicting.has(name),
             isGeneral: name => isGeneralInstance(this.fleetConfig, name),
-            isIdle: name => this.getInstanceExecutionState(name) === "idle",
+            // A work lease (Phase 2a) keeps a just-woken or mid-submission instance
+            // out of the eviction candidates; it is not idle in the sense that matters.
+            isIdle: name => this.getInstanceExecutionState(name) === "idle" && !this.lifecycle.hasWorkLease(name),
             lastInboundAt: name => readLastInboundAt(this.getInstanceDir(name)) ?? 0,
         });
         for (const victim of victims) {
             this.warmCapEvicting.add(victim);
             this.logger.info({ instance: victim, warm: warm.length, cap }, "warm_cap exceeded — auto-pausing LRU idle instance");
-            this.lifecycle.pause(victim)
+            this.lifecycle.pause(victim, "warm_cap")
                 .catch(err => this.logger.warn({ err, instance: victim }, "warm_cap auto-pause failed"))
                 .finally(() => this.warmCapEvicting.delete(victim));
         }
@@ -1729,7 +1760,10 @@ export class FleetManager {
             const query = () => {
                 const ipc = this.instanceIpcClients.get(instanceName);
                 if (ipc?.connected) {
-                    ipc.send({ type: "query_instance_state", requestId: `idle-gate-${Date.now()}` });
+                    // The daemon owns the backend/TTY proof and its 10s startup-input
+                    // timer. A cache-only query can never discover a Context-less idle
+                    // pane, and a second fleet timer would stack another 10s wait.
+                    ipc.send({ type: "query_instance_state", requestId: `idle-gate-${Date.now()}`, deliveryIdle: true });
                 }
                 check();
             };
@@ -1744,8 +1778,8 @@ export class FleetManager {
     /**
      * Ask the daemon to capture the pane before answering, then wait for any state
      * report produced after this request. The ordinary query is intentionally
-     * cache-only (idle gates call it frequently); this opt-in refresh is reserved
-     * for lifecycle decisions where a stale state would strand UI.
+     * cache-only; delivery idle gates opt into their own pane/input proof, and
+     * this refresh serves lifecycle decisions where a stale state would strand UI.
      */
     refreshInstanceExecutionState(instanceName, timeoutMs) {
         const ipc = this.instanceIpcClients.get(instanceName);
@@ -1783,16 +1817,22 @@ export class FleetManager {
                 finish(false);
         });
     }
-    async deliverWithIdleGate(instanceName, payload, timeoutMs, deliveryEpoch) {
+    async deliverWithIdleGate(instanceName, payload, timeoutMs, deliveryEpoch, noInlineWake = false) {
         if (this.shuttingDown || !this.isDeliveryEpochCurrent(instanceName, deliveryEpoch))
             return false;
         await this.holdDeliveryForStorm(instanceName, deliveryEpoch);
         if (this.shuttingDown || !this.isDeliveryEpochCurrent(instanceName, deliveryEpoch))
             return false;
         let idleObservedAfter = this.lastDeliveryAt.get(instanceName) ?? 0;
+        if (this.lifecycle.isPaused(instanceName) && noInlineWake) {
+            // Paused after its row was claimed (an operator or auth pause): hand the
+            // row back; the coordinator decides whether and when to wake it.
+            this.wakeCoordinator?.kick();
+            return false;
+        }
         if (this.lifecycle.isPaused(instanceName)) {
             const wakeStartedAt = Date.now();
-            await this.lifecycle.wake(instanceName, 30_000);
+            await this.explicitWake(instanceName, 30_000);
             if (!this.isDeliveryEpochCurrent(instanceName, deliveryEpoch))
                 return false;
             // Waking added one to the warm count — make room by evicting a different
@@ -1915,7 +1955,11 @@ export class FleetManager {
             ?? ((options.isCrossInstance ?? inferredCrossInstance) || payload.type === "fleet_schedule_trigger");
         if (!waitForIdle) {
             if (this.lifecycle.isPaused(instanceName)) {
-                await this.lifecycle.wake(instanceName, 30_000);
+                if (options.noInlineWake) {
+                    this.wakeCoordinator?.kick();
+                    return false;
+                }
+                await this.explicitWake(instanceName, 30_000);
                 if (!this.isDeliveryEpochCurrent(instanceName, deliveryEpoch))
                     return false;
                 this.enforceWarmCap(instanceName); // woke one → evict a different LRU idle if over cap
@@ -1931,7 +1975,7 @@ export class FleetManager {
             return true;
         }
         const previous = this.idleGatedDeliveryTails.get(instanceName) ?? Promise.resolve();
-        const delivery = previous.catch(() => { }).then(() => this.deliverWithIdleGate(instanceName, deliveryPayload, options.idleTimeoutMs ?? 60_000, deliveryEpoch));
+        const delivery = previous.catch(() => { }).then(() => this.deliverWithIdleGate(instanceName, deliveryPayload, options.idleTimeoutMs ?? 60_000, deliveryEpoch, options.noInlineWake === true));
         this.idleGatedDeliveryTails.set(instanceName, delivery);
         try {
             return await delivery;
@@ -1947,9 +1991,117 @@ export class FleetManager {
         const allowed = this.getChannelConfig(adapterId)?.access?.allowed_users ?? [];
         return allowed.some(entry => String(entry) === String(userId));
     }
+    /** Phase 2: delivery_worker for a target (instance override → fleet default → off). */
+    deliveryWorkerMode(target) {
+        return resolveDeliveryWorkerMode(this.fleetConfig, target);
+    }
+    /** Active instances mid-restart: they keep their warm slot through the stop → replacement gap. */
+    restartsHoldingSlot = new Set();
+    /**
+     * Instances counted against the wake coordinator's hard cap: running
+     * daemons, plus active instances whose restart is between stopping the old
+     * daemon and publishing the replacement.
+     */
+    warmInstanceNames() {
+        const names = new Set([...this.daemons.keys()].filter(name => this.getInstanceStatus(name) === "running"));
+        for (const name of this.restartsHoldingSlot)
+            names.add(name);
+        return [...names];
+    }
+    createWakeCoordinator() {
+        return new WakeCoordinator({
+            mode: target => this.deliveryWorkerMode(target),
+            available: () => !this.shuttingDown && this.deliveryOutbox?.isOpen === true,
+            listPending: () => this.deliveryOutbox?.listPending() ?? [],
+            isPaused: target => this.lifecycle.isPaused(target),
+            pauseReason: target => readPauseReason(this.getInstanceDir(target)),
+            isRestarting: target => this.isInstanceRestarting(target),
+            wake: async (target) => {
+                await this.lifecycle.wake(target, 30_000, undefined, { source: "coordinator" });
+                // The soft cap still applies: evict a different, unleased idle instance.
+                this.enforceWarmCap(target);
+            },
+            residentNames: () => this.warmInstanceNames(),
+            warmCap: () => this.fleetConfig?.defaults?.warm_cap ?? 0,
+            warmOverflow: () => this.fleetConfig?.defaults?.warm_overflow ?? DEFAULT_WARM_OVERFLOW,
+            wokeAt: target => this.lifecycle.wokeAtFor(target),
+            notAcceptingReason: target => this.daemons.get(target)?.notAcceptingReason?.() ?? null,
+            notifyTarget: (target, text) => { this.notifyInstanceTopic(target, text); },
+            notifySender: (source, text) => { this.notifyInstanceTopic(source, text); },
+            kickPump: () => this.scheduleDeliveryOutboxPump(),
+            now: () => Date.now(),
+            logger: this.logger,
+        });
+    }
+    /** LifecycleContext: an operator or user wake clears the coordinator's park/backoff for it. */
+    onExternalWake(name) {
+        this.wakeCoordinator?.noteExternalWake(name);
+    }
+    /**
+     * Phase 2b shared warm-slot admission (design §1.3, §1.6) for every wake
+     * that is not the coordinator's own: an operator's wake, a user's message,
+     * an explicit start or a restart of a paused instance. With delivery_worker
+     * off, or for a target that is not paused (an active restart is already
+     * counted), nothing is reserved. A target already being woken is joined —
+     * its flight holds the slot — rather than reserved twice. Otherwise a slot
+     * is taken under the hard cap, an unleased idle instance is paused to make
+     * one, and if none can be, the wake is refused instead of exceeding the cap.
+     */
+    async acquireWakeSlot(name) {
+        const coordinator = this.wakeCoordinator;
+        if (!coordinator || this.deliveryWorkerMode(name) === "off" || !this.lifecycle.isPaused(name))
+            return null;
+        if (coordinator.isWaking(name))
+            return null;
+        let token = coordinator.tryReserve(name);
+        if (!token) {
+            const victim = this.lruUnleasedIdle(name);
+            if (victim) {
+                await this.lifecycle.pause(victim, "warm_cap");
+                if (coordinator.isWaking(name))
+                    return null;
+                token = coordinator.tryReserve(name);
+            }
+        }
+        if (!token) {
+            throw new Error(`No warm slot is free for '${name}' (warm_cap + overflow reached and no idle instance can be paused); try again when one goes idle`);
+        }
+        return token;
+    }
+    releaseWakeSlot(name, token) {
+        if (!token || !this.wakeCoordinator)
+            return;
+        this.wakeCoordinator.release(name, token);
+        this.wakeCoordinator.kick();
+    }
+    /**
+     * An operator's or user's wake (/wake, wake_instance, start_instance on a
+     * paused instance, Settings, a channel message). With delivery_worker off it
+     * is exactly the old lifecycle wake; otherwise it goes through the shared
+     * slot admission and joins any wake already in flight for the target.
+     */
+    async explicitWake(name, timeoutMs = 30_000) {
+        const token = await this.acquireWakeSlot(name);
+        try {
+            await this.lifecycle.wake(name, timeoutMs);
+        }
+        finally {
+            this.releaseWakeSlot(name, token);
+        }
+    }
+    /** The least-recently-active idle, unleased, non-general running instance other than `exclude`. */
+    lruUnleasedIdle(exclude) {
+        return this.warmInstanceNames()
+            .filter(name => name !== exclude
+            && !this.warmCapEvicting.has(name)
+            && !isGeneralInstance(this.fleetConfig, name)
+            && this.getInstanceExecutionState(name) === "idle"
+            && !this.lifecycle.hasWorkLease(name))
+            .sort((a, b) => (readLastInboundAt(this.getInstanceDir(a)) ?? 0) - (readLastInboundAt(this.getInstanceDir(b)) ?? 0))[0];
+    }
     async changeInstancePauseState(name, action) {
         if (action === "wake") {
-            await this.lifecycle.wake(name, 30_000);
+            await this.explicitWake(name, 30_000);
             this.enforceWarmCap(name); // manual wake still respects the fleet warm cap
             return "awake";
         }
@@ -2068,12 +2220,14 @@ export class FleetManager {
      * and reconcile calls leave this false so a persisted pause remains paused
      * across a fleet restart.
      */
-    resumePaused = false) {
+    resumePaused = false, 
+    /** Phase 2a: the caller's transition, for a start made from inside a restart or wake. */
+    transition) {
         // Any start supersedes a pending automatic retry (it would otherwise fire
         // into a running instance — harmless, but noisy — or race this start).
         this.cancelStartupRetry(name);
         if (resumePaused && this.lifecycle.isPaused(name)) {
-            await this.lifecycle.wake(name, 30_000);
+            await this.explicitWake(name, 30_000);
             // A successful wake clears the persisted pause marker and produces a
             // fresh instance_state snapshot.  Drop any stale process error left by a
             // pre-pause crash so /api/fleet and `agend ls` converge on running.
@@ -2100,6 +2254,10 @@ export class FleetManager {
             this.logger.info({ name }, "Instance already running, skipping");
             return;
         }
+        // An explicit start (CLI/API) begins a fresh idle window; boot and
+        // reconcile starts keep the persisted last-inbound seed (Phase 2a).
+        if (resumePaused)
+            this.lifecycle.markActivitySeedNow(name);
         const backend = config.backend ?? this.fleetConfig?.defaults?.backend ?? "claude-code";
         if (config.general_topic) {
             this.ensureGeneralInstructions(config.working_directory, backend, name);
@@ -2123,7 +2281,7 @@ export class FleetManager {
             kind,
             backend,
             model: this.resolveInstanceModel(name).display,
-        });
+        }, transition);
         // Only clear a stale process status after a real start succeeded.  Clearing
         // it before lifecycle.start() can turn a crash-loop daemon's dead pane into
         // a falsely running instance when lifecycle.start() returns early.
@@ -2137,18 +2295,18 @@ export class FleetManager {
         this.requestDiscordUsagePresenceRefresh();
     }
     /** Recreate a daemon for a marker-only paused instance after an explicit wake/delivery. */
-    async startPersistedPausedInstance(name) {
+    async startPersistedPausedInstance(name, transition) {
         const topicMode = this.fleetConfig?.channel?.mode === "topic"
             || !!this.fleetConfig?.channels?.some(channel => channel.mode === "topic");
         const fleetConfig = this.fleetConfig?.instances[name];
         if (fleetConfig) {
-            await this.startInstance(name, fleetConfig, topicMode);
+            await this.startInstance(name, fleetConfig, topicMode, "fleet-topic", false, transition);
             return;
         }
         const channel = this.classicChannels?.getAll().find(item => item.instanceName === name);
         if (!channel || !this.classicChannels)
             throw new Error(`Paused instance '${name}' is no longer configured`);
-        await this.startClassicInstance(name, this.classicChannels.getBackendByInstance(name, this.fleetConfig?.defaults?.backend), this.classicChannels.getPreTaskCommand(channel.channelId, channel.adapterId), this.classicChannels.getModel(channel.channelId, channel.adapterId, this.fleetConfig?.defaults?.model), this.classicChannels.getAutoPauseAfter(channel.channelId, channel.adapterId, this.fleetConfig?.defaults?.auto_pause_after));
+        await this.startClassicInstance(name, this.classicChannels.getBackendByInstance(name, this.fleetConfig?.defaults?.backend), this.classicChannels.getPreTaskCommand(channel.channelId, channel.adapterId), this.classicChannels.getModel(channel.channelId, channel.adapterId, this.fleetConfig?.defaults?.model), this.classicChannels.getAutoPauseAfter(channel.channelId, channel.adapterId, this.fleetConfig?.defaults?.auto_pause_after), transition);
     }
     /**
      * Start instances with configurable concurrency and stagger delay.
@@ -2197,6 +2355,10 @@ export class FleetManager {
             return this.daemons.has(name);
         }
         catch (err) {
+            // Superseded by a stop/restart (Phase 2a): that transition owns the
+            // outcome. Retrying would start an instance the operator just stopped.
+            if (err instanceof SupersededStartError)
+                return false;
             this.logger.error({ err, name }, `Failed to start ${what}`);
             this.scheduleStartupRetry(name, 0);
             return false;
@@ -2318,6 +2480,9 @@ export class FleetManager {
             }
         }
         catch (err) {
+            // Superseded by a stop/restart: that transition owns the outcome.
+            if (err instanceof SupersededStartError)
+                return;
             this.logger.error({ err, name, attempt: attempt + 1 }, "Automatic startup retry failed");
             this.scheduleStartupRetry(name, attempt + 1);
         }
@@ -2358,6 +2523,8 @@ export class FleetManager {
             return this.daemons.has(ch.instanceName);
         }
         catch (err) {
+            if (err instanceof SupersededStartError)
+                return false;
             this.logger.warn({ err, instanceName: ch.instanceName }, `Failed to start ${what}`);
             this.scheduleStartupRetry(ch.instanceName, 0);
             return false;
@@ -2514,7 +2681,7 @@ export class FleetManager {
         }
         return false;
     }
-    async stopInstance(name) {
+    async stopInstance(name, transition) {
         this.explicitStopGeneration.set(name, (this.explicitStopGeneration.get(name) ?? 0) + 1);
         this.cancelStartupRetry(name);
         this.failoverActive.delete(name);
@@ -2533,7 +2700,7 @@ export class FleetManager {
         // the hand-off snapshotted it).
         const run = (async () => {
             try {
-                await this.lifecycle.stop(name);
+                await this.lifecycle.stop(name, transition);
             }
             finally {
                 this.clearNoncePromptsForInstance(name);
@@ -2555,11 +2722,16 @@ export class FleetManager {
             return inFlight;
         }
         const workingDirectory = this.fleetConfig?.instances[name]?.working_directory || this.getInstanceDir(name);
-        const run = this.spawnGate.run({
+        // Phase 2a: invalidate synchronously so a start still spawning does not
+        // publish, then queue behind it as this instance's next transition. The
+        // spawn gate is taken inside the transition, never the other way round, so
+        // the start being waited for can still get its own gate slot.
+        this.lifecycle.invalidate(name);
+        const run = this.lifecycle.runTransition(name, transition => this.spawnGate.run({
             instanceName: name,
             workingDirectory,
             reason: "restart",
-        }, () => this.doRestartSingleInstance(name, opts))
+        }, () => this.doRestartSingleInstance(name, opts, transition)))
             .finally(() => {
             this.restartsInFlight.delete(name);
             this.scheduleDeliveryOutboxPump();
@@ -2570,19 +2742,73 @@ export class FleetManager {
     isInstanceRestarting(name) {
         return this.restartsInFlight.has(name);
     }
-    async doRestartSingleInstance(name, opts) {
+    /** InstanceLifecycleContext: an explicit wake joins the restart in flight. */
+    restartInFlight(name) {
+        return this.restartsInFlight.get(name);
+    }
+    /**
+     * Phase 2a: restarting a paused instance is a wake. The stop leaves the
+     * pause marker in place, and the start used to skip on it ("Persisted
+     * paused instance"), turning a resident pause into a marker-only one that
+     * nothing would wake. Clear it before the start; if the start fails, put it
+     * back so the instance stays wakeable instead of becoming plain stopped.
+     */
+    async startAfterRestart(name, wasPaused, pausedAt, reason, start) {
+        const instanceDir = this.getInstanceDir(name);
+        if (wasPaused)
+            clearPausedMarker(instanceDir);
+        this.lifecycle.markActivitySeedNow(name);
+        try {
+            await start();
+        }
+        catch (err) {
+            if (wasPaused && !this.daemons.has(name))
+                writePausedMarker(instanceDir, pausedAt ?? Date.now(), reason);
+            throw err;
+        }
+        finally {
+            this.lifecycle.clearActivitySeedNow(name);
+        }
+    }
+    async doRestartSingleInstance(name, opts, transition) {
         if (this.configPath) {
             this.loadConfig(this.configPath);
             this.routing.rebuild(this.fleetConfig);
             this.reregisterClassicChannels();
         }
         const config = this.fleetConfig?.instances[name];
+        const wasPaused = this.lifecycle.isPaused(name);
+        // A paused instance's restart is a wake: it takes a warm slot like any other
+        // (refused before anything is stopped when none can be had). An active
+        // restart is already counted and reserves nothing.
+        const slot = await this.acquireWakeSlot(name);
+        // An active instance keeps the slot it already occupies across its own
+        // stop → replacement gap: counted as warm until the replacement is
+        // published or the restart settles, so no other target can take it.
+        if (!wasPaused)
+            this.restartsHoldingSlot.add(name);
+        try {
+            await this.doRestartWithSlot(name, opts, transition, config, wasPaused);
+            // An explicit restart of a paused instance is an operator wake (§1.6):
+            // its success lifts the coordinator's park/backoff (the level stays).
+            // Automatic restarts never do.
+            if (wasPaused && opts?.explicit && this.daemons.has(name))
+                this.wakeCoordinator?.noteExternalWake(name);
+        }
+        finally {
+            this.restartsHoldingSlot.delete(name);
+            this.releaseWakeSlot(name, slot);
+        }
+    }
+    async doRestartWithSlot(name, opts, transition, config, wasPaused) {
+        const pausedAt = wasPaused ? (this.lifecycle.getLastPausedAt(name) ?? readPausedAt(this.getInstanceDir(name))) : null;
+        const pauseReason = wasPaused ? readPauseReason(this.getInstanceDir(name)) : null;
         if (config) {
-            await this.stopInstance(name);
+            await this.stopInstance(name, transition);
             if (opts?.freshStart)
                 this.writeFreshStartMarker(name);
             const topicMode = this.fleetConfig?.channel?.mode === "topic";
-            await this.startInstance(name, config, topicMode ?? false);
+            await this.startAfterRestart(name, wasPaused, pausedAt, pauseReason, () => this.startInstance(name, config, topicMode ?? false, "fleet-topic", false, transition));
             this.stormWindow.markRecovered(name);
             return;
         }
@@ -2591,11 +2817,11 @@ export class FleetManager {
         if (channelId) {
             const fleetBackend = this.fleetConfig?.defaults?.backend;
             const adapterId = this.classicChannels.getAdapterIdByInstance(name);
-            await this.stopInstance(name);
+            await this.stopInstance(name, transition);
             await new Promise(r => setTimeout(r, 1000)); // let tmux clean up
             if (opts?.freshStart)
                 this.writeFreshStartMarker(name);
-            await this.startClassicInstance(name, this.classicChannels.getBackendByInstance(name, fleetBackend), this.classicChannels.getPreTaskCommand(channelId, adapterId), this.classicChannels.getModel(channelId, adapterId, this.fleetConfig?.defaults?.model), this.classicChannels.getAutoPauseAfter(channelId, adapterId, this.fleetConfig?.defaults?.auto_pause_after));
+            await this.startAfterRestart(name, wasPaused, pausedAt, pauseReason, () => this.startClassicInstance(name, this.classicChannels.getBackendByInstance(name, fleetBackend), this.classicChannels.getPreTaskCommand(channelId, adapterId), this.classicChannels.getModel(channelId, adapterId, this.fleetConfig?.defaults?.model), this.classicChannels.getAutoPauseAfter(channelId, adapterId, this.fleetConfig?.defaults?.auto_pause_after), transition));
             this.stormWindow.markRecovered(name);
             return;
         }
@@ -3915,7 +4141,7 @@ export class FleetManager {
             }
             else if (data.command === "sysinfo") {
                 // Slash commands are Discord-only; use plain lines (no markdown table)
-                await data.respond(this.topicCommands.getSysInfoText({ platform: "discord" }));
+                await this.topicCommands.sendSysInfo(text => data.respond(text), { platform: "discord" });
             }
             else if (data.command === "dashboard") {
                 // Reply is ephemeral (adapter defers non-chat commands ephemerally), so
@@ -4275,7 +4501,7 @@ export class FleetManager {
             }
             else if (data.command === "sysinfo") {
                 // Slash commands are Discord-only; use plain lines (no markdown table)
-                await data.respond(this.topicCommands.getSysInfoText({ platform: "discord" }));
+                await this.topicCommands.sendSysInfo(text => data.respond(text), { platform: "discord" });
             }
             else if (data.command === "dashboard") {
                 // Reply is ephemeral (adapter defers non-chat commands ephemerally), so
@@ -5850,7 +6076,8 @@ export class FleetManager {
             : 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";
+                        : type === "fleet_list_emojis" || type === "fleet_set_persona_emoji" || type === "fleet_preview_emojis" ? "fleet_persona_emoji_response"
+                            : "fleet_description_response";
         ipc.send({ type: responseType, fleetRequestId, error: message });
     }
     dispatchTypedIpc(name, msg) {
@@ -5875,6 +6102,24 @@ export class FleetManager {
             this.handleSetDescription(name, msg);
             return;
         }
+        if (type === "fleet_list_emojis" || type === "fleet_set_persona_emoji" || type === "fleet_preview_emojis") {
+            this.handlePersonaEmoji(name, msg);
+            return;
+        }
+    }
+    /** `list_emojis` / `set_persona_emoji` / `preview_emojis` over IPC; the agent endpoint calls the same methods. */
+    handlePersonaEmoji(instanceName, msg) {
+        const fleetRequestId = msg.fleetRequestId;
+        const payload = (msg.payload ?? {});
+        const ipc = this.instanceIpcClients.get(instanceName);
+        if (!ipc)
+            return;
+        const op = msg.type === "fleet_list_emojis" ? this.listEmojisFor(instanceName, payload.refresh === true)
+            : msg.type === "fleet_preview_emojis" ? this.previewEmojis(instanceName, payload)
+                : this.setPersonaEmoji(instanceName, payload);
+        op.then((r) => typeof r.error === "string"
+            ? ipc.send({ type: "fleet_persona_emoji_response", fleetRequestId, error: r.error })
+            : ipc.send({ type: "fleet_persona_emoji_response", fleetRequestId, result: r }), (err) => ipc.send({ type: "fleet_persona_emoji_response", fleetRequestId, error: err.message }));
     }
     handleScheduleCrud(instanceName, msg) {
         const fleetRequestId = msg.fleetRequestId;
@@ -5979,10 +6224,15 @@ export class FleetManager {
             ?? this.classicChannels?.getAll().find(ch => ch.instanceName === instanceName)?.displayName
             ?? instanceName;
     }
+    /** Inherited keys such as __proto__ must never resolve to a mutable instance. */
+    ownInstanceConfig(instanceName) {
+        const instances = this.fleetConfig?.instances;
+        return instances && Object.hasOwn(instances, instanceName) ? instances[instanceName] : undefined;
+    }
     /** Persist identity to the instance's actual config store. Classic instances
      * are registry rows in classicBot.yaml, not fleet.yaml instance entries. */
     setInstanceDisplayName(instanceName, displayName) {
-        const fleetInstance = this.fleetConfig?.instances[instanceName];
+        const fleetInstance = this.ownInstanceConfig(instanceName);
         if (fleetInstance) {
             fleetInstance.display_name = displayName;
             this.saveFleetConfig();
@@ -5991,7 +6241,7 @@ export class FleetManager {
         return this.classicChannels?.setDisplayNameByInstance(instanceName, displayName) ?? false;
     }
     setInstanceDescription(instanceName, description) {
-        const fleetInstance = this.fleetConfig?.instances[instanceName];
+        const fleetInstance = this.ownInstanceConfig(instanceName);
         if (fleetInstance) {
             fleetInstance.description = description;
             this.saveFleetConfig();
@@ -6217,6 +6467,15 @@ export class FleetManager {
             return { error: `Instance '${instance}' not found` };
         return { display_name: name };
     }
+    async handleListEmojisHttp(instance, refresh) {
+        return this.listEmojisFor(instance, refresh);
+    }
+    async handleSetPersonaEmojiHttp(instance, args) {
+        return this.setPersonaEmoji(instance, args);
+    }
+    async handlePreviewEmojisHttp(instance, args) {
+        return this.previewEmojis(instance, args);
+    }
     async handleSetDescriptionHttp(instance, description) {
         if (!this.fleetConfig)
             return { error: "Fleet config not available" };
@@ -6834,6 +7093,8 @@ export class FleetManager {
     deliveryStatusChains = new Map();
     /** #725: in-flight CLI env probes, keyed by backend name. Coalesces concurrent /model requests. */
     pendingCliEnvProbes = new Map();
+    /** Forced vendor catalog refreshes are separate flights, but sysinfo joins either flight. */
+    pendingVendorCliEnvProbes = new Map();
     /**
      * The status emojis for an instance (#1005): its own `status_emojis`, then
      * its channel's `options.status_emojis`, then the platform built-in. An
@@ -6864,10 +7125,15 @@ export class FleetManager {
     }
     warnedStatusEmojis = new Set();
     /**
-     * A Discord connection's server emojis for the Settings picker (#1005).
-     * Cached per connection — a server's emoji set changes rarely — and one
-     * fetch at a time; `refresh` forces a new one. Uses the running adapter, so
-     * the bot token never leaves the server.
+     * A Discord connection's server emojis for the Settings picker (#1005), from
+     * every server its bot can draw on (#1021): the primary `group_id` server,
+     * then each other server the bot is a member of that ClassicBot's
+     * `allowed_guilds` admits (unset = all, as for classic routing). A bot can
+     * react with a custom emoji from any server it is in. Cached per server — a
+     * server's emoji set changes rarely — and one fetch per server at a time;
+     * `refresh` forces new ones. One server refusing (e.g. Missing Access) is
+     * reported on that server and does not hide the others. Uses the running
+     * adapter, so the bot token never leaves the server.
      */
     async listGuildEmojis(channelId, refresh = false) {
         const world = this.worlds.get(channelId);
@@ -6878,28 +7144,268 @@ export class FleetManager {
         const adapter = world.adapter;
         if (!adapter.listGuildEmojis)
             return { ok: false, error: "this adapter cannot list server emojis" };
-        const cached = this.guildEmojiCache.get(channelId);
-        if (!refresh && cached && Date.now() - cached.fetched_at < FleetManager.GUILD_EMOJI_TTL_MS)
-            return { ok: true, ...cached };
-        let pending = this.guildEmojiFetches.get(channelId);
-        if (!pending) {
-            pending = adapter.listGuildEmojis().then(emojis => {
-                const entry = { fetched_at: Date.now(), emojis };
-                this.guildEmojiCache.set(channelId, entry);
-                return entry;
-            }).finally(() => this.guildEmojiFetches.delete(channelId));
-            this.guildEmojiFetches.set(channelId, pending);
-        }
+        const listEmojis = adapter.listGuildEmojis.bind(adapter);
+        let servers;
         try {
-            return { ok: true, ...(await pending) };
+            servers = adapter.listMemberGuilds
+                ? (await adapter.listMemberGuilds()).filter(g => g.primary || (this.classicChannels?.isGuildAllowed(g.id) ?? false))
+                : [{ id: "", name: "", primary: true }];
         }
         catch (e) {
-            return { ok: false, error: `Discord refused the emoji list: ${e.message}` };
-        }
+            return { ok: false, error: `Discord refused the server list: ${e.message}` };
+        }
+        const guilds = await Promise.all(servers.map(async (g) => {
+            const key = `${channelId}\0${g.id}`;
+            const cached = this.guildEmojiCache.get(key);
+            if (!refresh && cached && Date.now() - cached.fetched_at < FleetManager.GUILD_EMOJI_TTL_MS)
+                return { ...g, ...cached };
+            let pending = this.guildEmojiFetches.get(key);
+            if (!pending) {
+                pending = (g.id ? listEmojis(g.id) : listEmojis()).then(emojis => {
+                    const entry = { fetched_at: Date.now(), emojis };
+                    this.guildEmojiCache.set(key, entry);
+                    return entry;
+                }).finally(() => this.guildEmojiFetches.delete(key));
+                this.guildEmojiFetches.set(key, pending);
+            }
+            try {
+                return { ...g, ...(await pending) };
+            }
+            catch (e) {
+                return { ...g, error: `Discord refused the emoji list: ${e.message}` };
+            }
+        }));
+        const listed = guilds.filter((g) => !!g.emojis);
+        if (!listed.length)
+            return { ok: false, error: guilds[0]?.error ?? "no server to list emojis from" };
+        return {
+            ok: true,
+            fetched_at: Math.min(...listed.map(g => g.fetched_at)),
+            emojis: listed.flatMap(g => g.emojis),
+            guilds,
+        };
     }
     static GUILD_EMOJI_TTL_MS = 10 * 60_000;
+    /** Keyed `<connection>\0<server id>`. */
     guildEmojiCache = new Map();
     guildEmojiFetches = new Map();
+    /**
+     * What `instanceName` may pick as its persona emoji (the `list_emojis`
+     * tool): its current status set with where each value comes from, the
+     * standard emojis its platform takes, and on Discord the server emojis its
+     * bot can draw on — the same lists, and the same resolution, as the
+     * Settings picker (#1005/#1021), so an agent and an operator see one truth.
+     */
+    async listEmojisFor(instanceName, refresh = false) {
+        const self = this.fleetConfig?.instances[instanceName];
+        if (!self)
+            return { error: this.personaEmojiMissing(instanceName) };
+        const worldId = this.getInstanceAdapterId(instanceName);
+        const { platform } = this.resolveStatusEmojisFor(instanceName);
+        const channel = (worldId ? this.worlds.get(worldId)?.channelConfig : undefined) ?? this.getChannelConfig(worldId ?? undefined);
+        const current = previewStatusEmojis({ platform, platformConfig: channel?.options?.status_emojis, instanceConfig: self.status_emojis });
+        const out = {
+            platform: platform ?? null,
+            statuses: current.entries.map(e => ({ status: e.key, value: e.value, source: e.source })),
+            standard: platform === "telegram"
+                ? { reactions: [...TELEGRAM_REACTION_EMOJIS], note: "Telegram reacts only with these; progress_prefix may be any single emoji" }
+                : { suggestions: STATUS_EMOJI_SUGGESTIONS, note: "any single emoji works" },
+        };
+        if (platform === "discord" && worldId) {
+            const listed = await this.listGuildEmojis(worldId, refresh);
+            out.server_emojis = listed.ok
+                ? listed.guilds.map(g => g.emojis
+                    ? {
+                        server: g.name || g.id, primary: g.primary,
+                        emojis: g.emojis.filter(e => e.available).map(e => {
+                            const value = customEmojiValue(e);
+                            return { value, image_url: emojiImageUrl(value) };
+                        }),
+                    }
+                    : { server: g.name || g.id, primary: g.primary, error: g.error })
+                : { error: listed.error };
+        }
+        return out;
+    }
+    /**
+     * `preview_emojis` (#1040): download a few Discord server emojis so an agent
+     * can look at them before it picks one — a name and an id say nothing about
+     * what an emoji looks like. The fleet fetches, not the agent (not every
+     * backend can), and returns a local path per emoji to Read, as
+     * download_attachment does for an attachment.
+     *
+     * SSRF-safe by construction: nothing from the caller reaches a URL. The
+     * caller names emojis; each must be an available one in a server this bot
+     * can draw on (the list set_persona_emoji checks), and the CDN URL is built
+     * from that listed emoji's numeric id. Static PNG, size-capped, cached by id.
+     */
+    async previewEmojis(instanceName, args) {
+        const self = this.fleetConfig?.instances[instanceName];
+        if (!self)
+            return { error: this.personaEmojiMissing(instanceName) };
+        const wanted = args.emojis;
+        if (!Array.isArray(wanted) || wanted.length === 0 || wanted.some(e => typeof e !== "string")) {
+            return { error: "emojis is required: a list of <:name:id> values from list_emojis" };
+        }
+        if (wanted.length > FleetManager.EMOJI_PREVIEW_MAX) {
+            return { error: `at most ${FleetManager.EMOJI_PREVIEW_MAX} at a time: narrow them down by name first` };
+        }
+        const { platform } = this.resolveStatusEmojisFor(instanceName);
+        const worldId = this.getInstanceAdapterId(instanceName);
+        if (platform !== "discord" || !worldId) {
+            return { error: "only Discord server emojis need a preview; standard emojis are what they look like" };
+        }
+        const listed = await this.listGuildEmojis(worldId);
+        if (!listed.ok)
+            return { error: `cannot list this bot's server emojis: ${listed.error}` };
+        const previews = [];
+        const errors = [];
+        for (const raw of wanted) {
+            const e = normalizeEmoji(raw);
+            if (e?.kind !== "custom") {
+                errors.push({ emoji: raw, error: "not a server emoji (a standard emoji needs no preview)" });
+                continue;
+            }
+            const found = listed.emojis.find(g => g.id === e.id);
+            if (!found?.available) {
+                errors.push({ emoji: raw, error: "not a server emoji this bot can use" });
+                continue;
+            }
+            try {
+                previews.push({ emoji: customEmojiValue(found), path: await this.fetchEmojiPreview(found.id) });
+            }
+            catch (err) {
+                errors.push({ emoji: raw, error: `download failed: ${err.message}` });
+            }
+        }
+        return { previews, errors, note: "Read each path to see the emoji (a static PNG)." };
+    }
+    static EMOJI_PREVIEW_MAX = 8;
+    static EMOJI_PREVIEW_MAX_BYTES = 256 * 1024;
+    static EMOJI_PREVIEW_TTL_MS = 24 * 60 * 60_000;
+    /** One emoji's static PNG under the inbox, reused while fresh; stale ones are pruned. */
+    async fetchEmojiPreview(id) {
+        if (!/^\d{15,25}$/.test(id))
+            throw new Error("not a Discord emoji id");
+        const dir = join(this.dataDir, "inbox", "emoji-previews");
+        mkdirSync(dir, { recursive: true });
+        const now = Date.now();
+        for (const name of readdirSync(dir)) {
+            try {
+                if (now - statSync(join(dir, name)).mtimeMs > FleetManager.EMOJI_PREVIEW_TTL_MS)
+                    unlinkSync(join(dir, name));
+            }
+            catch { /* raced */ }
+        }
+        const path = join(dir, `${id}.png`);
+        if (existsSync(path))
+            return path;
+        const response = await fetch(`https://cdn.discordapp.com/emojis/${id}.png?size=96`, { signal: AbortSignal.timeout(10_000), redirect: "error" });
+        if (!response.ok)
+            throw new Error(`HTTP ${response.status}`);
+        if (!/^image\/png\b/.test(response.headers.get("content-type") ?? ""))
+            throw new Error("not a PNG");
+        const reader = response.body?.getReader();
+        if (!reader)
+            throw new Error("empty response");
+        const chunks = [];
+        let size = 0;
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            size += value.byteLength;
+            if (size > FleetManager.EMOJI_PREVIEW_MAX_BYTES) {
+                await reader.cancel();
+                throw new Error("image too large");
+            }
+            chunks.push(value);
+        }
+        const tmp = `${path}.${process.pid}.tmp`;
+        writeFileSync(tmp, Buffer.concat(chunks));
+        renameSync(tmp, path);
+        return path;
+    }
+    /**
+     * `set_persona_emoji`: `instanceName` sets one of its own status emojis —
+     * `delivered` unless it names another — in its per-instance `status_emojis`
+     * override (#1005 addendum 2), so its stamp is told apart from other bots'
+     * on a shared message. The value is judged exactly as Settings and the
+     * react path judge it (statusEmojiProblem on the instance's platform), and
+     * a Discord server emoji must be one its bot can use: an emoji from a
+     * server it is not in would be stored, preview fine, and fail every react.
+     * An empty emoji removes that status's override.
+     */
+    async setPersonaEmoji(instanceName, args) {
+        const self = this.ownInstanceConfig(instanceName);
+        if (!self)
+            return { error: this.personaEmojiMissing(instanceName) };
+        const status = (args.status ?? "delivered");
+        if (!STATUS_EMOJI_CONFIG_KEYS.includes(status)) {
+            return { error: `status must be one of ${STATUS_EMOJI_CONFIG_KEYS.join(", ")}` };
+        }
+        // Only an explicit "" removes the override. The agent endpoint, typed IPC
+        // and agent-cli do not run the MCP schema, so a call missing `emoji` must
+        // be refused here, never read as "clear my delivered stamp".
+        if (typeof args.emoji !== "string") {
+            return { error: 'emoji is required: one emoji, a <:name:id> from list_emojis, or "" to remove your override' };
+        }
+        const raw = args.emoji.trim();
+        // Whitespace is not an explicit "": a stray " " must not clear the stamp either.
+        if (!raw && args.emoji !== "") {
+            return { error: 'emoji is blank: pass one emoji, a <:name:id> from list_emojis, or exactly "" to remove your override' };
+        }
+        let value;
+        if (raw) {
+            const { platform } = this.resolveStatusEmojisFor(instanceName);
+            const problem = statusEmojiProblem(platform, status, raw);
+            if (problem)
+                return { error: `${problem}. Call list_emojis for what ${platform ?? "this channel"} accepts.` };
+            const e = normalizeEmoji(raw);
+            if (e.kind === "custom") {
+                const worldId = this.getInstanceAdapterId(instanceName);
+                if (!worldId)
+                    return { error: "no connection to check that server emoji against" };
+                const listed = await this.listGuildEmojis(worldId);
+                if (!listed.ok)
+                    return { error: `cannot check that server emoji: ${listed.error}` };
+                const found = listed.emojis.find(g => g.id === e.id);
+                if (!found?.available) {
+                    return { error: `${raw} is not a server emoji this bot can use${found ? " (Discord marks it unavailable)" : ""}. Call list_emojis for the ones it can.` };
+                }
+                value = customEmojiValue(found);
+            }
+            else {
+                value = e.value;
+            }
+        }
+        // Re-read after the validation above, which may have waited on Discord:
+        // another set_persona_emoji or a Settings save can have changed another
+        // status, or replaced this instance's config object, meanwhile. Change
+        // only this one key on what is there now. Ownership must still hold:
+        // removal during the await must not fall through to an inherited entry.
+        const current = this.ownInstanceConfig(instanceName);
+        if (!current)
+            return { error: this.personaEmojiMissing(instanceName) };
+        const map = { ...(current.status_emojis ?? {}) };
+        if (value)
+            map[status] = value;
+        else
+            delete map[status];
+        if (Object.keys(map).length)
+            current.status_emojis = map;
+        else
+            delete current.status_emojis;
+        this.saveFleetConfig();
+        this.logger.info({ instanceName, status, value: value ?? null }, value ? "Persona emoji set" : "Persona emoji cleared");
+        const resolved = this.resolveStatusEmojisFor(instanceName);
+        return { status, value: value ?? null, now: resolved[status], status_emojis: current.status_emojis ?? null };
+    }
+    personaEmojiMissing(instanceName) {
+        return this.classicChannels?.getAll().some(c => c.instanceName === instanceName)
+            ? "ClassicBot instances have no per-instance status emojis; an operator sets the connection's in Settings"
+            : `Instance '${instanceName}' not found`;
+    }
     /** What the instructions tell `instanceName` not to react with (its own status set). */
     statusEmojiAvoidList(instanceName) {
         return statusAvoidList(this.resolveStatusEmojisFor(instanceName));
@@ -9405,10 +9911,16 @@ export class FleetManager {
                 }
                 // The installer may only have added the binary to a profile PATH; a
                 // fresh login shell sees that, the fleet process's PATH may not.
-                if (!this.verifyBinaryOnLoginShell(info.binary)) {
+                const installedAt = this.locateBinaryOnLoginShell(info.binary);
+                if (!installedAt) {
                     await chat.adapter.sendText(chat.chatId, t("install.verify_failed", backend, info.binary), { threadId: chat.threadId }).catch(() => { });
                     return;
                 }
+                // #1059: make it reachable from this process too. `/login` lists what
+                // `which` finds on the fleet's own PATH, and instances resolve their
+                // binary the same way, so a binary only a login shell could see was
+                // installed, reported as verified, and then offered nowhere.
+                this.adoptBinaryDirectory(installedAt, backend);
                 if (!LOGIN_FLOWS[backend]) {
                     await chat.adapter.sendText(chat.chatId, t("install.success_no_login", backend), { threadId: chat.threadId }).catch(() => { });
                     return;
@@ -9468,15 +9980,35 @@ export class FleetManager {
         return t("install.cancelled", backend);
     }
     /** `command -v` on a login shell, so PATH additions from rc files count. */
-    verifyBinaryOnLoginShell(binary) {
+    /**
+     * The absolute path a fresh login shell resolves `binary` to, or null. Only
+     * a real executable file counts: `command -v` also answers with an alias
+     * definition or a function name, neither of which a spawn could run.
+     */
+    locateBinaryOnLoginShell(binary) {
         try {
-            const result = spawnSync("bash", ["-lc", `command -v ${binary}`], { timeout: 10_000, stdio: "pipe" });
-            return result.status === 0;
+            const result = spawnSync("bash", ["-lc", `command -v ${binary}`], { timeout: 10_000, stdio: "pipe", encoding: "utf8" });
+            if (result.status !== 0)
+                return null;
+            const path = String(result.stdout ?? "").trim().split("\n").pop()?.trim() ?? "";
+            if (!isAbsolute(path))
+                return null;
+            accessSync(path, fsConstants.X_OK);
+            return statSync(path).isFile() ? path : null;
         }
         catch {
-            return false;
+            return null;
         }
     }
+    /** Put an installed binary's directory on the fleet's PATH (#1059), once. */
+    adoptBinaryDirectory(binaryPath, backend) {
+        const dir = dirname(binaryPath);
+        const entries = (process.env.PATH ?? "").split(delimiter).filter(Boolean);
+        if (entries.includes(dir))
+            return;
+        process.env.PATH = [dir, ...entries].join(delimiter);
+        this.logger.info({ backend, dir }, "Added the installed CLI's directory to the fleet PATH");
+    }
     /** "Sign in now?" button after a successful install. */
     async handleInstallLoginConfirm(data, callbackAdapterId, receivingAdapter) {
         const claimed = this.consumeNonceCallback(INSTALL_LOGIN_CALLBACK_PREFIX, /^install-login:([0-9a-f]+):(go|later)$/, data, callbackAdapterId, receivingAdapter);
@@ -10325,6 +10857,32 @@ Plus the operational skills (fleet-health, instance-lifecycle, scheduling, sessi
         catch { /* missing / stale / corrupt */ }
         return null;
     }
+    /** Return cached CLI versions immediately. Refresh is started after /sysinfo is sent. */
+    getBackendCliVersionSnapshot() {
+        const snapshot = {};
+        for (const backend of SYSINFO_BACKEND_IDS) {
+            const cached = this.readCliEnv(backend);
+            const needsRefresh = this.cliEnvNeedsRefresh(cached);
+            const version = typeof cached?.version === "string" && cached.version.trim()
+                ? cached.version.trim()
+                : null;
+            snapshot[backend] = {
+                version,
+                probing: needsRefresh && version === null,
+            };
+        }
+        return snapshot;
+    }
+    /** Called only after the user-visible sysinfo send/respond has settled. */
+    refreshBackendCliVersions() {
+        for (const backend of SYSINFO_BACKEND_IDS) {
+            if (!this.cliEnvNeedsRefresh(this.readCliEnv(backend)))
+                continue;
+            void this.probeBackendBounded(backend, { nonBlocking: true }).catch(err => {
+                this.logger.debug({ err, backend }, "Background CLI version refresh failed");
+            });
+        }
+    }
     /** True when a cached CLI env is old enough that `/model` should re-probe. */
     cliEnvNeedsRefresh(env) {
         return !env || typeof env.probedAt !== "number" || Date.now() - env.probedAt >= CLI_ENV_FRESH_MS;
@@ -10335,33 +10893,97 @@ Plus the operational skills (fleet-health, instance-lifecycle, scheduling, sessi
      * previous list, never stall the command that asked for it.
      */
     async probeBackendBounded(backend, opts = {}) {
-        // #725: single-flight per backend — if a probe for this backend is already
-        // in flight, return the same promise instead of starting a duplicate.
-        // Refresh probes (refreshVendorCatalog=true) are always started fresh since
-        // the caller explicitly asked for a new vendor fetch.
-        if (!opts.refreshVendorCatalog) {
-            const existing = this.pendingCliEnvProbes.get(backend);
-            if (existing)
-                return existing;
-        }
-        const work = this.probeBackend(backend, opts);
+        // #725: single-flight per backend. Explicit vendor refreshes remain a
+        // separate flight from an ordinary probe, while sysinfo can join either.
+        const regularFlight = this.pendingCliEnvProbes.get(backend);
+        const vendorFlight = this.pendingVendorCliEnvProbes.get(backend);
+        if (opts.refreshVendorCatalog && vendorFlight)
+            return vendorFlight;
+        if (!opts.refreshVendorCatalog && (vendorFlight || regularFlight))
+            return vendorFlight ?? regularFlight;
+        const worker = opts.nonBlocking ? this.startCliEnvProbeWorker(backend, opts) : undefined;
+        const work = worker?.promise ?? this.probeBackend(backend, opts);
         work.catch(() => { });
         let timer;
         const deadline = new Promise(resolve => {
             timer = setTimeout(() => {
+                worker?.terminate();
                 this.logger.warn({ backend, deadlineMs: CLI_ENV_PROBE_DEADLINE_MS }, "CLI env live probe exceeded its deadline — serving the cached model list");
                 resolve(null);
             }, CLI_ENV_PROBE_DEADLINE_MS);
         });
         const bounded = Promise.race([work, deadline]).finally(() => {
             clearTimeout(timer);
-            if (this.pendingCliEnvProbes.get(backend) === bounded)
-                this.pendingCliEnvProbes.delete(backend);
+            const flights = opts.refreshVendorCatalog ? this.pendingVendorCliEnvProbes : this.pendingCliEnvProbes;
+            if (flights.get(backend) === bounded)
+                flights.delete(backend);
         });
-        if (!opts.refreshVendorCatalog)
-            this.pendingCliEnvProbes.set(backend, bounded);
+        (opts.refreshVendorCatalog ? this.pendingVendorCliEnvProbes : this.pendingCliEnvProbes).set(backend, bounded);
         return bounded;
     }
+    startCliEnvProbeWorker(backend, opts) {
+        const workerData = {
+            backend,
+            instanceDir: join(getAgendHome(), "cli-env"),
+            config: {
+                workingDirectory: "",
+                instanceDir: join(getAgendHome(), "cli-env"),
+                instanceName: `probe-${backend}`,
+                mcpServers: {},
+            },
+            refreshVendorCatalog: opts.refreshVendorCatalog === true,
+        };
+        // `tsx src/cli.ts` needs its TS module resolver inside the separate isolate.
+        // Published builds load the compiled worker and require no tsx dependency.
+        const worker = import.meta.url.endsWith(".ts")
+            ? new Worker(`const { workerData } = require("node:worker_threads"); import("tsx/esm/api").then(({ tsImport }) => tsImport(workerData.entry, workerData.entry));`, { eval: true, execArgv: [], workerData: { ...workerData, entry: new URL("./backend/cli-env-probe-worker.ts", import.meta.url).href } })
+            : new Worker(new URL("./backend/cli-env-probe-worker.js", import.meta.url), { execArgv: [], workerData });
+        let settled = false;
+        let resolveProbe;
+        const promise = new Promise(resolve => { resolveProbe = resolve; });
+        const finish = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            resolveProbe(value);
+            void worker.terminate().catch(err => {
+                this.logger.debug({ backend, err }, "CLI env worker termination failed");
+            });
+        };
+        worker.once("message", (message) => {
+            if (settled)
+                return;
+            if (!message.ok) {
+                this.logger.warn({ backend, error: message.error }, "CLI env worker failed");
+                finish(null);
+            }
+            else if (!message.result) {
+                finish(null);
+            }
+            else {
+                try {
+                    finish(this.persistCliEnvProbeResult(backend, message.result));
+                }
+                catch (err) {
+                    this.logger.warn({ backend, err }, "CLI env cache write failed");
+                    finish(null);
+                }
+            }
+        });
+        worker.once("error", err => {
+            if (settled)
+                return;
+            this.logger.warn({ backend, err }, "CLI env worker crashed");
+            finish(null);
+        });
+        worker.once("exit", code => {
+            if (settled)
+                return;
+            this.logger.warn({ backend, code }, "CLI env worker exited without a result");
+            finish(null);
+        });
+        return { promise, terminate: () => { finish(null); } };
+    }
     /**
      * Resolve the effective model for a fleet or ClassicBot instance, plus where it
      * came from. Single source of truth for `/model` and `/ctx` — precedence:
@@ -10428,35 +11050,39 @@ Plus the operational skills (fleet-health, instance-lifecycle, scheduling, sessi
             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
-            // probes hit the network (`agy models` fetches, 5s cap), so a slow moment
-            // returns [] — and writing that would blank the list for the whole 24h
-            // TTL, long after the CLI recovered. Observed live: a good 11-model
-            // antigravity cache replaced by an empty one. Keep the known models and
-            // let the fresher currentModel/version through.
-            if (!env.models?.length) {
-                const previous = this.readCliEnv(backend);
-                if (previous?.models?.length)
-                    env.models = previous.models;
-            }
-            // Same protection for the extended catalog: one offline moment must not
-            // blank a good account list for the whole cache TTL.
-            if (!env.apiModels?.length) {
-                const previous = this.readCliEnv(backend);
-                if (previous?.apiModels?.length)
-                    env.apiModels = previous.apiModels;
-            }
-            const path = this.cliEnvPath(backend);
-            mkdirSync(dirname(path), { recursive: true });
-            writeFileSync(path, JSON.stringify(env, null, 2));
-            return env;
+            return this.persistCliEnvProbeResult(backend, probed);
         }
         catch (err) {
             this.logger.warn({ err, backend }, "CLI env probe failed");
             return null;
         }
     }
+    /** Preserve the existing cache merge rules for both in-process and worker probes. */
+    persistCliEnvProbeResult(backend, probed) {
+        const env = { backend, probedAt: Date.now(), ...probed };
+        // An empty result must never overwrite a catalog we already have. Some
+        // probes hit the network (`agy models` fetches, 5s cap), so a slow moment
+        // returns [] — and writing that would blank the list for the whole 24h
+        // TTL, long after the CLI recovered. Observed live: a good 11-model
+        // antigravity cache replaced by an empty one. Keep the known models and
+        // let the fresher currentModel/version through.
+        if (!env.models?.length) {
+            const previous = this.readCliEnv(backend);
+            if (previous?.models?.length)
+                env.models = previous.models;
+        }
+        // Same protection for the extended catalog: one offline moment must not
+        // blank a good account list for the whole cache TTL.
+        if (!env.apiModels?.length) {
+            const previous = this.readCliEnv(backend);
+            if (previous?.apiModels?.length)
+                env.apiModels = previous.apiModels;
+        }
+        const path = this.cliEnvPath(backend);
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, JSON.stringify(env, null, 2));
+        return env;
+    }
     /** Background-probe every distinct backend in use at startup (non-blocking). */
     probeCliEnvs() {
         const backends = new Set();
@@ -11429,7 +12055,7 @@ Plus the operational skills (fleet-health, instance-lifecycle, scheduling, sessi
         await pending.complete(warning ? `${warning}\n\n${reply}` : reply, pending.messageId);
     }
     /** Start a classic channel instance with lightweight config */
-    async startClassicInstance(instanceName, backend, preTaskCommand, model, autoPauseAfter) {
+    async startClassicInstance(instanceName, backend, preTaskCommand, model, autoPauseAfter, transition) {
         if (this.daemons.has(instanceName))
             return;
         const workDir = join(getAgendHome(), "workspaces", instanceName);
@@ -11456,7 +12082,7 @@ Plus the operational skills (fleet-health, instance-lifecycle, scheduling, sessi
             ...(preTaskCommand ? { pre_task_command: preTaskCommand } : {}),
         };
         const topicMode = this.fleetConfig?.channel?.mode === "topic";
-        await this.startInstance(instanceName, config, topicMode, "classic");
+        await this.startInstance(instanceName, config, topicMode, "classic", false, transition);
     }
     /** Handle /start slash command — register classic channel */
     async handleClassicStart(channelId, channelName, userId, guildId, adapterId, backend) {
@@ -11568,6 +12194,7 @@ Plus the operational skills (fleet-health, instance-lifecycle, scheduling, sessi
             clearInterval(this.replyObligationTimer);
             this.replyObligationTimer = null;
         }
+        this.wakeCoordinator?.stop();
         if (this.logRotateTimer) {
             clearInterval(this.logRotateTimer);
             this.logRotateTimer = null;
@@ -13629,7 +14256,7 @@ Plus the operational skills (fleet-health, instance-lifecycle, scheduling, sessi
                 this.logger.info({ name }, "Instance restart requested via HTTP");
                 (async () => {
                     try {
-                        await this.restartSingleInstance(name);
+                        await this.restartSingleInstance(name, { explicit: true });
                         this.logger.info({ name }, "Instance restarted");
                         this.emitSseEvent("status", this.getUiStatus());
                         res.writeHead(200);