fix(ui): keep the diff engine off the startup path

.changeset/defer-syntax-worker-startup.md

@@ -0,0 +1,6 @@
+---
+"hunkdiff": patch
+---
+
+Keep `hunk --version`, `--help`, `daemon serve`, and `hunk session *` off the diff-engine startup
+path again, and release the syntax worker when the review app exits instead of at startup.

src/main.tsx

@@ -6,7 +6,6 @@ import { prepareStartupPlan } from "./app/startup";
 import { sanitizeTerminalText } from "./lib/terminalText";
 import { serveSessionBrokerDaemon } from "./session/broker/brokerServer";
 import { runSessionCommand } from "./session/agent/commands";
-import { disposeHighlightWorker } from "./ui/diff/worker";
 
 async function main() {
   const startupPlan = await prepareStartupPlan();
@@ -102,13 +101,10 @@ async function main() {
 
   // OpenTUI stays behind the interactive plan so headless commands never materialize its embedded
   // native library. The highlighting client starts the compiled worker only when an opted-in,
-  // eligible large diff needs it, so normal sessions do not pay its startup cost.
-  try {
-    const { runInteractiveApp } = await import("./ui/runInteractiveApp");
-    await runInteractiveApp(startupPlan);
-  } finally {
-    disposeHighlightWorker();
-  }
+  // eligible large diff needs it, so normal sessions do not pay its startup cost. The interactive
+  // app owns that worker's disposal: this call returns once the app is mounted, not once it exits.
+  const { runInteractiveApp } = await import("./ui/runInteractiveApp");
+  await runInteractiveApp(startupPlan);
 }
 
 await main().catch((error) => {

src/ui/runInteractiveApp.tsx

@@ -23,6 +23,7 @@ import type {
 } from "../session/types";
 import { SessionBrokerClient } from "../session/broker/brokerClient";
 import { AppHost } from "./AppHost";
+import { disposeHighlightWorker } from "./diff/worker";
 
 export interface InteractiveAppInput {
   bootstrap: AppBootstrap;
@@ -92,6 +93,10 @@ export async function runInteractiveApp({
     jobControlInterruptSupport.dispose();
     jobControlSuspendSupport.dispose();
     hostClient.stop();
+    // Release the syntax worker here rather than from the executable entrypoint: this function
+    // returns once the app is mounted, so an entrypoint-side dispose would fire before the first
+    // large diff ever asked for the worker.
+    disposeHighlightWorker();
     shutdownSession({ root, renderer: appRenderer });
   }
 

test/cli/startup-graph.test.ts

@@ -0,0 +1,113 @@
+import { describe, expect, test } from "bun:test";
+import { Transpiler } from "bun";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+
+/**
+ * Guards the startup cost of commands that never build a changeset.
+ *
+ * `hunk --version`, `--help`, `daemon serve`, the markup commands, and `hunk session *` answer
+ * without a diff engine, renderer, or VCS backend. Those subsystems are reached through dynamic
+ * `import()` from the interactive plan, so only eager `import` statements can pull them into the
+ * entrypoint graph. Walking the static graph catches the regression a timing assertion would
+ * measure inconsistently across machines.
+ */
+
+const REPO_ROOT = resolve(import.meta.dir, "../..");
+const ENTRYPOINT = join(REPO_ROOT, "src/main.tsx");
+
+/**
+ * Package prefixes the entrypoint must not load before a command selects an interactive plan.
+ *
+ * These are the heavy graphs named in the startup-deferral contract: the Pierre diff engine and
+ * its renderer, and OpenTUI's embedded native library.
+ */
+const DEFERRED_PACKAGE_PREFIXES = ["@pierre/", "@opentui/"];
+
+const MODULE_EXTENSIONS = [".ts", ".tsx", ".js", ".jsx"];
+
+/** Resolve one relative specifier to a source file the walker can read. */
+function resolveLocalModule(fromFile: string, specifier: string) {
+  const base = resolve(dirname(fromFile), specifier);
+  const candidates = [
+    base,
+    ...MODULE_EXTENSIONS.map((extension) => `${base}${extension}`),
+    ...MODULE_EXTENSIONS.map((extension) => join(base, `index${extension}`)),
+  ];
+
+  return (
+    candidates.find((candidate) => existsSync(candidate) && statSync(candidate).isFile()) ?? null
+  );
+}
+
+/** Strip the entrypoint shebang so the transpiler can scan it as a module. */
+function readModuleSource(file: string) {
+  const source = readFileSync(file, "utf8");
+  return source.startsWith("#!") ? source.slice(source.indexOf("\n") + 1) : source;
+}
+
+/**
+ * Walk every eagerly imported module reachable from the entrypoint.
+ *
+ * `scanImports` reports the imports that survive transpilation, so type-only imports are already
+ * excluded, and `dynamic-import` entries are skipped because those are exactly the deferral
+ * mechanism under test. Returns each external package with the chain that first reached it.
+ */
+function traceEagerExternals(entrypoint: string) {
+  const transpiler = new Transpiler({ loader: "tsx" });
+  const visited = new Set<string>();
+  const externals = new Map<string, string[]>();
+
+  const walk = (file: string, chain: string[]) => {
+    if (visited.has(file) || file.endsWith(".json")) {
+      return;
+    }
+    visited.add(file);
+
+    for (const imported of transpiler.scanImports(readModuleSource(file))) {
+      if (imported.kind !== "import-statement") {
+        continue;
+      }
+
+      if (imported.path.startsWith(".")) {
+        const next = resolveLocalModule(file, imported.path);
+        if (next) {
+          walk(next, [...chain, relative(REPO_ROOT, next)]);
+        }
+        continue;
+      }
+
+      if (!externals.has(imported.path)) {
+        externals.set(imported.path, [...chain, imported.path]);
+      }
+    }
+  };
+
+  walk(entrypoint, [relative(REPO_ROOT, entrypoint)]);
+  return externals;
+}
+
+describe("CLI startup graph", () => {
+  test("entrypoint does not eagerly import the diff engine or renderer", () => {
+    const externals = traceEagerExternals(ENTRYPOINT);
+    const eagerlyDeferred = [...externals.entries()]
+      .filter(([packageName]) =>
+        DEFERRED_PACKAGE_PREFIXES.some((prefix) => packageName.startsWith(prefix)),
+      )
+      .map(([packageName, chain]) => `${packageName} via ${chain.join(" -> ")}`);
+
+    expect(eagerlyDeferred).toEqual([]);
+  });
+
+  test("worker disposal stays with the interactive app rather than the entrypoint", () => {
+    // The entrypoint resolves once the app is mounted, so disposing from there would terminate the
+    // worker before the first large diff requested it.
+    const interactiveAppSource = readFileSync(
+      join(REPO_ROOT, "src/ui/runInteractiveApp.tsx"),
+      "utf8",
+    );
+
+    expect(readModuleSource(ENTRYPOINT).includes("disposeHighlightWorker")).toBe(false);
+    expect(interactiveAppSource.includes("disposeHighlightWorker()")).toBe(true);
+  });
+});