@akanjs/devkit 3.0.0-alpha.9 → 3.0.0-alpha.91

package/akanApp/akanApp.host.ts

@@ -1,15 +1,5 @@
-import { stat } from "node:fs/promises";
-import path from "node:path";
 import { Logger } from "akanjs/common";
-import type {
-  BuilderMessage,
-  BuilderMetrics,
-  BuildPhase,
-  ChangeBatch,
-  DevBuildStatus,
-  DevChangePlan,
-  DevChangeRole,
-} from "akanjs/server";
+import type { BuilderMessage, BuilderMetrics, BuildPhase, ChangeBatch, DevBuildStatus } from "akanjs/server";
 import type { App } from "../commandDecorators";
 import { createTunnel } from "../createTunnel";
 import { WorkspaceExecutor } from "../executors";
@@ -17,31 +7,67 @@ import { WorkspaceExecutor } from "../executors";
 // tailwind stack, which is exactly what a suspended dev host must not be holding.
 import { HmrWatcher } from "../frontendBuild/hmrWatcher";
 import { WatchRootResolver } from "../frontendBuild/watchRootResolver";
-import { IncrementalBuilderHost, type IncrementalBuilderStatus } from "../incrementalBuilder";
+import { type DevStdioMode, IncrementalBuilderHost } from "../incrementalBuilder";
 import { BuilderRequestRouter } from "../incrementalBuilder/builderRequestRouter";
+import { BackendImportGraph } from "./BackendImportGraph";
+import {
+  type BackendLifecycleState,
+  type BackendRestartReason,
+  BUILDER_MIN_RSS_RECYCLE_INTERVAL_MS,
+  backendRestartReasonFromMessage,
+  buildStatusReplaySequence,
+  createBackendBuildStatus,
+  type DevHostEvent,
+  type DevHostState,
+  decideBuilderRssRecycle,
+  decideBuilderRssSettle,
+  decideIdleSuspend,
+  devHostStateOf,
+  filesChangedSince,
+  hasAnyBuildFailure,
+  hasBuildFailureForGeneration,
+  isLegacyBackendFallbackFile,
+  isRssCeilingUnreachable,
+  mergeBackendRestartReasons,
+  mergeInvalidateMessages,
+  normalizeBackendReportedGeneration,
+  resolveIdleSuspendMs,
+  type SourceFingerprints,
+  shouldAbandonBackendRecovery,
+  shouldHoldForReturningBuilder,
+  shouldMarkBuildPhaseRecovered,
+  shouldQueueBuildStatusReplay,
+  shouldRefreshConfigOnIdleWake,
+  shouldRelayRecycledFrontendState,
+  shouldReplaceLastGoodMessage,
+  shouldRestartBackendByDevPlan,
+  shouldRestartBuilderByDevPlan,
+  shouldRestartDevHostByDevPlan,
+  shouldWarnBuilderRssCeilingTight,
+} from "./devHostPolicy";
 
 const backendMsgTypeSet = new Set<BuilderMessage["type"]>(["build-route", "build-csr"]);
+
 const BACKEND_RESTART_DEBOUNCE_MS = 120;
+
 // Must exceed the gateway's child-wait budget (AkanApp child shutdown, ~5s in dev) so the gateway
 // is never SIGKILLed while its replicas are still shutting down — that's what strands orphans.
 const BACKEND_GRACEFUL_TIMEOUT_MS = 8_000;
+
 const BACKEND_RECOVERY_BASE_DELAY_MS = 1_000;
+
 const BACKEND_RECOVERY_MAX_DELAY_MS = 30_000;
-const BACKEND_RECOVERY_MAX_ATTEMPTS = 5;
+
 const BACKEND_STDERR_TAIL_LIMIT = 40;
+
 const BUILDER_READY_TIMEOUT_MS = 150000;
+
 const BUILDER_START_MAX_ATTEMPTS = 3;
-/**
- * How many requests may wait for a builder that is coming back. Generous — a page load asks for
- * several routes — but finite, so a builder that never returns cannot grow this without bound. Past
- * it, requests are failed as they were before, which is the behaviour this limit falls back to.
- */
-const HELD_BUILDER_REQUEST_LIMIT = 64;
+
 // Save-on-keystroke arrives as a burst of batches. Recycling mid-burst would drop the watcher events
 // still on their way to the builder, so an over-ceiling builder is replaced only once it goes quiet.
 const BUILDER_RSS_RECYCLE_QUIET_MS = 750;
-const BUILDER_MIN_RSS_RECYCLE_INTERVAL_MS = 30_000;
-const BUILDER_TIGHT_RSS_REPORT_LIMIT = 2;
+
 // Linux hands the bundler arenas back on its own after ~10-15s idle — measured at 46-59% of the
 // builder's peak (`local/optimize-resource/09-linux-retention-measurement.md`) — while macOS returns
 // none of it. The builder only reports RSS at work-completion points, so the sample a recycle is armed
