talon-agent 5.2.1 → 5.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "talon-agent",
-  "version": "5.2.1",
+  "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,11 @@ 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,
@@ -67,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

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

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,
@@ -22,6 +33,11 @@ import { execFile } from "node:child_process";
 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 +52,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 +91,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;
@@ -265,5 +288,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/index.ts

@@ -1,11 +1,13 @@
 /**
  * Talon entry shim.
  *
- * Dispatches the hidden `_mcp-launch` (MCP supervisor) and `_lua-run`
- * (WASM Lua trigger runner) subcommands BEFORE the app graph loads —
- * both are Talon re-invoking itself (see core/mcp-hub/launcher.ts). The
- * dynamic import keeps these helper processes light: they evaluate this
- * shim and their own module, never the backends/frontends/plugins.
+ * Dispatches the hidden `_mcp-launch` (MCP supervisor), `_lua-run`
+ * (WASM Lua trigger runner) and `_handoff-watch` (restart/update
+ * witness) subcommands BEFORE the app graph loads — all three are Talon
+ * re-invoking itself (see core/mcp-hub/launcher.ts, core/daemon/
+ * handoff.ts). The dynamic import keeps these helper processes light:
+ * they evaluate this shim and their own module, never the
+ * backends/frontends/plugins.
  */
 
 import {
@@ -13,11 +15,17 @@ import {
   runSupervisor,
 } from "./core/mcp-hub/launcher.js";
 import { LUA_RUN_SUBCOMMAND, runLuaMain } from "./core/scripts/lua.js";
+import {
+  HANDOFF_WATCH_SUBCOMMAND,
+  runHandoffWatch,
+} from "./core/daemon/handoff.js";
 
 if (process.argv[2] === MCP_LAUNCH_SUBCOMMAND) {
   await runSupervisor(process.argv.slice(3));
 } else if (process.argv[2] === LUA_RUN_SUBCOMMAND) {
   await runLuaMain(process.argv.slice(3));
+} else if (process.argv[2] === HANDOFF_WATCH_SUBCOMMAND) {
+  await runHandoffWatch(process.argv.slice(3));
 } else {
   await import("./app.js");
 }

package/src/plugins/playwright/index.ts

@@ -25,9 +25,9 @@
  * with "428 Precondition Required". @playwright/mcp is therefore pinned
  * exactly in package.json (0.0.56 → playwright 1.58.x, matching python
  * playwright 1.58 which hosts Camoufox — camoufox itself caps playwright at
- * <1.61, so the node client cannot chase latest). Bump BOTH sides together,
- * deliberately — do not let a routine dependency bump move one without the
- * other.
+ * <1.61, so the node client cannot chase latest). The pin is enforced, not
+ * just documented: see version-coupling.ts (unit test that fails CI on a
+ * bump, validateConfig refusal, and a live handshake probe at init).
  */
 
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
@@ -35,6 +35,12 @@ import { dirname, resolve } from "node:path";
 import type { TalonPlugin } from "../../core/plugin/types.js";
 import { files } from "../../util/paths.js";
 import { log } from "../../util/log.js";
+import {
+  ENDPOINT_PLAYWRIGHT_MINOR,
+  bundledPlaywrightVersion,
+  couplingError,
+  probeEndpoint,
+} from "./version-coupling.js";
 
 export function createPlaywrightPlugin(config: {
   browser?: string;
@@ -141,6 +147,13 @@ export function createPlaywrightPlugin(config: {
         );
       }
 
+      // Endpoint mode: refuse to start on a client/server minor mismatch
+      // rather than fail every tool call later (see version-coupling.ts).
+      if (endpoint) {
+        const coupling = couplingError(bundledPlaywrightVersion());
+        if (coupling) errors.push(coupling);
+      }
+
       return errors.length > 0 ? errors : undefined;
     },
 
@@ -149,6 +162,29 @@ export function createPlaywrightPlugin(config: {
         "playwright",
         `Ready (${endpoint ? `Camoufox @ ${endpoint}` : `${browser}, headless=${headless}`})`,
       );
+      if (!endpoint) return;
+      // Live handshake with the bundled client version: catches a drifted
+      // server (the static check only knows the expected minor).
+      const client =
+        bundledPlaywrightVersion() ?? `${ENDPOINT_PLAYWRIGHT_MINOR}.0`;
+      const probe = await probeEndpoint(endpoint, client);
+      switch (probe.state) {
+        case "match":
+          log("playwright", `Endpoint handshake OK (Playwright ${client})`);
+          break;
+        case "mismatch":
+          log(
+            "playwright",
+            `ERROR: endpoint ${endpoint} is on Playwright ${probe.server} but the bundled client is ${probe.client} — every browser tool call will fail with 428. Align the python playwright hosting Camoufox with ENDPOINT_PLAYWRIGHT_MINOR (${ENDPOINT_PLAYWRIGHT_MINOR}) or re-pin @playwright/mcp.`,
+          );
+          break;
+        case "unreachable":
+          log(
+            "playwright",
+            `Warning: endpoint ${endpoint} did not answer the handshake probe (${probe.reason}); browser tools will fail until it is up.`,
+          );
+          break;
+      }
     },
   };
 }

