talon-agent 5.2.1 → 5.3.0

package/src/core/daemon/respawn.ts

@@ -1,38 +1,88 @@
 /**
- * Self-respawn helper for /restart commands across frontends.
+ * Self-respawn helper for /restart and /update across frontends.
  *
- * Spawns a fresh copy of the current process — same Node binary,
- * same `execArgv` (preserving the tsx loader so `.ts` entrypoints
- * still resolve), same script + user args, same cwd + env. The new
- * child is detached with stdio:"ignore" so it survives the parent's
- * exit; calling `unref()` lets the parent exit without waiting on
- * it.
+ * Spawns a fresh copy of the current process — same runtime binary, same
+ * `execArgv` (preserving a loader so `.ts` entrypoints still resolve),
+ * same script + user args, same cwd + env. The new child is detached so
+ * it survives the parent's exit; `unref()` lets the parent exit without
+ * waiting on it.
  *
- * Why not call the daemon's `talon restart` CLI? That path assumed
- * the bot was started via the daemon (talon.pid managed by
- * `daemonStart()`) and broke for anything else — `npm start`, `npx
- * tsx src/index.ts`, systemd, foreman, pm2, or running under a
- * debugger. Respawning from our own `process.argv` works regardless
- * of launch method.
+ * Why not call the daemon's `talon restart` CLI? That path assumed the
+ * bot was started via the daemon (talon.pid managed by `daemonStart()`)
+ * and broke for anything else — `npm start`, `npx tsx src/index.ts`,
+ * systemd, foreman, pm2, or running under a debugger. Respawning from
+ * our own `process.argv` works regardless of launch method.
  *
- * Ordering matters. `respawnSelf()` only *arms* the handoff and
- * raises SIGTERM; the successor is spawned by `spawnSuccessor()` at
- * the tail of graceful shutdown, once the frontends have stopped.
- * Spawning up-front (the previous behaviour) left the successor
- * long-polling `getUpdates` while the outgoing process was still
- * draining in-flight queries — up to DRAIN_TIMEOUT_MS of two live
- * pollers. Telegram answers only one of them and re-delivers the
- * unconfirmed updates to the other, so a restart mid-turn produced
- * a 409 Conflict on the way out and duplicate replies on the way in.
- * Releasing the poll before the successor binds it removes the
- * overlap rather than relying on grammy's 409 retry to paper over it.
+ * Ordering matters. `respawnSelf()` only *arms* the handoff and raises
+ * SIGTERM; the successor is spawned by `spawnSuccessor()` at the tail of
+ * graceful shutdown, once the frontends have stopped. Spawning up-front
+ * (the original behaviour) left the successor long-polling `getUpdates`
+ * while the outgoing process was still draining in-flight queries — up
+ * to DRAIN_TIMEOUT_MS of two live pollers. Telegram answers only one of
+ * them and re-delivers the unconfirmed updates to the other, so a
+ * restart mid-turn produced a 409 Conflict on the way out and duplicate
+ * replies on the way in. Releasing the poll before the successor binds
+ * it removes the overlap rather than relying on grammy's 409 retry to
+ * paper over it.
+ *
+ * Two things the 2026-09-18 outage added, both about the fact that the
+ * outgoing process is dying and cannot be the one responsible for the
+ * outcome:
+ *
+ *   - The successor's stdout and stderr go to ~/.talon/respawn.log, not
+ *     to "ignore". A successor that dies before its own logger exists —
+ *     a broken import after a dependency install, a fatal bind, a
+ *     runtime that aborts — used to leave no trace in any file, on any
+ *     process. That is precisely what happened: a successor was spawned,
+ *     lived ~20s, never bound its gateway, and vanished without a line.
+ *   - A watcher process is spawned alongside it (./handoff.ts). It
+ *     outlives us, verifies the successor over identity-checked /health
+ *     within a bounded window, and starts the daemon the way `talon
+ *     start` does if the successor never comes up. Nothing in the
+ *     handoff depends on a process that is about to call process.exit().
  */
 
 import { spawn } from "node:child_process";
