@songsid/agend 2.1.4-beta.1 → 2.1.4-beta.3

package/dist/fleet-manager.js

@@ -4,7 +4,8 @@ import { createServer } from "node:http";
 import { join, dirname, basename } from "node:path";
 import { fileURLToPath } from "node:url";
 import { getAgendHome, ensureWorkspaceGit } from "./paths.js";
-import { clearUpdateMarker, isUpdateInProgress } from "./update-marker.js";
+import { beginUpdateProgress as persistUpdateProgress, clearUpdateMarker, isUpdateInProgress, readUpdateProgress, setUpdateProgressStage, } from "./update-marker.js";
+import { formatUpdateProgress } from "./update-progress.js";
 import { sdNotify, sdNotifyBlocking } from "./sd-notify.js";
 import { readFleetMemory } from "./process-memory.js";
 import { ReplyDeduper } from "./reply-dedup.js";
@@ -153,6 +154,12 @@ const PROGRESS_ACTIVITY_MAX_CHARS = 48;
  * 🫡 passes too — it reads as a deliberate acknowledgement, not plumbing.
  */
 const DELIVERY_STATUS_EMOJIS = new Set(["👀", "⏳", "✅", "❌"]);
+/**
+ * Reactions that are neither delivery plumbing nor meaningful conversational
+ * feedback. Keep this separate from DELIVERY_STATUS_EMOJIS so adding a UI-only
+ * emoji never changes the documented delivery-state protocol.
+ */
+const IGNORED_REACTION_EMOJIS = new Set(["📷"]);
 /**
  * How long a delivery waits out a disconnected instance IPC before giving up.
  *
@@ -165,6 +172,11 @@ const CLASSIC_BACKEND_SELECTION_TIMEOUT_MS = 60_000;
 const CLASSIC_BACKEND_CALLBACK_PREFIX = "classic-backend:";
 const MODEL_SELECT_CALLBACK_PREFIX = "model-select:";
 const EFFORT_SELECT_CALLBACK_PREFIX = "effort-select:";
+const INTERACTIVE_ASSIST_CALLBACK_PREFIX = "interactive-assist:";
+const EXIT_RESTART_CALLBACK_PREFIX = "exit-restart:";
+const HANG_CALLBACK_PREFIX = "hang:";
+/** One lifetime for every nonce-armed button prompt (hang / assist / exit). */
+const NONCE_BUTTON_TIMEOUT_MS = 15 * 60_000;
 const CLI_ENV_TTL_MS = 24 * 60 * 60 * 1000; // /model reads cached CLI env within 24h
 export class FleetManager {
     dataDir;
@@ -253,6 +265,8 @@ export class FleetManager {
     /** In-flight /effort selections, same coordinator shape as pendingModelSelects. */
     pendingEffortSelects = new Map();
     pendingModelSelects = new Map();
+    /** nonce → pending button prompt (hang restart, interactive assist, clean-exit restart). */
+    pendingNonceButtons = new Map();
     // Model failover state
     failoverActive = new Map(); // instance → current failover model
     // IPC reconnect: tracks instances being intentionally stopped (skip reconnect)
@@ -274,6 +288,9 @@ export class FleetManager {
     healthServer = null;
     healthPortRetried = false;
     updateCheckTimer = null;
+    updateProgressTimer = null;
+    updateProgressEditRunning = false;
+    lastUpdateProgressText = null;
     eventLogPruneTimer = null;
     logRotateTimer = null;
     /** Days of event/activity history to keep. */
@@ -553,6 +570,38 @@ export class FleetManager {
         }
         await data.respond(await this.topicCommands.runPauseWake(target, action));
     }
+    async handleUpdateSlash(data, adapterId) {
+        const allowed = this.fleetConfig?.channel?.access?.allowed_users ?? [];
+        if (allowed.length > 0 && !allowed.some(u => String(u) === String(data.userId))) {
+            await data.respond(t("not_authorized"));
+            return;
+        }
+        const messageId = await data.respond(t("update.progress.preparing", 0));
+        const adapter = this.adapters.get(adapterId) ?? this.adapter;
+        if (messageId && adapter) {
+            const chatId = String(this.getChannelConfig(adapterId)?.group_id ?? data.channelId);
+            this.beginUpdateProgress(adapter, chatId, data.channelId, messageId);
+        }
+        const { spawn } = await import("node:child_process");
+        const currentVersion = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), "..", "package.json"), "utf-8")).version ?? "";
+        const command = currentVersion.includes("beta") ? "agend update --beta" : "agend update";
+        const child = spawn("sh", ["-c", `sleep 2 && ${command}`], { detached: true, stdio: "ignore" });
+        child.once("error", err => this.failUpdateProgress(err.message));
+        child.unref();
+    }
+    /** Admin-only full conversation reset for fleet-topic and Classic instances. */
+    async handleClearSlash(data, adapterId) {
+        if (!this.isModelAdmin(data.userId, data.channelId, adapterId)) {
+            await data.respond(t("permission.denied"));
+            return;
+        }
+        const name = this.resolveSlashTarget(data.channelId, adapterId);
+        if (!name) {
+            await data.respond(t("classic.no_agent"));
+            return;
+        }
+        await data.respond(await this.topicCommands.sendClear(name));
+    }
     /** Get the adapter bound to an instance, falling back to primary adapter */
     getAdapterForInstance(name) {
         const worldId = this.getInstanceAdapterId(name);
@@ -1193,7 +1242,18 @@ export class FleetManager {
         this.instanceStateCache.delete(name);
         this.instanceProcessStatus.delete(name);
         this.lastDeliveryAt.delete(name);
-        return this.lifecycle.stop(name);
+        // A pending hang/exit/assist offer refers to the instance being torn down;
+        // left alone it would stay clickable for the rest of its 15 minutes. Clear
+        // again AFTER the stop completes: the teardown itself can emit hang /
+        // interactive-prompt / clean-exit events whose handlers post fresh prompts
+        // while the stop is still awaiting (the TOCTOU sol's review called out).
+        this.clearNoncePromptsForInstance(name);
+        try {
+            return await this.lifecycle.stop(name);
+        }
+        finally {
+            this.clearNoncePromptsForInstance(name);
+        }
     }
     /** Restart a single instance, reloading fleet.yaml first to pick up config changes. */
     async restartSingleInstance(name, opts) {
@@ -1293,6 +1353,65 @@ export class FleetManager {
     getDashboardAccess() {
         return { ready: this.healthServerListening, token: this.webToken };
     }
+    beginUpdateProgress(adapter, chatId, threadId, messageId) {
+        persistUpdateProgress(this.dataDir, {
+            adapterId: adapter.id,
+            chatId,
+            ...(threadId ? { threadId } : {}),
+            messageId,
+        });
+        this.lastUpdateProgressText = null;
+        this.startUpdateProgressMonitor(adapter);
+    }
+    failUpdateProgress(message) {
+        setUpdateProgressStage(this.dataDir, "failed", { error: message });
+    }
+    /** The old fleet edits CLI install stages; the new fleet adopts the same message below. */
+    startUpdateProgressMonitor(initialAdapter) {
+        if (this.updateProgressTimer)
+            clearInterval(this.updateProgressTimer);
+        const tick = async () => {
+            if (this.updateProgressEditRunning)
+                return;
+            const marker = readUpdateProgress(this.dataDir);
+            if (!marker) {
+                if (this.updateProgressTimer)
+                    clearInterval(this.updateProgressTimer);
+                this.updateProgressTimer = null;
+                return;
+            }
+            const target = marker.progress.target;
+            const adapter = this.adapters.get(target.adapterId) ?? (initialAdapter?.id === target.adapterId ? initialAdapter : undefined);
+            if (!adapter)
+                return;
+            const text = formatUpdateProgress(marker);
+            if (text === this.lastUpdateProgressText)
+                return;
+            this.updateProgressEditRunning = true;
+            try {
+                await adapter.editMessage(target.chatId, target.messageId, text, target.threadId);
+                this.lastUpdateProgressText = text;
+                if (marker.progress.stage === "failed" || marker.progress.stage === "complete") {
+                    clearUpdateMarker(this.dataDir);
+                    if (this.updateProgressTimer)
+                        clearInterval(this.updateProgressTimer);
+                    this.updateProgressTimer = null;
+                }
+            }
+            catch (err) {
+                this.logger.warn({ err }, "Failed to edit update progress");
+            }
+            finally {
+                this.updateProgressEditRunning = false;
+            }
+        };
+        void tick();
+        // Poll stages faster than the elapsed-time display. npm verification and
+        // service-file refresh can be short; 200ms prevents those stages from being
+        // skipped while the text cache still limits normal edits to once per second.
+        this.updateProgressTimer = setInterval(() => void tick(), 200);
+        this.updateProgressTimer.unref?.();
+    }
     /** Start all instances from fleet config */
     async startAll(configPath) {
         const startupStartedAt = Date.now();
@@ -1307,6 +1426,15 @@ export class FleetManager {
         rotateLogIfNeeded(join(this.dataDir, "fleet.log"));
         const fleet = this.loadConfig(configPath);
         setLocale(detectLocale(fleet)); // user-facing text language (fleet.yaml defaults.locale / timezone)
+        const savedUpdateProgress = readUpdateProgress(this.dataDir);
+        const pendingUpdateProgress = savedUpdateProgress
+            && savedUpdateProgress.progress.stage !== "failed"
+            && savedUpdateProgress.progress.stage !== "complete"
+            ? savedUpdateProgress
+            : null;
+        if (pendingUpdateProgress) {
+            setUpdateProgressStage(this.dataDir, "starting", { version: pendingUpdateProgress.progress.version });
+        }
         this.initializeWebAuthTokens();
         const topicMode = fleet.channel?.mode === "topic" || !!fleet.channels?.some(ch => ch.mode === "topic");
         // Set tmux socket isolation for custom AGEND_HOME
@@ -1563,7 +1691,7 @@ export class FleetManager {
         const allEntries = Object.entries(fleet.instances);
         const generals = allEntries.filter(([_, cfg]) => cfg.general_topic);
         const others = allEntries.filter(([_, cfg]) => !cfg.general_topic);
-        const startupProgress = new RestartProgress(this.runnableStartupCount(fleet, topicMode), startupStartedAt, this.logger);
+        const startupProgress = new RestartProgress(this.runnableStartupCount(fleet, topicMode), pendingUpdateProgress?.startedAt ?? startupStartedAt, this.logger, { mode: pendingUpdateProgress ? "update" : "restart" });
         if (generals.length > 0) {
             for (const [name, cfg] of generals) {
                 try {
@@ -1602,7 +1730,19 @@ export class FleetManager {
                     this.logger.error({ err }, "startSharedAdapter failed — fleet continues without some adapters");
                 }
             })();
-            progressStart = adapterStartup.then(() => startupProgress.start(this.restartProgressTarget()));
+            progressStart = adapterStartup.then(() => {
+                if (pendingUpdateProgress) {
+                    const saved = pendingUpdateProgress.progress.target;
+                    const adapter = this.adapters.get(saved.adapterId);
+                    const target = adapter ? {
+                        adapter,
+                        chatId: saved.chatId,
+                        threadId: saved.threadId,
+                    } : null;
+                    return startupProgress.resume(target, saved.messageId);
+                }
+                return startupProgress.start(this.restartProgressTarget());
+            });
         }
         // The systemd watchdog answers exactly one question: is this process still
         // turning its event loop? Pinging from a timer proves that, and after the
@@ -1980,31 +2120,18 @@ export class FleetManager {
             await this.handleInboundReaction(r);
         }, this.logger, "adapter.reaction"));
         this.adapter.on("callback_query", safeHandler(async (data) => {
+            if (await this.handleExitRestartPrompt(data, adapterId, this.adapter ?? undefined))
+                return;
+            if (await this.handleInteractivePromptAssist(data, adapterId, this.adapter ?? undefined))
+                return;
             if (await this.handleClassicBackendSelection(data))
                 return;
             if (await this.handleModelSelection(data))
                 return;
             if (await this.handleEffortSelection(data))
                 return;
-            if (data.callbackData.startsWith("hang:")) {
-                const parts = data.callbackData.split(":");
-                const action = parts[1];
-                const instanceName = parts[2];
-                if (action === "restart") {
-                    await this.stopInstance(instanceName);
-                    const config = this.fleetConfig?.instances[instanceName];
-                    if (config) {
-                        const topicMode = this.fleetConfig?.channel?.mode === "topic";
-                        await this.startInstance(instanceName, config, topicMode);
-                        // startInstance already calls connectIpcToInstance
-                    }
-                    this.adapter?.editMessage(data.chatId, data.messageId, `🔄 ${instanceName} restarted.`, data.threadId).catch(() => { });
-                }
-                else {
-                    this.adapter?.editMessage(data.chatId, data.messageId, `⏳ Continuing to wait for ${instanceName}.`, data.threadId).catch(() => { });
-                }
+            if (await this.handleHangPrompt(data, adapterId, this.adapter ?? undefined))
                 return;
-            }
             if (data.callbackData.startsWith("cancel:")) {
                 this.handleCancelClick(data.callbackData.slice("cancel:".length), this.adapter, data);
                 return;
@@ -2083,6 +2210,9 @@ export class FleetManager {
                 const result = await this.topicCommands.sendCompact(name);
                 await data.respond(result);
             }
+            else if (data.command === "clear") {
+                await this.handleClearSlash(data, adapterId);
+            }
             else if (data.command === "model") {
                 await this.handleModelSlash(data, adapterId);
             }
@@ -2135,17 +2265,7 @@ export class FleetManager {
                     : t("collab.off.classic"));
             }
             else if (data.command === "update") {
-                const allowed = this.fleetConfig?.channel?.access?.allowed_users ?? [];
-                if (allowed.length > 0 && !allowed.some(u => String(u) === String(data.userId))) {
-                    await data.respond(t("not_authorized"));
-                    return;
-                }
-                await data.respond(t("update.running"));
-                const { spawn } = await import("node:child_process");
-                const _cv = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), "..", "package.json"), "utf-8")).version ?? "";
-                const _cmd = _cv.includes("beta") ? "agend update --beta" : "agend update";
-                const child = spawn("sh", ["-c", `sleep 2 && ${_cmd}`], { detached: true, stdio: "ignore" });
-                child.unref();
+                await this.handleUpdateSlash(data, adapterId);
             }
             else if (data.command === "doctor") {
                 const allowed = this.fleetConfig?.channel?.access?.allowed_users ?? [];
@@ -2290,30 +2410,18 @@ export class FleetManager {
             await this.handleInboundReaction(r);
         }, this.logger, `adapter[${adapterId}].reaction`));
         adapter.on("callback_query", safeHandler(async (data) => {
+            if (await this.handleExitRestartPrompt(data, adapterId, adapter))
+                return;
+            if (await this.handleInteractivePromptAssist(data, adapterId, adapter))
+                return;
             if (await this.handleClassicBackendSelection(data))
                 return;
             if (await this.handleModelSelection(data))
                 return;
             if (await this.handleEffortSelection(data))
                 return;
-            if (data.callbackData.startsWith("hang:")) {
-                const parts = data.callbackData.split(":");
-                const action = parts[1];
-                const instanceName = parts[2];
-                if (action === "restart") {
-                    await this.stopInstance(instanceName);
-                    const config = this.fleetConfig?.instances[instanceName];
-                    if (config) {
-                        const topicMode = this.fleetConfig?.channel?.mode === "topic";
-                        await this.startInstance(instanceName, config, topicMode);
-                    }
-                    adapter.editMessage(data.chatId, data.messageId, `🔄 ${instanceName} restarted.`, data.threadId).catch(() => { });
-                }
-                else {
-                    adapter.editMessage(data.chatId, data.messageId, `⏳ Continuing to wait for ${instanceName}.`, data.threadId).catch(() => { });
-                }
+            if (await this.handleHangPrompt(data, adapterId, adapter))
                 return;
-            }
             if (data.callbackData.startsWith("cancel:")) {
                 this.handleCancelClick(data.callbackData.slice("cancel:".length), adapter, data);
                 return;
@@ -2385,6 +2493,9 @@ export class FleetManager {
             else if (data.command === "model") {
                 await this.handleModelSlash(data, adapterId);
             }
+            else if (data.command === "clear") {
+                await this.handleClearSlash(data, adapterId);
+            }
             else if (data.command === "effort") {
                 await this.handleEffortSlash(data, adapterId);
             }
@@ -2434,17 +2545,7 @@ export class FleetManager {
                     : t("collab.off.classic"));
             }
             else if (data.command === "update") {
-                const allowed = this.fleetConfig?.channel?.access?.allowed_users ?? [];
-                if (allowed.length > 0 && !allowed.some(u => String(u) === String(data.userId))) {
-                    await data.respond(t("not_authorized"));
-                    return;
-                }
-                await data.respond(t("update.running"));
-                const { spawn } = await import("node:child_process");
-                const _cv = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), "..", "package.json"), "utf-8")).version ?? "";
-                const _cmd = _cv.includes("beta") ? "agend update --beta" : "agend update";
-                const child = spawn("sh", ["-c", `sleep 2 && ${_cmd}`], { detached: true, stdio: "ignore" });
-                child.unref();
+                await this.handleUpdateSlash(data, adapterId);
             }
             else if (data.command === "doctor") {
                 const allowed = this.fleetConfig?.channel?.access?.allowed_users ?? [];
@@ -2818,6 +2919,10 @@ export class FleetManager {
             this.logger.debug({ emoji: r.emoji, user: r.username }, "Ignoring delivery-status emoji as a reaction");
             return;
         }
+        if (IGNORED_REACTION_EMOJIS.has(r.emoji)) {
+            this.logger.debug({ emoji: r.emoji, user: r.username }, "Ignoring non-contextual emoji reaction");
+            return;
+        }
         this.eventLog?.logActivity("reaction", r.username, `${r.emoji} ${r.action}`, instanceName);
         if (r.action === "add") {
             this.eventLog?.addReaction(instanceName, r.messageId, r.username, r.emoji);
@@ -3073,6 +3178,21 @@ export class FleetManager {
                     await msgAdapter?.sendText(chatId, result);
                     return;
                 }
+                // Handle /clear command (admin only) — unlike /compact this starts a
+                // fresh conversation and intentionally discards the current history.
+                if (text === "/clear" || text.startsWith("/clear@")) {
+                    if (!this.isModelAdmin(msg.userId, chatId, msg.adapterId)) {
+                        await msgAdapter?.sendText(chatId, t("cmd.admin_required", "/clear"));
+                        return;
+                    }
+                    const clearName = this.classicChannels.getInstanceByChannel(chatId, msg.adapterId);
+                    if (!clearName) {
+                        await msgAdapter?.sendText(chatId, t("classic.no_agent_start"));
+                        return;
+                    }
+                    await msgAdapter?.sendText(chatId, await this.topicCommands.sendClear(clearName));
+                    return;
+                }
                 // Handle /cancel command
                 if (text === "/cancel" || text.startsWith("/cancel@")) {
                     const cancelName = this.classicChannels.getInstanceByChannel(chatId, msg.adapterId);
@@ -4212,7 +4332,13 @@ export class FleetManager {
         }
         catch (err) {
             const e = err;
-            return stripAnsi(e.stdout ?? e.message ?? "Doctor failed");
+            const output = stripAnsi(e.stdout ?? "").trim();
+            if (output)
+                return output;
+            if (e.code === "ENOENT") {
+                return "Backend doctor unavailable — agend CLI not found in PATH";
+            }
+            return stripAnsi(e.message ?? "").trim() || "Doctor failed";
         }
     }
     /** Drop event/activity rows older than the retention window. Best-effort. */
@@ -4364,6 +4490,316 @@ export class FleetManager {
                 .catch(e => this.logger.warn({ err: e, instanceName }, "Failed to send notification (no topic)"));
         }
     }
+    // ── Nonce-armed button prompts (hang / interactive-assist / exit-restart) ──
+    //
+    // One shared lifecycle for every "notification with decision buttons":
+    // post with a 128-bit nonce, arm a 15-min expiry, bind the click to the
+    // exact adapter+chat+thread+message that created it, require fleet admin,
+    // consume exactly once. The three features differ only in what they post
+    // and what a consumed click does.
+    /**
+     * Post decision buttons whose callback ids are `<prefix><nonce>:<action>`.
+     * The entry is registered before the send and rolled back if the send
+     * fails, so a nonce in the map always refers to a message that exists (or
+     * is about to). Returns the nonce, or null when the alert could not be sent.
+     */
+    async postNonceButtonPrompt(opts) {
+        // 16 bytes = the 128-bit capability the design claims. Telegram's 64-byte
+        // callback_data cap still holds: longest id is "interactive-assist:" (19)
+        // + 32 hex + ":confirm" (8) = 59 bytes.
+        const nonce = randomBytes(16).toString("hex");
+        const entry = {
+            prefix: opts.prefix,
+            instanceName: opts.instanceName,
+            adapterId: opts.adapterId,
+            adapter: opts.adapter,
+            chatId: opts.chatId,
+            threadId: opts.threadId,
+            expiredText: opts.expiredText,
+            ...opts.extra,
+        };
+        entry.timer = setTimeout(() => {
+            const pending = this.pendingNonceButtons.get(nonce);
+            if (pending !== entry)
+                return;
+            this.pendingNonceButtons.delete(nonce);
+            if (entry.messageId && entry.adapter.editMessageRemoveButtons) {
+                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 expire button prompt"));
+            }
+        }, opts.timeoutMs ?? NONCE_BUTTON_TIMEOUT_MS);
+        entry.timer.unref?.();
+        this.pendingNonceButtons.set(nonce, entry);
+        try {
+            const sent = await opts.adapter.notifyAlert(opts.chatId, {
+                type: opts.alertType,
+                instanceName: opts.instanceName,
+                message: opts.message,
+                choices: opts.choices.map(c => ({ id: `${opts.prefix}${nonce}:${c.action}`, label: c.label })),
+            }, opts.threadId ? { threadId: opts.threadId } : undefined);
+            entry.messageId = sent.messageId;
+            return nonce;
+        }
+        catch (err) {
+            this.pendingNonceButtons.delete(nonce);
+            if (entry.timer)
+                clearTimeout(entry.timer);
+            this.logger.warn({ err, instanceName: opts.instanceName, prefix: opts.prefix }, "Failed to send button prompt");
+            return null;
+        }
+    }
+    /**
+     * Claim a nonce-armed callback exactly once.
+     *
+     * Returns:
+     *  - null       — the callback is not for this prefix; try the next handler
+     *  - "consumed" — for this prefix but stale/denied/malformed; stop dispatch
+     *  - the entry+action — the click is authorized and now claimed (removed
+     *    from the map before any await, so double clicks cannot act twice)
+     *
+     * A stale click (expired nonce, or a pre-upgrade button whose payload no
+     * longer parses) collapses the clicked message so the dead button stops
+     * inviting clicks — the same courtesy the cancel button extends.
+     */
+    consumeNonceCallback(prefix, actionRe, data, callbackAdapterId, receivingAdapter) {
+        if (!data.callbackData.startsWith(prefix))
+            return null;
+        const match = data.callbackData.match(actionRe);
+        let pending = match ? this.pendingNonceButtons.get(match[1]) : undefined;
+        // The map is shared across prompt kinds. A nonce that resolves to an entry
+        // of a DIFFERENT kind is not a usable capability for this handler — treat
+        // it as stale rather than acting across kinds (fail closed).
+        if (pending && pending.prefix !== prefix)
+            pending = undefined;
+        if (!match || !pending) {
+            const adapter = receivingAdapter ?? this.adapter;
+            adapter?.editMessageRemoveButtons?.(data.chatId, data.messageId, t("buttons.stale"), data.threadId).catch(() => { });
+            return "consumed";
+        }
+        // Bind the capability to the exact message/world that created it. Telegram
+        // keyboards are visible to everyone, so the click also requires fleet admin.
+        if (pending.adapterId !== callbackAdapterId
+            || data.chatId !== pending.chatId
+            || (pending.threadId != null && data.threadId !== pending.threadId)
+            || (pending.messageId != null && data.messageId !== pending.messageId)
+            || !data.userId
+            || !this.isFleetAdmin(data.userId, callbackAdapterId)) {
+            // Deliberately does NOT consume the nonce: the real admin can still click.
+            this.logger.warn({ instanceName: pending.instanceName, prefix, userId: data.userId }, "Rejected unauthorized or mismatched button callback");
+            return "consumed";
+        }
+        // Claim before any await: double clicks and duplicate callback delivery can
+        // never act twice.
+        this.pendingNonceButtons.delete(match[1]);
+        if (pending.timer)
+            clearTimeout(pending.timer);
+        return { entry: pending, action: match[2] };
+    }
+    /** Collapse a consumed prompt's buttons into a final status line. */
+    async retireNonceButtons(pending, messageId, text) {
+        if (!pending.adapter.editMessageRemoveButtons) {
+            this.logger.warn({ instanceName: pending.instanceName, adapterId: pending.adapterId }, "Adapter cannot remove prompt buttons");
+            return;
+        }
+        try {
+            await pending.adapter.editMessageRemoveButtons(pending.chatId, messageId, text, pending.threadId);
+        }
+        catch (err) {
+            // The action was already atomically consumed. An edit failure must not
+            // undo that or make the button actionable again.
+            this.logger.warn({ err, instanceName: pending.instanceName }, "Failed to retire prompt buttons");
+        }
+    }
+    /**
+     * Drop every pending prompt that refers to an instance being stopped or
+     * restarted — a restart offer for an instance the operator just restarted
+     * (or an assist for one they stopped) must not stay clickable for the rest
+     * of its 15 minutes.
+     */
+    clearNoncePromptsForInstance(instanceName) {
+        for (const [nonce, entry] of this.pendingNonceButtons) {
+            if (entry.instanceName !== instanceName)
+                continue;
+            this.pendingNonceButtons.delete(nonce);
+            if (entry.timer)
+                clearTimeout(entry.timer);
+            if (entry.messageId && entry.adapter.editMessageRemoveButtons) {
+                entry.adapter.editMessageRemoveButtons(entry.chatId, entry.messageId, entry.expiredText, entry.threadId)
+                    .catch(err => this.logger.debug({ err, instanceName, prefix: entry.prefix }, "Failed to collapse prompt during instance stop"));
+            }
+        }
+    }
+    /** A clean exit is intentional from the CLI's perspective, but often not from
+     * the operator's. Keep the instance notice passive and put the action in the
+     * same-world General topic where an administrator can make the choice. */
+    async notifyNormalExit(instanceName) {
+        this.notifyInstanceTopic(instanceName, t("exit.instance_notice", instanceName));
+        const worldId = this.getInstanceAdapterId(instanceName);
+        const generalName = this.findGeneralInstance(worldId);
+        if (!generalName) {
+            this.logger.warn({ instanceName, worldId }, "Normal CLI exit has no General notification target");
+            return;
+        }
+        const adapterId = this.getInstanceAdapterId(generalName);
+        const adapter = this.getAdapterForInstance(generalName);
+        const chatId = this.getGroupIdForInstance(generalName);
+        const topicId = this.fleetConfig?.instances[generalName]?.topic_id;
+        const threadId = topicId != null ? String(topicId) : undefined;
+        if (!adapter || !adapterId || !chatId) {
+            this.logger.warn({ instanceName, generalName, adapterId, chatId }, "Cannot address normal-exit restart controls");
+            return;
+        }
+        await this.postNonceButtonPrompt({
+            prefix: EXIT_RESTART_CALLBACK_PREFIX,
+            alertType: "exit_restart",
+            instanceName,
+            adapter,
+            adapterId,
+            chatId,
+            threadId,
+            message: t("exit.general_notice", instanceName),
+            choices: [
+                { action: "restart", label: t("exit.restart") },
+                { action: "ignore", label: t("exit.ignore") },
+            ],
+            expiredText: t("exit.expired", instanceName),
+        });
+    }
+    /** Consume a clean-exit Restart/Ignore button exactly once. */
+    async handleExitRestartPrompt(data, callbackAdapterId, receivingAdapter) {
+        const claimed = this.consumeNonceCallback(EXIT_RESTART_CALLBACK_PREFIX, /^exit-restart:([0-9a-f]+):(restart|ignore)$/, data, callbackAdapterId, receivingAdapter);
+        if (claimed === null)
+            return false;
+        if (claimed === "consumed")
+            return true;
+        const { entry: pending, action } = claimed;
+        this.eventLog?.insert(pending.instanceName, "normal_exit_action", { action, userId: data.userId });
+        if (action === "ignore") {
+            await this.retireNonceButtons(pending, pending.messageId ?? data.messageId, t("exit.ignored", pending.instanceName));
+            return true;
+        }
+        await this.retireNonceButtons(pending, pending.messageId ?? data.messageId, t("exit.restarting", pending.instanceName));
+        try {
+            await this.restartSingleInstance(pending.instanceName);
+            await pending.adapter.editMessage(pending.chatId, pending.messageId ?? data.messageId, t("exit.restarted", pending.instanceName), pending.threadId);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            this.logger.error({ err, instanceName: pending.instanceName }, "Normal-exit restart failed");
+            await pending.adapter.editMessage(pending.chatId, pending.messageId ?? data.messageId, t("exit.restart_failed", pending.instanceName, message), pending.threadId).catch(editErr => this.logger.warn({ err: editErr, instanceName: pending.instanceName }, "Failed to show normal-exit restart error"));
+        }
+        return true;
+    }
+    interactivePromptLabel(kind) {
+        const key = `interactive.kind.${kind}`;
+        const translated = t(key);
+        return translated === key ? kind.replaceAll("_", " ") : translated;
+    }
+    /**
+     * Surface a stable terminal prompt in both places that matter:
+     * - the blocked instance gets a plain pointer to General;
+     * - General gets one-shot Confirm/Cancel controls on its own bound adapter.
+     *
+     * Only the prompt category crosses channels. The captured terminal line can
+     * contain usernames or secret-adjacent text and stays in daemon.log.
+     */
+    async notifyInteractivePrompt(instanceName, kind) {
+        this.notifyInstanceTopic(instanceName, t("interactive.instance_notice", instanceName));
+        // Multi-world fleets can have one General per bot/platform. Route the assist
+        // request to the General bound to the same adapter as the blocked instance.
+        const generalName = this.findGeneralInstance(this.getInstanceAdapterId(instanceName));
+        if (!generalName) {
+            this.logger.warn({ instanceName }, "Interactive prompt has no General topic notification target");
+            return;
+        }
+        const adapterId = this.getInstanceAdapterId(generalName);
+        const adapter = this.getAdapterForInstance(generalName);
+        const chatId = this.getGroupIdForInstance(generalName);
+        const topicId = this.fleetConfig?.instances[generalName]?.topic_id;
+        const threadId = topicId != null ? String(topicId) : undefined;
+        if (!adapter || !adapterId || !chatId) {
+            this.logger.warn({ instanceName, generalName, adapterId, chatId }, "Cannot address interactive prompt assistance controls");
+            return;
+        }
+        const label = this.interactivePromptLabel(kind);
+        await this.postNonceButtonPrompt({
+            prefix: INTERACTIVE_ASSIST_CALLBACK_PREFIX,
+            alertType: "interactive_prompt",
+            instanceName,
+            adapter,
+            adapterId,
+            chatId,
+            threadId,
+            message: t("interactive.general_notice", instanceName, label),
+            choices: [
+                { action: "confirm", label: t("interactive.confirm") },
+                { action: "cancel", label: t("interactive.cancel") },
+            ],
+            expiredText: t("interactive.expired", instanceName),
+            extra: { generalName, promptKind: kind },
+        });
+    }
+    /** Consume a General assist button exactly once. */
+    async handleInteractivePromptAssist(data, callbackAdapterId, receivingAdapter) {
+        const claimed = this.consumeNonceCallback(INTERACTIVE_ASSIST_CALLBACK_PREFIX, /^interactive-assist:([0-9a-f]+):(confirm|cancel)$/, data, callbackAdapterId, receivingAdapter);
+        if (claimed === null)
+            return false;
+        if (claimed === "consumed")
+            return true;
+        const { entry: pending, action } = claimed;
+        this.eventLog?.insert(pending.instanceName, "interactive_prompt_assist", {
+            action,
+            userId: data.userId,
+            generalName: pending.generalName,
+        });
+        if (action === "cancel") {
+            await this.retireNonceButtons(pending, pending.messageId ?? data.messageId, t("interactive.ignored", pending.instanceName));
+            return true;
+        }
+        // Fail closed on a malformed entry. generalName is set at posting time for
+        // every interactive-assist entry; its absence means entry confusion, and
+        // falling back to the blocked instance would type the assist text into the
+        // very terminal prompt this feature exists to keep humans in front of.
+        const generalName = pending.generalName;
+        if (!generalName) {
+            this.logger.error({ instanceName: pending.instanceName }, "Interactive-assist entry has no General target — refusing to deliver");
+            await this.retireNonceButtons(pending, pending.messageId ?? data.messageId, t("interactive.delivery_failed", pending.instanceName));
+            return true;
+        }
+        // Injecting into General while General itself is blocked would type into the
+        // terminal prompt instead of the agent input. Fail safe and require attach.
+        if (pending.instanceName === generalName) {
+            await this.retireNonceButtons(pending, pending.messageId ?? data.messageId, t("interactive.self_assist", pending.instanceName));
+            return true;
+        }
+        await this.retireNonceButtons(pending, pending.messageId ?? data.messageId, t("interactive.confirmed", pending.instanceName));
+        try {
+            await this.deliverToInstance(generalName, {
+                type: "fleet_inbound",
+                content: t("interactive.assist_request", pending.instanceName, this.interactivePromptLabel(pending.promptKind ?? "")),
+                targetSession: generalName,
+                meta: {
+                    chat_id: pending.chatId,
+                    message_id: pending.messageId ?? data.messageId,
+                    user: "AgEnD",
+                    user_id: data.userId,
+                    ts: new Date().toISOString(),
+                    thread_id: pending.threadId ?? "",
+                    adapter_id: pending.adapterId,
+                    source: pending.adapter.type,
+                },
+            }, {
+                // This is system-generated work, not a live user message. Queue behind
+                // General's current turn so Kiro/Claude do not lose it while busy.
+                isCrossInstance: true,
+            });
+            this.logger.info({ instanceName: pending.instanceName, generalName: pending.generalName }, "Interactive prompt assistance delivered to General");
+        }
+        catch (err) {
+            this.logger.warn({ err, instanceName: pending.instanceName, generalName: pending.generalName }, "Failed to deliver interactive prompt assistance to General");
+            await pending.adapter.editMessage(pending.chatId, pending.messageId ?? data.messageId, t("interactive.delivery_failed", pending.instanceName), pending.threadId);
+        }
+        return true;
+    }
     // ── Cancel button ────────────────────────────────────────────────────
     // Sent after delivering a user message to an instance; clicking it (or
     // /cancel) sends Escape to the instance's pane to interrupt generation.
@@ -4890,13 +5326,29 @@ export class FleetManager {
     }
     async sendHangNotification(instanceName, unchangedForMs) {
         const adapter = this.getAdapterForInstance(instanceName) ?? this.adapter;
-        if (!adapter)
-            return;
-        const channelCfg = this.getChannelConfig(this.getInstanceAdapterId(instanceName));
-        const groupId = channelCfg?.group_id;
-        if (!groupId)
+        const adapterId = this.getInstanceAdapterId(instanceName);
+        // Same three-way addressing as sendCancelButton: fleet topic → group+thread,
+        // Classic → its own channel (Classic instances are absent from
+        // fleetConfig.instances, so the topic path can never address them), else the
+        // world group flat. getGroupIdForInstance (not getChannelConfig().group_id)
+        // because on channels[]-configured fleets the legacy channel: block is empty.
+        const topicId = this.fleetConfig?.instances[instanceName]?.topic_id;
+        const groupId = this.getGroupIdForInstance(instanceName) || undefined;
+        let chatId;
+        let threadId;
+        if (topicId != null && groupId) {
+            chatId = String(groupId);
+            threadId = String(topicId);
+        }
+        else {
+            chatId = this.classicChannels?.getChannelIdByInstance(instanceName);
+            if (!chatId && groupId)
+                chatId = String(groupId);
+        }
+        if (!adapter || !adapterId || !chatId) {
+            this.logger.warn({ instanceName, adapterId, chatId }, "Cannot address hang notification");
             return;
-        const threadId = this.fleetConfig?.instances[instanceName]?.topic_id;
+        }
         const instanceHangConfig = this.fleetConfig?.instances[instanceName]?.hang_detector;
         const configuredMinutes = instanceHangConfig?.timeout_minutes
             ?? this.fleetConfig?.defaults?.hang_detector?.timeout_minutes
@@ -4905,17 +5357,52 @@ export class FleetManager {
             ? configuredMinutes
             : Math.max(1, Math.floor(unchangedForMs / 60_000));
         this.setTopicIcon(instanceName, "red");
-        await adapter.notifyAlert(String(groupId), {
-            type: "hang",
+        await this.postNonceButtonPrompt({
+            prefix: HANG_CALLBACK_PREFIX,
+            alertType: "hang",
             instanceName,
-            message: `⚠️ ${instanceName} may be stuck — pane unchanged for ${unchangedMinutes}min, ready prompt not recognized`,
+            adapter,
+            adapterId,
+            chatId,
+            threadId,
+            message: t("hang.detected", instanceName, unchangedMinutes),
             choices: [
-                { id: `hang:restart:${instanceName}`, label: "🔄 Force restart" },
-                { id: `hang:wait:${instanceName}`, label: "⏳ Keep waiting" },
+                { action: "restart", label: t("hang.restart") },
+                { action: "wait", label: t("hang.wait") },
             ],
-        }, {
-            threadId: threadId != null ? String(threadId) : undefined,
-        }).catch(e => this.logger.warn({ err: e }, "Failed to send hang notification"));
+            expiredText: t("hang.expired", instanceName),
+        });
+    }
+    /**
+     * Consume a hang Force-restart / Keep-waiting button exactly once. Restart
+     * goes through restartSingleInstance — serialized against concurrent restart
+     * sources, and with a Classic-instance fallback (the previous hand-rolled
+     * stop+start silently left Classic instances stopped while reporting
+     * "restarted").
+     */
+    async handleHangPrompt(data, callbackAdapterId, receivingAdapter) {
+        const claimed = this.consumeNonceCallback(HANG_CALLBACK_PREFIX, /^hang:([0-9a-f]+):(restart|wait)$/, data, callbackAdapterId, receivingAdapter);
+        if (claimed === null)
+            return false;
+        if (claimed === "consumed")
+            return true;
+        const { entry: pending, action } = claimed;
+        this.eventLog?.insert(pending.instanceName, "hang_action", { action, userId: data.userId });
+        if (action === "wait") {
+            await this.retireNonceButtons(pending, pending.messageId ?? data.messageId, t("hang.waiting", pending.instanceName));
+            return true;
+        }
+        await this.retireNonceButtons(pending, pending.messageId ?? data.messageId, t("hang.restarting", pending.instanceName));
+        try {
+            await this.restartSingleInstance(pending.instanceName);
+            await pending.adapter.editMessage(pending.chatId, pending.messageId ?? data.messageId, t("hang.restarted", pending.instanceName), pending.threadId);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            this.logger.error({ err, instanceName: pending.instanceName }, "Hang force-restart failed");
+            await pending.adapter.editMessage(pending.chatId, pending.messageId ?? data.messageId, t("hang.restart_failed", pending.instanceName, message), pending.threadId).catch(editErr => this.logger.warn({ err: editErr, instanceName: pending.instanceName }, "Failed to show hang restart error"));
+        }
+        return true;
     }
     // ── Topic icon + auto-archive ─────────────────────────────────────────────
     static INSTRUCTIONS_FILENAME = {
@@ -6401,6 +6888,11 @@ When users create specialized instances, suggest these configurations:
         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();
         this.topicArchiver.stop();
         this.scheduler?.shutdown();
         // Stop instances in parallel batches to avoid long sequential waits.