@akanjs/devkit 2.4.1-rc.6 → 2.4.1

package/integration/devResourceProbe.ts

@@ -0,0 +1,319 @@
+import os from "node:os";
+import path from "node:path";
+
+export type DevResourceRole = "host" | "builder" | "batch" | "gateway" | "replica" | "rsc" | "other";
+
+export interface DevResourceProc {
+  pid: number;
+  ppid: number;
+  rssMb: number;
+  cpuSec: number;
+  role: DevResourceRole;
+  command: string;
+}
+
+export interface DevResourceProbeOptions {
+  appName: string;
+  /** Must be the workspace root: package resolution has to match the real dev processes. */
+  workspaceRoot: string;
+  /** A tenant runs `node_modules/@akanjs/cli`; this repo runs its own `dist` build. */
+  cliEntry: string;
+  port: number;
+  edits: number;
+  idleSeconds: number;
+  /** `0` leaves idle suspend at its default; any other value also arms the suspend phase. */
+  suspendSeconds: number;
+  /** App-relative file to append a comment to, once per edit. */
+  editPath: string;
+  logPath: string;
+}
+
+/**
+ * Process-tree RSS over boot, browse, edits and idle-suspend — probe #1 of
+ * `04-measurement-harness.md`, and the source of every idle/warm/suspended number in the
+ * `optimize-resource` docs.
+ *
+ *   bun pkgs/@akanjs/devkit/integration/devResourceProbe.ts <app> [--idle=120] [--edits=3] [--suspend=60]
+ *
+ * Run it from the workspace root. Two things it exists to get right, both learned the hard way:
+ * it walks the process tree to a **fixpoint** (the tree is seven levels deep in places, so a
+ * fixed-depth walk silently misses the workers), and it **restores the edited file** in a `finally`
+ * so a killed probe cannot leave a comment in the tree.
+ *
+ * On macOS, a plateau that drops with no activity is the OS trimming idle pages, not convergence —
+ * report both numbers rather than the lower one.
+ */
+export class DevResourceProbe {
+  static readonly #columns: DevResourceRole[] = ["host", "builder", "batch", "gateway", "replica", "rsc"];
+
+  static parseArgs(argv: string[]): DevResourceProbeOptions {
+    const args = new Map(
+      argv.slice(1).map((arg) => {
+        const [key, value] = arg.replace(/^--/, "").split("=");
+        return [key ?? "", value ?? "1"];
+      }),
+    );
+    const appName = argv[0] ?? "akan";
+    const num = (key: string, fallback: number) => Number(args.get(key) ?? fallback);
+    return {
+      appName,
+      workspaceRoot: args.get("root") ?? process.cwd(),
+      cliEntry: args.get("cli") ?? "dist/pkgs/@akanjs/cli/index.js",
+      port: num("port", 8482),
+      edits: num("edits", 3),
+      idleSeconds: num("idle", 120),
+      suspendSeconds: num("suspend", 0),
+      editPath: args.get("edit") ?? "page/(home)/_index.tsx",
+      logPath: args.get("log") ?? path.join(os.tmpdir(), `akan-dev-resource-${appName}.log`),
+    };
+  }
+
+  readonly #options: DevResourceProbeOptions;
+  #hostPid = 0;
+
+  constructor(options: DevResourceProbeOptions) {
+    this.#options = options;
+  }
+
+  async run(): Promise<void> {
+    const { appName, workspaceRoot, cliEntry, port, logPath, suspendSeconds } = this.#options;
+    await Bun.write(logPath, "");
+    const host = Bun.spawn(["bun", cliEntry, "start", appName], {
+      cwd: workspaceRoot,
+      env: {
+        ...process.env,
+        AKAN_PUBLIC_LOG_LEVEL: "verbose",
+        // Pinned: the derived port moves with the `apps/` listing, so a probe cannot predict it.
+        AKAN_DEV_PORT: String(port),
+        ...(suspendSeconds ? { AKAN_DEV_IDLE_SUSPEND_MS: String(suspendSeconds * 1_000) } : {}),
+      },
+      stdout: Bun.file(logPath),
+      stderr: Bun.file(logPath),
+    });
+    this.#hostPid = host.pid;
+    console.info(`[probe] app=${appName} hostPid=${host.pid} port=${port} log=${logPath}`);
+
+    // Captured before the try so a crashed probe cannot leave a probe comment in the user's tree.
+    const target = path.join(workspaceRoot, "apps", appName, this.#options.editPath);
+    const original = await Bun.file(target)
+      .text()
+      .catch(() => null);
+    try {
+      await this.#measure(target, original);
+    } finally {
+      if (
+        original !== null &&
+        (await Bun.file(target)
+          .text()
+          .catch(() => "")) !== original
+      )
+        await Bun.write(target, original);
+      await this.#cleanup(host);
+    }
+  }
+
+  async #measure(target: string, original: string | null): Promise<void> {
+    const { appName, edits, idleSeconds, suspendSeconds } = this.#options;
+    const booted = await this.#waitForLog(/backend ready pid=\d+|gateway is running on port/, 240_000);
+    console.info(`[probe] boot log seen=${booted}`);
+
+    const header = ["host", "bldr", "batch", "gway", "repl", "rsc"].map((h) => h.padStart(5)).join(" ");
+    console.info(`\n${"sample".padEnd(22)} ${header}`);
+    const started = Date.now();
+    let idleTotal = 0;
+    while ((Date.now() - started) / 1_000 < idleSeconds) {
+      await Bun.sleep(5_000);
+      idleTotal = this.#row(`idle+${Math.round((Date.now() - started) / 1_000)}s`, await this.#sampleTree());
+    }
+    console.info(`[probe] IDLE BASELINE ${idleTotal.toFixed(0)}MB`);
+    await this.#reportMetrics("idle");
+
+    // 4.2: every idle number understates, because route modules are evaluated on first request.
+    const routes = await this.#staticRoutes();
+    const first = await this.#browse(routes);
+    console.info(`[probe] browsed ${routes.length} static route(s): ok=${first.ok} failed=${first.failed}`);
+    this.#row("browse-all-once", await this.#sampleTree());
+    const hot = routes.slice(0, Math.max(1, Math.ceil(routes.length / 4)));
+    for (let pass = 1; pass <= 3; pass++) await this.#browse(hot);
+    const warm = this.#row("browse-hot-x3", await this.#sampleTree());
+    console.info(`[probe] WARM TOTAL ${warm.toFixed(0)}MB (idle was ${idleTotal.toFixed(0)}MB)`);
+    await this.#reportMetrics("warm");
+
+    if (original === null) console.info(`[probe] no edit target at ${target}; skipping edits`);
+    else {
+      for (let edit = 1; edit <= edits; edit++) {
+        await Bun.write(target, `${original}\n// probe-edit-${edit}\n`);
+        await Bun.sleep(25_000);
+        this.#row(`edit${edit}`, await this.#sampleTree());
+      }
+      await Bun.write(target, original);
+      await Bun.sleep(10_000);
+      this.#row("restored", await this.#sampleTree());
+    }
+    await this.#reportMetrics("after-edits");
+
+    if (!suspendSeconds) return;
+    const suspended = await this.#waitForLog(/\[idle-suspend\].*released the builder/, (suspendSeconds + 60) * 1_000);
+    console.info(`[probe] idle-suspend seen=${suspended} (app=${appName})`);
+    await Bun.sleep(5_000);
+    console.info(`[probe] IDLE-SUSPENDED ${this.#row("idle-suspended", await this.#sampleTree()).toFixed(0)}MB`);
+  }
+
+  #roleOf(command: string): DevResourceRole {
+    if (/cli\/index\.js\s+start\s/.test(command)) return "host";
+    if (/incrementalBuilder\.proc/.test(command)) return "builder";
+    if (/buildBatch\.proc/.test(command)) return "batch";
+    if (/rscWorker|react-server/.test(command)) return "rsc";
+    if (new RegExp(`apps/${this.#options.appName}/main\\.ts`).test(command)) return "gateway";
+    if (/server\.ts|import\(/.test(command)) return "replica";
+    return "other";
+  }
+
+  /** One `ps`, then walk from the host pid to a fixpoint — the tree is seven levels deep in places. */
+  async #sampleTree(): Promise<DevResourceProc[]> {
+    const proc = Bun.spawn(["ps", "-eo", "pid=,ppid=,rss=,time=,command="], { stdout: "pipe" });
+    const text = await new Response(proc.stdout).text();
+    await proc.exited;
+    const all = text
+      .split("\n")
+      .map((line) => line.trim())
+      .filter(Boolean)
+      .map((line) => {
+        const match = /^(\d+)\s+(\d+)\s+(\d+)\s+([\d:.]+)\s+(.*)$/.exec(line);
+        if (!match) return null;
+        const [, pid, ppid, rss, time, command] = match;
+        const parts = (time ?? "0:0").split(":");
+        const cpuSec =
+          parts.length === 3
+            ? Number(parts[0]) * 3600 + Number(parts[1]) * 60 + Number(parts[2])
+            : Number(parts[0] ?? 0) * 60 + Number(parts[1] ?? 0);
+        return {
+          pid: Number(pid),
+          ppid: Number(ppid),
+          rssMb: Number(rss) / 1024,
+          cpuSec,
+          role: this.#roleOf(command ?? ""),
+          command: command ?? "",
+        } satisfies DevResourceProc;
+      })
+      .filter((proc): proc is DevResourceProc => proc !== null);
+    const kept = new Map<number, DevResourceProc>();
+    const root = all.find((proc) => proc.pid === this.#hostPid);
+    if (root) kept.set(this.#hostPid, root);
+    for (let pass = 0; pass < 12; pass++) {
+      const before = kept.size;
+      for (const proc of all) if (kept.has(proc.ppid) && !kept.has(proc.pid)) kept.set(proc.pid, proc);
+      if (kept.size === before) break;
+    }
+    return [...kept.values()].filter((proc) => proc.role !== "other" || proc.pid === this.#hostPid);
+  }
+
+  #row(label: string, procs: DevResourceProc[]): number {
+    const byRole = new Map<DevResourceRole, number>();
+    for (const proc of procs) byRole.set(proc.role, (byRole.get(proc.role) ?? 0) + proc.rssMb);
+    const total = procs.reduce((sum, proc) => sum + proc.rssMb, 0);
+    const cpu = procs.reduce((sum, proc) => sum + proc.cpuSec, 0);
+    const fmt = (value: number) => value.toFixed(0).padStart(5);
+    const cells = DevResourceProbe.#columns.map((role) => (byRole.has(role) ? fmt(byRole.get(role) ?? 0) : "    —"));
+    console.info(
+      `${label.padEnd(22)} ${cells.join(" ")} | total ${fmt(total)}MB cpu ${cpu.toFixed(0)}s n=${procs.length}`,
+    );
+    return total;
+  }
+
+  /**
+   * Static route urls from the page tree: `(group)` segments are stripped, and a route with a
+   * `[dynamic]` segment is skipped because it needs a real id to render.
+   */
+  async #staticRoutes(): Promise<string[]> {
+    const glob = new Bun.Glob("**/_index.tsx");
+    const cwd = path.join(this.#options.workspaceRoot, "apps", this.#options.appName, "page");
+    const urls = new Set<string>();
+    for await (const file of glob.scan({ cwd })) {
+      if (/\[[^\]]+\]/.test(file)) continue;
+      const segments = file
+        .replace(/\/?_index\.tsx$/, "")
+        .split("/")
+        .filter((segment) => segment && !/^\(.*\)$/.test(segment));
+      urls.add(`/${segments.join("/")}`);
+    }
+    return [...urls].sort();
+  }
+
+  async #browse(urls: string[]): Promise<{ ok: number; failed: number }> {
+    let ok = 0;
+    let failed = 0;
+    for (const url of urls) {
+      try {
+        const res = await fetch(`http://localhost:${this.#options.port}${url}`, {
+          signal: AbortSignal.timeout(60_000),
+        });
+        await res.text();
+        if (res.ok) ok++;
+        else failed++;
+      } catch {
+        failed++;
+      }
+    }
+    return { ok, failed };
+  }
+
+  /** Only the counters 4.2 asks for; the raw payload is hundreds of fields. */
+  async #reportMetrics(label: string): Promise<void> {
+    const child = await (async () => {
+      try {
+        const res = await fetch(`http://localhost:${this.#options.port}/_akan/app/metrics`, {
+          signal: AbortSignal.timeout(5_000),
+        });
+        if (!res.ok) return null;
+        const body = (await res.json()) as { children?: { metrics?: { [key: string]: number } }[] };
+        return body.children?.[0]?.metrics ?? null;
+      } catch {
+        return null;
+      }
+    })();
+    if (!child) {
+      console.info(`[metrics ${label}] unavailable`);
+      return;
+    }
+    const keys = [
+      "rscRenderCount",
+      "rscRouteModuleCount",
+      "rscLoadedRouteModuleCount",
+      "ssrChunkRegistrySize",
+      "ssrChunkLoadCount",
+      "rscWorkerRecycleCount",
+      "httpFullSsrCount",
+    ];
+    const rssMb = (Number(child.rssBytes ?? 0) / 1024 / 1024).toFixed(0);
+    const parts = keys.map((key) => `${key}=${child[key] ?? "?"}`);
+    console.info(`[metrics ${label}] rsc rss=${rssMb}MB ${parts.join(" ")}`);
+  }
+
+  async #waitForLog(pattern: RegExp, timeoutMs: number): Promise<boolean> {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+      const text = await Bun.file(this.#options.logPath)
+        .text()
+        .catch(() => "");
+      if (pattern.test(text)) return true;
+      await Bun.sleep(500);
+    }
+    return false;
+  }
+
+  async #cleanup(host: { kill: (signal: NodeJS.Signals) => void }): Promise<void> {
+    for (const proc of (await this.#sampleTree()).reverse()) {
+      try {
+        process.kill(proc.pid, "SIGKILL");
+      } catch {}
+    }
+    try {
+      host.kill("SIGKILL");
+    } catch {}
+    await Bun.sleep(1_000);
+    console.info(`[probe] survivors after kill: ${(await this.#sampleTree()).length}`);
+  }
+}
+
+if (import.meta.main) await new DevResourceProbe(DevResourceProbe.parseArgs(process.argv.slice(2))).run();