-import { log, logError } from "../../util/log.js";
+import { log, logError, openRespawnLog } from "../../util/log.js";
+import { HANDOFF_WATCH_SUBCOMMAND } from "./handoff.js";
 
 let pendingReason: string | null = null;
 
+/**
+ * Argv flag that makes the daemon entry resolve its whole import graph
+ * and exit 0 without booting (src/app.ts acts on it before the first
+ * bootstrap step). `/update` runs the freshly installed tree with this
+ * flag before handing off — see core/update/self-update.ts.
+ */
+export const BOOT_SMOKE_FLAG = "--boot-smoke";
+
+/** Printed by a successful smoke run; the update step matches on it. */
+export const BOOT_SMOKE_OK = "talon boot-smoke ok";
+
+/**
+ * A bun-compiled binary embeds its source tree: `process.argv[1]` points
+ * into the virtual FS ($bunfs / ~BUN) and has no path on disk, so the
+ * binary is re-invoked with no script argument at all.
+ */
+function isEmbeddedEntry(entry: string): boolean {
+  return entry.includes("$bunfs") || entry.includes("~BUN");
+}
+
+/** The exact command that re-runs this process. */
+export function successorCommand(): { cmd: string; args: string[] } {
+  return {
+    cmd: process.argv[0],
+    args: [...process.execArgv, ...process.argv.slice(1)],
+  };
+}
+
+/** The same runtime + entry, re-invoked with one of our own subcommands. */
+function selfInvocation(extra: string[]): { cmd: string; args: string[] } {
+  const entry = process.argv[1] ?? "";
+  const prefix = isEmbeddedEntry(entry) ? [] : [...process.execArgv, entry];
+  return { cmd: process.argv[0], args: [...prefix, ...extra] };
+}
+
 /**
  * Arm a respawn and raise SIGTERM on ourselves so the existing
  * graceful-shutdown path cleanly stops the frontends, flushes state,
@@ -57,46 +107,71 @@ export function respawnRequested(): boolean {
   return pendingReason !== null;
 }
 
+export type SpawnFn = typeof spawn;
+
+/**
+ * Start the watcher that outlives this process and answers the only
+ * question that matters: did the successor actually come up? Never
+ * throws — a missing watcher must not cost us the successor itself.
+ */
+function spawnHandoffWatcher(
+  childPid: number,
+  fd: number | null,
+  spawnFn: SpawnFn,
+): void {
+  try {
+    const { cmd, args } = selfInvocation([
+      HANDOFF_WATCH_SUBCOMMAND,
+      String(childPid),
+    ]);
+    const watcher = spawnFn(cmd, args, {
+      cwd: process.cwd(),
+      detached: true,
+      stdio: ["ignore", fd ?? "ignore", fd ?? "ignore"],
+      env: { ...process.env },
+    });
+    watcher.once("error", (err) => {
+      logError("shutdown", "Handoff watcher failed to start", err);
+    });
+    watcher.unref();
+    log("shutdown", `Handoff watcher started (pid ${watcher.pid})`);
+  } catch (err) {
+    logError("shutdown", "Handoff watcher failed to start", err);
+  }
+}
+
 /**
- * Spawn the successor process. Called at the end of graceful
- * shutdown, after the frontends have stopped — so the incoming
- * process binds Telegram's long-poll only once this one has let go
- * of it. No-op unless `respawnSelf()` armed a handoff.
+ * Spawn the successor process. Called at the end of graceful shutdown,
+ * after the frontends have stopped — so the incoming process binds
+ * Telegram's long-poll only once this one has let go of it. No-op unless
+ * `respawnSelf()` armed a handoff.
  *
  * Never throws: a failed handoff must not prevent this process from
- * exiting. An external supervisor (systemd, pm2, the user's
- * terminal) can pick things up.
+ * exiting. The watcher is the safety net, not an external supervisor.
  */
