talon-agent 5.2.0 → 5.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "talon-agent",
-  "version": "5.2.0",
+  "version": "5.2.2",
   "description": "Multi-frontend AI agent with full tool access, streaming, cron jobs, and plugin system",
   "author": "Dylan Neve",
   "license": "MIT",
@@ -110,7 +110,7 @@
     "@openai/agents": "^0.18.0",
     "@openai/codex-sdk": "^0.154.0",
     "@opencode-ai/sdk": "^1.17.4",
-    "@playwright/mcp": "0.0.81",
+    "@playwright/mcp": "0.0.56",
     "@types/cross-spawn": "^6.0.6",
     "@types/qrcode": "^1.5.6",
     "baileys": "^7.0.0-rc14",

package/src/app.ts

@@ -29,7 +29,16 @@ import { shutdownTriggers } from "./core/background/triggers/index.js";
 import { shutdownAgents } from "./core/agents/index.js";
 import { pruneSettledTriggers } from "./storage/triggers.js";
 import { startWatchdog, stopWatchdog } from "./util/watchdog.js";
-import { spawnSuccessor } from "./core/daemon/respawn.js";
+import {
+  BOOT_SMOKE_FLAG,
+  BOOT_SMOKE_OK,
+  spawnSuccessor,
+} from "./core/daemon/respawn.js";
+import {
+  crashCleanup,
+  crashStep,
+  handleUncaughtException,
+} from "./core/daemon/crash.js";
 import { log, logError, logWarn } from "./util/log.js";
 import { bootPhase, bootReport } from "./core/daemon/boot-timer.js";
 import {
@@ -62,6 +71,17 @@ import {
   stopResourceSampler,
 } from "./core/daemon/resource-sampler.js";
 
+// `/update` runs the freshly installed tree with --boot-smoke before it
+// hands off. Every static import above has just been resolved against
+// the new node_modules — reaching this line is the proof that the tree
+// the successor will run is importable at all. Nothing has booted yet,
+// so this is both the strongest and the last harmless place to say so.
+// See core/update/self-update.ts for what a failure does instead.
+if (process.argv.includes(BOOT_SMOKE_FLAG)) {
+  console.log(BOOT_SMOKE_OK);
+  process.exit(0);
+}
+
 const { config } = await bootPhase("bootstrap", () => bootstrap());
 
 // Record this process as the daemon. The gateway port is appended once
@@ -114,6 +134,10 @@ onBackendChange((holder, newBackend, info) => {
 let shuttingDown = false;
 let triggerPruneTimer: ReturnType<typeof setInterval> | null = null;
 
+// The composition root owns the SQLite handle, so it hands the crash
+// path its checkpoint (see core/daemon/crash.ts).
+const crashHooks = { flushDatabase };
+
 const SHUTDOWN_TIMEOUT_MS = 15_000;
 const DRAIN_TIMEOUT_MS = 5_000;
 
@@ -127,7 +151,11 @@ async function shutdownStep(name: string, fn: () => unknown): Promise<void> {
   try {
     await fn();
   } catch (err) {
-    logError("shutdown", `${name} failed`, err);
+    // Even the report is best-effort: a shutdown triggered by a full
+    // disk must not die inside its own error path.
+    crashStep("shutdown report", () =>
+      logError("shutdown", `${name} failed`, err),
+    );
   }
 }
 
@@ -138,15 +166,18 @@ async function gracefulShutdown(signal: string): Promise<void> {
 
   const deadlineAt = Date.now() + SHUTDOWN_TIMEOUT_MS;
   const forceTimer = setTimeout(() => {
-    logError("shutdown", "Timeout exceeded, forcing exit");
-    // Hand off even on the forced path. A restart must survive a
-    // subsystem that won't stop (a wedged FUSE unmount, an MCP server
-    // ignoring SIGTERM, a backend child that never acks): without this
-    // the timeout exits without a successor and `/restart` silently
-    // takes the daemon down for good. The successor may briefly race
-    // the long-poll we failed to release, but grammy retries the 409 —
-    // a few seconds of overlap beats staying down.
-    spawnSuccessor();
+    // Cleanup first, report second. Handing off matters most here: a
+    // restart must survive a subsystem that won't stop (a wedged FUSE
+    // unmount, an MCP server ignoring SIGTERM, a backend child that
+    // never acks), and it must also survive a logger that can't write —
+    // logging first is what cost us the successor on 2026-09-18. The
+    // successor may briefly race the long-poll we failed to release,
+    // but grammy retries the 409 — a few seconds of overlap beats
+    // staying down.
+    crashCleanup(crashHooks);
+    crashStep("timeout report", () =>
+      logError("shutdown", "Timeout exceeded, forcing exit"),
+    );
     process.exit(1);
   }, SHUTDOWN_TIMEOUT_MS);
   forceTimer.unref();
@@ -225,37 +256,29 @@ async function gracefulShutdown(signal: string): Promise<void> {
     const { shutdownHub } = await import("./core/mcp-hub/index.js");
     await shutdownHub();
   });
-  flushDatabase();
+  // Each tail step stands alone: a full disk can make any of them throw,
+  // and none of them may cost us the ones that follow.
+  crashStep("database flush", () => flushDatabase());
   // Guarded removal: only clear the record if it still names us. A
   // successor that raced ahead and wrote its own pid here must not be
   // orphaned (the bug that made `talon restart` spawn duplicate daemons).
-  removePidRecordIfOwnedBy(process.pid);
-  log("shutdown", "State saved");
+  crashStep("pid record removal", () => removePidRecordIfOwnedBy(process.pid));
+  crashStep("shutdown report", () => log("shutdown", "State saved"));
   // Hand off last: the frontends are stopped, so the successor binds
   // Telegram's long-poll only after we have released it. No-op unless
   // /restart or /update armed a respawn.
-  spawnSuccessor();
+  crashStep("respawn handoff", () => spawnSuccessor());
   process.exit(0);
 }
 
 process.on("SIGTERM", () => gracefulShutdown("SIGTERM"));
 process.on("SIGINT", () => gracefulShutdown("SIGINT"));
 
-process.on("uncaughtException", (err) => {
-  // EPIPE errors from network sockets (e.g. Telegram MTProto) are transient —
-  // gramjs will reconnect; crashing the process here is wrong.
-  if ((err as NodeJS.ErrnoException).code === "EPIPE") {
-    logWarn("bot", `Suppressed transient EPIPE error: ${err.message}`);
-    return;
-  }
-  logError("bot", "Uncaught exception", err);
-  flushDatabase();
-  // Same pid-guarded removal as the graceful path — a crashed daemon
-  // must not leave a record that makes `talon status` chase a dead or
-  // recycled pid.
-  removePidRecordIfOwnedBy(process.pid);
-  process.exit(1);
-});
+// Cleanup runs before the crash is reported (and the EPIPE suppression
+// is unchanged) — see core/daemon/crash.ts for why the order matters.
+process.on("uncaughtException", (err) =>
+  handleUncaughtException(err, crashHooks),
+);
 
 process.on("unhandledRejection", (reason) => {
   logWarn(
@@ -333,8 +356,9 @@ async function main(): Promise<void> {
 }
 
 main().catch((err) => {
-  logError("bot", "Fatal startup error", err);
-  flushDatabase();
-  removePidRecordIfOwnedBy(process.pid);
+  crashCleanup(crashHooks);
+  crashStep("startup report", () =>
+    logError("bot", "Fatal startup error", err),
+  );
   process.exit(1);
 });

package/src/core/daemon/crash.ts

@@ -0,0 +1,82 @@
+/**
+ * Crash-path cleanup — what has to happen when the daemon goes down
+ * abnormally: an uncaught exception, the forced exit after a shutdown
+ * timeout, or a fatal startup error.
+ *
+ * Ordering is the whole point. The old handler logged first and cleaned
+ * up afterwards, which works right up until logging is the thing that
+ * broke. On 2026-09-18 the root disk filled; the log file's write stream
+ * emitted ENOSPC with nobody listening, the uncaught-exception handler
+ * called `logError` as its first act, threw inside itself, and Node
+ * aborted the process — no database checkpoint, a stale pidfile left
+ * behind, and (the expensive part) an armed `/update` handoff that never
+ * spawned its successor. The daemon simply vanished.
+ *
+ * So: the essentials first, each in its own try/catch, logging last and
+ * strictly best-effort. `src/util/log.ts` now keeps a broken log file
+ * from throwing at all — this is the second line of defence, for every
+ * other way logging can fail while the machine is sick.
+ */
+
+import { logError, logWarn } from "../../util/log.js";
+import { removePidRecordIfOwnedBy } from "./pidfile.js";
+import { spawnSuccessor } from "./respawn.js";
+
+/**
+ * Steps the crash path can only get from the composition root.
+ * `flushDatabase` is injected because the SQLite handle stays inside
+ * `storage/` (.dependency-cruiser: db-handle-stays-in-storage).
+ */
+export type CrashHooks = {
+  flushDatabase: () => void;
+};
+
+/**
+ * Run one crash-path step. Never throws, and never uses the logger —
+ * a broken logger is precisely the case this path exists for, so the
+ * console is the fallback of last resort.
+ */
+export function crashStep(name: string, fn: () => void): void {
+  try {
+    fn();
+  } catch (err) {
+    try {
+      console.error(`[talon] crash cleanup: ${name} failed`, err);
+    } catch {
+      /* stdio is gone too — nothing left to try */
+    }
+  }
+}
+
+/**
+ * The non-logging essentials, in the order that matters:
+ *   1. drop the pid record, so `talon status` stops chasing a dead pid
+ *      (before the successor writes its own — the guarded removal then
+ *      cannot possibly orphan it),
+ *   2. hand off to the successor if `/restart` or `/update` armed one
+ *      (a no-op otherwise, see respawn.ts),
+ *   3. checkpoint the database.
+ */
+export function crashCleanup(hooks: CrashHooks): void {
+  crashStep("pid record removal", () => removePidRecordIfOwnedBy(process.pid));
+  crashStep("respawn handoff", () => spawnSuccessor());
+  crashStep("database flush", hooks.flushDatabase);
+}
+
+/**
+ * `process.on("uncaughtException")` body. Cleanup happens before the
+ * crash is reported, never after.
+ */
+export function handleUncaughtException(err: Error, hooks: CrashHooks): void {
+  // EPIPE errors from network sockets (e.g. Telegram MTProto) are transient —
+  // gramjs will reconnect; crashing the process here is wrong.
+  if ((err as NodeJS.ErrnoException).code === "EPIPE") {
+    crashStep("EPIPE notice", () =>
+      logWarn("bot", `Suppressed transient EPIPE error: ${err.message}`),
+    );
+    return;
+  }
+  crashCleanup(hooks);
+  crashStep("crash report", () => logError("bot", "Uncaught exception", err));
+  process.exit(1);
+}

package/src/core/daemon/handoff.ts

@@ -0,0 +1,192 @@
+/**
+ * Handoff watcher — the process that proves a `/restart` or `/update`
+ * actually landed.
+ *
+ * The outgoing daemon spawns its successor and then calls
+ * `process.exit()`. Until 2026-09-18 that was the whole handoff, which
+ * means nothing in the system knew whether the successor had come up.
+ * On that day one didn't: it was spawned, lived about twenty seconds,
+ * never bound its gateway, and died — and because the dying parent was
+ * the only party to the handoff, Talon simply stayed down until a human
+ * noticed forty-five minutes later.
+ *
+ * So the handoff gets a witness. `spawnSuccessor()` (./respawn.ts)
+ * starts this watcher detached, sharing the successor's respawn.log fd.
+ * It polls identity-verified discovery (./discovery.ts — `app: "talon"`,
+ * `mode: "daemon"`, matching pid) until the successor answers /health or
+ * the window closes. Only a /health answer counts: discovery will also
+ * report a daemon whose pid is merely alive, and "the process exists" is
+ * exactly the claim that was false for 20 seconds on 2026-09-18. If the
+ * successor never serves, the watcher starts the daemon exactly
+ * the way `talon start` does (./control.ts — same spawn, same boot
+ * verification) and says why in the log. The watcher is tiny on purpose:
+ * `src/index.ts` dispatches its subcommand before the app graph loads,
+ * so it costs a bare runtime and these three modules.
+ */
+
+import { dirname, resolve } from "node:path";
+import { log, logError, logWarn } from "../../util/log.js";
+import { startDaemon, type StartOutcome } from "./control.js";
+import { findRunningInstance, type RunningInstance } from "./discovery.js";
+import { isProcessAlive } from "./pidfile.js";
+
+/** Hidden subcommand: `talon _handoff-watch <successor-pid>`. */
+export const HANDOFF_WATCH_SUBCOMMAND = "_handoff-watch";
+
+/**
+ * How long a successor gets to answer /health. Generous on purpose: a
+ * cold boot with every plugin and MCP server takes ~10s on the reference
+ * host, and `startDaemon()` itself waits 30s before calling a boot late.
+ */
+const HANDOFF_WINDOW_MS = 90_000;
+const POLL_MS = 500;
+
+export type HandoffOutcome =
+  | { ok: true; via: "successor" | "restart"; pid: number; port?: number }
+  | { ok: false; reason: string };
+
+export type WatchHandoffOptions = {
+  /** The pid `spawnSuccessor()` created. */
+  childPid: number;
+  /** Repo/package root, for the `talon start` equivalent. */
+  pkgRoot: string;
+  windowMs?: number;
+  pollMs?: number;
+  pidfilePath?: string;
+  /** Injection seams for tests. */
+  find?: typeof findRunningInstance;
+  alive?: (pid: number) => boolean;
+  start?: typeof startDaemon;
+  sleep?: (ms: number) => Promise<void>;
+};
+
+function defaultSleep(ms: number): Promise<void> {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+/** Why the wait ended without a live daemon. */
+type WaitFailure = "successor-exited" | "window-expired";
+
+/** Discovery found a process; only a /health answer proves it serves. */
+function isServing(instance: RunningInstance | null): boolean {
+  return instance?.health !== undefined;
+}
+
+/**
+ * Poll until a serving daemon answers, the successor process
+ * disappears, or the window closes. A daemon that isn't our child still
+ * counts: the goal is a live Talon, not a particular pid.
+ */
+async function awaitDaemon(
+  opts: WatchHandoffOptions,
+): Promise<RunningInstance | WaitFailure> {
+  const find = opts.find ?? findRunningInstance;
+  const alive = opts.alive ?? isProcessAlive;
+  const sleep = opts.sleep ?? defaultSleep;
+  const pollMs = opts.pollMs ?? POLL_MS;
+  const deadline = Date.now() + (opts.windowMs ?? HANDOFF_WINDOW_MS);
+
+  while (Date.now() < deadline) {
+    const instance = await find(opts.pidfilePath);
+    if (instance && isServing(instance)) return instance;
+    if (!alive(opts.childPid)) return "successor-exited";
+    await sleep(pollMs);
+  }
+  return "window-expired";
+}
+
+const FAILURE_DETAIL: Record<WaitFailure, string> = {
+  "successor-exited": "the successor exited before serving /health",
+  "window-expired": "the successor never answered /health in time",
+};
+
+function describeStart(outcome: StartOutcome): string {
+  if (outcome.ok) return `started (pid ${outcome.pid})`;
+  if (outcome.reason === "already-running") {
+    return `already running (pid ${outcome.instance.pid})`;
+  }
+  if (outcome.reason === "boot-timeout") return "spawned but not yet healthy";
+  return `${outcome.reason}${outcome.detail ? `: ${outcome.detail}` : ""}`;
+}
+
+function toOutcome(started: StartOutcome, why: string): HandoffOutcome {
+  if (started.ok) {
+    return { ok: true, via: "restart", pid: started.pid, port: started.port };
+  }
+  if (started.reason === "already-running") {
+    const inst = started.instance;
+    // `talon start` refuses while a pid is alive — right, since a second
+    // daemon would fight the first for Telegram's getUpdates. But an
+    // alive pid that has never served /health is the failure, not the
+    // recovery, so it is reported as one.
+    if (!isServing(inst)) {
+      return {
+        ok: false,
+        reason: `${why}; pid ${inst.pid} is alive but not serving — kill it and run \`talon start\``,
+      };
+    }
+    return { ok: true, via: "restart", pid: inst.pid, port: inst.port };
+  }
+  return { ok: false, reason: `${why}; restart ${describeStart(started)}` };
+}
+
+/**
+ * Verify the handoff, and repair it if it failed. Never throws: this
+ * process exists only to make the outcome known.
+ */
+export async function watchHandoff(
+  opts: WatchHandoffOptions,
+): Promise<HandoffOutcome> {
+  const result = await awaitDaemon(opts);
+  if (typeof result !== "string") {
+    const via = result.pid === opts.childPid ? "successor" : "restart";
+    log(
+      "shutdown",
+      `Handoff verified — daemon pid ${result.pid} serving on ` +
+        `:${result.port ?? "?"} (${via})`,
+    );
+    return { ok: true, via, pid: result.pid, port: result.port };
+  }
+
+  const why = FAILURE_DETAIL[result];
+  logWarn(
+    "shutdown",
+    `Handoff failed — ${why}; starting Talon the way \`talon start\` does`,
+  );
+  const start = opts.start ?? startDaemon;
+  const started = await start({
+    pkgRoot: opts.pkgRoot,
+    pidfilePath: opts.pidfilePath,
+  });
+  const outcome = toOutcome(started, why);
+  if (outcome.ok)
+    log("shutdown", `Handoff recovered — ${describeStart(started)}`);
+  else logError("shutdown", `Handoff unrecoverable — ${outcome.reason}`);
+  return outcome;
+}
+
+/** src/core/daemon/ → the package root. */
+function packageRoot(): string {
+  const here = import.meta.dirname ?? process.cwd();
+  return here.includes("$bunfs") || here.includes("~BUN")
+    ? dirname(process.execPath)
+    : resolve(here, "..", "..", "..");
+}
+
+/** Entry point for `talon _handoff-watch <pid>` (src/index.ts). */
+export async function runHandoffWatch(argv: readonly string[]): Promise<void> {
+  const childPid = Number.parseInt(argv[0] ?? "", 10);
+  if (!Number.isInteger(childPid) || childPid <= 0) {
+    logError("shutdown", `Handoff watcher got no successor pid (${argv[0]})`);
+    process.exitCode = 2;
+    return;
+  }
+  log("shutdown", `Handoff watcher armed for pid ${childPid}`);
+  try {
+    const outcome = await watchHandoff({ childPid, pkgRoot: packageRoot() });
+    process.exitCode = outcome.ok ? 0 : 1;
+  } catch (err) {
+    logError("shutdown", "Handoff watcher crashed", err);
+    process.exitCode = 1;
+  }
+}

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);
   }
 }