fix(session): refresh stale daemons after upgrades (#178)

Author: benvinegar

src/mcp/client.test.ts

@@ -21,7 +21,7 @@ function createRegistration() {
     repoRoot: process.cwd(),
     sourceLabel: "before.ts -> after.ts",
     title: "before.ts ↔ after.ts",
-    reviewFiles: [createTestSessionReviewFile({ path: "after.ts" })],
+    files: [createTestSessionReviewFile({ path: "after.ts" })],
   });
 }
 
@@ -101,6 +101,35 @@ describe("Hunk MCP client", () => {
     }
   }, 10_000);
 
+  test("restartIncompatibleDaemon lets startup recover when the stale daemon already exited", async () => {
+    const server = createServer((_request, response) => {
+      response.writeHead(404, { "content-type": "text/plain" });
+      response.end("gone");
+    });
+    await new Promise<void>((resolve, reject) => {
+      server.once("error", reject);
+      server.listen(0, "127.0.0.1", () => resolve());
+    });
+
+    const address = server.address();
+    const port = typeof address === "object" && address ? address.port : 0;
+    const config = {
+      host: "127.0.0.1",
+      port,
+      httpOrigin: `http://127.0.0.1:${port}`,
+      wsOrigin: `ws://127.0.0.1:${port}`,
+    };
+
+    const client = new HunkHostClient(createRegistration(), createSnapshot());
+
+    try {
+      await expect((client as any).restartIncompatibleDaemon(config)).resolves.toBeUndefined();
+    } finally {
+      client.stop();
+      await new Promise<void>((resolve) => server.close(() => resolve()));
+    }
+  });
+
   test("logs one actionable warning when a non-Hunk listener owns the MCP port", async () => {
     const conflictingListener = createServer((_request, response) => {
       response.writeHead(404, { "content-type": "text/plain" });

src/mcp/client.ts

@@ -15,7 +15,15 @@ import {
   resolveHunkMcpConfig,
   type ResolvedHunkMcpConfig,
 } from "./config";
-import { ensureHunkDaemonAvailable } from "./daemonLauncher";
+import {
+  ensureHunkDaemonAvailable,
+  readHunkDaemonHealth,
+  waitForHunkDaemonShutdown,
+} from "./daemonLauncher";
+import {
+  readHunkSessionDaemonCapabilities,
+  reportHunkDaemonUpgradeRestart,
+} from "../session/capabilities";
 
 const DAEMON_STARTUP_TIMEOUT_MS = 3_000;
 const RECONNECT_DELAY_MS = 3_000;
@@ -119,9 +127,62 @@ export class HunkHostClient {
       config,
       timeoutMs: DAEMON_STARTUP_TIMEOUT_MS,
     });
+
+    const capabilities = await readHunkSessionDaemonCapabilities(config);
+    if (!capabilities) {
+      await this.restartIncompatibleDaemon(config);
+      await ensureHunkDaemonAvailable({
+        config,
+        timeoutMs: DAEMON_STARTUP_TIMEOUT_MS,
+      });
+
+      if (!(await readHunkSessionDaemonCapabilities(config))) {
+        throw new Error(
+          "The running Hunk session daemon is incompatible with this Hunk build. " +
+            "Restart Hunk so it can launch a fresh daemon from the current source tree.",
+        );
+      }
+    }
+
     this.lastConnectionWarning = null;
   }
 
+  private async restartIncompatibleDaemon(config: ResolvedHunkMcpConfig) {
+    reportHunkDaemonUpgradeRestart();
+    const health = await readHunkDaemonHealth(config);
+    const pid = health?.pid;
+    if (pid === process.pid) {
+      throw new Error(
+        "The running Hunk session daemon is incompatible with this Hunk build. " +
+          "Restart Hunk so it can launch a fresh daemon from the current source tree.",
+      );
+    }
+
+    // If the stale daemon already disappeared on its own, let the normal startup path launch a
+    // fresh one instead of turning that race into a manual restart error.
+    if (!pid) {
+      return;
+    }
+
+    try {
+      process.kill(pid, "SIGTERM");
+    } catch (error) {
+      if (!(error instanceof Error) || !("code" in error) || error.code !== "ESRCH") {
+        throw error;
+      }
+    }
+
+    const shutDown = await waitForHunkDaemonShutdown({
+      config,
+      timeoutMs: DAEMON_STARTUP_TIMEOUT_MS,
+    });
+    if (!shutDown) {
+      throw new Error(
+        "Stopped waiting for the old Hunk session daemon to exit after it was found incompatible.",
+      );
+    }
+  }
+
   setBridge(bridge: HunkAppBridge | null) {
     this.bridge = bridge;
     void this.flushQueuedMessages();

src/mcp/daemonLauncher.ts

@@ -286,8 +286,21 @@ export function resolveHunkDaemonRuntimePaths(
   };
 }
 
-/** Check whether the loopback Hunk daemon already answers health probes. */
-export async function isHunkDaemonHealthy(
+export interface HunkDaemonHealth {
+  ok: boolean;
+  pid?: number;
+  sessions?: number;
+  pendingCommands?: number;
+  startedAt?: string;
+  uptimeMs?: number;
+  sessionApi?: string;
+  sessionCapabilities?: string;
+  sessionSocket?: string;
+  staleSessionTtlMs?: number;
+}
+
+/** Read the daemon's health payload when one is reachable on the configured loopback port. */
+export async function readHunkDaemonHealth(
   config: ResolvedHunkMcpConfig = resolveHunkMcpConfig(),
   timeoutMs = 500,
 ) {
@@ -299,15 +312,26 @@ export async function isHunkDaemonHealthy(
     const response = await fetch(`${config.httpOrigin}/health`, {
       signal: controller.signal,
     });
+    if (!response.ok) {
+      return null;
+    }
 
-    return response.ok;
+    return (await response.json()) as HunkDaemonHealth;
   } catch {
-    return false;
+    return null;
   } finally {
     clearTimeout(timeout);
   }
 }
 
+/** Check whether the loopback Hunk daemon already answers health probes. */
+export async function isHunkDaemonHealthy(
+  config: ResolvedHunkMcpConfig = resolveHunkMcpConfig(),
+  timeoutMs = 500,
+) {
+  return (await readHunkDaemonHealth(config, timeoutMs))?.ok === true;
+}
+
 /** Check whether some local process is already accepting TCP connections on the daemon port. */
 export function isLoopbackPortReachable(
   config: Pick<ResolvedHunkMcpConfig, "host" | "port"> = resolveHunkMcpConfig(),
@@ -338,6 +362,29 @@ export function isLoopbackPortReachable(
   });
 }
 
+/** Wait for the running daemon to stop responding on its health endpoint. */
+export async function waitForHunkDaemonShutdown({
+  config = resolveHunkMcpConfig(),
+  timeoutMs = 3_000,
+  intervalMs = 100,
+}: {
+  config?: ResolvedHunkMcpConfig;
+  timeoutMs?: number;
+  intervalMs?: number;
+} = {}) {
+  const deadline = Date.now() + timeoutMs;
+
+  while (Date.now() < deadline) {
+    if (!(await isHunkDaemonHealthy(config))) {
+      return true;
+    }
+
+    await Bun.sleep(intervalMs);
+  }
+
+  return false;
+}
+
 /** Wait briefly for a just-launched daemon to become reachable on its health endpoint. */
 export async function waitForHunkDaemonHealth({
   config = resolveHunkMcpConfig(),

src/mcp/daemonState.registration.test.ts

@@ -10,7 +10,7 @@ function createRegistration(overrides = {}) {
     inputKind: "diff",
     launchedAt: "2026-03-23T00:00:00.000Z",
     pid: 1234,
-    reviewFiles: [],
+    files: [],
     sessionId: "test-session",
     title: "repo diff",
     ...overrides,

src/mcp/daemonState.ts

@@ -63,9 +63,9 @@ function findSelectedFile(session: ListedSession) {
 }
 
 /** Match one review-export file against the live snapshot's current file selection. */
-function findSelectedReviewFile(reviewFiles: SessionReviewFile[], snapshot: HunkSessionSnapshot) {
+function findSelectedReviewFile(files: SessionReviewFile[], snapshot: HunkSessionSnapshot) {
   return (
-    reviewFiles.find(
+    files.find(
       (file) =>
         file.id === snapshot.selectedFileId ||
         file.path === snapshot.selectedFilePath ||
@@ -177,8 +177,8 @@ export class HunkDaemonState {
         sourceLabel: entry.registration.sourceLabel,
         launchedAt: entry.registration.launchedAt,
         terminal: entry.registration.terminal,
-        fileCount: entry.registration.reviewFiles.length,
-        files: entry.registration.reviewFiles.map(summarizeReviewFile),
+        fileCount: entry.registration.files.length,
+        files: entry.registration.files.map(summarizeReviewFile),
         snapshot: entry.snapshot,
       }))
       .sort((left, right) => right.snapshot.updatedAt.localeCompare(left.snapshot.updatedAt));
@@ -195,7 +195,7 @@ export class HunkDaemonState {
   ): SessionReview {
     const entry = this.getSessionEntry(selector);
     const { registration, snapshot } = entry;
-    const selectedFile = findSelectedReviewFile(registration.reviewFiles, snapshot);
+    const selectedFile = findSelectedReviewFile(registration.files, snapshot);
     const includePatch = options.includePatch ?? false;
 
     return {
@@ -209,7 +209,7 @@ export class HunkDaemonState {
       selectedHunk: selectedFile ? (selectedFile.hunks[snapshot.selectedHunkIndex] ?? null) : null,
       showAgentNotes: snapshot.showAgentNotes,
       liveCommentCount: snapshot.liveCommentCount,
-      files: registration.reviewFiles.map((file) => serializeReviewFile(file, includePatch)),
+      files: registration.files.map((file) => serializeReviewFile(file, includePatch)),
     };
   }
 

src/mcp/sessionRegistration.ts

@@ -31,7 +31,7 @@ function inferRepoRoot(bootstrap: AppBootstrap) {
 }
 
 /** Convert the loaded changeset into the daemon's file-and-hunk review export model. */
-function buildSessionReviewFiles(bootstrap: AppBootstrap): SessionReviewFile[] {
+function buildSessionFiles(bootstrap: AppBootstrap): SessionReviewFile[] {
   return bootstrap.changeset.files.map((file) => ({
     id: file.id,
     path: file.path,
@@ -62,7 +62,7 @@ export function createSessionRegistration(bootstrap: AppBootstrap): HunkSessionR
     sourceLabel: bootstrap.changeset.sourceLabel,
     launchedAt: new Date().toISOString(),
     terminal,
-    reviewFiles: buildSessionReviewFiles(bootstrap),
+    files: buildSessionFiles(bootstrap),
   };
 }
 
@@ -77,7 +77,7 @@ export function updateSessionRegistration(
     inputKind: bootstrap.input.kind,
     title: bootstrap.changeset.title,
     sourceLabel: bootstrap.changeset.sourceLabel,
-    reviewFiles: buildSessionReviewFiles(bootstrap),
+    files: buildSessionFiles(bootstrap),
   };
 }
 

src/mcp/types.ts

@@ -60,7 +60,7 @@ export interface HunkSessionRegistration {
   sourceLabel: string;
   launchedAt: string;
   terminal?: SessionTerminalMetadata;
-  reviewFiles: SessionReviewFile[];
+  files: SessionReviewFile[];
 }
 
 export interface HunkSessionSnapshot {

src/session/capabilities.test.ts

@@ -0,0 +1,52 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { createServer, type IncomingMessage, type ServerResponse } from "node:http";
+import { readHunkSessionDaemonCapabilities } from "./capabilities";
+
+const servers = new Set<ReturnType<typeof createServer>>();
+
+async function listen(
+  handler: (request: IncomingMessage, response: ServerResponse<IncomingMessage>) => void,
+) {
+  const server = createServer(handler);
+  servers.add(server);
+
+  await new Promise<void>((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => resolve());
+  });
+
+  const address = server.address();
+  const port = typeof address === "object" && address ? address.port : 0;
+  return {
+    server,
+    config: {
+      host: "127.0.0.1",
+      port,
+      httpOrigin: `http://127.0.0.1:${port}`,
+      wsOrigin: `ws://127.0.0.1:${port}`,
+    },
+  };
+}
+
+afterEach(async () => {
+  await Promise.all(
+    [...servers].map(
+      (server) =>
+        new Promise<void>((resolve) => {
+          server.close(() => resolve());
+        }),
+    ),
+  );
+  servers.clear();
+});
+
+describe("readHunkSessionDaemonCapabilities", () => {
+  test("returns null for non-ok capability responses so callers can trigger daemon refresh", async () => {
+    const { config } = await listen((_request: IncomingMessage, response: ServerResponse) => {
+      response.writeHead(500, { "content-type": "application/json" });
+      response.end(JSON.stringify({ error: "boom" }));
+    });
+
+    await expect(readHunkSessionDaemonCapabilities(config)).resolves.toBeNull();
+  });
+});

src/session/capabilities.ts

@@ -0,0 +1,46 @@
+import { resolveHunkMcpConfig, type ResolvedHunkMcpConfig } from "../mcp/config";
+import {
+  HUNK_SESSION_API_VERSION,
+  HUNK_SESSION_CAPABILITIES_PATH,
+  type SessionDaemonCapabilities,
+} from "./protocol";
+
+export const HUNK_DAEMON_UPGRADE_RESTART_NOTICE =
+  "[hunk:mcp] Restarting stale session daemon after upgrade.";
+
+/** Tell the user that Hunk is refreshing an old daemon left running across an upgrade. */
+export function reportHunkDaemonUpgradeRestart(log: (message: string) => void = console.error) {
+  log(HUNK_DAEMON_UPGRADE_RESTART_NOTICE);
+}
+
+/** Read the live daemon's session API capabilities, returning null for incompatible daemons. */
+export async function readHunkSessionDaemonCapabilities(
+  config: ResolvedHunkMcpConfig = resolveHunkMcpConfig(),
+): Promise<SessionDaemonCapabilities | null> {
+  const response = await fetch(`${config.httpOrigin}${HUNK_SESSION_CAPABILITIES_PATH}`);
+  if (response.status === 404 || response.status === 410) {
+    return null;
+  }
+
+  if (!response.ok) {
+    return null;
+  }
+
+  let capabilities: unknown;
+  try {
+    capabilities = await response.json();
+  } catch {
+    return null;
+  }
+
+  if (
+    !capabilities ||
+    typeof capabilities !== "object" ||
+    (capabilities as { version?: unknown }).version !== HUNK_SESSION_API_VERSION ||
+    !Array.isArray((capabilities as { actions?: unknown }).actions)
+  ) {
+    return null;
+  }
+
+  return capabilities as SessionDaemonCapabilities;
+}