@@ -49,564 +75,28 @@ const BUILDER_TIGHT_RSS_REPORT_LIMIT = 2;
 // paying a cold boot build for memory the OS was about to return anyway. On macOS the re-read returns
 // the same value, so this only ever costs the delay.
 const BUILDER_RSS_SETTLE_MS = 20_000;
+
 /** Reading one process's rss is a millisecond of work; anything near this is a `ps` that is stuck. */
 const PS_RSS_TIMEOUT_MS = 2_000;
-// Far enough above the ceiling that no purge would rescue it; recycle without waiting.
-const BUILDER_RSS_HARD_MULTIPLE = 1.5;
-// A sandbox between user turns pays for a watcher that is watching nothing change. Suspending build
-// capacity after this long returns the builder's residency until the next edit or route request.
-const DEV_IDLE_SUSPEND_MS = 300_000;
-// A wake that immediately suspends again would flap around whatever woke it.
-const DEV_IDLE_MIN_UPTIME_MS = 30_000;
+
 // The builder is the file watcher: while it is down no edit can trigger a retry, so unlike the
 // backend the recovery loop never gives up — it only backs off.
 const BUILDER_RECOVERY_BASE_DELAY_MS = 2_000;
-const BUILDER_RECOVERY_MAX_DELAY_MS = 60_000;
-const SOURCE_EXTS = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"]);
-const NON_SOURCE_EXT_RE =
-  /\.(css|scss|sass|less|json|svg|png|jpe?g|webp|gif|avif|ico|woff2?|ttf|otf|mp3|mp4|wav|html)$/i;
-const SERVER_SUFFIXES = [".service.ts", ".document.ts"];
-const SHARED_SUFFIXES = [".constant.ts", ".dictionary.ts", ".signal.ts"];
-const RUNTIME_METADATA_BASENAMES = new Set(["dict.ts", "sig.ts", "useClient.ts", "useServer.ts"]);
-const GRAPH_IMPORT_KINDS = new Set<Bun.ImportKind>([
-  "import-statement",
-  "require-call",
-  "require-resolve",
-  "dynamic-import",
-]);
-
-export const shouldRestartBackendByDevPlan = (
-  message: Extract<BuilderMessage, { type: "invalidate" }>,
-): boolean | null => {
-  if (!message.devPlan) return null;
-  if (message.devPlan.actions.includes("report-error")) return false;
-  if (message.devPlan.actions.includes("restart-builder")) return false;
-  return message.devPlan.actions.includes("restart-backend");
-};
-
-export const shouldRestartBuilderByDevPlan = (message: Extract<BuilderMessage, { type: "invalidate" }>): boolean =>
-  message.devPlan?.actions.includes("restart-builder") ?? false;
-
-/**
- * A backend that keeps dying isn't going to heal by retrying the same code; after this many
- * consecutive attempts the host idles and the next server-side edit triggers a fresh restart.
- */
-export const shouldAbandonBackendRecovery = (attempts: number, maxAttempts = BACKEND_RECOVERY_MAX_ATTEMPTS): boolean =>
-  attempts >= maxAttempts;
 
-/** The gateway reports backend failures with `generation: -1`; the host assigns its own counter then. */
-export const normalizeBackendReportedGeneration = (generation: number): number | undefined =>
-  generation >= 0 ? generation : undefined;
-
-export const shouldRestartDevHostByDevPlan = (message: Extract<BuilderMessage, { type: "invalidate" }>): boolean =>
-  message.devPlan?.actions.includes("restart-dev-host") ?? message.kinds.includes("config");
-
-export type BackendLifecycleState = "starting" | "ready" | "restart-pending" | "stopping" | "recovering" | "stopped";
-
-export interface BackendRestartReason {
-  generation?: number;
-  files: string[];
-  roles: Extract<DevChangeRole, "server" | "shared" | "barrel" | "config">[];
-}
+const BUILDER_RECOVERY_MAX_DELAY_MS = 60_000;
 
 interface LastGoodFrontendState {
   pages?: Extract<BuilderMessage, { type: "pages-updated" }>;
   css?: Extract<BuilderMessage, { type: "css-updated" }>;
 }
 
