@akanjs/devkit 3.0.0-beta.25 → 3.0.0-beta.26

package/DEV_RUNTIME_KNOBS.md

@@ -37,8 +37,10 @@ this repo's own `apps/akan`). None of those has a ceiling, and none is subtracte
 
 In practice this holds because the two ceilings are rarely at their limit simultaneously and the build
 worker exits. But if you are sizing a container to a hard number, size it against the *sum of observed
-peaks*, not against these fractions. Measured floors, for reference: builder 134-202MB at rest and
-~490MB after a route build, RSC worker ~142MB after boot, ~247MB per route build.
+peaks*, not against these fractions. Measured on `apps/minimal` (macOS, 2026-09-29), for reference: the
+builder ~120MB at rest after boot, ~540MB right after its first route build (the bundler hands most of it
+back after ~20s idle), ~250MB while it patches saves into the SSR registry; the RSC worker ~75MB after boot
+and ~110MB after route builds; the build worker ~900MB for the SSR registry's boot build.
 
 ## Recycling behaviour
 
@@ -133,13 +135,14 @@ AKAN_MEMORY_LIMIT=1200mb          # builder gets ~420MB, rsc worker ~660MB
 AKAN_DEV_IDLE_SUSPEND_MS=300000   # release the builder after 5 idle minutes
 ```
 
-Two things to expect at that size. The builder crosses 420MB during ordinary work — one route build
-costs ~247MB on top of its floor — so it is replaced roughly once per 30s while you keep building, each
+Two things to expect at that size. The builder crosses 420MB during ordinary work — its first route
+build alone takes it to ~540MB — so it is replaced roughly once per 30s while you keep building, each
 replacement costing a boot build that requests wait through rather than fail. And the build worker's
 peak is not covered by any of these ceilings; if the kernel OOM-kills it, the dev server survives with a
 red build for that generation and the log names the signal. On a boot whose `.akan` was cleared, the SSR
-registry's first build is such a worker: a killed one leaves no registry, and every later save retries that
-same whole build, so a container that cannot fit it once cannot fit it at all.
+registry's first build is such a worker, peaking near 900MB on `apps/minimal`: a killed one leaves no
+registry, and every later save retries that same whole build, so a container that cannot fit it once
+cannot fit it at all.
 
 Raising `AKAN_BUILDER_MAX_RSS_MB` above the derived share trades memory for fewer boot builds. Setting
 it to `0` trades the bound away entirely, which on a container this size means the kernel decides

package/akanApp/akanApp.host.ts

@@ -1,3 +1,4 @@
+import path from "node:path";
 import { Logger } from "akanjs/common";
 import type { BuilderMessage, BuilderMetrics, BuildPhase, ChangeBatch, DevBuildStatus } from "akanjs/server";
 import type { App } from "../commandDecorators";
@@ -93,6 +94,8 @@ export class AkanAppHost {
   readonly #bootLatch = new DevBootLatch(() => this.#onDevEvent?.({ app: this.app.name, booted: true }));
   #backend: Bun.Subprocess<"ignore", "inherit" | "pipe", "inherit" | "pipe"> | null = null;
   #builder: IncrementalBuilderHost | null = null;
+  //? Outlives the builder host, which idle wake and recovery replace; a config or metadata restart clears it.
+  #patcherOff = false;
   #backendReady = false;
   #plannedBackendStops = new WeakSet<Bun.Subprocess<"ignore", "inherit", "inherit">>();
   #restartTimer: ReturnType<typeof setTimeout> | null = null;
@@ -101,7 +104,16 @@ export class AkanAppHost {
   #backendGaveUp = false;
   #backendLifecycleState: BackendLifecycleState = "stopped";
   #pendingRestartReason: BackendRestartReason | null = null;
-  #pendingRecycle: { message: Extract<BuilderMessage, { type: "invalidate" }>; refreshConfig: boolean } | null = null;
+  #pendingRecycle: {
+    message: Extract<BuilderMessage, { type: "invalidate" }>;
+    refreshConfig: boolean;
+    failed?: boolean;
+    failedGeneration?: number;
+  } | null = null;
+  //? A restart that failed after its change applied (the builder or backend did not come up): the builder's return is
+  //? its recovery, reported past the failure's generation so the scan overlay clears.
+  #restartFailedAfterApply: number | null = null;
+  #stopping = false;
   #builderRecoveryTimer: ReturnType<typeof setTimeout> | null = null;
   #builderRecoveryAttempts = 0;
   #backendStartStatus: { generation?: number; files: string[] } | null = null;
@@ -163,6 +175,9 @@ export class AkanAppHost {
     return this;
   }
   async stop() {
+    //? Nothing reapplies once it stops: a pages ok received meanwhile would bring children back after it.
+    this.#stopping = true;
+    this.#pendingRecycle = null;
     this.#cancelIdleSuspend();
     this.#stopIdleWatcher();
     this.#clearRestartTimers();
@@ -430,12 +445,14 @@ export class AkanAppHost {
       });
   }
   async #handleBuilderMessage(message: BuilderMessage) {
+    if (this.#stopping) return;
     this.#markDevActivity();
     this.#trackBuilderGeneration(message);
     if (message.type === "build-status") {
       this.#recordBuildStatus(message.data);
       this.#sendOrQueueBuildStatus(message.data);
       this.#reviveBackendAfterGreenBuild(message.data);
+      await this.#resumeFailedRecycle(message.data);
       return;
     }
     if (message.type === "builder-metrics") {
@@ -778,12 +795,8 @@ export class AkanAppHost {
       this.logger.verbose("[idle-suspend] config changed while suspended; restarting the dev host");
       // Replaces the backend too, and a baseline kept past its own gap costs a restart at the next one.
       this.#discardBuilderGap("config change replaces the backend anyway");
-      await this.#recycleDevChildren(
-        { type: "invalidate", kinds: [...(batch?.kinds ?? [])], files },
-        {
-          refreshConfig: true,
-        },
-      );
+      //? Through the same path as a save's: a failure is reported and stays pending, as one would be awake.
+      await this.#applyRecycle({ type: "invalidate", kinds: [...(batch?.kinds ?? [])], files }, true);
       return;
     }
     // Refresh before deciding: a file created while suspended is not in the graph yet.
@@ -889,7 +902,8 @@ export class AkanAppHost {
     const wantsDevHostRestart = shouldRestartDevHostByDevPlan(message);
     const pending = this.#pendingRecycle;
     // A deferred recycle resumes on the next code batch; a css-only batch cannot heal a compile error.
-    if (wantsDevHostRestart || shouldRestartBuilderByDevPlan(message) || (pending && message.kinds.includes("code"))) {
+    const resumes = !!pending && message.kinds.includes("code") && this.#touchesFailedRecycle(message.files);
+    if (wantsDevHostRestart || shouldRestartBuilderByDevPlan(message) || resumes) {
       const refreshConfig = wantsDevHostRestart || (pending?.refreshConfig ?? false);
       const merged = pending ? mergeInvalidateMessages(pending.message, message) : message;
       const generation = message.devPlan?.generation ?? message.generation;
@@ -897,14 +911,7 @@ export class AkanAppHost {
         this.#deferRecycle(merged, { refreshConfig, generation });
         return;
       }
-      this.#pendingRecycle = null;
-      try {
-        if (refreshConfig) await this.#restartDevHost(merged);
-        else await this.#restartDevChildren(merged);
-      } catch (err) {
-        this.#recordDevHostRestartFailure(merged, err, refreshConfig ? "Config" : "Runtime metadata");
-        this.#resurrectDevChildren(merged);
-      }
+      await this.#applyRecycle(merged, refreshConfig);
       return;
     }
     if (await this.#shouldRestartBackend(message)) {
@@ -913,6 +920,38 @@ export class AkanAppHost {
     }
     this.#sendToBackend(message);
   }
+  async #applyRecycle(message: Extract<BuilderMessage, { type: "invalidate" }>, refreshConfig: boolean): Promise<void> {
+    if (this.#stopping) return;
+    this.#pendingRecycle = null;
+    const progress = { applied: !refreshConfig };
+    try {
+      if (refreshConfig) await this.#restartDevHost(message, progress);
+      else await this.#restartDevChildren(message);
+    } catch (err) {
+      const kind = refreshConfig ? "Config" : "Runtime metadata";
+      const generation = this.#recordDevHostRestartFailure(message, err, kind, { applied: progress.applied });
+      //? Kept only when the change itself did not apply: a builder that booted degraded (a broken akan.config.ts)
+      //? takes the fixing save itself and sends no invalidate, so without this the old config would keep running.
+      if (progress.applied) this.#restartFailedAfterApply = generation;
+      else this.#pendingRecycle = { message, refreshConfig, failed: true, failedGeneration: generation };
+      this.#resurrectDevChildren(message);
+    }
+  }
+  //? The first green pages build after a failed restart that touches its change is the fix: the change applies then. A
+  //? cause no save fixes (an env value) waits for the next change of those files, not for every green save.
+  async #resumeFailedRecycle(status: DevBuildStatus): Promise<void> {
+    const pending = this.#pendingRecycle;
+    if (!pending?.failed || !status.ok || status.phase !== "pages" || !this.#touchesFailedRecycle(status.files)) return;
+    //? Newer than the failure: the batch that carried the change reports its own pages ok while the restart runs.
+    if (status.generation <= (pending.failedGeneration ?? -1)) return;
+    await this.#applyRecycle(pending.message, pending.refreshConfig);
+  }
+  #touchesFailedRecycle(files: string[]): boolean {
+    const pending = this.#pendingRecycle;
+    if (!pending?.failed) return true;
+    const changed = new Set(pending.message.files);
+    return files.some((file) => changed.has(file));
+  }
   #deferRecycle(
     message: Extract<BuilderMessage, { type: "invalidate" }>,
     { refreshConfig, generation }: { refreshConfig: boolean; generation?: number },
@@ -963,8 +1002,13 @@ export class AkanAppHost {
     this.#builderRecoveryAttempts = 0;
     this.logger.info("[builder-recovery] builder recovered");
     void this.#restartBackendForGapChanges();
+    const failedAfterApply = this.#restartFailedAfterApply;
+    this.#restartFailedAfterApply = null;
     const status: DevBuildStatus = {
-      generation: reason.generation ?? this.#nextBackendBuildStatusGeneration(),
+      generation:
+        failedAfterApply !== null
+          ? this.#nextBackendBuildStatusGeneration(failedAfterApply + 1)
+          : (reason.generation ?? this.#nextBackendBuildStatusGeneration()),
       phase: "scan",
       ok: true,
       files: reason.files,
@@ -991,16 +1035,19 @@ export class AkanAppHost {
   }
   // The config is re-imported with a cache-busting query, but modules it imports stay cached: a change inside an
   // imported plugin file still needs a manual `akan start` restart.
-  async #restartDevHost(message: Extract<BuilderMessage, { type: "invalidate" }>): Promise<void> {
+  async #restartDevHost(
+    message: Extract<BuilderMessage, { type: "invalidate" }>,
+    progress?: { applied: boolean },
+  ): Promise<void> {
     const generation = message.devPlan?.generation ?? message.generation;
     this.logger.warn(
       `[dev-host] config change detected; restarting dev host generation=${generation ?? "(unknown)"} files=${message.files.length}`,
     );
-    await this.#recycleDevChildren(message, { refreshConfig: true });
+    await this.#recycleDevChildren(message, { refreshConfig: true, progress });
   }
   async #recycleDevChildren(
     message: Extract<BuilderMessage, { type: "invalidate" }>,
-    { refreshConfig = false }: { refreshConfig?: boolean } = {},
+    { refreshConfig = false, progress }: { refreshConfig?: boolean; progress?: { applied: boolean } } = {},
   ): Promise<void> {
     const generation = message.devPlan?.generation ?? message.generation;
     this.#clearRestartTimers();
@@ -1011,11 +1058,13 @@ export class AkanAppHost {
     this.#pendingBuildStatusReplay = [];
     await this.#stopBackend();
     this.#stopBuilder();
+    this.#patcherOff = false;
     if (refreshConfig) {
       await this.app.getConfig({ refresh: true });
       // Merge, not replace: `start()` added values prepare does not produce (REDIS_HOST from the tunnel).
       const { env } = await this.app.prepareCommand("start");
       Object.assign(this.env, env);
+      if (progress) progress.applied = true;
     }
     await this.#backendGraph.refresh();
     await this.#startBuilder();
@@ -1044,19 +1093,25 @@ export class AkanAppHost {
     message: Extract<BuilderMessage, { type: "invalidate" }>,
     err: unknown,
     kind: "Config" | "Runtime metadata",
-  ): void {
+    { applied }: { applied: boolean },
+  ): number {
     const generation = message.devPlan?.generation ?? message.generation ?? this.#nextBackendBuildStatusGeneration();
     const detail = err instanceof Error ? err.message : String(err);
     this.logger.warn(`[dev-host] ${kind.toLowerCase()} restart failed generation=${generation}: ${detail}`);
+    const names = message.files.slice(0, 3).map((file) => path.basename(file));
+    const saved = names.length > 0 ? names.join(", ") : "the changed file";
     const status: DevBuildStatus = {
       generation,
       phase: "scan",
       ok: false,
       files: message.files,
-      message: `${kind} change failed to apply; recovering the dev server automatically: ${detail}`,
+      message: applied
+        ? `${kind} change applied, but the dev server failed to restart: ${detail}. It is recovering on its own.`
+        : `${kind} change failed to apply: ${detail}. The dev server keeps running on the previous ${kind.toLowerCase()}; once it is fixed, save ${saved} again or restart the dev server to apply it.`,
     };
     this.#recordBuildStatus(status);
     this.#sendOrQueueBuildStatus(status);
+    return generation;
   }
   #recordBuildStatus(status: DevBuildStatus): void {
     const recovered = shouldMarkBuildPhaseRecovered(this.#buildStatusByPhase, status);
@@ -1139,6 +1194,7 @@ export class AkanAppHost {
         {
           stdio: this.stdio,
           onOutput: (kind, text) => void (kind === "stderr" ? process.stderr : process.stdout).write(text),
+          patcherOff: this.#patcherOff,
         },
       );
       try {
@@ -1226,6 +1282,7 @@ export class AkanAppHost {
   #stopBuilder(): void {
     this.#cancelRssRecycle();
     if (!this.#builder) return;
+    if (this.#builder.patcherOff) this.#patcherOff = true;
     this.#builder.stop();
     this.#builder = null;
   }

package/akanApp/devHostPolicy.test.ts

@@ -1,5 +1,7 @@
 import { describe, expect, test } from "bun:test";
 import type { BuilderMessage, BuildPhase, DevBuildStatus, DevChangeAction } from "akanjs/server";
+//? The source itself, not the package: the published akanjs exports no such subpath, and tests are not bundled.
+import { DevBuildRecovery } from "../../../akanjs/server/artifact/devBuildRecovery";
 import {
   backendRestartReasonFromMessage,
   buildStatusReplaySequence,
@@ -282,8 +284,9 @@ describe("dev idle suspend", () => {
     expect(resolveIdleSuspendMs("1500")).toBe(1_500);
   });
 
-  test("blocks a suspend on a failure in any phase, not just the newest generation", () => {
+  test("blocks a suspend on a failure in any phase but a route's, not just the newest generation", () => {
     expect(hasAnyBuildFailure(new Map())).toBe(false);
+    expect(hasAnyBuildFailure(new Map([["route", status("route", 1, false)]]))).toBe(false);
     expect(hasAnyBuildFailure(new Map([["scan", status("scan", 1, true)]]))).toBe(false);
     expect(
       hasAnyBuildFailure(
@@ -368,16 +371,53 @@ describe("build status helpers", () => {
     expect(shouldMarkBuildPhaseRecovered(previousByPhase, status("backend", 7, true))).toBe(true);
   });
 
-  test("a route built again and a builder that came back recover on the failure's own generation", () => {
-    const previousByPhase = new Map<DevBuildStatus["phase"], DevBuildStatus>([
-      ["route", status("route", 4, false)],
-      ["scan", status("scan", 42, false)],
-    ]);
-    expect(shouldMarkBuildPhaseRecovered(previousByPhase, status("route", 4, true))).toBe(true);
-    expect(shouldKeepBuildFailure(previousByPhase, status("route", 4, true))).toBe(false);
-    expect(shouldMarkBuildPhaseRecovered(previousByPhase, status("scan", 42, true))).toBe(true);
-    expect(shouldKeepBuildFailure(previousByPhase, status("scan", 42, true))).toBe(false);
-    expect(shouldKeepBuildFailure(previousByPhase, status("route", 3, true))).toBe(true);
+  test("the same route built again recovers at the failure's generation or later, and another route's ok never does", () => {
+    const routeA = (ok: boolean, generation = 4) => ({ ...status("route", generation, ok), scope: "/:lang/a" });
+    const routeB = (ok: boolean, generation = 4) => ({ ...status("route", generation, ok), scope: "/:lang/b" });
+    const previousByPhase = new Map<DevBuildStatus["phase"], DevBuildStatus>([["route", routeA(false)]]);
+    expect(shouldMarkBuildPhaseRecovered(previousByPhase, routeA(true))).toBe(true);
+    expect(shouldKeepBuildFailure(previousByPhase, routeA(true))).toBe(false);
+    expect(shouldMarkBuildPhaseRecovered(previousByPhase, routeB(true))).toBe(false);
+    expect(shouldKeepBuildFailure(previousByPhase, routeB(true))).toBe(true);
+    expect(shouldMarkBuildPhaseRecovered(previousByPhase, routeB(true, 5))).toBe(false);
+    expect(shouldMarkBuildPhaseRecovered(previousByPhase, routeA(true, 5))).toBe(true);
+    expect(shouldKeepBuildFailure(previousByPhase, routeA(true, 3))).toBe(true);
+  });
+
+  test("judges recovery as the backend does (akanjs DevBuildRecovery), case for case", () => {
+    const at = (phase: BuildPhase, generation: number, ok: boolean, scope?: string): DevBuildStatus => ({
+      ...status(phase, generation, ok),
+      ...(scope ? { scope } : {}),
+    });
+    const cases: [DevBuildStatus | undefined, DevBuildStatus][] = [];
+    for (const phase of ["backend", "route", "scan", "pages", "ssr"] as BuildPhase[])
+      for (const [previousOk, ok] of [
+        [false, true],
+        [true, true],
+        [false, false],
+      ])
+        for (const generation of [3, 4, 5])
+          for (const [previousScope, scope] of [
+            [undefined, undefined],
+            ["/a", "/a"],
+            ["/a", "/b"],
+          ])
+            cases.push([at(phase, 4, previousOk, previousScope), at(phase, generation, ok, scope)]);
+    cases.push([undefined, at("pages", 4, true)]);
+    for (const [previous, next] of cases) {
+      const previousByPhase = new Map<BuildPhase, DevBuildStatus>(previous ? [[previous.phase, previous]] : []);
+      expect([previous, next, shouldMarkBuildPhaseRecovered(previousByPhase, next)]).toEqual([
+        previous,
+        next,
+        DevBuildRecovery.recovers(previous, next),
+      ]);
+    }
+  });
+
+  test("a builder that came back clears no config change still on hold, or one that failed to apply", () => {
+    const previousByPhase = new Map<DevBuildStatus["phase"], DevBuildStatus>([["scan", status("scan", 42, false)]]);
+    expect(shouldMarkBuildPhaseRecovered(previousByPhase, status("scan", 42, true))).toBe(false);
+    expect(shouldMarkBuildPhaseRecovered(previousByPhase, status("scan", 43, true))).toBe(true);
   });
 
   test("creates backend build-status payloads for lifecycle test hooks", () => {
@@ -465,6 +505,11 @@ describe("hasBuildFailureForGeneration", () => {
     expect(hasBuildFailureForGeneration(statusByPhase, 4)).toBe(false);
   });
 
+  test("leaves a route's failure out: nothing a replacement builder boots builds a route", () => {
+    const statusByPhase = new Map<DevBuildStatus["phase"], DevBuildStatus>([["route", status("route", 42, false)]]);
+    expect(hasBuildFailureForGeneration(statusByPhase, 42)).toBe(false);
+  });
+
   test("treats unknown generations and green boards as healthy", () => {
     const statusByPhase = new Map<DevBuildStatus["phase"], DevBuildStatus>([["csr", status("csr", 3, false)]]);
     expect(hasBuildFailureForGeneration(statusByPhase, undefined)).toBe(false);

package/akanApp/devHostPolicy.ts

@@ -120,20 +120,18 @@ export const isLegacyBackendFallbackFile = (file: string, workspaceRoot: string)
   );
 };
 
-const recoversOnSameGeneration = (phase: BuildPhase): boolean =>
-  phase === "backend" || phase === "scan" || phase === "route";
-
-//? A newer generation, as the backend and the tabs judge it: an ok of the failure's own generation (a route build's
-//? registry check that had nothing to add) says nothing about the failure. The phases whose retry reports the
-//? failure's generation again (a backend or builder that came back, a route built again) recover on it.
+//? The backend's rule (akanjs `DevBuildRecovery`), copied: no exported akanjs subpath reaches it from the CLI bundle.
 export const shouldMarkBuildPhaseRecovered = (
   previousByPhase: ReadonlyMap<BuildPhase, DevBuildStatus>,
   status: DevBuildStatus,
 ): boolean => {
   const previous = previousByPhase.get(status.phase);
-  if (!previous || !status.ok || previous.ok) return false;
+  if (!previous || previous.ok || !status.ok) return false;
   const generation = generationValue(status.generation);
-  return recoversOnSameGeneration(status.phase) ? generation >= previous.generation : generation > previous.generation;
+  if (status.phase === "route" && status.scope !== undefined && previous.scope !== undefined)
+    return status.scope === previous.scope && generation >= previous.generation;
+  if (generation !== previous.generation) return generation > previous.generation;
+  return status.phase === "backend";
 };
 
 /** An ok that recovers nothing leaves the failure standing, for hello and for whatever waits on a clean build. */
@@ -205,7 +203,8 @@ export const hasBuildFailureForGeneration = (
 ): boolean => {
   if (typeof generation !== "number") return false;
   for (const status of statusByPhase.values()) {
-    if (!status.ok && status.generation === generation) return true;
+    //? Not a route's: a replacement builder or a restarted dev host boots without building one, so it cannot hit it.
+    if (!status.ok && status.phase !== "route" && status.generation === generation) return true;
   }
   return false;
 };
@@ -293,8 +292,9 @@ export const resolveIdleSuspendMs = (raw: string | undefined): number | null =>
   return Math.round(parsed);
 };
 
+//? Not a route's: a broken route builds again on its next request, which wakes a suspended builder anyway.
 export const hasAnyBuildFailure = (statusByPhase: ReadonlyMap<BuildPhase, DevBuildStatus>): boolean =>
-  [...statusByPhase.values()].some((status) => !status.ok);
+  [...statusByPhase.values()].some((status) => !status.ok && status.phase !== "route");
 
 export const shouldRefreshConfigOnIdleWake = (batch: ChangeBatch | null): boolean =>
   !!batch && batch.kinds.has("config");

package/frontendBuild/clientEntryDiscovery.test.ts

@@ -34,4 +34,79 @@ describe("GraphClientEntryDiscovery", () => {
       expect(await discovery.discover([file("S.tsx")])).toEqual([file("C.tsx")]);
     }
   });
+
+  const tempDir = async () => {
+    const dir = await mkdtemp(path.join(os.tmpdir(), "akan-discovery-"));
+    dirs.push(dir);
+    return (name: string) => path.join(dir, name);
+  };
+
+  test("an entry moved into a folder, or to another extension, is found once the move is invalidated", async () => {
+    const file = await tempDir();
+    await Bun.write(file("S.tsx"), 'import "./ui/Chart";\nimport "./ui/Card";\n');
+    await Bun.write(file("ui/Chart.tsx"), '"use client";\nexport const Chart = () => null;\n');
+    await Bun.write(file("ui/Card.tsx"), '"use client";\nexport const Card = () => null;\n');
+    const discovery = new GraphClientEntryDiscovery({ barrelImports: [] }, (async () => null) as never);
+    expect(await discovery.discover([file("S.tsx")])).toEqual([file("ui/Card.tsx"), file("ui/Chart.tsx")]);
+
+    await rm(file("ui/Chart.tsx"));
+    await Bun.write(file("ui/Chart/index.tsx"), '"use client";\nexport const Chart = () => null;\n');
+    await rm(file("ui/Card.tsx"));
+    await Bun.write(file("ui/Card.ts"), '"use client";\nexport const Card = () => null;\n');
+    discovery.invalidate([file("ui/Chart.tsx"), file("ui/Chart/index.tsx"), file("ui/Card.tsx"), file("ui/Card.ts")]);
+    expect(await discovery.discover([file("S.tsx")])).toEqual([file("ui/Card.ts"), file("ui/Chart/index.tsx")]);
+  });
+
+  test("a resolution still in flight when its target appears is not what the next walk reads", async () => {
+    const file = await tempDir();
+    await Bun.write(file("S.tsx"), 'import "./B";\n');
+    await Bun.write(file("B.tsx"), 'import "@demo/C";\nexport const b = 1;\n');
+    const gate = Promise.withResolvers<void>();
+    const seen = Promise.withResolvers<void>();
+    let calls = 0;
+    const resolvePackage = async () => {
+      calls += 1;
+      const exists = await Bun.file(file("C.tsx")).exists();
+      if (calls === 1) {
+        seen.resolve();
+        await gate.promise;
+      }
+      return exists ? { entryFile: file("C.tsx") } : null;
+    };
+    const discovery = new GraphClientEntryDiscovery({ barrelImports: [] }, resolvePackage as never);
+    const walk = discovery.discover([file("S.tsx")]);
+    await seen.promise;
+    await Bun.write(file("C.tsx"), '"use client";\nexport const C = () => null;\n');
+    discovery.invalidate([file("C.tsx")]);
+    gate.resolve();
+    await walk;
+    expect(await discovery.discover([file("S.tsx")])).toEqual([file("C.tsx")]);
+  });
+
+  test("a dense import cycle is walked once per file, not once per path", async () => {
+    const file = await tempDir();
+    const names = Array.from({ length: 12 }, (_, idx) => `M${idx}.tsx`);
+    for (const name of names)
+      await Bun.write(file(name), names.map((other) => `import "./${other.replace(".tsx", "")}";\n`).join(""));
+    await Bun.write(file("C.tsx"), '"use client";\nexport const C = () => null;\n');
+    await Bun.write(
+      file("M11.tsx"),
+      `${names.map((other) => `import "./${other.replace(".tsx", "")}";\n`).join("")}import "./C";\n`,
+    );
+    const discovery = new GraphClientEntryDiscovery({ barrelImports: [] }, (async () => null) as never);
+    const started = performance.now();
+    expect(await discovery.discover([file("M0.tsx")])).toEqual([file("C.tsx")]);
+    expect(performance.now() - started).toBeLessThan(2_000);
+    expect(await discovery.discover([file("M5.tsx")])).toEqual([file("C.tsx")]);
+  });
+
+  test("a file walked inside an import cycle keeps no partial result for a walk that starts at it", async () => {
+    const file = await tempDir();
+    await Bun.write(file("A.tsx"), 'import "./B";\nimport "./C";\n');
+    await Bun.write(file("B.tsx"), 'import "./A";\n');
+    await Bun.write(file("C.tsx"), '"use client";\nexport const C = () => null;\n');
+    const discovery = new GraphClientEntryDiscovery({ barrelImports: [] }, (async () => null) as never);
+    expect(await discovery.discover([file("A.tsx")])).toEqual([file("C.tsx")]);
+    expect(await discovery.discover([file("B.tsx")])).toEqual([file("C.tsx")]);
+  });
 });