package/src/plugins/playwright/provision.ts

@@ -28,6 +28,11 @@ import {
   type ProvisionOutcome,
 } from "../../core/plugin/provision.js";
 import { dirs } from "../../util/paths.js";
+import {
+  ENDPOINT_PLAYWRIGHT_MINOR,
+  bundledPlaywrightVersion,
+  couplingError,
+} from "./version-coupling.js";
 
 /** Engines whose builds Playwright manages (vs system channels). */
 const MANAGED_ENGINES = new Set(["chromium", "firefox", "webkit"]);
@@ -54,6 +59,8 @@ export interface PlaywrightProvisionDeps {
   listDir?: (p: string) => string[];
   /** playwright-core's browser registry (default: browsers.json beside the CLI). */
   registry?: BrowserDescriptor[];
+  /** Bundled playwright-core version (default: read from node_modules). */
+  bundledPlaywrightVersion?: string;
 }
 
 /** One entry of playwright-core's browsers.json. */
@@ -287,12 +294,26 @@ export function inspectPlaywright(
   deps: PlaywrightProvisionDeps = {},
 ): DoctorCheck[] {
   if (section.endpoint ?? section.endpointFile) {
+    const bundled = deps.bundledPlaywrightVersion ?? bundledPlaywrightVersion();
+    const coupling = couplingError(bundled);
     return [
       {
         label: "Playwright: remote endpoint mode",
         status: "info",
         detail: "browser lives on the remote end",
       },
+      coupling
+        ? {
+            label: "Playwright: client/endpoint version mismatch",
+            status: "fail",
+            detail: coupling,
+            issue: true,
+          }
+        : {
+            label: `Playwright: client on endpoint minor ${ENDPOINT_PLAYWRIGHT_MINOR}`,
+            status: "ok",
+            detail: bundled ? `playwright-core ${bundled}` : undefined,
+          },
     ];
   }
   const browser = section.browser ?? "chromium";

package/src/plugins/playwright/version-coupling.ts

@@ -0,0 +1,195 @@
+/**
+ * Endpoint-mode version coupling — the machinery behind the pin.
+ *
+ * In endpoint mode the MCP child connects to a remote Playwright server
+ * (the python-playwright process hosting Camoufox). Playwright's server
+ * refuses the WebSocket upgrade with "428 Precondition Required" when the
+ * client's playwright MINOR (sent in the User-Agent, `Playwright/x.y.z`)
+ * differs from its own — so a client bump that nobody noticed turns every
+ * browser tool call into an opaque error at the worst possible moment.
+ *
+ * Three guards, all keyed on ENDPOINT_PLAYWRIGHT_MINOR:
+ *  - a unit test asserts the playwright-core that @playwright/mcp bundles is
+ *    on that minor, so a dependency bump goes red in CI instead of green;
+ *  - `validateConfig` refuses to start the plugin on a mismatch, with a
+ *    message that names both versions and the fix;
+ *  - `probeEndpoint` performs the real handshake at init and reports the
+ *    server's verdict, so a drifted *server* is caught too.
+ *
+ * Bumping: change ENDPOINT_PLAYWRIGHT_MINOR and `@playwright/mcp` in
+ * package.json in the same commit, after upgrading the python side
+ * (camoufox caps python-playwright, so the node side cannot chase latest).
+ */
+
+import { randomBytes } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { request as httpRequest } from "node:http";
+import { request as httpsRequest } from "node:https";
+import { resolve } from "node:path";
+
+/**
+ * Playwright minor of the remote endpoint (python playwright behind
+ * Camoufox). Must equal the minor of the playwright-core bundled by the
+ * pinned @playwright/mcp — see the header comment before changing it.
+ */
+export const ENDPOINT_PLAYWRIGHT_MINOR = "1.58";
+
+/** "1.58.0-alpha-2026-01-16" → "1.58". */
+export function minorOf(version: string): string {
+  const m = version.match(/^(\d+)\.(\d+)/);
+  return m ? `${m[1]}.${m[2]}` : version;
+}
+
+function defaultModulesRoot(): string {
+  return resolve(import.meta.dirname ?? ".", "../../../node_modules");
+}
+
+/** Version of the playwright-core the MCP child will run with. */
+export function bundledPlaywrightVersion(
+  modulesRoot: string = defaultModulesRoot(),
+): string | undefined {
+  try {
+    const pkg = JSON.parse(
+      readFileSync(
+        resolve(modulesRoot, "playwright-core/package.json"),
+        "utf-8",
+      ),
+    ) as { version?: string };
+    return pkg.version;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Static check: does the bundled client sit on the endpoint's minor?
+ * Returns an error message, or undefined when coupled (or when the bundle
+ * cannot be read — that is reported separately as a missing install).
+ */
+export function couplingError(
+  bundled: string | undefined,
+  expectedMinor: string = ENDPOINT_PLAYWRIGHT_MINOR,
+): string | undefined {
+  if (!bundled) return undefined;
+  const got = minorOf(bundled);
+  if (got === expectedMinor) return undefined;
+  return (
+    `@playwright/mcp bundles playwright-core ${bundled} (minor ${got}) but the ` +
+    `remote endpoint is on Playwright ${expectedMinor} — every browser tool call ` +
+    `would fail with "428 Precondition Required". Pin @playwright/mcp to the ` +
+    `release that bundles playwright-core ${expectedMinor}.x, or bump ` +
+    `ENDPOINT_PLAYWRIGHT_MINOR together with the python side ` +
+    `(src/plugins/playwright/version-coupling.ts).`
+  );
+}
+
+export type EndpointProbe =
+  | { state: "match"; client: string }
+  | { state: "mismatch"; client: string; server: string }
+  | { state: "unreachable"; client: string; reason: string };
+
+/** Parse the body Playwright's server sends with its 428. */
+export function parseMismatch(
+  body: string,
+): { server: string; client: string } | undefined {
+  const server = body.match(/server version:\s*v?([\d.]+)/);
+  const client = body.match(/client version:\s*v?([\d.]+)/);
+  return server && client
+    ? { server: server[1], client: client[1] }
+    : undefined;
+}
+
+/**
+ * Perform the WebSocket upgrade the MCP child performs, advertising
+ * `clientVersion`, and read the server's verdict. Never throws; never
+ * leaves a connection open (a completed upgrade is torn down at once, and
+ * Playwright's server treats that as an ordinary client disconnect).
+ */
+export function probeEndpoint(
+  endpoint: string,
+  clientVersion: string,
+  timeoutMs = 3000,
+): Promise<EndpointProbe> {
+  return new Promise((settle) => {
+    let url: URL;
+    try {
+      url = new URL(endpoint);
+    } catch {
+      settle({
+        state: "unreachable",
+        client: clientVersion,
+        reason: `invalid endpoint URL: ${endpoint}`,
+      });
+      return;
+    }
+    const secure = url.protocol === "wss:" || url.protocol === "https:";
+    const request = secure ? httpsRequest : httpRequest;
+    const req = request({
+      host: url.hostname,
+      port: url.port || (secure ? 443 : 80),
+      path: `${url.pathname}${url.search}`,
+      method: "GET",
+      headers: {
+        Connection: "Upgrade",
+        Upgrade: "websocket",
+        "Sec-WebSocket-Version": "13",
+        "Sec-WebSocket-Key": randomBytes(16).toString("base64"),
+        "User-Agent": `Playwright/${clientVersion} (talon endpoint probe)`,
+      },
+      timeout: timeoutMs,
+    });
+    let settled = false;
+    const done = (result: EndpointProbe) => {
+      if (settled) return;
+      settled = true;
+      req.destroy();
+      settle(result);
+    };
+    req.on("upgrade", (_res, socket) => {
+      socket.destroy();
+      done({ state: "match", client: clientVersion });
+    });
+    req.on("response", (res) => {
+      let body = "";
+      res.setEncoding("utf-8");
+      res.on("data", (chunk: string) => {
+        body += chunk;
+      });
+      res.on("end", () => {
+        if (res.statusCode === 428) {
+          const parsed = parseMismatch(body);
+          done(
+            parsed
+              ? {
+                  state: "mismatch",
+                  client: clientVersion,
+                  server: parsed.server,
+                }
+              : {
+                  state: "unreachable",
+                  client: clientVersion,
+                  reason: "428 without a version box in the body",
+                },
+          );
+          return;
+        }
+        done({
+          state: "unreachable",
+          client: clientVersion,
+          reason: `HTTP ${res.statusCode ?? "?"} instead of an upgrade`,
+        });
+      });
+    });
+    req.on("timeout", () =>
+      done({ state: "unreachable", client: clientVersion, reason: "timeout" }),
+    );
+    req.on("error", (err: Error) =>
+      done({
+        state: "unreachable",
+        client: clientVersion,
+        reason: err.message,
+      }),
+    );
+    req.end();
+  });
+}

package/src/util/log.ts

@@ -16,9 +16,10 @@ import {
   statSync,
   renameSync,
   unlinkSync,
-  createWriteStream,
+  openSync,
+  writeSync,
+  closeSync,
 } from "node:fs";
-import { Writable } from "node:stream";
 import { dirs, files } from "./paths.js";
 
 export type LogComponent =
@@ -81,20 +82,29 @@ if (!existsSync(dirs.root)) {
 
 // Rotate log file on startup if it exceeds 10MB
 const MAX_LOG_SIZE = 10 * 1024 * 1024;
-try {
-  if (existsSync(LOG_FILE) && statSync(LOG_FILE).size > MAX_LOG_SIZE) {
-    const rotated = `${LOG_FILE}.old`;
+
+/**
+ * Move `path` aside to `path.old` when it has outgrown the cap. Used at
+ * import time for talon.log and at handoff time for respawn.log, so both
+ * files follow the same one-generation rule. Never throws.
+ */
+function rotateIfLarge(path: string): void {
+  try {
+    if (!existsSync(path) || statSync(path).size <= MAX_LOG_SIZE) return;
+    const rotated = `${path}.old`;
     try {
       unlinkSync(rotated);
     } catch {
-      /* ignore */
+      /* no previous generation */
     }
-    renameSync(LOG_FILE, rotated);
+    renameSync(path, rotated);
+  } catch {
+    /* a log file we cannot rotate is still a log file we can append to */
   }
-} catch {
-  /* ignore */
 }
 
+rotateIfLarge(LOG_FILE);
+
 // Suppress console output for terminal frontend (stdout belongs to the REPL)
 let quiet = process.env.TALON_QUIET === "1";
 if (!quiet) {
@@ -149,9 +159,21 @@ const SINK_RETRY_MS = 30_000;
 /** Ceiling for the doubling backoff between reopen attempts. */
 const SINK_MAX_RETRY_MS = 5 * 60_000;
 
+/**
+ * Where a {@link ResilientFileSink} puts its lines. Writing is
+ * synchronous by contract: a line that `write()` returned from is on the
+ * fd, not in a userspace queue. See the class doc for why that matters.
+ */
+export type SyncLogTarget = {
+  /** Append one already-serialized line. Throws on failure. */
+  write(line: string): void;
+  /** Release the underlying handle. Never throws. */
+  close(): void;
+};
+
 export type ResilientFileSinkOptions = {
-  /** Opens the underlying file stream. Injection seam for tests. */
-  open?: (path: string) => Writable;
+  /** Opens the underlying file. Injection seam for tests. */
+  open?: (path: string) => SyncLogTarget;
   /** Where the pause/resume notices go. Defaults to the console sink. */
   notify?: (level: "warn" | "info", message: string) => void;
   /** First backoff step (default 30s). */
@@ -161,20 +183,34 @@ export type ResilientFileSinkOptions = {
 };
 
 /**
- * A log file destination that cannot take the process down.
+ * A log file destination that cannot take the process down, and cannot
+ * lose the last thing the process said.
  *
- * A bare `createWriteStream` handed to `pino.multistream` is a loaded
- * gun: when the disk fills (ENOSPC), or the file is unlinked under a
- * rotation (EBADF), or the fd goes bad (EIO), the stream emits `error`.
- * With no listener that is an uncaught exception — and it fires from
+ * Two failures shaped this class, both on 2026-09-18.
+ *
+ * First, a bare `createWriteStream` handed to `pino.multistream` is a
+ * loaded gun: when the disk fills (ENOSPC), or the file is unlinked
+ * under a rotation (EBADF), or the fd goes bad (EIO), the stream emits
+ * `error`. With no listener that is an uncaught exception — raised from
  * inside a log call, so the crash handler's own `logError` runs on a
- * logger that is already broken. That is how a full disk killed the
- * daemon on 2026-09-18: the process aborted mid-`/update` with no
- * shutdown, no pidfile cleanup, and no successor.
+ * logger that is already broken. A full disk killed the daemon that
+ * way: no shutdown, no pidfile cleanup, no successor.
+ *
+ * Second — and this is why the writes below are synchronous — a
+ * `createWriteStream` buffers in userspace and drains on later ticks,
+ * while every terminal log line Talon writes is immediately followed by
+ * `process.exit()`: "State saved", "Respawn child started", "Timeout
+ * exceeded, forcing exit", "Fatal startup error". `process.exit()`
+ * discards whatever is still queued, so precisely the lines that explain
+ * a failed handoff were the ones that never reached the file. Measured
+ * under Bun 1.3.9: three lines logged and then `process.exit(0)` produced
+ * an empty (not even created) log file. A sink that writes with
+ * `writeSync` has nothing to flush and nothing to lose — no flush step to
+ * remember at any exit site, which is the only version of this that stays
+ * fixed.
  *
- * This sink owns the file stream instead of exposing it. pino only ever
- * sees this object, which never emits `error` and never blocks:
- *   - write failures pause file logging and destroy the broken stream,
+ * pino only ever sees this object, which never throws and never blocks:
+ *   - write failures pause file logging and close the broken handle,
  *   - lines written while paused are DROPPED and counted (never
  *     buffered — the failure mode here is "no space", so growing a
  *     buffer is the last thing to do),
@@ -184,26 +220,21 @@ export type ResilientFileSinkOptions = {
  * The console sink keeps working throughout, and carries the two
  * notices.
  */
-export class ResilientFileSink extends Writable {
+export class ResilientFileSink {
   private readonly path: string;
-  private readonly openStream: (path: string) => Writable;
+  private readonly openTarget: (path: string) => SyncLogTarget;
   private readonly notify: (level: "warn" | "info", message: string) => void;
   private readonly baseRetryMs: number;
   private readonly maxRetryMs: number;
-  private inner: Writable | null = null;
+  private target: SyncLogTarget | null = null;
   private retryMs: number;
   private retryTimer: ReturnType<typeof setTimeout> | null = null;
   private droppedWhileDown = 0;
   private down = false;
 
   constructor(path: string, opts: ResilientFileSinkOptions = {}) {
-    // decodeStrings:false keeps pino's serialized lines as strings;
-    // autoDestroy:false means a downstream failure can never tear this
-    // object down — it is the only thing standing between a broken file
-    // and the process.
-    super({ decodeStrings: false, autoDestroy: false });
     this.path = path;
-    this.openStream = opts.open ?? openLogFile;
+    this.openTarget = opts.open ?? openSyncLogFile;
     this.notify = opts.notify ?? notifyViaConsoleSink;
     this.baseRetryMs = opts.retryMs ?? SINK_RETRY_MS;
     this.maxRetryMs = opts.maxRetryMs ?? SINK_MAX_RETRY_MS;
@@ -221,63 +252,41 @@ export class ResilientFileSink extends Writable {
     return this.down;
   }
 
-  override _write(
-    chunk: unknown,
-    _encoding: BufferEncoding,
-    callback: (error?: Error | null) => void,
-  ): void {
-    const inner = this.inner;
-    if (inner === null) {
+  /** pino.multistream's entire contract: one serialized line in. */
+  write(line: string): void {
+    const target = this.target;
+    if (target === null) {
       this.droppedWhileDown++;
-    } else {
-      try {
-        inner.write(chunk as string, (err) => {
-          if (!err) this.markHealthy();
-        });
-      } catch (err) {
-        // Synchronous throw (write-after-destroy on a stream we have not
-        // been told about yet) — same handling as an `error` event.
-        this.fail(err);
-      }
+      return;
     }
-    // Always report success: pino must never see this sink fail, and
-    // backpressure here would stall whoever called log().
-    callback();
-  }
-
-  override _final(callback: (error?: Error | null) => void): void {
-    this.clearRetry();
     try {
-      this.inner?.end();
-    } catch {
-      /* going away anyway */
+      target.write(line);
+    } catch (err) {
+      this.droppedWhileDown++;
+      this.fail(err);
+      return;
     }
-    callback();
+    this.markHealthy();
   }
 
-  override _destroy(
-    _err: Error | null,
-    callback: (error?: Error | null) => void,
-  ): void {
+  /** No-op: every write already reached the fd. Part of pino's shape. */
+  flushSync(): void {}
+
+  /** Close the file and stop retrying. Part of pino's shape. */
+  end(): void {
     this.clearRetry();
     this.detachInner();
-    callback(null);
   }
 
   private openInner(): void {
     try {
-      const inner = this.openStream(this.path);
-      inner.on("error", (err: Error) => {
-        // Ignore errors from a stream we have already given up on.
-        if (this.inner === inner) this.fail(err);
-      });
-      this.inner = inner;
+      this.target = this.openTarget(this.path);
     } catch (err) {
       this.fail(err);
     }
   }
 
-  /** Give up on the current stream and arm a reopen. Never throws. */
+  /** Give up on the current handle and arm a reopen. Never throws. */
   private fail(err: unknown): void {
     const firstFailure = !this.down;
     this.detachInner();
@@ -311,15 +320,11 @@ export class ResilientFileSink extends Writable {
   }
 
   private detachInner(): void {
-    const inner = this.inner;
-    this.inner = null;
-    if (inner === null) return;
+    const target = this.target;
+    this.target = null;
+    if (target === null) return;
     try {
-      inner.removeAllListeners("error");
-      // destroy() can surface one last error — swallow it here rather
-      // than let it reach process-level uncaughtException.
-      inner.on("error", () => {});
-      inner.destroy();
+      target.close();
     } catch {
       /* best effort */
     }
@@ -358,9 +363,51 @@ export class ResilientFileSink extends Writable {
   }
 }
 
-function openLogFile(path: string): Writable {
+/** Append `line` to `fd`, looping over a short write. Throws on failure. */
+function appendLine(fd: number, line: string): void {
+  const buf = Buffer.from(line, "utf-8");
+  let offset = 0;
+  while (offset < buf.length) {
+    offset += writeSync(fd, buf, offset, buf.length - offset);
+  }
+}
+
+/** The production {@link SyncLogTarget}: an appended fd, written with writeSync. */
+export function openSyncLogFile(path: string): SyncLogTarget {
   // 0600: turns and tool output land here — same sensitivity as history.
-  return createWriteStream(path, { flags: "a", mode: 0o600 });
+  const fd = openSync(path, "a", 0o600);
+  return {
+    write: (line) => appendLine(fd, line),
+    close: () => {
+      try {
+        closeSync(fd);
+      } catch {
+        /* already gone */
+      }
+    },
+  };
+}
+
+/**
+ * Open ~/.talon/respawn.log for a successor's stdout+stderr.
+ *
+ * A `/restart` or `/update` handoff spawns the next daemon detached; with
+ * `stdio: "ignore"` a successor that dies before its logger exists — a
+ * broken import after a dependency install, a fatal bind, a runtime that
+ * aborts — leaves no trace anywhere, which is exactly how the 2026-09-18
+ * handoff vanished. Handing the child this fd makes that visible. Same
+ * one-generation rotation as talon.log.
+ *
+ * Returns null when the file cannot be opened; the caller falls back to
+ * nothing, never to a failed handoff.
+ */
+export function openRespawnLog(path: string = files.respawnLog): number | null {
+  try {
+    rotateIfLarge(path);
+    return openSync(path, "a", 0o600);
+  } catch {
+    return null;
+  }
 }
 
 function notifyViaConsoleSink(level: "warn" | "info", message: string): void {

package/src/util/paths.ts

@@ -102,6 +102,11 @@ export const files = {
   config: resolve(TALON_ROOT, "config.json"),
   /** Structured log: ~/.talon/talon.log */
   log: resolve(TALON_ROOT, "talon.log"),
+  /**
+   * Successor stdout+stderr during a `/restart` or `/update` handoff:
+   * ~/.talon/respawn.log. See core/daemon/respawn.ts.
+   */
+  respawnLog: resolve(TALON_ROOT, "respawn.log"),
   /** Legacy JSON session store (imported into talon.db on first boot) */
   sessions: resolve(TALON_ROOT, "data", "sessions.json"),
   /** SQLite database (history, sessions, chat settings, media index): ~/.talon/data/talon.db */