-const RESTART_ROLE_ORDER: BackendRestartReason["roles"] = ["server", "shared", "barrel", "config"];
-
-const generationValue = (generation: number | undefined): number => generation ?? -1;
-
-export const isLegacyBackendFallbackFile = (file: string, workspaceRoot: string): boolean => {
-  const abs = path.resolve(file);
-  const ext = path.extname(abs).toLowerCase();
-  if (!SOURCE_EXTS.has(ext)) return false;
-  const rel = path.relative(path.resolve(workspaceRoot), abs);
-  if (!rel || rel.startsWith("..") || path.isAbsolute(rel)) return false;
-  const parts = rel.split(path.sep).filter(Boolean);
-  const [scope] = parts;
-  if (scope !== "apps" && scope !== "libs" && scope !== "pkgs") return false;
-
-  const base = path.basename(abs);
-  return (
-    parts.includes("srvkit") ||
-    parts.includes("common") ||
-    SERVER_SUFFIXES.some((suffix) => base.endsWith(suffix)) ||
-    SHARED_SUFFIXES.some((suffix) => base.endsWith(suffix)) ||
-    RUNTIME_METADATA_BASENAMES.has(base) ||
-    base === "main.ts" ||
-    base === "server.ts"
-  );
-};
-
-export const shouldMarkBuildPhaseRecovered = (
-  previousByPhase: ReadonlyMap<BuildPhase, DevBuildStatus>,
-  status: DevBuildStatus,
-): boolean => {
-  const previous = previousByPhase.get(status.phase);
-  return Boolean(previous && status.ok && !previous.ok && generationValue(status.generation) >= previous.generation);
-};
-
-export const createBackendBuildStatus = ({
-  generation,
-  ok,
-  files = [],
-  message,
-}: {
-  generation: number;
-  ok: boolean;
-  files?: string[];
-  message?: string;
-}): DevBuildStatus => ({
-  generation,
-  phase: "backend",
-  ok,
-  files,
-  message,
-});
-
-export const backendRestartReasonFromMessage = (
-  message: Extract<BuilderMessage, { type: "invalidate" }>,
-): BackendRestartReason => {
-  const roleSet = new Set<BackendRestartReason["roles"][number]>();
-  for (const role of message.devPlan?.roles ?? []) {
-    if (role === "server" || role === "shared" || role === "barrel" || role === "config") roleSet.add(role);
-  }
-  return {
-    generation: message.devPlan?.generation ?? message.generation,
-    files: [...new Set(message.files)].sort(),
-    roles: RESTART_ROLE_ORDER.filter((role) => roleSet.has(role)),
-  };
-};
-
-export const mergeBackendRestartReasons = (
-  current: BackendRestartReason | null,
-  next: BackendRestartReason,
-): BackendRestartReason => ({
-  generation:
-    generationValue(next.generation) >= generationValue(current?.generation) ? next.generation : current?.generation,
-  files: [...new Set([...(current?.files ?? []), ...next.files])].sort(),
-  roles: RESTART_ROLE_ORDER.filter((role) => current?.roles.includes(role) || next.roles.includes(role)),
-});
-
-export const shouldReplaceLastGoodMessage = (
-  current:
-    | Extract<BuilderMessage, { type: "pages-updated" }>
-    | Extract<BuilderMessage, { type: "css-updated" }>
-    | undefined,
-  next: Extract<BuilderMessage, { type: "pages-updated" }> | Extract<BuilderMessage, { type: "css-updated" }>,
-): boolean => !current || generationValue(next.data.generation) >= generationValue(current.data.generation);
-
-export const shouldQueueBuildStatusReplay = (backendReady: boolean, pendingReplayCount: number): boolean =>
-  !backendReady || pendingReplayCount > 0;
-
-/**
- * Recycling the builder/backend on a generation whose build already failed is guaranteed to strand
- * the dev server: the rebooted builder hits the same compile error and exits before builder-ready.
- * Failing phase statuses for a generation arrive over IPC before that generation's invalidate, so
- * the host can check them here and defer the recycle until a healthy batch lands.
- */
-export const hasBuildFailureForGeneration = (
-  statusByPhase: ReadonlyMap<BuildPhase, DevBuildStatus>,
-  generation: number | undefined,
-): boolean => {
-  if (typeof generation !== "number") return false;
-  for (const status of statusByPhase.values()) {
-    if (!status.ok && status.generation === generation) return true;
-  }
-  return false;
-};
-
-export type BuilderRssRecycleDecision = "unbounded" | "below-ceiling" | "build-failed" | "too-soon" | "recycle";
-
-/**
- * Whether an over-ceiling builder should be replaced now.
- *
- * `Bun.build` never returns its native arenas, so the builder's RSS only comes back when the process
- * exits. Recycling it is therefore the only bound available — but it costs a boot build, so the two
- * cases where a recycle cannot help are excluded: a generation whose build already failed (the
- * replacement would hit the same compile error), and a recycle so soon after the last one that the
- * ceiling is evidently unreachable for this app.
- */
-export const decideBuilderRssRecycle = ({
-  rssBytes,
-  ceilingBytes,
-  buildFailed,
-  msSinceLastRecycle,
-  minIntervalMs = BUILDER_MIN_RSS_RECYCLE_INTERVAL_MS,
-}: {
-  rssBytes: number;
-  ceilingBytes: number | null;
-  buildFailed: boolean;
-  msSinceLastRecycle: number | null;
-  minIntervalMs?: number;
-}): BuilderRssRecycleDecision => {
-  if (!ceilingBytes) return "unbounded";
-  if (rssBytes < ceilingBytes) return "below-ceiling";
-  if (buildFailed) return "build-failed";
-  if (msSinceLastRecycle !== null && msSinceLastRecycle < minIntervalMs) return "too-soon";
-  return "recycle";
-};
-
-export type BuilderRssSettleDecision = "recycle-now" | "wait-and-recheck";
-
-/**
- * Whether an armed recycle should wait out the allocator's purge window before committing. A builder
- * far enough over the ceiling is not going to be rescued by a purge, so waiting there only delays a
- * recycle that has to happen.
- */
-export const decideBuilderRssSettle = ({
-  rssBytes,
-  ceilingBytes,
-  hardMultiple = BUILDER_RSS_HARD_MULTIPLE,
-}: {
-  rssBytes: number;
-  ceilingBytes: number;
-  hardMultiple?: number;
-}): BuilderRssSettleDecision => (rssBytes >= ceilingBytes * hardMultiple ? "recycle-now" : "wait-and-recheck");
-
-export type IdleSuspendDecision =
-  | "disabled"
-  | "already-suspended"
-  | "builder-not-ready"
-  | "backend-not-ready"
-  | "build-failed"
-  | "restart-pending"
-  | "too-soon"
-  | "suspend";
-
-/**
- * Whether the dev host may drop its build capacity now. Every "no" here is a case where suspending
- * would either lose work or produce a wake that immediately re-suspends:
- *
- * - a red build means the developer is mid-fix and about to save again, and a wake would boot straight
- *   back into the same error via the degraded-boot path
- * - a pending restart/recovery already has its own plan for the builder
- * - `too-soon` keeps a wake from flapping around whatever triggered it
- */
-export const decideIdleSuspend = ({
-  enabled,
-  suspended,
-  builderReady,
-  backendReady,
-  buildFailed,
-  restartPending,
-  msSinceWake,
-  minUptimeMs = DEV_IDLE_MIN_UPTIME_MS,
-}: {
-  enabled: boolean;
-  suspended: boolean;
-  builderReady: boolean;
-  backendReady: boolean;
-  buildFailed: boolean;
-  restartPending: boolean;
-  msSinceWake: number | null;
-  minUptimeMs?: number;
-}): IdleSuspendDecision => {
-  if (!enabled) return "disabled";
-  if (suspended) return "already-suspended";
-  if (!builderReady) return "builder-not-ready";
-  if (!backendReady) return "backend-not-ready";
-  if (buildFailed) return "build-failed";
-  if (restartPending) return "restart-pending";
-  if (msSinceWake !== null && msSinceWake < minUptimeMs) return "too-soon";
-  return "suspend";
-};
-
-/** `undefined` env means the default is on; any non-positive value turns idle suspend off. */
-export const resolveIdleSuspendMs = (raw: string | undefined): number | null => {
-  if (raw === undefined || raw === "") return DEV_IDLE_SUSPEND_MS;
-  const parsed = Number(raw);
-  if (!Number.isFinite(parsed) || parsed <= 0) return null;
-  return Math.round(parsed);
-};
-
-/** Any red phase blocks a suspend, unlike the rss recycle which only cares about one generation. */
-export const hasAnyBuildFailure = (statusByPhase: ReadonlyMap<BuildPhase, DevBuildStatus>): boolean =>
-  [...statusByPhase.values()].some((status) => !status.ok);
-
-/**
- * A config change while suspended cannot be applied by restarting the builder alone — the dev host
- * itself has to re-read the config, which is the same path an ordinary config save takes.
- */
-export const shouldRefreshConfigOnIdleWake = (batch: ChangeBatch | null): boolean =>
-  !!batch && batch.kinds.has("config");
-
-/**
- * Whether a request that arrived while the builder was away should wait for the one coming back.
- *
- * A recycle or a crash-restart is a gap, not a failure — the request that lands in it is the page a
- * developer is waiting on. A stopped builder is a different thing: nothing is bringing it back, so
- * waiting would only delay the error.
- *
- * `recycling` is in here for the same reason as `restarting`, and was the hole this decision shipped
- * with: a draining builder is still alive, so the request reached it and came back refused while the
- * host still thought there was nothing to wait for.
- */
-const RETURNING_BUILDER_STATUSES = new Set<IncrementalBuilderStatus>(["starting", "recycling", "restarting"]);
-export const shouldHoldForReturningBuilder = ({
-  status,
-  heldCount,
-  limit = HELD_BUILDER_REQUEST_LIMIT,
-}: {
-  status: IncrementalBuilderStatus;
-  heldCount: number;
-  limit?: number;
-}): boolean => RETURNING_BUILDER_STATUSES.has(status) && heldCount < limit;
-
-/**
- * Whether a builder that is over the ceiling again this soon after being replaced is worth saying so
- * about, once. Not a reason to stop enforcing the ceiling: the minimum interval already bounds what
- * this costs at one recycle per interval, and dropping the bound is how a container gets OOM-killed.
- *
- * This used to disable the ceiling for the session, on a count that a single page load reaches — two
- * route builds, two reports, both inside the interval. That is normal work on any app whose builds sit
- * above the ceiling, which is the same app the ceiling was derived for.
- */
-export const shouldWarnBuilderRssCeilingTight = (
-  reportsSinceRecycle: number,
-  limit = BUILDER_TIGHT_RSS_REPORT_LIMIT,
-): boolean => reportsSinceRecycle >= limit;
-
-/**
- * Whether recycling can ever bring this builder under the ceiling.
- *
- * Measured on a replacement the moment it is ready, before it has built anything on demand: that is
- * the floor every future replacement lands on, so a floor already over the ceiling is the one case
- * where the recycle loop is pure cost. It is also the case the escape hatch was always described as
- * being for — the previous rule inferred it from report timing and caught ordinary work instead.
- */
-export const isRssCeilingUnreachable = (freshRssBytes: number | null, ceilingBytes: number | null): boolean =>
-  freshRssBytes !== null && ceilingBytes !== null && freshRssBytes >= ceilingBytes;
-
-/**
- * Whether a recycled builder's re-announced boot artifact actually differs from what the backend
- * already has. Both payload identities are content hashes — `pages-[hash].js` and
- * `<name>-[hash].css` — so an unchanged recycle produces identical ones and needs no reload. Only a
- * save that raced the recycle moves them, and that is the case worth pushing.
- */
-export const shouldRelayRecycledFrontendState = (
-  current:
-    | Extract<BuilderMessage, { type: "pages-updated" }>
-    | Extract<BuilderMessage, { type: "css-updated" }>
-    | undefined,
-  next: Extract<BuilderMessage, { type: "pages-updated" }> | Extract<BuilderMessage, { type: "css-updated" }>,
-): boolean => {
-  if (!current || current.type !== next.type) return true;
-  if (current.type === "pages-updated" && next.type === "pages-updated")
-    return current.data.bundlePath !== next.data.bundlePath;
-  if (current.type === "css-updated" && next.type === "css-updated")
-    return JSON.stringify(current.data.cssAssets) !== JSON.stringify(next.data.cssAssets);
-  return true;
-};
-
-const mergeDevPlans = (current?: DevChangePlan, next?: DevChangePlan): DevChangePlan | undefined => {
-  if (!current) return next;
-  if (!next) return current;
-  const reasonByFile: Record<string, string[]> = { ...current.reasonByFile };
-  for (const [file, reasons] of Object.entries(next.reasonByFile)) {
-    reasonByFile[file] = [...new Set([...(reasonByFile[file] ?? []), ...reasons])].sort();
-  }
-  return {
-    generation: Math.max(current.generation, next.generation),
-    files: [...new Set([...current.files, ...next.files])].sort(),
-    generatedFiles: [...new Set([...current.generatedFiles, ...next.generatedFiles])].sort(),
-    roles: [...new Set([...current.roles, ...next.roles])].sort(),
-    actions: [...new Set([...current.actions, ...next.actions])].sort(),
-    reasonByFile,
-  };
-};
-
-/** A deferred recycle accumulates every batch it skipped so the eventual restart covers them all. */
-export const mergeInvalidateMessages = (
-  current: Extract<BuilderMessage, { type: "invalidate" }>,
-  next: Extract<BuilderMessage, { type: "invalidate" }>,
-): Extract<BuilderMessage, { type: "invalidate" }> => {
-  const generation = Math.max(generationValue(current.generation), generationValue(next.generation));
-  return {
-    type: "invalidate",
-    kinds: [...new Set([...current.kinds, ...next.kinds])].sort(),
-    files: [...new Set([...current.files, ...next.files])].sort(),
-    generation: generation >= 0 ? generation : undefined,
-    devPlan: mergeDevPlans(current.devPlan, next.devPlan),
-  };
-};
-
-export const buildStatusReplaySequence = (
-  pendingReplay: readonly DevBuildStatus[],
-  latestByPhase: ReadonlyMap<BuildPhase, DevBuildStatus>,
-): DevBuildStatus[] => [...pendingReplay, ...latestByPhase.values()];
-
-/** `(mtimeMs, size)` per file — what a save moves, and what a rebuild of identical content does not. */
-export type SourceFingerprints = ReadonlyMap<string, string>;
-
-/**
- * Which of the files in `before` are no longer stamped the way they were.
- *
- * Only files present in `before` are compared. The question this answers is which *running* code went
- * stale while nothing was watching, and a file that did not exist then is not running anywhere.
- */
-export const filesChangedSince = (before: SourceFingerprints, after: SourceFingerprints): string[] =>
-  [...before].filter(([file, stamp]) => after.get(file) !== stamp).map(([file]) => file);
-
-export class BackendImportGraph {
-  readonly #app: App;
-  readonly #logger: Logger;
-  readonly #tsTranspiler = new Bun.Transpiler({ loader: "ts" });
-  readonly #tsxTranspiler = new Bun.Transpiler({ loader: "tsx" });
-  readonly #jsTranspiler = new Bun.Transpiler({ loader: "js" });
-  readonly #jsxTranspiler = new Bun.Transpiler({ loader: "jsx" });
-  #files = new Set<string>();
-  /**
-   * `refresh()` runs on every server-side save and on every dev-host recycle, and re-reading plus
-   * re-parsing files that did not change is the whole cost of it. Keyed on (mtimeMs, size).
-   *
-   * Specifiers are cached, not resolved paths: creating a file can change what an *unchanged* importer's
-   * specifier resolves to, and `Bun.resolveSync` is cheap next to a read plus a transpiler scan. Only
-   * the scan result is retained — never the source text.
-   */
-  #scanCache = new Map<string, { mtimeMs: number; size: number; specifiers: Bun.Import[] }>();
-  #ready = false;
-  #lastRefreshSucceeded = false;
-
-  constructor(app: App, logger: Logger) {
-    this.#app = app;
-    this.#logger = logger;
-  }
-
-  get ready() {
-    return this.#ready;
-  }
-
-  get lastRefreshSucceeded() {
-    return this.#lastRefreshSucceeded;
-  }
-
-  has(file: string) {
-    return this.#files.has(path.resolve(file));
-  }
-
-  /**
-   * Stamp every file the backend runs, so a caller can ask later what moved.
-   *
-   * Taken when the builder goes away and compared when its replacement is up, because nothing watches
-   * the tree in between: the departing builder's watcher left with it, and the replacement's index
-   * primes from the disk it finds, so an edit that lands in the gap is *baseline* to it and is never
-   * reported at all. The client half of such an edit is rescued by the replacement's boot build; the
-   * backend half is a server left running code that no longer exists, with nothing on screen to say so.
-   *
-   * One `stat` per graph file, against a gap that costs a whole boot build anyway.
-   */
-  async fingerprint(): Promise<SourceFingerprints> {
-    const stamps = await Promise.all(
-      [...this.#files].map(async (file) => {
-        const stats = await stat(file).catch(() => null);
-        return [file, stats ? `${Math.round(stats.mtimeMs)}:${stats.size}` : "(gone)"] as const;
-      }),
-    );
-    return new Map(stamps);
-  }
-
-  async refresh(): Promise<boolean> {
-    try {
-      const files = await this.#build();
-      this.#files = files;
-      this.#ready = true;
-      this.#lastRefreshSucceeded = true;
-      this.#logger.verbose(`[backend-graph] scanned ${files.size} files`);
-      return true;
-    } catch (err) {
-      this.#ready = this.#files.size > 0;
-      this.#lastRefreshSucceeded = false;
-      this.#logger.warn(
-        `[backend-graph] scan failed; ${this.#ready ? "using previous graph" : "using fallback rules"}: ${err instanceof Error ? err.message : String(err)}`,
-      );
-      return this.#ready;
-    }
-  }
-
-  async #build(): Promise<Set<string>> {
-    const roots = await this.#entrypoints();
-    const files = new Set<string>();
-    const queue = [...roots];
-    const workspaceRoot = path.resolve(this.#app.workspace.workspaceRoot);
-
-    while (queue.length > 0) {
-      const current = path.resolve(queue.pop() as string);
-      if (files.has(current)) continue;
-      if (!this.#isWorkspaceSource(current, workspaceRoot)) continue;
-      const imports = await this.#importsOf(current);
-      if (!imports) continue;
-
-      files.add(current);
-      const importerDir = path.dirname(current);
-      for (const imp of imports) {
-        if (!GRAPH_IMPORT_KINDS.has(imp.kind) || !imp.path || NON_SOURCE_EXT_RE.test(imp.path)) continue;
-        const resolved = this.#resolve(imp.path, importerDir);
-        if (!resolved || files.has(resolved)) continue;
-        queue.push(resolved);
-      }
-    }
-    // Files that dropped out of the graph would otherwise be cached for the life of the dev session.
-    for (const cached of this.#scanCache.keys()) if (!files.has(cached)) this.#scanCache.delete(cached);
-    return files;
-  }
-
-  /** Null when the file is gone, which is the existence check the walk used to make separately. */
-  async #importsOf(file: string): Promise<Bun.Import[] | null> {
-    const stats = await stat(file).catch(() => null);
-    if (!stats?.isFile()) return null;
-    const mtimeMs = Math.round(stats.mtimeMs);
-    const cached = this.#scanCache.get(file);
-    if (cached && cached.mtimeMs === mtimeMs && cached.size === stats.size) return cached.specifiers;
-    const specifiers = this.#scanImports(file, await Bun.file(file).text());
-    this.#scanCache.set(file, { mtimeMs, size: stats.size, specifiers });
-    return specifiers;
-  }
-
-  async #entrypoints(): Promise<string[]> {
-    const roots = [`${this.#app.cwdPath}/main.ts`, `${this.#app.cwdPath}/server.ts`];
-    const existing: string[] = [];
-    for (const root of roots) {
-      const abs = path.resolve(root);
-      if (await Bun.file(abs).exists()) existing.push(abs);
-    }
-    return existing;
-  }
-
-  #resolve(specifier: string, importerDir: string): string | null {
-    try {
-      const resolved = Bun.resolveSync(specifier, importerDir);
-      if (!path.isAbsolute(resolved)) return null;
-      if (!SOURCE_EXTS.has(path.extname(resolved).toLowerCase())) return null;
-      return path.resolve(resolved);
-    } catch {
-      return null;
-    }
-  }
-
-  #isWorkspaceSource(file: string, workspaceRoot: string): boolean {
-    const rel = path.relative(workspaceRoot, file);
-    if (rel.startsWith("..") || path.isAbsolute(rel)) return false;
-    if (rel.includes(`${path.sep}node_modules${path.sep}`) || rel.includes(`${path.sep}.akan${path.sep}`)) return false;
-    return SOURCE_EXTS.has(path.extname(file).toLowerCase());
-  }
-
-  #scanImports(file: string, source: string): Bun.Import[] {
-    const ext = path.extname(file).toLowerCase();
-    if (ext === ".tsx") return this.#tsxTranspiler.scanImports(source);
-    if (ext === ".jsx") return this.#jsxTranspiler.scanImports(source);
-    if (ext === ".js" || ext === ".mjs" || ext === ".cjs") return this.#jsTranspiler.scanImports(source);
-    return this.#tsTranspiler.scanImports(source);
-  }
-}
-
 export class AkanAppHost {
   logger = new Logger("AkanAppHost");
-  readonly withInk: boolean;
+  readonly stdio: DevStdioMode;
   readonly env: Record<string, string>;
-  #backend: Bun.Subprocess<"ignore", "inherit", "inherit"> | null = null;
+  readonly #onDevEvent: ((event: DevHostEvent) => void) | null;
+  #lastDevState: DevHostState | null = null;
+  #backend: Bun.Subprocess<"ignore", "inherit" | "pipe", "inherit" | "pipe"> | null = null;
   #builder: IncrementalBuilderHost | null = null;
   #backendReady = false;
   #plannedBackendStops = new WeakSet<Bun.Subprocess<"ignore", "inherit", "inherit">>();
@@ -649,12 +139,22 @@ export class AkanAppHost {
   readonly #builderRequests = new BuilderRequestRouter();
   constructor(
     private readonly app: App,
-    { env, withInk = false }: { env: Record<string, string>; withInk?: boolean },
+    {
+      env,
+      stdio = "inherit",
+      onDevEvent,
+    }: { env: Record<string, string>; stdio?: DevStdioMode; onDevEvent?: (event: DevHostEvent) => void },
   ) {
     this.env = env;
-    this.withInk = withInk;
+    this.stdio = stdio;
+    this.#onDevEvent = onDevEvent ?? null;
     this.#backendGraph = new BackendImportGraph(app, this.logger);
   }
+  #emitDevEvent(state: DevHostState, detail?: string) {
+    if (!this.#onDevEvent || state === this.#lastDevState) return;
+    this.#lastDevState = state;
+    this.#onDevEvent({ app: this.app.name, state, ...(detail ? { detail } : {}) });
+  }
   async start() {
     if (this.#backend) await this.#stopBackend();
     if (this.#builder) this.#stopBuilder();
@@ -702,6 +202,7 @@ export class AkanAppHost {
     // Before the spawn: from here on, a builder answer for the departing backend must not be delivered to
     // this one, which numbers its requests from 1 all over again.
     this.#builderRequests.startGeneration();
+    this.#discardPendingBuilderMessages("the backend restarted while the builder was away");
     this.#backendStartStatus = startStatus;
     this.#backendGaveUp = false;
     this.#setBackendLifecycleState("starting");
@@ -709,7 +210,7 @@ export class AkanAppHost {
     this.#backendStderrTail = [];
     const backend = Bun.spawn(["bun", `apps/${this.app.name}/main.ts`], {
       cwd: this.app.workspace.workspaceRoot,
-      stdio: this.withInk ? ["ignore", "pipe", "pipe"] : ["inherit", "inherit", "inherit"],
+      stdio: this.stdio === "pipe" ? ["ignore", "pipe", "pipe"] : ["inherit", "inherit", "inherit"],
       env: this.env,
       ipc: (msg: BuilderMessage) => {
         if (!msg || typeof msg !== "object") return;
@@ -749,9 +250,9 @@ export class AkanAppHost {
     });
     this.#backend = backend;
     this.logger.verbose(`backend spawned pid=${backend.pid}`);
-    if (this.withInk) {
-      // Ink mode pipes backend stdio to keep the TUI clean; drain the pipes and surface
-      // them through the logger so runtime errors are not silently swallowed.
+    if (this.stdio === "pipe") {
+      // A piped backend writes to nobody unless the pipes are drained; surface them through the logger
+      // so a runtime error is not silently swallowed, and so the tail kept for a boot failure still fills.
       void this.#forwardBackendStream(backend.stderr as unknown as ReadableStream<Uint8Array> | undefined, "stderr");
       void this.#forwardBackendStream(backend.stdout as unknown as ReadableStream<Uint8Array> | undefined, "stdout");
     }
@@ -764,19 +265,23 @@ export class AkanAppHost {
       this.#backendStderrTail.splice(0, this.#backendStderrTail.length - BACKEND_STDERR_TAIL_LIMIT);
     }
   }
+  /**
+   * A piped child is written through verbatim rather than re-logged: a level floor here would swallow
+   * what the runtime printed, and re-rendering would double the timestamp the child already wrote. So
+   * `"pipe"` looks exactly like `"inherit"` to whoever owns this process's stdout — the only difference
+   * is `#backendStderrTail`, which is what the crash-loop diagnostic reads.
+   */
   async #forwardBackendStream(stream: ReadableStream<Uint8Array> | undefined | null, kind: "stdout" | "stderr") {
     if (!stream) return;
     const decoder = new TextDecoder();
     try {
       for await (const chunk of stream) {
         const text = decoder.decode(chunk, { stream: true });
-        if (!text.trim()) continue;
+        if (!text) continue;
         if (kind === "stderr") {
           this.#recordBackendStderr(text);
-          this.logger.warn(`[backend] ${text.trimEnd()}`);
-        } else {
-          this.logger.verbose(`[backend] ${text.trimEnd()}`);
-        }
+          process.stderr.write(text);
+        } else process.stdout.write(text);
       }
     } catch {
       // The stream closes when the backend exits; nothing further to surface here.
@@ -829,6 +334,7 @@ export class AkanAppHost {
     const prev = this.#backendLifecycleState;
     this.#backendLifecycleState = next;
     this.logger.verbose(`[backend-lifecycle] ${prev} -> ${next}${detail ? ` ${detail}` : ""}`);
+    this.#emitDevEvent(devHostStateOf(next, this.#backendGaveUp), detail);
   }
   #sendToBackend(message: BuilderMessage) {
     if (!this.#backend || !this.#backendReady) {
@@ -1209,6 +715,7 @@ export class AkanAppHost {
       return;
     }
     this.#suspended = true;
+    this.#emitDevEvent("suspended", `idle ${Math.round(idleMs / 1000)}s`);
     this.#stopBuilder();
     this.#openBuilderGap("idle suspend");
     this.logger.info(
@@ -1293,6 +800,9 @@ export class AkanAppHost {
       this.#wokeAtMono = performance.now();
       this.#flushPendingBuilderMessages();
       this.#armIdleSuspend();
+      // A wake often leaves the backend's own state untouched, so nothing else would report that the
+      // app came back and a supervisor would show it suspended for the rest of the session.
+      this.#emitDevEvent(devHostStateOf(this.#backendLifecycleState, this.#backendGaveUp));
     }
   }
   async #applyIdleWake(batch: ChangeBatch | null): Promise<void> {
@@ -1412,6 +922,23 @@ export class AkanAppHost {
     );
   }
 
+  /**
+   * Drop everything held for a backend generation that has been replaced, answering nobody.
+   *
+   * A held request carries the id the *departing* backend gave it, and `startGeneration` only clears the
+   * router — so a replay after the restart would issue that id under the new generation and settle the
+   * builder's answer to an id the new backend is itself handing out from 1. That is exactly the
+   * misdelivery `BuilderRequestRouter` exists to prevent, reached through the hold queue instead: the
+   * new backend gets another route's manifest delta, and its real answer is dropped as unclaimed.
+   *
+   * Nothing is answered because every caller of `#startBackend` has already stopped the old backend, so
+   * a failure reply would only be dropped as undeliverable.
+   */
+  #discardPendingBuilderMessages(reason: string): void {
+    const held = this.#pendingBuilderMessages.splice(0);
+    if (held.length === 0) return;
+    this.logger.verbose(`[builder] dropped ${held.length} held builder request(s): ${reason}`);
+  }
   /**
    * Answer everything still waiting on a builder that is not coming back. Held requests are otherwise
    * invisible to the backend, which would sit on them until its own timeout with no reason given.
@@ -1718,9 +1245,17 @@ export class AkanAppHost {
     this.app.verbose(`[cli] waiting for builder to complete initial base build…`);
     let lastError: unknown;
     for (let attempt = 1; attempt <= BUILDER_START_MAX_ATTEMPTS; attempt++) {
-      this.#builder = await IncrementalBuilderHost.create(this.app, this.env, (msg) => {
-        this.#enqueueBuilderMessage(msg);
-      });
+      this.#builder = await IncrementalBuilderHost.create(
+        this.app,
+        this.env,
+        (msg) => {
+          this.#enqueueBuilderMessage(msg);
+        },
+        {
+          stdio: this.stdio,
+          onOutput: (kind, text) => void (kind === "stderr" ? process.stderr : process.stdout).write(text),
+        },
+      );
       try {
         await this.#waitForBuilderReady(attempt, { announceBootState });
         this.app.verbose(`[cli] base build ready in ${Date.now() - startTime}ms — starting backend`);