-export function spawnSuccessor(): void {
+export function spawnSuccessor(spawnFn: SpawnFn = spawn): void {
   if (pendingReason === null) return;
   const reason = pendingReason;
   pendingReason = null;
 
+  // One fd for both streams, shared with the watcher: the successor's
+  // boot output and the watcher's verdict land in the same file, in
+  // order, even when the successor never gets far enough to log.
+  const fd = openRespawnLog();
   try {
-    const child = spawn(
-      process.argv[0],
-      [...process.execArgv, ...process.argv.slice(1)],
-      {
-        cwd: process.cwd(),
-        detached: true,
-        stdio: "ignore",
-        env: { ...process.env },
-      },
-    );
+    const child = spawnFn(process.argv[0], successorCommand().args, {
+      cwd: process.cwd(),
+      detached: true,
+      stdio: ["ignore", fd ?? "ignore", fd ?? "ignore"],
+      env: { ...process.env },
+    });
     child.once("error", (err) => {
-      logError(
-        "shutdown",
-        `Respawn failed; exiting without a successor — restart manually`,
-        err,
-      );
+      logError("shutdown", `Respawn failed (${reason}) — see respawn.log`, err);
     });
     child.unref();
     log("shutdown", `Respawn child started (pid ${child.pid}) — ${reason}`);
+    if (child.pid) spawnHandoffWatcher(child.pid, fd, spawnFn);
   } catch (err) {
-    logError(
-      "shutdown",
-      `Respawn failed; exiting without a successor — restart manually`,
-      err,
-    );
+    logError("shutdown", `Respawn failed (${reason}) — see respawn.log`, err);
   }
 }

package/src/core/engine/gateway-actions/backup/index.ts

@@ -0,0 +1,129 @@
+/**
+ * Backup actions — the agent tools and the companion app's read surface.
+ *
+ * Two vocabularies over one subsystem. `create_checkpoint`,
+ * `list_checkpoints` and `backup_status` are the model's tools and answer
+ * in prose; `backup.status`, `backup.now` and `backup.list` are the
+ * companion app's and answer with structured fields beside the text.
+ *
+ * All of them are chat-free: a snapshot belongs to the daemon, not to a
+ * conversation, so the heartbeat and background runs can take one too.
+ *
+ * There is no restore action. Restoring replaces memory, database and
+ * identity underneath a running daemon — that is a decision for a human
+ * at a CLI or behind a confirmation button, never a tool call.
+ */
+
+import {
+  collectBackupStatus,
+  formatBackupStatus,
+  formatSnapshotList,
+  listSnapshots,
+  runBackup,
+} from "../../../backup/index.js";
+import { log } from "../../../../util/log.js";
+import type { SharedActionHandlers } from "../types.js";
+
+const DEFAULT_LIST_LIMIT = 20;
+
+function limitOf(
+  body: Record<string, unknown>,
+  fallback = DEFAULT_LIST_LIMIT,
+): number {
+  const raw = Number(body.limit);
+  return Number.isInteger(raw) && raw > 0 ? Math.min(raw, 100) : fallback;
+}
+
+async function takeCheckpoint(
+  label: string,
+  pinned: boolean,
+  trigger: string,
+): Promise<ReturnType<SharedActionHandlers[string]>> {
+  try {
+    const manifest = await runBackup({
+      kind: "checkpoint",
+      label,
+      pinned,
+      trigger,
+    });
+    log("gateway", `create_checkpoint: ${manifest.id} "${label}"`);
+    return {
+      ok: true,
+      id: manifest.id,
+      text:
+        `Checkpoint ${manifest.id} taken — "${label}"` +
+        (pinned ? " (pinned, never pruned)" : "") +
+        `\n${manifest.parts.length} part(s), ${(manifest.sizeBytes / 1024 / 1024).toFixed(1)} MB.` +
+        `\nRestore it with: talon backup restore ${manifest.id}`,
+    };
+  } catch (err) {
+    return {
+      ok: false,
+      error: `Checkpoint failed: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+}
+
+export const backupHandlers: SharedActionHandlers = {
+  create_checkpoint: async (body) => {
+    const label = String(body.label ?? "").trim();
+    if (!label)
+      return { ok: false, error: "create_checkpoint: label is required" };
+    return takeCheckpoint(label, body.pin === true, "tool");
+  },
+
+  list_checkpoints: async (body) => {
+    const snapshots = await listSnapshots();
+    if (snapshots.length === 0) {
+      return {
+        ok: true,
+        text: "No snapshots yet. create_checkpoint takes one now.",
+        snapshots: [],
+      };
+    }
+    const limited = snapshots.slice(0, limitOf(body));
+    return {
+      ok: true,
+      text: formatSnapshotList(limited, limited.length),
+      snapshots: limited,
+    };
+  },
+
+  backup_status: async () => {
+    const status = await collectBackupStatus({ withTargets: false });
+    return { ok: true, text: formatBackupStatus(status) };
+  },
+
+  "backup.status": async () => {
+    const status = await collectBackupStatus();
+    return { ok: true, text: formatBackupStatus(status), status };
+  },
+
+  "backup.list": async (body) => {
+    const snapshots = (await listSnapshots()).slice(0, limitOf(body, 50));
+    return { ok: true, text: formatSnapshotList(snapshots), snapshots };
+  },
+
+  "backup.now": async (body) => {
+    const label = String(body.label ?? "").trim();
+    if (label) return takeCheckpoint(label, body.pin === true, "manual");
+    try {
+      const manifest = await runBackup({ kind: "backup", trigger: "manual" });
+      return {
+        ok: true,
+        id: manifest.id,
+        text: `Snapshot ${manifest.id} taken (${(manifest.sizeBytes / 1024 / 1024).toFixed(1)} MB).`,
+      };
+    } catch (err) {
+      return {
+        ok: false,
+        error: `Backup failed: ${err instanceof Error ? err.message : String(err)}`,
+      };
+    }
+  },
+};
+
+/** None of these need a chat — backups belong to the daemon. */
+export const backupChatFreeActions: ReadonlySet<string> = new Set(
+  Object.keys(backupHandlers),
+);

package/src/core/engine/gateway-actions/index.ts

@@ -21,6 +21,7 @@
  *   - `models`    — model / backend discovery
  *   - `mesh`      — companion device mesh (presence + location)
  *   - `cross-send` — explicit-target sends through any enabled frontend
+ *   - `backup`    — snapshots and checkpoints (chat-free; no restore)
  */
 
 import type { ActionResult } from "../../types.js";
@@ -47,6 +48,7 @@ import {
   whatsappAccountChatFreeActions,
 } from "./whatsapp-account.js";
 import { nativeHandlers } from "./native/index.js";
+import { backupChatFreeActions, backupHandlers } from "./backup/index.js";
 
 // Null-prototype so a request `action` of "toString" / "constructor" / etc.
 // can't resolve an inherited Object.prototype method — `handlers[action]` only
@@ -67,6 +69,7 @@ const handlers: SharedActionHandlers = Object.assign(Object.create(null), {
   ...crossSendHandlers,
   ...whatsappAccountHandlers,
   ...nativeHandlers,
+  ...backupHandlers,
 });
 
 /**
@@ -77,6 +80,7 @@ const chatFreeActions: ReadonlySet<string> = new Set([
   ...meshChatFreeActions,
   ...crossSendChatFreeActions,
   ...whatsappAccountChatFreeActions,
+  ...backupChatFreeActions,
 ]);
 
 /**

package/src/core/mcp-hub/talon-server.ts

@@ -16,7 +16,7 @@
 
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { composeTools } from "../tools/index.js";
-import { createBridge, textResult } from "../tools/ops/bridge.js";
+import { createBridge, textResult } from "../tools/bridge.js";
 import type { ToolFrontend, ToolTag } from "../tools/types.js";
 
 export const VALID_TOOL_FRONTENDS: ReadonlySet<string> = new Set([

package/src/core/plugin/actions.ts

@@ -2,6 +2,13 @@
  * Action routing — try a gateway action through every loaded plugin in load
  * order; first non-null result wins. Per-plugin errors are caught and surfaced
  * as error results rather than cascading.
+ *
+ * `handlePluginActionIn` is the addressed form: the backup subsystem asks
+ * each plugin in turn whether it is a remote target, and must then be able
+ * to send the follow-up uploads to THAT plugin. First-non-null routing
+ * cannot express "this one", and the wire protocol carries no plugin id —
+ * so the addressing lives here, on the core side, and the plugin-facing
+ * contract is unchanged.
  */
 
 import { logError } from "../../util/log.js";
@@ -30,3 +37,30 @@ export async function handlePluginAction(
   }
   return null;
 }
+
+/** Names of the loaded plugins that can answer gateway actions, in load order. */
+export function pluginsWithActions(): string[] {
+  return registry.all
+    .filter(({ plugin }) => plugin.handleAction !== undefined)
+    .map(({ plugin }) => plugin.name);
+}
+
+/**
+ * Run an action against one named plugin. Returns null when no plugin by
+ * that name is loaded or it does not recognise the action.
+ */
+export async function handlePluginActionIn(
+  name: string,
+  body: Record<string, unknown>,
+  chatId: string,
+): Promise<ActionResult | null> {
+  const entry = registry.all.find(({ plugin }) => plugin.name === name);
+  if (!entry?.plugin.handleAction) return null;
+  try {
+    return await entry.plugin.handleAction(body, chatId);
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    logError("plugin", `${name} action error: ${detail}`);
+    return { ok: false, error: `Plugin ${name}: ${detail}` };
+  }
+}

package/src/core/plugin/index.ts

@@ -23,5 +23,9 @@ export {
   getPluginPromptAdditions,
 } from "./loader.js";
 export { loadBuiltinPlugins, reloadPlugins } from "./builtins.js";
-export { handlePluginAction } from "./actions.js";
+export {
+  handlePluginAction,
+  handlePluginActionIn,
+  pluginsWithActions,
+} from "./actions.js";
 export { getPluginMcpServers } from "./mcp.js";

package/src/core/tools/{ops/bridge.ts → bridge.ts}

@@ -3,11 +3,16 @@
  *
  * Extracted from the old per-backend tools.ts files so there's
  * exactly one copy of callBridge / textResult.
+ *
+ * At the tools root, not in `ops/`: the group directories hold tool
+ * DOMAINS (one file per family of tool definitions), and this is the
+ * transport they all answer over — the same kind of module as
+ * `types.ts` and `schemas.ts` beside it.
  */
 
 import { Agent, fetch as undiciFetch } from "undici";
-import { isBunRuntime } from "../../../util/runtime.js";
-import type { BridgeFunction } from "../types.js";
+import { isBunRuntime } from "../../util/runtime.js";
+import type { BridgeFunction } from "./types.js";
 
 /** Default wall-clock budget for a bridge action. */
 const DEFAULT_TIMEOUT_MS = 120_000;

package/src/core/tools/index.ts

@@ -28,6 +28,7 @@ import { crossSendTools } from "./chat/cross-send.js";
 import { whatsappTools } from "./chat/whatsapp.js";
 import { moderationTools } from "./chat/moderation.js";
 import { nativeTools } from "./ops/native.js";
+import { backupTools } from "./ops/backup.js";
 
 /** All built-in tool definitions. */
 export const ALL_TOOLS: readonly ToolDefinition[] = [
@@ -54,6 +55,7 @@ export const ALL_TOOLS: readonly ToolDefinition[] = [
   // prefix, so a new family goes on the end or every live chat re-bills its
   // system prompt (see compose-tools.test.ts).
   ...agentTools,
+  ...backupTools,
 ];
 
 /**

package/src/core/tools/ops/backup.ts

@@ -0,0 +1,67 @@
+/**
+ * Backup tools — the agent's own access to its safety net.
+ *
+ * Three tools, and deliberately no fourth: there is no restore tool.
+ * Restoring replaces the agent's memory, database and identity while it
+ * is running, which is a decision for a human at a CLI or behind a
+ * confirmation button, not something a model should be able to reach for
+ * mid-turn. Taking a checkpoint, on the other hand, is cheap and always
+ * safe — so the agent is encouraged to do it before it changes itself.
+ */
+
+import { z } from "zod";
+import type { ToolDefinition } from "../types.js";
+
+export const backupTools: ToolDefinition[] = [
+  {
+    name: "create_checkpoint",
+    description: `Take a labelled snapshot of your whole state right now — config, prompts, keys, sessions, the database, your memory and skills, and the memory palace.
+
+Reach for this BEFORE you change yourself in a way you might want undone: editing identity.md, a big memory rewrite, a risky config change, installing or reconfiguring a plugin. It takes seconds and costs no tokens.
+
+Pin a checkpoint you want kept past the retention window (12 scheduled backups by default). Restoring is a human operation — 'talon backup restore <id>' or /backup restore <id> — so say the id in your reply if the checkpoint is the point of the turn.`,
+    schema: {
+      label: z
+        .string()
+        .min(1)
+        .max(80)
+        .describe(
+          "Why this checkpoint exists, in a few words ('before identity rewrite'). Shown in every listing.",
+        ),
+      pin: z
+        .boolean()
+        .optional()
+        .describe(
+          "Keep it forever — pinned checkpoints are never pruned by retention. Default false.",
+        ),
+    },
+    execute: (params, bridge) => bridge("create_checkpoint", params),
+    tag: "backup",
+  },
+
+  {
+    name: "list_checkpoints",
+    description:
+      "List recent snapshots — id, kind, label, size, whether pinned, and which remote targets hold a copy. Newest first. Use it to find the id of something you or the schedule took earlier.",
+    schema: {
+      limit: z
+        .number()
+        .int()
+        .positive()
+        .max(100)
+        .optional()
+        .describe("How many to return (default 20, max 100)."),
+    },
+    execute: (params, bridge) => bridge("list_checkpoints", params),
+    tag: "backup",
+  },
+
+  {
+    name: "backup_status",
+    description:
+      "Health of the backup subsystem: when the last snapshot ran and when the next one is due, how many snapshots exist locally and how big they are, which remote targets are registered and whether they are ready, and whether recent runs have been failing.",
+    schema: {},
+    execute: (_params, bridge) => bridge("backup_status", {}),
+    tag: "backup",
+  },
+];

package/src/core/tools/types.ts

@@ -31,7 +31,8 @@ export type ToolTag =
   | "models"
   | "mesh"
   | "moderation"
-  | "native";
+  | "native"
+  | "backup";
 
 /** The bridge caller signature — injected into execute(). */
 export type BridgeFunction = (

package/src/core/update/self-update.ts

@@ -8,6 +8,17 @@
  * source tree on disk, so {@link getRepoRoot} returns `null` and the
  * `/update` command is never registered.
  *
+ * The install is verified before anyone hands off to it. `npm install`
+ * rewrites node_modules underneath the still-running process, so a bad
+ * dependency resolution does not surface until the *successor* imports
+ * the tree — detached, with its output going nowhere, at the one moment
+ * the daemon has no one left to report to. On 2026-09-18 that cost a
+ * 45-minute outage. The last step of an update therefore runs the new
+ * tree in a child with {@link BOOT_SMOKE_FLAG}: it resolves the daemon's
+ * entire import graph and exits without booting. If it fails, the update
+ * fails — the caller reports it to the chat and the current process, the
+ * one that still works, keeps running.
+ *
  * The update force-syncs the checkout to the remote branch with
  * `git reset --hard` (plus `git clean -fd`), discarding any local edits
  * or diverged commits. A bot host is meant to mirror the remote exactly,
@@ -19,9 +30,15 @@
  */
 
 import { execFile } from "node:child_process";
+import { checkpointBeforeUpdate } from "../backup/index.js";
 import { existsSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import {
+  BOOT_SMOKE_FLAG,
+  BOOT_SMOKE_OK,
+  successorCommand,
+} from "../daemon/respawn.js";
 
 /** Tuning knobs for {@link runSelfUpdate}. */
 export interface UpdateOptions {
@@ -36,6 +53,11 @@ export interface UpdateOptions {
   setup?: readonly string[];
   /** Override the repo root (tests). Defaults to {@link getRepoRoot}. */
   repoRoot?: string;
+  /**
+   * The command that re-runs this process, used for the post-install
+   * import check. Defaults to our own argv (tests override it).
+   */
+  entry?: { cmd: string; args: readonly string[] };
   /** Injectable command runner (tests). */
   runner?: CommandRunner;
 }
@@ -70,6 +92,8 @@ export type CommandRunner = (
 ) => Promise<{ ok: boolean; output: string }>;
 
 const GIT_TIMEOUT_MS = 60_000;
+/** A cold import of the whole daemon graph, on a busy host. */
+const VERIFY_TIMEOUT_MS = 180_000;
 const INSTALL_TIMEOUT_MS = 300_000;
 const SETUP_TIMEOUT_MS = 300_000;
 const MAX_OUTPUT_BUFFER = 16 * 1024 * 1024;
@@ -225,6 +249,8 @@ export async function runSelfUpdate(
     return { ok: true, repoRoot, steps, before, after, changed: false };
   }
 
+  await checkpointBeforeUpdate(before, after);
+
   const install = await record(
     "npm install",
     "npm",
@@ -265,5 +291,26 @@ export async function runSelfUpdate(
     }
   }
 
+  const entry = opts.entry ?? successorCommand();
+  const verify = await record(
+    "verify import",
+    entry.cmd,
+    [...entry.args, BOOT_SMOKE_FLAG],
+    VERIFY_TIMEOUT_MS,
+  );
+  if (!verify.ok || !verify.output.includes(BOOT_SMOKE_OK)) {
+    return {
+      ok: false,
+      repoRoot,
+      steps,
+      before,
+      after,
+      changed,
+      error:
+        `the updated tree does not import — not restarting into it. ` +
+        `Still running ${before}; the checkout is at ${after}.`,
+    };
+  }
+
   return { ok: true, repoRoot, steps, before, after, changed: true };
 }

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

@@ -18,6 +18,7 @@
  *   model:nav:*                 (pager)
  *   model:backend-select        (select menu)
  *   metrics:today | metrics:all
+ *   backup:restore:<id> | backup:cancel  (restore confirmation, admin only)
  *   ai:<id>                     (AI-generated buttons — forwarded to agent)
  */
 
@@ -36,6 +37,7 @@ import { handleMetricsComponent } from "./metrics.js";
 import { handleModelComponent } from "./model.js";
 import { handlePulseComponent } from "./pulse.js";
 import { handleSettingsComponent } from "./settings.js";
+import { handleBackupComponent } from "../../commands/backup.js";
 import type { ComponentHandlers, ComponentInteraction } from "./types.js";
 
 // Null-prototype so a custom id of "toString:" / "constructor:" / etc.
@@ -48,6 +50,7 @@ export const COMPONENT_HANDLERS: ComponentHandlers = Object.assign(
     "effort:": handleEffortComponent,
     "model:": handleModelComponent,
     "metrics:": handleMetricsComponent,
+    "backup:": handleBackupComponent,
     "ai:": forwardToAgent,
   } satisfies ComponentHandlers,
 );