@nifrajs/cli 5.0.0 → 5.1.0

package/src/internal/source-facts.ts

@@ -82,8 +82,26 @@ function rawResponseExpression(ts: TypeScriptApi, node: TSApi.Expression): boole
   )
 }
 
-export function createSourceFacts(ts: TypeScriptApi): SourceFacts {
+export interface SourceFactsOptions {
+  /** Whether the compiler settings for a parsed file keep an import whose named specifiers are all
+   * type-only (`verbatimModuleSyntax`). Without it such an import is erased. */
+  readonly keepsTypeOnlyImports?: (file: string) => boolean
+}
+
+export function createSourceFacts(
+  ts: TypeScriptApi,
+  options: SourceFactsOptions = {},
+): SourceFacts {
   const cache = new Map<string, { content: string; source: TSApi.SourceFile | undefined }>()
+  // `{}` loads its module in every bundler; a list of type-only specifiers is erased unless the
+  // compiler keeps it as `import {} from "x"`.
+  const loadsModule = (
+    source: TSApi.SourceFile,
+    elements: readonly { readonly isTypeOnly: boolean }[],
+  ): boolean =>
+    elements.length === 0 ||
+    elements.some((element) => !element.isTypeOnly) ||
+    (options.keepsTypeOnlyImports?.(source.fileName) ?? false)
 
   const parse = (file: string, content: string): TSApi.SourceFile | undefined => {
     const cached = cache.get(file)
@@ -118,7 +136,7 @@ export function createSourceFacts(ts: TypeScriptApi): SourceFacts {
       if (reexport.isTypeOnly) return false
       const named = reexport.exportClause
       if (named !== undefined && ts.isNamedExports(named))
-        return named.elements.some((element) => !element.isTypeOnly)
+        return loadsModule(source, named.elements)
       return true // `export *` and `export * as ns`
     }
     const declaration = ancestorAt(ts, source, position, ts.isImportDeclaration)
@@ -128,9 +146,9 @@ export function createSourceFacts(ts: TypeScriptApi): SourceFacts {
     const clause = declaration.importClause
     if (clause === undefined) return true // side-effect import
     if (clause.isTypeOnly) return false
-    if (clause.namedBindings !== undefined && ts.isNamedImports(clause.namedBindings)) {
-      return clause.namedBindings.elements.some((element) => !element.isTypeOnly)
-    }
+    // A default binding is a runtime import whatever its named list holds.
+    const named = clause.name === undefined ? clause.namedBindings : undefined
+    if (named !== undefined && ts.isNamedImports(named)) return loadsModule(source, named.elements)
     return true // default and namespace bindings are runtime imports
   }
 

package/src/internal/typescript-import.ts

@@ -323,9 +323,9 @@ function syntaxKinds(module: UnknownRecord, names: readonly string[]): ReadonlyS
 
 function createVirtualFileSystem(
   sourceFiles: ReadonlyMap<string, string>,
-  root: string,
+  roots: readonly string[],
 ): UnknownRecord {
-  const rootPaths = pathVariants(root)
+  const rootPaths = [...new Set(roots.flatMap(pathVariants))]
   const virtualFiles: string[] = []
   const seenFiles = new Set<string>()
   for (const file of sourceFiles.keys()) {
@@ -454,7 +454,9 @@ async function createTypeScript7Session(
 
   const api = new API({
     cwd: sessionRoot,
-    fs: createVirtualFileSystem(files, sessionRoot),
+    // The root as the caller spells it too: a file not yet on disk keeps that spelling (`/var`, not
+    // `/private/var`), and the session reaches it through the caller's config.
+    fs: createVirtualFileSystem(files, [sessionRoot, root]),
   })
   let snapshot: TypeScript7Snapshot | undefined
   let configuredProject: TypeScript7Project | undefined

package/src/introspect.ts

@@ -438,6 +438,9 @@ export interface RouteTableEntry {
    * through the same web app, no hand-wired `if (pathname.startsWith("/api/"))`). Pages are never
    * auto-mounted (they ARE the page router); only API routes carry this flag. */
   readonly autoMounted?: boolean
+  /** True for an API route outside a set `apiPrefix` while `apiStrip` is off: the mount passes the
+   * request's full path, so no HTTP request reaches it; loaders still call it in-process. */
+  readonly inProcessOnly?: boolean
 }
 
 /** A page route + whether its module exports an `action` (→ it also serves POST). The caller resolves
@@ -506,6 +509,8 @@ export function buildRouteTable(input: RouteTableInput): RouteTableEntry[] {
       path,
       methods: [...info.methods].sort(),
       autoMounted: info.autoMounted,
+      // biome-ignore lint/plugin/noConditionalEmptyObjectSpread: only a route outside apiPrefix carries the flag, so every other row keeps its shape.
+      ...(apiPrefix !== "" && !info.autoMounted ? { inProcessOnly: true } : {}),
     })
   }
   return rows.sort(
@@ -544,7 +549,12 @@ export function renderRouteTable(rows: readonly RouteTableEntry[]): string {
   const display = rows.map((r) => ({
     methods: r.methods.join(", "),
     kind: r.kind,
-    path: r.kind === "api" && r.autoMounted ? `${r.path}  (auto-mounted)` : r.path,
+    path:
+      r.kind === "api" && r.autoMounted
+        ? `${r.path}  (auto-mounted)`
+        : r.inProcessOnly === true
+          ? `${r.path}  (in-process only: outside apiPrefix)`
+          : r.path,
     client: clientSpellingFor(r.path),
   }))
   const methodW = Math.max("METHOD".length, ...display.map((d) => d.methods.length))
@@ -577,6 +587,7 @@ export interface RouteJsonRow {
   readonly methods: readonly string[]
   readonly file?: string
   readonly autoMounted?: boolean
+  readonly inProcessOnly?: boolean
   /** The reserved typed-client key a static segment of this path collides with, when one does. */
   readonly reservedKey?: string
   /** The typed-client call spelling that reaches this route, present only alongside `reservedKey`. */
@@ -599,6 +610,8 @@ export function routeTableToJson(rows: readonly RouteTableEntry[]): {
         methods: r.methods,
         ...(r.file !== undefined ? { file: r.file } : {}),
         ...(r.kind === "api" ? { autoMounted: r.autoMounted === true } : {}),
+        // biome-ignore lint/plugin/noConditionalEmptyObjectSpread: `--json` rows gain the key only where it is true, so existing consumers see no change.
+        ...(r.inProcessOnly === true ? { inProcessOnly: true } : {}),
         ...(client === undefined
           ? {}
           : { reservedKey: client.reserved, clientSpelling: client.spelling }),
@@ -748,6 +761,31 @@ async function collectRouteTable(app: IntrospectedApp): Promise<RouteTableEntry[
   return rows
 }
 
+/**
+ * The warning `nifra dev` and `nifra build` print for backend routes no HTTP request reaches, read from
+ * the routes the backend registers, prefixes and mounts resolved; `undefined` when there are none.
+ */
+export function unservedRoutesWarning(
+  app: Pick<IntrospectedApp, "framework" | "backend">,
+): string | undefined {
+  const apiPrefix = app.framework?.apiPrefix ?? ""
+  if (apiPrefix === "" || app.backend === undefined) return undefined
+  const rows = buildRouteTable({
+    pages: [],
+    api: backendRoutes(app.backend),
+    apiPrefix,
+    apiStrip: app.framework?.apiStrip === true,
+  }).filter((row) => row.inProcessOnly === true)
+  if (rows.length === 0) return undefined
+  const listed = rows.map((row) => `${row.methods.join(",")} ${row.path}`)
+  const named =
+    listed.length > 3
+      ? `${listed.slice(0, 3).join(", ")} and ${listed.length - 3} more`
+      : listed.join(", ")
+  const one = rows.length === 1
+  return `[nifra] ${one ? "a backend route is" : `${rows.length} backend routes are`} served over HTTP nowhere: ${named}. backend/app.ts is mounted at apiPrefix ${apiPrefix} with apiStrip off, so it sees each request's full path, and ${one ? "this route sits" : "these sit"} outside it; loaders still call ${one ? "it" : "them"} in-process. Register ${one ? "it" : "them"} under ${apiPrefix}, or export \`apiStrip = true\` to serve every backend route at ${apiPrefix} plus its path.`
+}
+
 export async function describeRoutes(
   app: IntrospectedApp,
   opts: { readonly json?: boolean } = {},

package/src/levels-tool.ts

@@ -15,6 +15,7 @@ import { existsSync } from "node:fs"
 import { resolve } from "node:path"
 import type {
   AssuranceReport,
+  AssuredRoute,
   InvariantSetup,
   InvariantSetupResult,
   InvariantsConfig,
@@ -26,6 +27,7 @@ import {
   type ContractTestApp,
   runAdversarialContract,
 } from "@nifrajs/testing"
+import { RESPONSE_CONTRACT_BASELINE_HINT, responseContractGaps } from "./assure.ts"
 import {
   type CapabilityProjectReport,
   diffCapabilitySnapshots,
@@ -310,7 +312,7 @@ const messageOf = (error: unknown): string =>
 
 function finalize(
   statuses: readonly { level: number; name: string; ok: boolean; reasons: string[] }[],
-  routes: readonly { readonly responseContract?: "enforce" | "warn" | "unchecked" }[],
+  routes: readonly AssuredRoute[],
 ): VerificationLevelsResult {
   // Cumulative: the achieved level is the last rung with every rung below it also holding.
   let achieved = -1
@@ -322,6 +324,7 @@ function finalize(
   const enforced = declared.filter((route) => route.responseContract === "enforce").length
   const warnOnly = declared.filter((route) => route.responseContract === "warn").length
   const typedOnly = declared.filter((route) => route.responseContract === "unchecked").length
+  const gaps = responseContractGaps(routes)
   const responseContracts: ResponseContractStatus = {
     declared: declared.length,
     enforced,
@@ -333,14 +336,9 @@ function finalize(
       declared.length === 0
         ? ["no response/error schemas declared"]
         : [
-            ...(typedOnly > 0
-              ? [
-                  `${typedOnly} declared route(s) are typed-only; install responseContract("enforce")`,
-                ]
-              : []),
-            ...(warnOnly > 0
-              ? [`${warnOnly} declared route(s) are warn-only and still send the original payload`]
-              : []),
+            ...(gaps.typedOnlyReason === undefined ? [] : [gaps.typedOnlyReason]),
+            ...(gaps.warnOnlyReason === undefined ? [] : [gaps.warnOnlyReason]),
+            ...(typedOnly + warnOnly > 0 ? [RESPONSE_CONTRACT_BASELINE_HINT] : []),
           ],
   }
   return Object.freeze({

package/src/load.ts

@@ -342,9 +342,31 @@ export async function loadBackendApp(
   return { cwd, backend }
 }
 
+/** The fields the generated server entry imports from backend/framework.ts. */
+const SERVER_OPTIONS = [...FRAMEWORK_WEB_OPTIONS, "use"] as const
+
+/**
+ * `config` with each server option it leaves unset taken from backend/framework.ts, so `nifra dev` and
+ * the server entry `nifra build` generates read one value without nifra.config.ts re-exporting it.
+ */
+async function withServerOptions(
+  config: Partial<NifraFramework>,
+  frameworkPath: string,
+  importQuery: string | undefined,
+): Promise<Partial<NifraFramework>> {
+  // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: a config module, read like nifra.config.ts; every web option taken from it is validated below.
+  const framework = (await importWithQuery(frameworkPath, importQuery)) as Partial<NifraFramework>
+  const taken: Record<string, unknown> = {}
+  for (const name of SERVER_OPTIONS) {
+    if (config[name] === undefined && framework[name] !== undefined) taken[name] = framework[name]
+  }
+  assertFrameworkWebOptions(taken, FRAMEWORK_FILE)
+  return { ...config, ...taken }
+}
+
 /** Discover + validate the app conventions rooted at `cwd`. Prefers `nifra.config.ts`, falls back
- * to
- * `backend/framework.ts`. Throws a clear, actionable error if neither exists or the config is
+ * to `backend/framework.ts`; with both, a server option nifra.config.ts leaves unset comes from
+ * backend/framework.ts. Throws a clear, actionable error if neither exists or the config is
  * malformed. */
 export async function loadApp(
   cwd: string,
@@ -375,7 +397,11 @@ export async function loadApp(
       `[nifra] no routes/ directory in ${cwd} - nifra apps are file-routed under routes/.`,
     )
   }
-  const fw = (await importWithQuery(configPath, options.importQuery)) as Partial<NifraFramework>
+  const loaded = (await importWithQuery(configPath, options.importQuery)) as Partial<NifraFramework>
+  const fw =
+    configFile === CONFIG_FILE && existsSync(resolve(cwd, FRAMEWORK_FILE))
+      ? await withServerOptions(loaded, resolve(cwd, FRAMEWORK_FILE), options.importQuery)
+      : loaded
   if (!isAdapter(fw.adapter) || typeof fw.clientModule !== "string") {
     throw new Error(
       `[nifra] ${configFile} must export \`adapter\` (a render adapter object) and \`clientModule\` (a string).`,

package/src/mcp-context.ts

@@ -12,6 +12,7 @@ import type { AppLoader } from "./load.ts"
 import { createCachedAppLoader } from "./mcp-exec.ts"
 import { resolveMcpProjectPath } from "./mcp-path.ts"
 import type { McpPrompt, McpResource, McpServerFeatures, McpTool } from "./mcp-protocol.ts"
+import { writeTargetOf } from "./project-path.ts"
 
 function openApiFormat(args: Record<string, unknown>): "json" | "yaml" {
   const format = args.format
@@ -186,24 +187,10 @@ export function resolveProjectDir(root: string, dir: string | undefined): string
     const lexical = relative(root, target)
     return lexical === "" || (!lexical.startsWith("..") && !isAbsolute(lexical)) ? target : null
   }
-  let probe = target
-  const missing: string[] = []
-  while (true) {
-    try {
-      const canonicalProbe = realpathSync(probe)
-      const rel = relative(canonicalRoot, canonicalProbe)
-      if (rel.startsWith("..") || isAbsolute(rel)) return null
-      return missing.length === 0 ? canonicalProbe : resolve(canonicalProbe, ...missing.reverse())
-    } catch {
-      const parent = resolve(probe, "..")
-      if (parent === probe) return null
-      // `basename`, not a slice past `parent`: when `parent` is the filesystem root its trailing
-      // separator is part of it, so `parent.length + 1` eats the first character of the segment and
-      // the path gets rebuilt wrong.
-      missing.push(basename(probe))
-      probe = parent
-    }
-  }
+  const canonical = writeTargetOf(target)
+  if (canonical === undefined) return null
+  const rel = relative(canonicalRoot, canonical)
+  return rel.startsWith("..") || isAbsolute(rel) ? null : canonical
 }
 
 /** Consistent error string for a `dir` that escapes the project root. */

package/src/mcp-delegate.ts

@@ -6,7 +6,7 @@
  * answer still reads as authoritative. So the server settles the version before it serves:
  *
  *   1. The project installs its own `@nifrajs/cli` at a different version: hand the whole session to
- *      that CLI (`node_modules/.bin/nifra mcp`, stdio inherited) and step aside.
+ *      that CLI (its `bin` script, run by this Bun with `--no-env-file`, stdio inherited) and step aside.
  *   2. Handing off is impossible (no project CLI, a missing bin, or this process IS the hand-off and
  *      the versions still disagree): serve, but the version-sensitive tools refuse with the fix
  *      instead of answering for the wrong release.
@@ -31,27 +31,37 @@ export const VERSION_SENSITIVE_TOOLS: ReadonlySet<string> = new Set([
   "nifra_contracts",
 ])
 
-/** The project's own CLI: its version and, when the install linked one, its bin. */
+/** The project's own CLI: its version and, when it is on disk, the script its `bin` names. */
 export interface ProjectCli {
   readonly version: string
   readonly bin?: string
 }
 
-const BIN_NAME = process.platform === "win32" ? "nifra.exe" : "nifra"
 const MAX_ANCESTOR_DIRS = 8
 
+function binScript(bin: unknown): string | undefined {
+  if (typeof bin === "string") return bin
+  if (typeof bin !== "object" || bin === null) return undefined
+  const named: unknown = Reflect.get(bin, "nifra")
+  return typeof named === "string" ? named : undefined
+}
+
 /** The nearest `@nifrajs/cli` install at or above `root` (a monorepo app hoists to the repo root). */
 export async function findProjectCli(root: string): Promise<ProjectCli | undefined> {
   let dir = root
   for (let depth = 0; depth < MAX_ANCESTOR_DIRS; depth++) {
-    const modules = join(dir, "node_modules")
+    const pkg = join(dir, "node_modules", "@nifrajs", "cli")
     try {
-      const meta = JSON.parse(
-        await readFile(join(modules, "@nifrajs", "cli", "package.json"), "utf8"),
-      ) as { version?: unknown }
+      const meta = JSON.parse(await readFile(join(pkg, "package.json"), "utf8")) as {
+        version?: unknown
+        bin?: unknown
+      }
       if (typeof meta.version === "string" && meta.version.length > 0) {
-        const bin = join(modules, ".bin", BIN_NAME)
-        return existsSync(bin) ? { version: meta.version, bin } : { version: meta.version }
+        const script = binScript(meta.bin)
+        const bin = script === undefined ? undefined : join(pkg, script)
+        return bin !== undefined && existsSync(bin)
+          ? { version: meta.version, bin }
+          : { version: meta.version }
       }
     } catch {
       // Not installed at this level - keep walking up.
@@ -79,7 +89,9 @@ export async function delegateToProjectCli(options: {
   const cli = await findProjectCli(options.root)
   if (cli === undefined || cli.version === options.version || cli.bin === undefined)
     return undefined
-  return handOffSession([cli.bin, "mcp", ...options.args], {
+  // Not the `.bin` shim: its `bun` would load the project's `.env`, and the inherited
+  // NIFRA_MCP_WITHOUT_ENV_FILES then tells that CLI the values are already gone.
+  return handOffSession([process.execPath, "--no-env-file", cli.bin, "mcp", ...options.args], {
     cwd: options.cwd,
     env: { ...process.env, [MCP_DELEGATED_ENV]: "1" },
     announce: `[nifra] mcp: this CLI is ${options.version}; the project installs @nifrajs/cli ${cli.version} - serving this session from ${cli.bin}`,

package/src/mcp-exec.ts

@@ -36,6 +36,8 @@ import {
   CHILD_INPUT_MAX_BYTES,
   CHILD_OUTPUT_MAX_BYTES,
   CHILD_TIMEOUT_MS,
+  type EscalatingStop,
+  escalatingStop,
   OWN_PROCESS_GROUP,
   readBoundedStream,
   signalProcessGroup,
@@ -714,11 +716,12 @@ export async function spawnChild(
     stderr: "pipe",
     detached: OWN_PROCESS_GROUP,
   })
+  const stopper = escalatingStop((name) => signalProcessGroup(proc, name))
   let killed = false
   const kill = (): void => {
     if (killed) return
     killed = true
-    signalProcessGroup(proc, "SIGTERM")
+    stopper.stop()
   }
   const abort = (): void => kill()
   signal?.addEventListener("abort", abort, { once: true })
@@ -759,6 +762,7 @@ export async function spawnChild(
     return text || `${label} failed:\n${err.text.trim() || "(no output)"}`
   } finally {
     clearTimeout(timer)
+    stopper.dispose()
     signal?.removeEventListener("abort", abort)
   }
 }
@@ -838,6 +842,7 @@ export class WarmWorker {
       readonly cleanup: () => void
     }
   >()
+  private readonly stopper: EscalatingStop
   private stdoutBuffer = ""
   private stdoutBufferBytes = 0
   private stderrBuffer = ""
@@ -858,11 +863,13 @@ export class WarmWorker {
       stdout: "pipe",
       stderr: "pipe",
     }) as PipeSubprocess
+    this.stopper = escalatingStop((name) => this.proc.kill(name))
     liveWarmWorkers.add(this)
     void this.readStdout()
     void this.readStderr()
     void this.proc.exited.then((code) => {
       this.closed = true
+      this.stopper.dispose()
       liveWarmWorkers.delete(this)
       const err = new Error(
         `warm ${this.label} worker exited (${code})${this.stderrBuffer ? `:\n${this.stderrBuffer}` : ""}`,
@@ -876,7 +883,7 @@ export class WarmWorker {
   }
 
   stop(): void {
-    if (!this.closed) this.proc.kill()
+    if (!this.closed) this.stopper.stop()
   }
 
   async request(input: unknown, signal?: AbortSignal): Promise<string> {

package/src/mcp-http.ts

@@ -29,7 +29,7 @@ export { docsTools } from "./mcp-docs-tools.ts"
 export type { TypeEntry } from "./types-search.ts"
 
 // Kept in lockstep with packages/cli/package.json by check:publish's version-consistency gate.
-const VERSION = "5.0.0"
+const VERSION = "5.1.0"
 const SERVER_INFO = { name: "nifra-docs", version: VERSION }
 // Derive the GET/health tool list from the tools actually served, so the line can never drift from them.
 const docsHealth = (tools: McpTool[]): string =>

package/src/mcp-io.ts

@@ -36,6 +36,39 @@ export function signalProcessGroup(
   }
 }
 
+/** How long a stopped child gets to exit after SIGTERM before it is sent SIGKILL. */
+export const KILL_GRACE_MS = 2_000
+
+/** Stopping a child: `stop` sends SIGTERM, `dispose` drops the SIGKILL still pending once it is done. */
+export interface EscalatingStop {
+  readonly stop: () => void
+  readonly dispose: () => void
+}
+
+/**
+ * Stop a child with SIGTERM, then SIGKILL once `graceMs` passes. Project code can catch SIGTERM
+ * (a graceful-shutdown hook waiting on a hung request), and a child that never exits keeps its
+ * caller waiting and outlives it. `send` delivers one signal to the child or its group.
+ */
+export function escalatingStop(
+  send: (signal: NodeJS.Signals) => void,
+  graceMs: number = KILL_GRACE_MS,
+): EscalatingStop {
+  let escalation: ReturnType<typeof setTimeout> | undefined
+  let disposed = false
+  return {
+    stop: () => {
+      if (disposed) return
+      send("SIGTERM")
+      escalation ??= setTimeout(() => send("SIGKILL"), graceMs)
+    },
+    dispose: () => {
+      disposed = true
+      clearTimeout(escalation)
+    },
+  }
+}
+
 const FORWARDED_SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP"] as const
 
 /**

package/src/mcp-path.ts

@@ -1,12 +1,14 @@
 import { realpathSync } from "node:fs"
-import { basename, isAbsolute, relative, resolve } from "node:path"
+import { isAbsolute, relative, resolve } from "node:path"
+import { writeTargetOf } from "./project-path.ts"
 
 /**
  * Resolve an MCP path without allowing lexical or symlink escapes from the selected project.
  *
  * MCP callers are not equivalent to a local CLI user: the selected checkout is their filesystem
  * capability boundary. The nearest-existing-ancestor walk also supports output files that do not
- * exist yet while still canonicalizing every existing path component.
+ * exist yet while still canonicalizing every existing path component, and a dangling symlink is
+ * judged by where it points.
  */
 export function resolveMcpProjectPath(root: string, value: string): string | null {
   if (value.length === 0 || isAbsolute(value)) return null
@@ -23,26 +25,10 @@ export function resolveMcpProjectPath(root: string, value: string): string | nul
     return null
   }
 
-  let probe = target
-  const missing: string[] = []
-  while (true) {
-    try {
-      const canonicalProbe = realpathSync(probe)
-      const canonicalRelative = relative(canonicalRoot, canonicalProbe)
-      if (canonicalRelative.startsWith("..") || isAbsolute(canonicalRelative)) return null
-
-      const candidate = resolve(canonicalProbe, ...missing.reverse())
-      const candidateRelative = relative(canonicalRoot, candidate)
-      return candidateRelative.startsWith("..") || isAbsolute(candidateRelative) ? null : candidate
-    } catch (error) {
-      if (!(error && typeof error === "object" && (error as { code?: string }).code === "ENOENT"))
-        return null
-      const parent = resolve(probe, "..")
-      if (parent === probe) return null
-      missing.push(basename(probe))
-      probe = parent
-    }
-  }
+  const candidate = writeTargetOf(target)
+  if (candidate === undefined) return null
+  const candidateRelative = relative(canonicalRoot, candidate)
+  return candidateRelative.startsWith("..") || isAbsolute(candidateRelative) ? null : candidate
 }
 
 export function mcpProjectPathError(label: string, value: string): string {

package/src/mcp.ts

@@ -181,6 +181,13 @@ function appFeatures(cwd: string, surface: IsolatedSurface): McpServerFeatures {
 }
 
 const ROOTS_REQUEST_ID = "nifra:roots/list"
+/** Messages whose answer reads nothing the app declares: the handshake is never held up by its import. */
+const ANSWERED_WITHOUT_THE_APP: ReadonlySet<string> = new Set([
+  "initialize",
+  "ping",
+  "notifications/initialized",
+  "notifications/roots/list_changed",
+])
 const MAX_STDIO_MESSAGE_BYTES = 8 * 1024 * 1024
 const STDIO_ENCODER = new TextEncoder()
 
@@ -207,8 +214,12 @@ async function createProjectContext(root: string): Promise<ProjectContext> {
     )
     const allResources: McpResource[] = []
     const allPrompts: McpPrompt[] = []
-    for (const { name, cwd: appCwd, surface } of apps) {
-      const ns = namespaceForApp(name, [], appFeatures(appCwd, await surface()))
+    // Each app loads in its own subprocess, so they load side by side.
+    const loaded = await Promise.all(
+      apps.map(async (app) => ({ app, surface: await app.surface() })),
+    )
+    for (const { app, surface } of loaded) {
+      const ns = namespaceForApp(app.name, [], appFeatures(app.cwd, surface))
       allResources.push(...(ns.features.resources ?? []))
       allPrompts.push(...(ns.features.prompts ?? []))
     }
@@ -251,7 +262,9 @@ export async function runMcpServer(
       return
     }
   }
-  let ctx = await createProjectContext(rootState.root)
+  // Loaded in the background: the app's import can take seconds, and the handshake needs none of it.
+  let ctx = createProjectContext(rootState.root)
+  ctx.catch(() => {})
   let drift: ToolingDrift | undefined = await detectToolingDrift(rootState.root, version)
   const serverInfo = { name: "nifra", version }
   const state = createMcpProtocolState()
@@ -286,7 +299,8 @@ export async function runMcpServer(
     if (result === undefined) return
     const next = await applyClientRoots(rootState, pathsFromRootsResult(result))
     if (next.root !== rootState.root) {
-      ctx = await createProjectContext(next.root)
+      ctx = createProjectContext(next.root)
+      ctx.catch(() => {})
       drift = await detectToolingDrift(next.root, version)
     }
     rootState = next
@@ -313,15 +327,38 @@ export async function runMcpServer(
     // the code it started with: re-read the installed version per call so no answer is for a stale one.
     if (message.method === "tools/call") drift = await detectToolingDrift(rootState.root, version)
 
+    const method = message.method ?? ""
+    if (ANSWERED_WITHOUT_THE_APP.has(method)) {
+      const response = await handleRpc(
+        message,
+        [],
+        serverInfo,
+        {
+          resources: projectResources(rootState.root, noAppInServer),
+          prompts: projectPrompts(),
+          instructions: rootInstructions(rootState, drift),
+        },
+        { state, sendNotification: send, exposeToolErrors: true },
+      )
+      if (response) send(response)
+      // Ask for the client's workspace roots once the handshake completes, and again whenever the
+      // client says they changed. The answer comes back through the interception above.
+      if (method.startsWith("notifications/")) requestRoots()
+      return
+    }
+    const project = await ctx
     let activeTools: McpTool[]
-    if (ctx.apps) {
+    if (project.apps) {
+      const loaded = await Promise.all(
+        project.apps.map(async (app) => ({ app, surface: await app.surface() })),
+      )
       const allTools: McpTool[] = []
-      for (const { name, cwd: appCwd, surface } of ctx.apps) {
+      for (const { app, surface } of loaded) {
         const tools = [
-          ...refuseVersionSensitive(isolatedProjectTools(appCwd), drift),
-          ...(await surface()).tools,
+          ...refuseVersionSensitive(isolatedProjectTools(app.cwd), drift),
+          ...surface.tools,
         ]
-        const ns = namespaceForApp(name, tools, { resources: [], prompts: [] })
+        const ns = namespaceForApp(app.name, tools, { resources: [], prompts: [] })
         allTools.push(...ns.tools)
       }
       activeTools = [
@@ -334,7 +371,7 @@ export async function runMcpServer(
     } else {
       activeTools = [
         ...refuseVersionSensitive(isolatedProjectTools(rootState.root), drift),
-        ...(await ctx.surface()).tools,
+        ...(await project.surface()).tools,
       ]
     }
     const verdict = await rootVerdict(rootState)
@@ -346,7 +383,7 @@ export async function runMcpServer(
     )
 
     const features: McpServerFeatures = {
-      ...ctx.features,
+      ...project.features,
       instructions: rootInstructions(rootState, drift),
     }
     const response = await handleRpc(message, activeTools, serverInfo, features, {
@@ -356,14 +393,6 @@ export async function runMcpServer(
       exposeToolErrors: true,
     })
     if (response) send(response)
-    // Ask for the client's workspace roots once the handshake completes, and again whenever the
-    // client says they changed. The answer comes back through the interception above.
-    if (
-      message.method === "notifications/initialized" ||
-      message.method === "notifications/roots/list_changed"
-    ) {
-      requestRoots()
-    }
   }
 
   const decoder = new TextDecoder()