talon-agent 5.25.1 → 5.26.1

package/src/core/mesh/credentials/store.ts

@@ -69,6 +69,12 @@ export type BindResult =
 
 const PERSIST_ALERT = "mesh.credentials.persist";
 
+/** Operator-minted, bind-on-first-use origins allowed to re-pair a device. */
+const REPAIR_ORIGINS: ReadonlySet<CredentialOrigin> = new Set([
+  "pair",
+  "install",
+]);
+
 export class DeviceCredentialStore {
   private records = new Map<string, DeviceCredentialRecord>();
   private loading: Promise<void> | null = null;
@@ -146,9 +152,21 @@ export class DeviceCredentialStore {
   }
 
   /**
-   * Bind an unbound credential to the device id it just named. Refused when
-   * another live credential already holds that id — a pairing link can add
-   * a device, never take one over.
+   * Bind an unbound credential to the device id it just named.
+   *
+   * When that id already holds live credentials, an operator-minted pairing
+   * or installer credential takes the device over (a re-pair): the old
+   * credentials are revoked and their live sessions dropped. This is the
+   * "the Mac's app was reset but kept its device id" case, which otherwise
+   * needs a `talon mesh revoke` before the new link can work.
+   *
+   * Trust: every unbound credential is operator-minted (`pair`/`install`,
+   * see MeshService → BridgeLinks) and binds exactly once — after this call
+   * it is bound, so a replayed link cannot bind again. Takeover is further
+   * limited to devices whose live credentials carry no scope the new one
+   * lacks: a device-only installer link can re-provision a node, but can
+   * never evict (and then impersonate) a companion holding client/operator.
+   * A credential of any other origin keeps the old rule — refused.
    */
   bind(credentialId: string, deviceId: string): BindResult {
     const record = this.records.get(credentialId);
@@ -164,19 +182,52 @@ export class DeviceCredentialStore {
     if (!id || id.length > MAX_DEVICE_ID_CHARS) {
       return { ok: false, error: "Invalid device id" };
     }
-    if (this.activeRecordsFor(id).length > 0) {
-      return {
-        ok: false,
-        error: `Device ${id} already has a credential — revoke it first (talon mesh revoke ${id})`,
-      };
+    const existing = this.activeRecordsFor(id);
+    if (existing.length > 0) {
+      const refusal = this.takeoverRefusal(record, id, existing);
+      if (refusal) return { ok: false, error: refusal };
     }
     record.deviceId = id;
     delete record.expiresAt;
     log("mesh", `Credential ${record.id} bound to device ${id}`);
-    this.persistSoon();
+    if (existing.length > 0) {
+      logWarn(
+        "mesh",
+        `Credential ${record.id} (${record.origin}) re-paired device ${id}; revoking ${existing.map((r) => r.id).join(", ")}`,
+      );
+      // Mark revoked synchronously (authenticate must reject them from this
+      // instant); revokeRecords drops their sessions and persists.
+      void this.revokeRecords(existing, `re-paired by ${record.id}`).catch(
+        (err: unknown) =>
+          logWarn("mesh", `Could not persist re-pair revocation: ${err}`),
+      );
+    } else {
+      this.persistSoon();
+    }
     return { ok: true, credential: publicView(record) };
   }
 
+  /** Why `record` may not take over `deviceId` from `existing`, if it may not. */
+  private takeoverRefusal(
+    record: DeviceCredentialRecord,
+    deviceId: string,
+    existing: readonly DeviceCredentialRecord[],
+  ): string | null {
+    const revokeHint = `revoke it first (talon mesh revoke ${deviceId})`;
+    if (!REPAIR_ORIGINS.has(record.origin)) {
+      return `Device ${deviceId} already has a credential — ${revokeHint}`;
+    }
+    const held = new Set(record.scopes);
+    const wider = existing.flatMap((r) => r.scopes).filter((s) => !held.has(s));
+    if (wider.length > 0) {
+      return (
+        `Device ${deviceId} already has a credential with scopes this link does not carry ` +
+        `(${[...new Set(wider)].join(", ")}) — ${revokeHint}`
+      );
+    }
+    return null;
+  }
+
   /** True when the operator asked for this credential to be replaced. */
   rotationDue(credentialId: string): boolean {
     const record = this.records.get(credentialId);

package/src/core/models/active-model.ts

@@ -36,19 +36,20 @@
  *   1. `modelByBackend[B]` — per-chat-per-backend pick, if it still
  *      validates against B's catalog. Cross-backend orphans surface
  *      as `kind: "missing"` and fall through.
- *   2. `backend.models?.getDefaultModelId()` — backend's canonical default.
+ *   2. `config.backendDefaults[B]` — operator-configured per-backend
+ *      default in `talon.json`.
+ *   3. `config.model` — only when B is the global chat-role backend
+ *      (`config.backend === B`).
+ *      Operator picks (2/3) must validate against B's catalog when B
+ *      has a canonical default to fall back to; an unknown pin falls
+ *      through to step 4 (what the boot-time model audit warns about).
+ *   4. `backend.models?.getDefaultModelId()` — backend's canonical default.
  *      Codex picks auth-aware (`gpt-5-codex` on API key, `gpt-5.5`
  *      on ChatGPT OAuth). Claude SDK returns the `"default"` alias.
  *      Stock OpenAI Agents returns a constant.
  *      Catalog-driven backends without a canonical (Kilo, OpenCode,
  *      OpenAI Agents on OpenRouter / custom OpenAI-compatible) do
- *      NOT implement this — they fall through to step 3.
- *   3. `config.backendDefaults[B]` — operator-configured per-backend
- *      default in `talon.json`. Escape hatch for "no canonical"
- *      backends.
- *   4. `config.model` — only when B is the global chat-role backend
- *      (`config.backend === B`). Back-compat for installs that
- *      predate `backendDefaults`.
+ *      NOT implement this.
  *   5. `null` → UI renders "No model selected", send guard refuses
  *      with a "use /model to pick one" reply.
  *
@@ -56,6 +57,10 @@
  * is called. Only `kind: "exact"` with `selectable: true` honours the
  * stored override. Anything else falls through to step 2.
  *
+ * Operator config ranks above the canonical so a pinned `config.model`
+ * is actually honoured (it used to lose to Claude's `"default"`, so a
+ * claude install pinned to any model silently ran the default).
+ *
  * Backends with no `resolveModel` (rare — defensive fallback only)
  * have their stored override returned verbatim — no way to validate.
  */
@@ -157,8 +162,8 @@ async function runChain(
     }
   }
 
-  // ── Step 2-5: backend canonical → config.backendDefaults →
-  //              config.model (chat-role only) → null
+  // ── Steps 2-5: backendDefaults → config.model (chat-role only) →
+  //              backend canonical → null
   return stepsTwoThroughFive(backend, backendId, config, null);
 }
 
@@ -196,57 +201,61 @@ async function stepsTwoThroughFive(
   config: TalonConfig,
   fallbackSourceOverride: "override-invalid-fallback" | null,
 ): Promise<{ model: string | null; source: ActiveModelSource }> {
-  // Step 2: backend.models.getDefaultModelId()
-  if (backend?.models) {
-    const canonical = await safeBackendDefault(backend);
-    if (canonical) {
-      return {
-        model: canonical,
-        source: fallbackSourceOverride ?? "backend-canonical",
-      };
+  const withSource = (model: string, source: ActiveModelSource) => ({
+    model,
+    source: fallbackSourceOverride ?? source,
+  });
+
+  const operatorPick = pickOperatorDefault(backendId, config);
+  const canonical = backend?.models ? await safeBackendDefault(backend) : null;
+
+  // Operator config (steps 2/3) beats the backend canonical (step 4): a
+  // pinned `config.model` is an explicit choice, and letting the canonical
+  // win meant a claude install pinned to e.g. "opus[1m]" silently ran
+  // "default" on every turn. The pin must still validate — a withdrawn id
+  // falls back to the canonical, exactly what the boot-time model audit
+  // warns about. Without a canonical to fall back to, the pin is returned
+  // unvalidated (catalog-driven backends with no default, unchanged).
+  if (operatorPick) {
+    if (!canonical) return withSource(operatorPick.model, operatorPick.source);
+    if (await validateModelOnBackend(backend, operatorPick.model)) {
+      return withSource(operatorPick.model, operatorPick.source);
     }
   }
 
-  // Step 3: config.backendDefaults[backendId]
+  // Step 4: backend.models.getDefaultModelId()
+  if (canonical) return withSource(canonical, "backend-canonical");
+
+  // Step 5: null. Callers must render "No model selected" / refuse send.
+  return { model: null, source: "none" };
+}
+
+/**
+ * The operator-configured default for a backend, if any:
+ *   - `config.backendDefaults[B]`;
+ *   - else `config.model` — only when B is the global chat-role backend
+ *     (`config.backend === B`), or when no backend id is known at all
+ *     (pre-bootstrap callers passing null).
+ */
+function pickOperatorDefault(
+  backendId: string | null,
+  config: TalonConfig,
+): { model: string; source: ActiveModelSource } | null {
   if (backendId && config.backendDefaults) {
     const operatorDefault = config.backendDefaults[backendId];
     if (operatorDefault && operatorDefault.length > 0) {
-      return {
-        model: operatorDefault,
-        source: fallbackSourceOverride ?? "config-backend-defaults",
-      };
+      return { model: operatorDefault, source: "config-backend-defaults" };
     }
   }
-
-  // Step 4: legacy config.model — only for the global chat-role backend
+  const modelAppliesHere = !backendId || backendId === config.backend;
   if (
-    backendId &&
-    backendId === config.backend &&
+    modelAppliesHere &&
     typeof config.model === "string" &&
     config.model.length > 0
   ) {
-    return {
-      model: config.model,
-      source: fallbackSourceOverride ?? "config-legacy-global",
-    };
+    return { model: config.model, source: "config-legacy-global" };
   }
-
-  // Step 4b: even without a backendId, honour config.model if no
-  // backend is bound at all (callers passing null for both — rare,
-  // typically pre-bootstrap code paths).
-  if (
-    !backendId &&
-    typeof config.model === "string" &&
-    config.model.length > 0
-  ) {
-    return {
-      model: config.model,
-      source: fallbackSourceOverride ?? "config-legacy-global",
-    };
-  }
-
-  // Step 5: null. Callers must render "No model selected" / refuse send.
-  return { model: null, source: "none" };
+  return null;
 }
 
 async function validateModelOnBackend(

package/src/core/plugin/loader.ts

@@ -98,6 +98,15 @@ function registerPluginInstance(
   return loaded;
 }
 
+/**
+ * Run a plugin's init, waiting at most `timeoutMs` for it before boot moves
+ * on. The deadline bounds how long boot waits, not the init itself: a
+ * plugin stays registered either way (its tools are served from
+ * `mcpServer` whether or not init finished), so an init that outlives the
+ * deadline keeps running and, when it does finish, clears the alert the
+ * timeout raised — a slow handshake on a busy boot is a delay, not a
+ * failure that lingers until the next restart.
+ */
 export async function initPluginWithTimeout(
   plugin: TalonPlugin,
   config: Record<string, unknown>,
@@ -108,28 +117,54 @@ export async function initPluginWithTimeout(
   if (!plugin.init) return;
 
   let timer: ReturnType<typeof setTimeout> | undefined;
-
   const alertKey = `plugin.${plugin.name}`;
+  const startedAt = Date.now();
+  // Started (and timed) only here, when this plugin's own init begins.
+  const init = Promise.resolve().then(() => plugin.init!(config));
+  const TIMED_OUT = Symbol("timed out");
+
   try {
-    await Promise.race([
-      Promise.resolve(plugin.init(config)),
-      new Promise<never>((_, reject) => {
-        timer = setTimeout(() => {
-          reject(
-            new Error(`${timeoutLabel} timed out after ${timeoutMs / 1000}s`),
-          );
-        }, timeoutMs);
+    const outcome = await Promise.race([
+      init,
+      new Promise<typeof TIMED_OUT>((settle) => {
+        timer = setTimeout(() => settle(TIMED_OUT), timeoutMs);
         timer.unref?.();
       }),
     ]);
-    resolveAlert(alertKey, `Plugin "${plugin.name}" initialised normally.`);
+    if (outcome !== TIMED_OUT) {
+      resolveAlert(alertKey, `Plugin "${plugin.name}" initialised normally.`);
+      return;
+    }
+    const message = `${timeoutLabel} timed out after ${timeoutMs / 1000}s`;
+    logError("plugin", `${errorPrefix}: ${message}; still waiting for it`);
+    raiseAlert(
+      alertKey,
+      `Plugin "${plugin.name}" failed to initialise: ${message}. Its tools stay registered; this clears itself if init finishes late.`,
+    );
+    void init.then(
+      () => {
+        // Reloaded or unloaded meanwhile: this instance's verdict is moot.
+        if (registry.getByName(plugin.name)?.plugin !== plugin) return;
+        const took = Math.round((Date.now() - startedAt) / 1000);
+        log("plugin", `${plugin.name} init finished late (${took}s)`);
+        resolveAlert(
+          alertKey,
+          `Plugin "${plugin.name}" finished initialising late (${took}s).`,
+        );
+      },
+      (err: unknown) =>
+        logError(
+          "plugin",
+          `${errorPrefix} (after timing out): ${err instanceof Error ? err.message : err}`,
+        ),
+    );
   } catch (err) {
     logError(
       "plugin",
       `${errorPrefix}: ${err instanceof Error ? err.message : err}`,
     );
-    // Init runs once per boot or reload: a plugin that failed it stays
-    // half-loaded until someone fixes it, so this needs no threshold.
+    // An init that threw won't retry on its own: it needs a reload or
+    // restart, so this needs no threshold.
     raiseAlert(
       alertKey,
       `Plugin "${plugin.name}" failed to initialise: ${faultText(err)}. Its tools may not work until the next reload or restart.`,

package/src/core/tools/bridge.ts

@@ -11,6 +11,8 @@
 import { Agent, fetch as undiciFetch } from "undici";
 import { isBunRuntime } from "../../util/runtime.js";
 import { gatewayAuthHeaders } from "../engine/gateway-auth.js";
+import { logWarn } from "../../util/log.js";
+import { TalonError } from "../errors.js";
 import type { BridgeFunction } from "./types.js";
 
 /** Default wall-clock budget for a bridge action. */
@@ -64,6 +66,26 @@ function dispatcher(): Agent {
 /** Built-in fetch's default dispatcher fails headers slower than this. */
 const BUILTIN_FETCH_HEADERS_CEILING_MS = 300_000;
 
+/** Best-effort one-line description of an abort's reason / error cause. */
+function describeAbort(err: Error, signal: AbortSignal): string {
+  const parts: string[] = [];
+  if (err.message) parts.push(err.message);
+  const cause = (err as { cause?: unknown }).cause;
+  if (cause instanceof Error && cause.message)
+    parts.push(`cause: ${cause.name}: ${cause.message}`);
+  else if (cause !== undefined && cause !== null)
+    parts.push(`cause: ${String(cause)}`);
+  if (signal.aborted && signal.reason !== undefined) {
+    const r = signal.reason as { name?: string; message?: string };
+    const reason =
+      r instanceof Error || (r && typeof r === "object" && "name" in r)
+        ? `${r.name}: ${r.message ?? ""}`
+        : String(signal.reason);
+    if (!parts.some((p) => p.includes(reason))) parts.push(`reason: ${reason}`);
+  }
+  return parts.join("; ") || err.name || "unknown abort";
+}
+
 /**
  * Create a bridge caller bound to a default URL and chat.
  *
@@ -93,13 +115,15 @@ export function createBridge(
         : null;
     const effectiveChatId = explicitChatId ?? chatId;
     const timeoutMs = LONG_ACTION_TIMEOUTS_MS[action] ?? DEFAULT_TIMEOUT_MS;
+    const signal = AbortSignal.timeout(timeoutMs);
+    const startedAt = Date.now();
     const init = {
       method: "POST",
       headers: { "Content-Type": "application/json", ...gatewayAuthHeaders() },
       // chat_id stays in body when set — gateway uses its presence as the
       // "explicit routing" signal. _chatId is the routing key either way.
       body: JSON.stringify({ action, ...params, _chatId: effectiveChatId }),
-      signal: AbortSignal.timeout(timeoutMs),
+      signal,
     };
     // Minimal common surface of DOM Response and undici's Response.
     let resp: {
@@ -123,11 +147,41 @@ export function createBridge(
           : await fetch(`${bridgeUrl}/action`, init);
     } catch (err) {
       const cause = err as Error & { name?: string };
+      const elapsedMs = Date.now() - startedAt;
       if (cause.name === "TimeoutError" || cause.name === "AbortError") {
-        throw new Error(
-          `"${action}" did not complete within ${Math.round(timeoutMs / 1000)}s. ` +
+        // Only call it a timeout when the budget actually ran out: the
+        // deadline signal fired (a TimeoutError, thrown or as the signal's
+        // reason) or the full budget elapsed. Anything earlier — a dropped socket, a daemon
+        // restart, a cancelled request — is an abort with its own cause,
+        // and mislabelling it as "did not complete within 3600s" after
+        // 780s sends the diagnosis in the wrong direction.
+        const reasonName = (signal.reason as { name?: string } | undefined)
+          ?.name;
+        const timedOut =
+          cause.name === "TimeoutError" ||
+          (signal.aborted && reasonName === "TimeoutError") ||
+          elapsedMs >= timeoutMs;
+        const detail = describeAbort(cause, signal);
+        logWarn(
+          "bridge",
+          `tool bridge "${action}" ${timedOut ? "timed out" : "aborted"} after ${elapsedMs}ms (budget ${timeoutMs}ms): ${detail}`,
+        );
+        if (timedOut) {
+          throw new Error(
+            `"${action}" did not complete within ${Math.round(timeoutMs / 1000)}s. ` +
+              `The operation may still be running on the daemon — check its ` +
+              `outcome (e.g. list the target directory) before retrying.`,
+          );
+        }
+        // Classified as a non-retryable network fault: the transport
+        // dropped mid-call, but the daemon may already have acted, so a
+        // blind retry could run the action twice.
+        throw new TalonError(
+          `"${action}" was aborted after ${Math.round(elapsedMs / 1000)}s ` +
+            `(${elapsedMs}ms; before its ${Math.round(timeoutMs / 1000)}s budget): ${detail}. ` +
             `The operation may still be running on the daemon — check its ` +
-            `outcome (e.g. list the target directory) before retrying.`,
+            `outcome before retrying.`,
+          { reason: "network", retryable: false, cause },
         );
       }
       throw new Error(

package/src/frontend/discord/callbacks/components/effort.ts

@@ -30,15 +30,15 @@ async function selectEffort(
     backendId: beId,
     config,
   });
-  if (reasoning.levels.length === 0) {
+  // Adaptive needs no model levels — reachable even when the model has none.
+  if (level === "adaptive") setChatEffort(chatId, undefined);
+  else if (reasoning.levels.length === 0) {
     await interaction.update({
       content: "No valid reasoning levels found for this model.",
       components: [],
     });
     return;
-  }
-  if (level === "adaptive") setChatEffort(chatId, undefined);
-  else if (supportsReasoningLevel(level, reasoning.levels))
+  } else if (supportsReasoningLevel(level, reasoning.levels))
     setChatEffort(chatId, level as EffortLevel);
   else {
     await interaction.update({

package/src/frontend/discord/callbacks/components/index.ts

@@ -18,6 +18,8 @@
  *   model:nav:*                 (pager)
  *   model:backend-select        (select menu)
  *   metrics:today | metrics:all
+ *   backup:panel|now|guide|list:<p>|pin:<p>:<id>|unpin:<p>:<id>|ask:<p>:<id>
+ *                               (the /backup panel, admin only)
  *   backup:restore:<id> | backup:cancel  (restore confirmation, admin only)
  *   ai:<id>                     (AI-generated buttons — forwarded to agent)
  */

package/src/frontend/discord/commands/backup-panel.ts

@@ -0,0 +1,219 @@
+/**
+ * The /backup panel on Discord — the same views and custom-id grammar as
+ * Telegram (frontend/presentation/backup-panel.ts), spelled in Discord
+ * markdown and mapped onto button rows.
+ *
+ * Discord allows five action rows per message, so snapshot pages hold
+ * three snapshots (three rows, navigation, Back). The staged restore
+ * (`backup:restore:<id>`) and the confirmation's Cancel stay in
+ * backup.ts; this module owns every other `backup:*` button, and every
+ * one of them re-checks the admin before it runs (see
+ * `handleBackupComponent`).
+ */
+
+import {
+  ActionRowBuilder,
+  ButtonBuilder,
+  ButtonStyle,
+  MessageFlags,
+  type ChatInputCommandInteraction,
+} from "discord.js";
+import {
+  collectBackupStatus,
+  listSnapshots,
+  readManifest,
+  runBackup,
+  setSnapshotPinned,
+} from "../../../core/backup/index.js";
+import { logError } from "../../../util/log.js";
+import {
+  GUIDE_BUTTONS,
+  PANEL_BUTTONS,
+  backupPanelView,
+  renderRestoreGuide,
+  restoreConfirmView,
+  snapshotPageView,
+  type BackupAction,
+  type PanelButton,
+  type PanelView,
+} from "../../presentation/backup-panel.js";
+import { DISCORD_REPORTS } from "../render.js";
+import type { ComponentInteraction } from "../callbacks/components/types.js";
+
+const DISCORD_PAGE_SIZE = 3;
+
+function buttonRows(
+  rows: readonly PanelButton[][],
+): ActionRowBuilder<ButtonBuilder>[] {
+  return rows.map((row) =>
+    new ActionRowBuilder<ButtonBuilder>().addComponents(
+      row.map((button) =>
+        new ButtonBuilder()
+          .setCustomId(button.data)
+          .setLabel(button.label)
+          .setStyle(
+            button.data.startsWith("backup:restore:")
+              ? ButtonStyle.Danger
+              : ButtonStyle.Secondary,
+          ),
+      ),
+    ),
+  );
+}
+
+function payload(view: PanelView) {
+  return {
+    content: view.text,
+    components: buttonRows(view.buttons).map((row) => row.toJSON()),
+    allowedMentions: { parse: [] as never[] },
+  };
+}
+
+/**
+ * Run one snapshot; the outcome as one markdown line. Never throws. Shared
+ * by `/backup now|checkpoint` and the panel's 📸 button.
+ */
+export async function runSnapshotLine(label?: string): Promise<string> {
+  try {
+    const manifest = await runBackup({
+      kind: label ? "checkpoint" : "backup",
+      label,
+      pinned: Boolean(label),
+      trigger: "command",
+    });
+    return (
+      `✅ \`${manifest.id}\` — ${manifest.parts.length} part(s), ` +
+      `${(manifest.sizeBytes / 1024 / 1024).toFixed(1)} MB` +
+      (label ? " (pinned)" : "")
+    );
+  } catch (err) {
+    logError("backup", "/backup now failed", err);
+    return `⚠️ Backup failed: ${err instanceof Error ? err.message : String(err)}`;
+  }
+}
+
+async function statusView(notice?: string): Promise<PanelView> {
+  return backupPanelView(
+    DISCORD_REPORTS,
+    await collectBackupStatus(),
+    Date.now(),
+    notice,
+  );
+}
+
+async function pageView(page: number): Promise<PanelView> {
+  return snapshotPageView(
+    DISCORD_REPORTS,
+    await listSnapshots(),
+    page,
+    Date.now(),
+    DISCORD_PAGE_SIZE,
+  );
+}
+
+/** Bare `/backup`: the panel, ephemeral, with its buttons. */
+export async function replyWithPanel(
+  i: ChatInputCommandInteraction,
+): Promise<void> {
+  await i.reply({
+    ...payload(await statusView()),
+    flags: MessageFlags.Ephemeral,
+  });
+}
+
+/** One panel snapshot at a time: a double tap must not take two. */
+let panelSnapshotRunning = false;
+
+/** Tests only. */
+export function _resetDiscordBackupPanel(): void {
+  panelSnapshotRunning = false;
+}
+
+async function backUpNow(interaction: ComponentInteraction): Promise<void> {
+  if (panelSnapshotRunning) {
+    await interaction.reply({
+      content: "A snapshot is already running.",
+      flags: MessageFlags.Ephemeral,
+    });
+    return;
+  }
+  panelSnapshotRunning = true;
+  try {
+    await interaction.update({
+      content:
+        "📸 **Taking a snapshot…**\nBuilding it, then pruning and uploading to any " +
+        "targets. This can take a few minutes — this message updates when it is done.",
+      components: [],
+    });
+    const line = await runSnapshotLine();
+    const view = await statusView(line).catch((err: unknown) => {
+      logError("backup", "Backup panel status read failed", err);
+      return { text: line, buttons: PANEL_BUTTONS };
+    });
+    await interaction.editReply(payload(view));
+  } finally {
+    panelSnapshotRunning = false;
+  }
+}
+
+async function viewFor(
+  action: Exclude<BackupAction, { kind: "now" | "restore" | "cancel" }>,
+): Promise<PanelView | null> {
+  switch (action.kind) {
+    case "panel":
+      return statusView();
+    case "list":
+      return pageView(action.page);
+    case "guide":
+      return {
+        text: renderRestoreGuide(DISCORD_REPORTS),
+        buttons: GUIDE_BUTTONS,
+      };
+    case "pin":
+    case "unpin":
+      await setSnapshotPinned(action.id, action.kind === "pin");
+      return pageView(action.page);
+    case "ask": {
+      // The confirmation only — the restore is its own, second tap.
+      const manifest = await readManifest(action.id);
+      return manifest
+        ? restoreConfirmView(DISCORD_REPORTS, manifest, action.page)
+        : null;
+    }
+  }
+}
+
+/**
+ * Every panel button except the staged restore and Cancel. The caller has
+ * already checked the admin.
+ */
+export async function handleBackupPanelAction(
+  interaction: ComponentInteraction,
+  action: Exclude<BackupAction, { kind: "restore" | "cancel" }>,
+): Promise<void> {
+  try {
+    if (action.kind === "now") {
+      await backUpNow(interaction);
+      return;
+    }
+    const view = await viewFor(action);
+    if (!view) {
+      await interaction.reply({
+        content: "That snapshot has no copy on this machine.",
+        flags: MessageFlags.Ephemeral,
+      });
+      return;
+    }
+    await interaction.update(payload(view));
+  } catch (err) {
+    logError("backup", `Backup panel action ${action.kind} failed`, err);
+    if (!interaction.replied && !interaction.deferred) {
+      await interaction
+        .reply({
+          content: "⚠️ That did not work — see the log.",
+          flags: MessageFlags.Ephemeral,
+        })
+        .catch(() => {});
+    }
+  }
+}