package/integration/devStability.integration.test.ts

@@ -513,6 +513,13 @@ export class FixtureService extends serve("fixture" as const, { serverMode: "bat
 describe("dev resource budgets", () => {
   const BOOT_MS = 150_000;
   const WAIT_MS = 90_000;
+  /**
+   * Measured on this fixture at **260-516ms** per save. Set ~6× above that, like every budget here: it is
+   * looking for a path that got slower by a factor — a boot build that stopped being avoidable, a worker
+   * spawn that stopped being warm — not for jitter on a busy laptop. `apps/akan`, ~25× this fixture's
+   * pages bundle, took ~1.5s per save when the plan started.
+   */
+  const SAVE_LATENCY_BUDGET_MS = 3_000;
   const budgetTest = (name: string, fn: () => Promise<void>): void => {
     if (integrationEnabled) test(name, fn, 300_000);
     else test.skip(name, fn);
@@ -669,15 +676,116 @@ describe("dev resource budgets", () => {
     );
     await harness.waitForHttpText("marker-after-recycle", WAIT_MS);
 
-    // A replacement that is still over the ceiling proves the ceiling cannot be met, and the host has
-    // to stop rather than recycle forever. Two reports inside the minimum interval is the threshold.
+    // This fixture's builder boots well under the ceiling and blows past it on its first build, which
+    // is the shape of every app the ceiling is derived for — a 1.2GB sandbox gives the builder ~420MB
+    // and a single route build costs ~247MB. So the host says the ceiling is tight...
     for (let i = 1; i <= 3; i++) {
       const { mark } = await harness.editUntilSeen(host, (attempt) =>
         harness.replaceText("ui/ClientMarker.tsx", /marker(-[\w-]+)?/, `marker-settled-${i}-${attempt}`),
       );
       await host.waitForLogSince(mark, /pages-rebundle ok/, WAIT_MS).catch(() => undefined);
     }
-    await host.waitForLogSince(start, /ceiling cannot be met for this app/, WAIT_MS);
+    await host.waitForLogSince(start, /ceiling costs about one boot build per interval/, WAIT_MS);
+    // ...and goes on enforcing it. This used to disable the ceiling for the rest of the session on the
+    // same evidence, which on a small sandbox means nothing bounds the builder from the first page load
+    // onwards. Recycling is throttled to one per interval; that throttle is the answer to the cost, not
+    // dropping the bound.
+    expect(host.logs.join("").slice(start)).not.toMatch(/no longer enforcing it this session/);
+  });
+
+  // The guard the memory work did not have. Every budget above asserts RSS; none of them asserts that a
+  // page still renders while the machinery those budgets require is mid-swap — and that gap is where two
+  // shipped defects lived (`local/optimize-resource/19-shutdown-and-restart-races.md`).
+  budgetTest("serves a page requested while the builder is being replaced", async () => {
+    const harness = await createHarness();
+    // Same unmeetable ceiling as the guard above, for the same reason: a builder that no longer grows
+    // into a ceiling has to start under one for the recycle path to run end to end.
+    const host = await harness.startHost({ timeoutMs: BOOT_MS, env: { AKAN_BUILDER_MAX_RSS_MB: "200" } });
+    const port = await harness.resolvePort();
+    await harness.waitForHttpText("initial-client-marker", WAIT_MS);
+
+    const start = host.markLog();
+    // One save does both halves of the setup: it drops the route's client entries, so the next request
+    // has to ask the builder again rather than being served from cache, and it makes the builder report
+    // an rss over the ceiling, which is what arms the recycle.
+    const { mark } = await harness.editUntilSeen(host, (attempt) =>
+      harness.replaceText("ui/ClientMarker.tsx", /marker(-[\w-]+)?/, `marker-through-recycle-${attempt}`),
+    );
+    await host.waitForLogSince(mark, /pages-rebundle ok/, WAIT_MS);
+
+    // A builder that has been asked to drain is still alive and refuses everything new, so this request
+    // has to be held for the replacement exactly like one that arrives after the process is gone. Timing
+    // decides which of the two windows it actually lands in — the drain of an idle builder is short, and
+    // the log is polled — so what is asserted is the outcome both windows must produce. The drain itself
+    // is pinned deterministically one layer down, in `incrementalBuilder.host.test.ts`.
+    await host.waitForLogSince(start, /recycling builder pid=\d+/, WAIT_MS);
+    // Not awaited here: a held request only returns once the replacement is up, and waiting for it would
+    // put every assertion below on the far side of the window they are about.
+    const drainRequest = fetch(`http://127.0.0.1:${port}/`, { signal: AbortSignal.timeout(WAIT_MS) }).then(
+      async (response) => ({ status: response.status, html: await response.text() }),
+    );
+
+    // Wait until the replacement exists but is still doing its boot build. From here it cannot answer
+    // anything for seconds — which is exactly the window a developer's reload lands in, and the point of
+    // anchoring on the spawn rather than on the exit: the gap after it is wide and known, not a race.
+    await host.waitForLogSince(start, /exiting for recycle/, WAIT_MS);
+    await host.waitForLogSince(start, /builder spawned pid=\d+ .*restart=1/, WAIT_MS);
+
+    const holdMark = host.markLog();
+    const startedAtMono = performance.now();
+    // The second route, never requested before, so this one cannot be answered from the route cache the
+    // request above just populated — it has to reach a builder that is not there yet.
+    const res = await fetch(`http://127.0.0.1:${port}/second`, { signal: AbortSignal.timeout(WAIT_MS) });
+    const html = await res.text();
+    const heldMs = Math.round(performance.now() - startedAtMono);
+
+    // What the developer sees, asserted first because it is the whole point: with the hold removed this
+    // same request is answered **500** by the dev error page, and nothing retries on its own — the tab
+    // stays broken until it is reloaded by hand. Measured both ways before this guard was committed.
+    expect(res.status).toBe(200);
+    expect(html).toContain("marker-through-recycle");
+    expect(html).not.toContain("reload after the builder is ready");
+    // And this is what stops the test passing having tested nothing: a request that arrives after the
+    // replacement is already ready never reaches the path under test, and everything above holds anyway.
+    expect(host.logs.join("").slice(holdMark)).toMatch(/holding build-route until the builder is ready/);
+
+    // The one fired at the drain, whichever side of the exit it landed on.
+    const drained = await drainRequest;
+    expect(drained.status).toBe(200);
+    expect(drained.html).toContain("marker-through-recycle");
+    console.info(`[restart-guard] page held ${heldMs}ms across the recycle, then rendered`);
+  });
+
+  // The other half of a resource budget, and the half this plan spent: every megabyte above was bought
+  // with latency — a worker process spawned per save, a boot build per recycle and per wake, a hold
+  // window in front of requests that land in one. Nothing measured what that cost, so a change that
+  // traded another second per save for another 50MB would have passed every guard in this block.
+  budgetTest("keeps a save's round trip inside its budget", async () => {
+    const harness = await createHarness();
+    const host = await harness.startHost({ timeoutMs: BOOT_MS });
+    await harness.waitForHttpText("initial-client-marker", WAIT_MS);
+
+    const samples: number[] = [];
+    for (let i = 1; i <= 3; i++) {
+      let savedAtMono = 0;
+      // Timed from inside the mutate callback so a retried save — Bun drops watcher events, which is why
+      // `editUntilSeen` exists — is measured from the attempt that actually landed, not from the first.
+      const { mark } = await harness.editUntilSeen(host, async (attempt) => {
+        await harness.replaceText("ui/ClientMarker.tsx", /marker(-[\w-]+)?/, `marker-latency-${i}-${attempt}`);
+        savedAtMono = performance.now();
+      });
+      // The moment the running dev server is serving the new code, which is everything the developer is
+      // waiting for. Deliberately not the browser's refresh message: that one is only published when a
+      // client is connected, so measuring it would measure a WebSocket probe's reconnects as well.
+      await host.waitForLogSince(mark, /\[hmr\] backend apply/, WAIT_MS);
+      samples.push(performance.now() - savedAtMono);
+    }
+
+    const rounded = samples.map((ms) => Math.round(ms));
+    console.info(`[latency-guard] save -> new code live ${rounded.join("ms, ")}ms`);
+    // Per save, not summed: the interesting regression is one save getting slower, and the median would
+    // hide a first save that pays for something the rest do not.
+    expect(Math.max(...rounded)).toBeLessThan(SAVE_LATENCY_BUDGET_MS);
   });
 
   budgetTest("suspends the builder when the dev server goes idle and wakes it on the next edit", async () => {
@@ -739,8 +847,49 @@ describe("dev resource budgets", () => {
       .catch(() => 0);
 
     await host.waitForLogSince(mark, /\[idle-suspend\] waking \(build-csr arrived while suspended\)/, WAIT_MS);
-    await host.waitForLogSince(mark, /\[idle-suspend\] replaying 1 request\(s\) held during the wake/, WAIT_MS);
+    // `[builder]`, not `[idle-suspend]`: the same queue now also holds requests across a builder restart,
+    // so the replay says what it did rather than which of the two reasons put the request there. The wake
+    // line above is what distinguishes them, and it is asserted first for that reason.
+    await host.waitForLogSince(mark, /\[builder\] replaying 1 request\(s\) held while the builder was away/, WAIT_MS);
     expect(status).toBe(200);
     expect(await DevStabilityHarness.builderProcess(host.proc.pid)).not.toBeNull();
   });
+
+  // The gap on the other side of the same window: requests held across it are answered, but for a while
+  // nothing was *watching* across it. The suspend stops its watcher before the replacement builder has
+  // primed its index, and the replacement primes from the disk it finds — so a save in between is
+  // baseline to it, reported by nobody, and the backend goes on running the code it replaced. Phase 2
+  // made this window routine by recycling the builder on every rss ceiling crossing.
+  budgetTest("restarts the backend for a save that lands while the builder is away", async () => {
+    const harness = await createHarness();
+    const host = await harness.startHost({ timeoutMs: BOOT_MS, env: { AKAN_DEV_IDLE_SUSPEND_MS: "3000" } });
+    const start = host.markLog();
+    await harness.waitForHttpText("initial-client-marker", WAIT_MS);
+    await host.waitForLogSince(start, /\[idle-suspend\] .*released the builder/, WAIT_MS);
+
+    const mark = host.markLog();
+    const port = await harness.resolvePort();
+    // This request is the clock: it wakes the dev server and is answered only once the replacement
+    // builder is ready, so a write issued while it is in flight lands squarely inside the gap. Its own
+    // status is not asserted here — the write below restarts the backend, which drops the connection.
+    const request = fetch(`http://127.0.0.1:${port}/__csr`).catch(() => null);
+    // A service the backend imports, rather than this fixture's `srvkit/backendMarker.ts`: that marker is
+    // orphaned once `akan start` regenerates `server.ts`, so it is not in the backend graph at all and an
+    // edit to it restarts the backend by path role instead.
+    await harness.writeFile(
+      "lib/_fixture/fixture.service.ts",
+      `import { serve } from "akanjs/service";
+
+export class FixtureService extends serve("fixture" as const, { serverMode: "batch" }, () => ({})) {}
+// touched while the builder was away
+`,
+    );
+    await request;
+
+    await host.waitForLogSince(mark, /\[builder-gap\] 1 backend file\(s\) changed while the builder was away/, WAIT_MS);
+    await host.waitForLogSince(mark, /\[backend-reload\]/, WAIT_MS);
+    // And back to a working dev server, rather than one stuck restarting.
+    await host.waitForLogSince(mark, /backend ready pid=(\d+)|AkanApp gateway is running on port/, WAIT_MS);
+    await harness.waitForHttpText("initial-client-marker", WAIT_MS);
+  });
 });

package/integration/devStabilityHarness.ts

@@ -188,6 +188,23 @@ export default function Page() {
     </main>
   );
 }
+`,
+      ),
+      // A second route exists so a test can ask for a page the backend has *never* built, at a moment of
+      // its choosing. Route clients are built on demand and cached, so on a one-route fixture the first
+      // request of a test is the only one that reaches the builder at all.
+      this.writeFile(
+        "page/second/_index.tsx",
+        `import { ClientMarker } from "../../ui/ClientMarker";
+
+export default function Page() {
+  return (
+    <main>
+      <h1>Second route</h1>
+      <ClientMarker />
+    </main>
+  );
+}
 `,
       ),
       this.writeFile(
@@ -968,11 +985,19 @@ export const dictionary = serviceDictionary(["en", "ko"])
   static readonly #psTimeoutMs = 5_000;
 
   static async #psRows(): Promise<Array<{ pid: number; ppid: number; rssKb: number; cmd: string }> | null> {
-    const proc = Bun.spawn(["ps", "-eo", "pid,ppid,rss,command"], {
-      stdout: "pipe",
-      stderr: "ignore",
-      stdin: "ignore",
-    });
+    let proc: Bun.Subprocess<"ignore", "pipe", "ignore">;
+    try {
+      proc = Bun.spawn(["ps", "-eo", "pid,ppid,rss,command"], {
+        stdout: "pipe",
+        stderr: "ignore",
+        stdin: "ignore",
+      });
+    } catch (error) {
+      // No `ps` at all — a slim container image such as `oven/bun` ships without procps. Same answer as
+      // a timeout, and for the same reason: this is "could not look", not "nothing is running".
+      console.warn(`[harness] could not run ps: ${error instanceof Error ? error.message : String(error)}`);
+      return null;
+    }
     const output = await Promise.race([
       new Response(proc.stdout).text().catch(() => ""),
       wait(DevStabilityHarness.#psTimeoutMs).then(() => null),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "2.4.1-rc.6",
+  "version": "2.4.1",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -44,7 +44,7 @@
     "@langchain/openai": "^1.4.6",
     "@tailwindcss/node": "^4.3.0",
     "@trapezedev/project": "^7.1.4",
-    "akanjs": "2.4.1-rc.6",
+    "akanjs": "2.4.1",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "daisyui": "5.5.23",

package/transforms/barrelImportsPlugin.ts

@@ -64,18 +64,10 @@ export const createBarrelImportsPlugin = async (
           const hasMacroAttr = MACRO_ATTR_RE.test(source);
 
           if (!hasMacroAttr && barrels.length > 0) {
-            // Fast pre-check to avoid tokenizing every file in the workspace.
-            let maybe = false;
-            for (const b of barrels) {
-              if (source.includes(b)) {
-                maybe = true;
-                break;
-              }
-            }
-            if (maybe) {
-              const rewritten = await rewriteBarrelImports(source, barrels, analyzer);
-              if (rewritten !== null) source = rewritten;
-            }
+            // The pre-check that used to live here — "does this file mention a barrel at all" — now
+            // lives inside `rewriteBarrelImports`, so every caller gets it rather than just this one.
+            const rewritten = await rewriteBarrelImports(source, barrels, analyzer);
+            if (rewritten !== null) source = rewritten;
           }
 
           if (pipeAfter) {
@@ -309,6 +301,12 @@ export const rewriteBarrelImports = async (
   barrels: string[],
   analyzer: BarrelAnalyzer,
 ): Promise<string | null> => {
+  // Establish there is something to rewrite before the TypeScript parser is involved. This runs on
+  // every source file of every dev rebuild, and parsing was by far the most expensive thing in one:
+  // measured across 1189 files here, 299ms and 161MB of RSS, of which **63% of files import no barrel
+  // at all**. A static import cannot name a specifier without that specifier appearing literally in the
+  // text, so a substring test is a sound filter and costs 4ms for the whole corpus.
+  if (!barrels.some((barrel) => source.includes(barrel))) return null;
   const statements = findImportStatements(source);
   if (statements.length === 0) return null;
 
@@ -340,7 +338,16 @@ interface ImportStatement {
 
 const findImportStatements = (source: string): ImportStatement[] => {
   const statements: ImportStatement[] = [];
-  const sourceFile = ts.createSourceFile("barrel-imports.tsx", source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+  // `setParentNodes: false`: nothing below reads `node.parent`, and every position comes from
+  // `getStart(sourceFile)`, which takes the file explicitly. Building the parent links cost 132ms and
+  // 143MB of RSS across 1189 files for no reader.
+  const sourceFile = ts.createSourceFile(
+    "barrel-imports.tsx",
+    source,
+    ts.ScriptTarget.Latest,
+    false,
+    ts.ScriptKind.TSX,
+  );
   for (const statement of sourceFile.statements) {
     if (!ts.isImportDeclaration(statement)) continue;
     if (!ts.isStringLiteral(statement.moduleSpecifier)) continue;