blume 1.4.2 → 1.4.3

package/src/astro/templates.ts

@@ -868,11 +868,24 @@ export const collections = { docs${options.staged ? ", staged" : ""} };
 };
 
 /** Generate `.blume/src/pages/[...slug].astro`, the docs catch-all route. */
-/** Generate the Ask AI server endpoint (`.blume/src/pages/api/ask.ts`). */
+/** The plain prompt used when there is no grounding context to inject. */
+const ASK_FALLBACK_PROMPT =
+  "You are a helpful documentation assistant. Answer using the project's documentation.";
+
+/**
+ * Generate the Ask AI server endpoint (`.blume/src/pages/api/ask.ts`).
+ * `instructions` (the `ai.ask.instructions` config) is appended to the
+ * built-in prompt on every path: the grounded prompt via `createAskContext`,
+ * and the plain fallback here.
+ */
 export const askEndpointTemplate = (
   backend: AskBackend,
-  grounded: boolean
+  grounded: boolean,
+  instructions?: string
 ): string => {
+  const fallbackPrompt = instructions
+    ? `${ASK_FALLBACK_PROMPT}\n\n${instructions}`
+    : ASK_FALLBACK_PROMPT;
   const imports = [
     'import type { APIRoute } from "astro";',
     'import { streamText } from "ai";',
@@ -905,7 +918,10 @@ export const askEndpointTemplate = (
       'import { createAskContext } from "blume/ai/ask-context.ts";',
       'import askData from "../../generated/ask-data.json";'
     );
-    setup += "\nconst ground = createAskContext(askData);\n";
+    const groundOptions = instructions
+      ? `, { instructions: ${JSON.stringify(instructions)} }`
+      : "";
+    setup += `\nconst ground = createAskContext(askData${groundOptions});\n`;
   }
   // Validate the client-supplied body and cap its size. The endpoint is
   // unauthenticated, so bounding message count/length limits how much a caller
@@ -966,7 +982,7 @@ export const askEndpointTemplate = (
   const stream = grounded
     ? `    const instructions =
       (await ground(messages, body.page)) ??
-      "You are a helpful documentation assistant. Answer using the project's documentation.";
+      ${JSON.stringify(fallbackPrompt)};
     const result = streamText({
       model: ${modelExpr},
       instructions,
@@ -976,7 +992,7 @@ ${onError}
     : `    const result = streamText({
       model: ${modelExpr},
       instructions:
-        "You are a helpful documentation assistant. Answer using the project's documentation.",
+        ${JSON.stringify(fallbackPrompt)},
       messages,
 ${onError}
     });`;
@@ -1261,7 +1277,7 @@ export const contentAssetsEndpointTemplate = (
   `// Generated by Blume. Do not edit.
 import { existsSync } from "node:fs";
 import { readdir, readFile } from "node:fs/promises";
-import { join, relative, resolve } from "node:path";
+import { isAbsolute, join, relative, resolve } from "node:path";
 import type { APIRoute } from "astro";
 import assets from "../../generated/content-assets.json";
 
@@ -1321,7 +1337,13 @@ const resolveAsset = (asset: string): string | null => {
   const abs = resolve(STAGED_DIR, asset);
   // Traversal guard: the dev server renders on demand, so the param is
   // attacker-controlled there — never step outside the staged directory.
-  if (!abs.startsWith(STAGED_DIR + "/")) {
+  // path.relative rather than a string-prefix test: STAGED_DIR is baked in
+  // with forward slashes while resolve() answers in the platform's
+  // separators, so on Windows the prefix test 404'd every legitimate staged
+  // asset — and a bare prefix also admits a sibling directory that merely
+  // shares the name.
+  const rel = relative(STAGED_DIR, abs);
+  if (rel === "" || rel.startsWith("..") || isAbsolute(rel)) {
     return null;
   }
   return existsSync(abs) ? abs : null;
@@ -1680,8 +1702,11 @@ const frontmatter = entry.data ?? {};
 const seo = frontmatter.seo ?? {};
 const base = data.config.site ? data.config.site.replace(/\\/$/, "") : null;
 
+// Percent-encode the route-derived path (the sitemap convention): a Unicode
+// slug (\`/api/größe\`) is not legal in a raw URI, and crawlers compare
+// canonical against the sitemap's encoded <loc> byte-for-byte.
 const ogPath = data.config.og.enabled
-  ? \`/og/\${route === "/" ? "index" : route.slice(1)}.png\`
+  ? encodeURI(\`/og/\${route === "/" ? "index" : route.slice(1)}.png\`)
   : null;
 const ogRel = seo.image ?? ogPath;
 // Absolute URLs also carry the deployment base (the page is served under it):
@@ -1700,7 +1725,7 @@ const x = { ...data.config.x, ...(seo.x?.creator ? { creator: seo.x.creator } :
 const basedRoute = withBase(route);
 const canonical =
   seo.canonical ??
-  (base ? \`\${base}\${basedRoute === "/" ? "" : basedRoute}\` : null);
+  (base ? \`\${base}\${basedRoute === "/" ? "" : encodeURI(basedRoute)}\` : null);
 
 // Locale resolution. With i18n on, pick the active locale's nav + dictionary,
 // build hreflang alternates, and derive the language-switcher targets.

package/src/audit/agent.ts

@@ -1,7 +1,7 @@
-import { spawn } from "node:child_process";
 import { mkdtemp, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 
+import spawn from "cross-spawn";
 import { join } from "pathe";
 
 import { reportJson } from "./report.ts";
@@ -61,37 +61,26 @@ Work through every finding:
 
 When you are done, run \`blume build\` and then \`blume audit\` to verify, and repeat until the audit reports no issues.`;
 
-const spawnAgent = (
-  command: string,
-  args: string[],
-  shell: boolean
-): Promise<number> =>
+const spawnAgent = (bin: string, args: string[]): Promise<number> =>
   // oxlint-disable-next-line promise/avoid-new -- adapt spawn's event callbacks
   new Promise((resolve, reject) => {
-    const child = spawn(command, args, { shell, stdio: "inherit" });
+    const child = spawn(bin, args, { stdio: "inherit" });
     child.once("error", reject);
     child.once("close", (code) => resolve(code ?? 1));
   });
 
-/**
- * cmd.exe reports a missing executable through this exit code instead of a
- * spawn error, so a shell launch can't rely on the `error` event for the
- * "not installed" diagnosis.
- */
-export const WINDOWS_COMMAND_NOT_FOUND = 9009;
-
 /**
  * Run the agent CLI interactively with the handoff prompt, inheriting the
  * terminal so the user watches and steers the fixes rather than granting a
  * headless process blanket write access. Resolves with the agent's exit code;
- * rejects when the executable isn't on PATH.
+ * rejects when the executable isn't on PATH — on every platform, since
+ * cross-spawn resolves npm's `.cmd` shims itself and escapes their arguments
+ * (the old `shell: true` launch left quoting to a hand-built command line and
+ * reported a missing executable as cmd.exe's exit code 9009).
  *
- * On Windows, npm installs agent CLIs as `.cmd` shims, which Node refuses to
- * spawn without a shell — and cmd.exe cannot carry the multi-line prompt as an
- * argument (a newline ends the command). So there the prompt is written to a
- * file next to the report and handed over via a one-line pointer that survives
- * cmd.exe quoting; a missing executable surfaces as
- * {@link WINDOWS_COMMAND_NOT_FOUND} rather than a rejection.
+ * cmd.exe still cannot carry the multi-line prompt as an argument (a newline
+ * ends the command), so on Windows the prompt is written to a file next to
+ * the report and handed over via a one-line pointer.
  */
 export const launchAgent = async (
   bin: string,
@@ -99,16 +88,12 @@ export const launchAgent = async (
   platform: NodeJS.Platform = process.platform
 ): Promise<number> => {
   if (platform !== "win32") {
-    return await spawnAgent(bin, [prompt], false);
+    return await spawnAgent(bin, [prompt]);
   }
   const dir = await mkdtemp(join(tmpdir(), "blume-audit-"));
   const promptPath = join(dir, "prompt.md");
   await writeFile(promptPath, prompt);
-  // Double quotes are the one grouping cmd.exe respects; neither the temp
-  // path nor the fixed pointer text can contain one.
-  return await spawnAgent(
-    `"${bin}" "Read ${promptPath} and follow its instructions exactly."`,
-    [],
-    true
-  );
+  return await spawnAgent(bin, [
+    `Read ${promptPath} and follow its instructions exactly.`,
+  ]);
 };

package/src/audit/crawl.ts

@@ -1,6 +1,9 @@
 import { readFile, stat } from "node:fs/promises";
 
 import { XMLParser } from "fast-xml-parser";
+import type { Nodes } from "mdast";
+import { fromMarkdown } from "mdast-util-from-markdown";
+import pMap from "p-map";
 import { join, relative } from "pathe";
 import { glob } from "tinyglobby";
 
@@ -18,6 +21,13 @@ import type { LlmsDoc, PageSnapshot, RobotsDoc, SitemapDoc } from "./types.ts";
  */
 const EXAMPLES_PREFIX = `${examplesRouteBase("")}/`;
 
+/**
+ * Ceiling on concurrent file reads/stats while crawling. Unbounded fan-out
+ * over a large `dist` risks EMFILE and holds every page's HTML in memory at
+ * once.
+ */
+const CRAWL_CONCURRENCY = 16;
+
 /** Everything read off disk in one pass over the built site. */
 export interface CrawlResult {
   pages: PageSnapshot[];
@@ -45,12 +55,14 @@ export const fileToUrl = (staticDir: string, file: string): string => {
  */
 const indexFiles = async (staticDir: string): Promise<Map<string, number>> => {
   const found = await glob("**/*", { cwd: staticDir, dot: true });
-  const sized = await Promise.all(
-    found.map(async (file) => {
+  const sized = await pMap(
+    found,
+    async (file) => {
       const path = `/${file.replaceAll("\\", "/")}`;
       const info = await stat(join(staticDir, file));
       return [path, info.size] as const;
-    })
+    },
+    { concurrency: CRAWL_CONCURRENCY }
   );
   return new Map(sized);
 };
@@ -135,21 +147,32 @@ export const parseSitemap = (
 };
 
 /**
- * Parse the `llms.txt` index into its Markdown link targets. Deliberately
- * shallow, like {@link parseSitemap}: the checks only need "which pages does
- * this file claim exist", not a Markdown AST.
+ * Parse the `llms.txt` index into its Markdown link targets, with the line
+ * each target sits on so findings can point at it. A real parse rather than a
+ * `](url)` regex: angle-bracket destinations, link titles, reference-style
+ * links (the definition line carries the URL), and autolinks all resolve, and
+ * a link-shaped string inside a fenced code block is no longer reported as a
+ * claim. Blume's own llms.txt only emits inline links, but the file is also
+ * hand-edited.
  */
 export const parseLlms = (file: string, text: string): LlmsDoc => {
   const entries: LlmsDoc["entries"] = [];
-  const link = /\]\((?<url>[^)\s]+)\)/gu;
-  for (const [index, line] of text.split(/\r?\n/u).entries()) {
-    for (const match of line.matchAll(link)) {
-      const url = match.groups?.url;
-      if (url) {
-        entries.push({ line: index + 1, url });
+  const collect = (node: Nodes): void => {
+    if (
+      (node.type === "link" ||
+        node.type === "image" ||
+        node.type === "definition") &&
+      node.url
+    ) {
+      entries.push({ line: node.position?.start.line ?? 1, url: node.url });
+    }
+    if ("children" in node) {
+      for (const child of node.children) {
+        collect(child);
       }
     }
-  }
+  };
+  collect(fromMarkdown(text));
   return { entries, file };
 };
 
@@ -214,8 +237,9 @@ export const crawlStaticDir = async (options: {
   const routes = routeIndex(manifest, basePath);
 
   const htmlFiles = await glob("**/*.html", { absolute: true, cwd: staticDir });
-  const snapshots = await Promise.all(
-    htmlFiles.toSorted().map(async (file) => {
+  const snapshots = await pMap(
+    htmlFiles.toSorted(),
+    async (file) => {
       const url = fileToUrl(staticDir, file);
       if (stripBasePath(basePath, url).startsWith(EXAMPLES_PREFIX)) {
         return null;
@@ -230,7 +254,8 @@ export const crawlStaticDir = async (options: {
         route: routes.get(url) ?? routes.get(stripBasePath(basePath, url)),
         url,
       });
-    })
+    },
+    { concurrency: CRAWL_CONCURRENCY }
   );
   const pages = snapshots.filter((page) => page !== null);
 

package/src/audit/run.ts

@@ -1,5 +1,7 @@
 import { readFile } from "node:fs/promises";
 
+import pMap from "p-map";
+
 import { normalizeBasePath, withBasePath } from "../core/base-path.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
 import type { Diagnostic } from "../core/types.ts";
@@ -88,6 +90,9 @@ export class NoBuildError extends Error {
   }
 }
 
+/** Ceiling on concurrent source reads; unbounded fan-out risks EMFILE. */
+const READ_CONCURRENCY = 16;
+
 /** Read every page's source file once, so findings can cite front matter lines. */
 const readSources = async (
   pages: PageSnapshot[]
@@ -95,8 +100,9 @@ const readSources = async (
   const paths = [
     ...new Set(pages.flatMap((page) => (page.source ? [page.source] : []))),
   ];
-  const entries = await Promise.all(
-    paths.map(async (path) => {
+  const entries = await pMap(
+    paths,
+    async (path) => {
       try {
         return [path, await readFile(path, "utf-8")] as const;
       } catch {
@@ -104,7 +110,8 @@ const readSources = async (
         // still names the URL; it just can't cite a line.
         return null;
       }
-    })
+    },
+    { concurrency: READ_CONCURRENCY }
   );
   return new Map(entries.filter((entry) => entry !== null));
 };

package/src/audit/snapshot.ts

@@ -8,6 +8,30 @@ import type { PageSnapshot, SnapshotAsset, SnapshotLink } from "./types.ts";
 /** Site chrome: links here are navigation, not editorial. */
 const CHROME = "nav, aside, header, footer";
 
+/**
+ * Count prose words with `Intl.Segmenter`, seeded with the page's declared
+ * language. The whitespace split this replaces counted a fully written
+ * Japanese or Chinese page — scripts with no interword spaces — as a handful
+ * of "words", tripping BLUME_AUDIT_LOW_WORD_COUNT on every page of a CJK
+ * site. An unparseable `lang` attribute falls back to the default locale
+ * rather than failing the crawl.
+ */
+const countWords = (prose: string, lang: string | null): number => {
+  let segmenter: Intl.Segmenter;
+  try {
+    segmenter = new Intl.Segmenter(lang ?? undefined, { granularity: "word" });
+  } catch {
+    segmenter = new Intl.Segmenter(undefined, { granularity: "word" });
+  }
+  let count = 0;
+  for (const segment of segmenter.segment(prose)) {
+    if (segment.isWordLike) {
+      count += 1;
+    }
+  }
+  return count;
+};
+
 /** Where a page's prose lives, in preference order. */
 const CONTENT_ROOTS = ["main", "article", "body"];
 
@@ -123,6 +147,7 @@ export const buildSnapshot = (options: {
   const root = contentRoot(document);
   const prose = root ? visibleText(root) : "";
   const robots = document.querySelector('meta[name="robots"]');
+  const lang = attr(document.querySelector("html") ?? document, "lang");
   const { jsonld, jsonldErrors } = collectJsonLd(document);
 
   return {
@@ -160,7 +185,7 @@ export const buildSnapshot = (options: {
     indexable: !robots?.getAttribute("content")?.includes("noindex"),
     jsonld,
     jsonldErrors,
-    lang: attr(document.querySelector("html") ?? document, "lang"),
+    lang,
     links,
     metaRefresh:
       document
@@ -184,6 +209,6 @@ export const buildSnapshot = (options: {
         .querySelector('meta[name="viewport"]')
         ?.getAttribute("content")
         ?.trim() ?? null,
-    wordCount: prose ? prose.split(/\s+/u).length : 0,
+    wordCount: countWords(prose, lang),
   };
 };

package/src/cli/commands/audit.ts

@@ -4,7 +4,6 @@ import {
   AGENTS,
   fixPrompt,
   launchAgent,
-  WINDOWS_COMMAND_NOT_FOUND,
   writeAgentReport,
 } from "../../audit/agent.ts";
 import type { AgentKind } from "../../audit/agent.ts";
@@ -41,22 +40,26 @@ export const shouldFail = (
 };
 
 /**
- * Launch the agent CLI, translating a missing executable into the Windows
- * not-found sentinel. Only `ENOENT` means "not installed" — any other spawn
- * failure (`EACCES`, `EMFILE`, …) must surface as itself, not be masked by an
- * irrelevant install hint.
+ * Launch the agent CLI, turning a missing executable into the install hint.
+ * Only `ENOENT` means "not installed" — any other spawn failure (`EACCES`,
+ * `EMFILE`, …) must surface as itself, not be masked by an irrelevant
+ * install hint.
  */
 const launchAgentCode = async (
-  bin: string,
+  agent: AgentKind,
   prompt: string
 ): Promise<number> => {
+  const cli = AGENTS[agent];
   try {
-    return await launchAgent(bin, prompt);
+    return await launchAgent(cli.bin, prompt);
   } catch (error) {
     if ((error as NodeJS.ErrnoException)?.code !== "ENOENT") {
       throw error;
     }
-    return WINDOWS_COMMAND_NOT_FOUND;
+    logger.error(
+      `${cli.name} (\`${cli.bin}\`) was not found on PATH. Install it with \`${cli.install}\`.`
+    );
+    return process.exit(1);
   }
 };
 
@@ -183,15 +186,7 @@ export const auditCommand = defineCommand({
       process.stderr.write(
         `  Handing ${count} finding${count === 1 ? "" : "s"} to ${cli.name}…\n\n`
       );
-      const code = await launchAgentCode(cli.bin, fixPrompt(report));
-      // A POSIX spawn rejects on a missing executable; the Windows shell
-      // launch reports it through cmd.exe's 9009 instead. Same diagnosis.
-      if (code === WINDOWS_COMMAND_NOT_FOUND) {
-        logger.error(
-          `${cli.name} (\`${cli.bin}\`) was not found on PATH. Install it with \`${cli.install}\`.`
-        );
-        process.exit(1);
-      }
+      const code = await launchAgentCode(agent, fixPrompt(report));
       if (code !== 0) {
         process.exit(code);
       }

package/src/cli/commands/build.ts

@@ -54,7 +54,7 @@ import {
   platformRedirects,
 } from "../../deploy/redirects.ts";
 import { buildRobots } from "../../deploy/robots.ts";
-import { buildSitemap } from "../../deploy/sitemap.ts";
+import { buildSitemapFiles } from "../../deploy/sitemap.ts";
 import { injectNegotiationRoutes } from "../../deploy/vercel-negotiation.ts";
 import { buildSearchIndex } from "../../search/build.ts";
 import { syncSearchProvider } from "../../search/sync/index.ts";
@@ -616,10 +616,18 @@ const publishBuildArtifacts = async (
   }
 
   // A user's own public/ file (copied into dist by Astro) always wins.
-  const sitemap = buildSitemap(project);
-  if (sitemap && !existsSync(join(distDir, "sitemap.xml"))) {
-    await writeFile(join(distDir, "sitemap.xml"), sitemap, "utf-8");
-    logger.success("Generated sitemap.xml");
+  const sitemapFiles = buildSitemapFiles(project);
+  if (sitemapFiles && !existsSync(join(distDir, "sitemap.xml"))) {
+    await Promise.all(
+      sitemapFiles.map((file) =>
+        writeFile(join(distDir, file.name), file.xml, "utf-8")
+      )
+    );
+    logger.success(
+      sitemapFiles.length === 1
+        ? "Generated sitemap.xml"
+        : `Generated sitemap.xml (index of ${sitemapFiles.length - 1} sitemap files)`
+    );
   }
 
   const robots = buildRobots(project);
@@ -649,7 +657,7 @@ const publishBuildArtifacts = async (
 
   const { config } = project;
   const features = serverFeatures(config);
-  // `buildSitemap` returns null both when the sitemap is disabled and when no
+  // `buildSitemapFiles` returns null both when the sitemap is disabled and when no
   // `site` is configured — only the latter deserves the remediation hint.
   const sitemapNote = config.seo.sitemap
     ? "no (set deployment.site)"
@@ -661,7 +669,7 @@ const publishBuildArtifacts = async (
       `Site       ${config.deployment.site ?? "not set"}`,
       `Search     ${config.search.provider}`,
       `Redirects  ${config.redirects.length}`,
-      `Sitemap    ${sitemap ? "yes" : sitemapNote}`,
+      `Sitemap    ${sitemapFiles ? "yes" : sitemapNote}`,
       `Robots     ${robots ? "yes" : "no"}`,
       `Agent JSON ${agentReadability ? "yes" : "no"}`,
       `LLM files  ${config.ai.llmsTxt.enabled ? "yes" : "no"}`,

package/src/cli/commands/dev.ts

@@ -1,13 +1,13 @@
 import { dev } from "astro";
 import { watch } from "chokidar";
 import { defineCommand } from "citty";
+import { debounce } from "perfect-debounce";
 
 import { generateRuntime } from "../../astro/generate.ts";
 import { showBlumeErrorOverlay } from "../../astro/integration.ts";
 import { scanProject } from "../../core/project-graph.ts";
 import { resolveRuntimeDir } from "../../core/project.ts";
 import { parsePort } from "../args.ts";
-import { coalescedRunner } from "../coalesce.ts";
 import {
   acquireDevLock,
   describeDevLock,
@@ -146,10 +146,16 @@ export const devCommand = defineCommand({
     // watcher misses directory renames, so a renamed page 404s (`getEntry` reads
     // a stale in-memory store) until the server is restarted. We restart it
     // ourselves — stop, regenerate while down (no watcher races), then bring up
-    // a fresh container whose cold sync re-globs everything. `coalescedRunner`
-    // single-flights the scan so a burst of watch events can never stack
-    // overlapping regenerations (piled-up scans exhaust the heap).
-    const runRegenerate = coalescedRunner(async () => {
+    // a fresh container whose cold sync re-globs everything. perfect-debounce
+    // both debounces the watch burst (80ms) and single-flights the scan: a
+    // trigger during a run never starts a second run, only marks one trailing
+    // rerun after the current settles. Both halves are load-bearing — a plain
+    // debounce once let bursts stack overlapping scans until the heap was
+    // exhausted (observed as an OOM after minutes of looping). The contract is
+    // pinned by test/dev-debounce.test.ts. The task must not reject (the
+    // library re-invokes it from an unhandled .finally), so the body catches
+    // its own errors and always resolves.
+    const regenerate = debounce(async () => {
       try {
         const next = await scanProject(root, {
           devServerUrl,
@@ -181,21 +187,13 @@ export const devCommand = defineCommand({
       } catch (error) {
         logger.error(`Regeneration failed: ${(error as Error).message}`);
       }
-    });
-
-    let timer: ReturnType<typeof setTimeout> | null = null;
-    const regenerate = () => {
-      if (timer) {
-        clearTimeout(timer);
-      }
-      timer = setTimeout(runRegenerate, 80);
-    };
+    }, 80);
 
     // The runtime prepared above baked the *requested* port into the site
     // fallback; if Vite bumped it, regenerate so OG images, canonicals, and
     // other site-gated URLs point at the port actually serving.
     if (boundPort !== port) {
-      void runRegenerate();
+      void regenerate();
     }
 
     // Content is watched per source (filesystem uses fs.watch; remote sources

package/src/cli/commands/eject.ts

@@ -8,7 +8,7 @@ import {
   droppedArtifactNotices,
   updatePackageScripts,
 } from "../eject-scripts.ts";
-import { commandsFor, detectPackageManager } from "../init/scaffold.ts";
+import { commandsFor, detectProjectPackageManager } from "../init/scaffold.ts";
 import { logger } from "../log.ts";
 
 /**
@@ -76,9 +76,9 @@ export const ejectCommand = defineCommand({
       process.stdout.write(`  ${relative(root, file)}\n`);
     }
     reportDroppedArtifacts(notices);
-    // Print run commands matching the user's package manager, detected the
-    // same way as `blume init`'s next-steps hint.
-    const pm = detectPackageManager(process.env.npm_config_user_agent);
+    // Print run commands matching the project's package manager (lockfile
+    // detection, since eject runs inside an existing project).
+    const pm = await detectProjectPackageManager(root);
     const { build, dev } = commandsFor(pm);
     logger.box(
       `Your project is now a standalone Astro app.\n\n  ${dev}\n  ${build}\n\nThe blume package remains importable.`

package/src/cli/commands/eval.ts

@@ -3,11 +3,7 @@ import { existsSync } from "node:fs";
 import { defineCommand } from "citty";
 import { join } from "pathe";
 
-import {
-  AGENTS,
-  launchAgent,
-  WINDOWS_COMMAND_NOT_FOUND,
-} from "../../audit/agent.ts";
+import { AGENTS, launchAgent } from "../../audit/agent.ts";
 import type { AgentKind } from "../../audit/agent.ts";
 import { BlumeError } from "../../core/diagnostics.ts";
 import { scanProject } from "../../core/project-graph.ts";
@@ -37,32 +33,32 @@ const DEFAULT_TIMEOUT_S = 180;
 const isAgentKind = (value: string): value is AgentKind => value in AGENTS;
 
 /**
- * Launch the interactive agent CLI, translating a missing executable into the
- * Windows not-found sentinel. Only `ENOENT` means "not installed" — any other
- * spawn failure (`EACCES`, `EMFILE`, …) must surface as itself.
+ * Launch the interactive agent CLI, turning a missing executable into the
+ * install hint. Only `ENOENT` means "not installed" — any other spawn failure
+ * (`EACCES`, `EMFILE`, …) must surface as itself.
  */
+const notInstalled = (agent: AgentKind): never => {
+  const cli = AGENTS[agent];
+  logger.error(
+    `${cli.name} (\`${cli.bin}\`) was not found on PATH. Install it with \`${cli.install}\`.`
+  );
+  return process.exit(1);
+};
+
 const launchAgentCode = async (
-  bin: string,
+  agent: AgentKind,
   prompt: string
 ): Promise<number> => {
   try {
-    return await launchAgent(bin, prompt);
+    return await launchAgent(AGENTS[agent].bin, prompt);
   } catch (error) {
     if ((error as NodeJS.ErrnoException)?.code !== "ENOENT") {
       throw error;
     }
-    return WINDOWS_COMMAND_NOT_FOUND;
+    return notInstalled(agent);
   }
 };
 
-const notInstalled = (agent: AgentKind): never => {
-  const cli = AGENTS[agent];
-  logger.error(
-    `${cli.name} (\`${cli.bin}\`) was not found on PATH. Install it with \`${cli.install}\`.`
-  );
-  return process.exit(1);
-};
-
 /** The fraction of run (non-skipped) questions that passed. */
 export const passFraction = (result: EvalResult): number => {
   const ran = result.results.length - result.counts.skip;
@@ -125,10 +121,7 @@ const runFixHandoff = async (
   process.stderr.write(
     `  Handing ${count} failed question${count === 1 ? "" : "s"} to ${cli.name}…\n\n`
   );
-  const code = await launchAgentCode(cli.bin, evalFixPrompt(report));
-  if (code === WINDOWS_COMMAND_NOT_FOUND) {
-    notInstalled(agent);
-  }
+  const code = await launchAgentCode(agent, evalFixPrompt(report));
   if (code !== 0) {
     process.exit(code);
   }
@@ -143,10 +136,7 @@ const runInit = async (agent: AgentKind, file: string): Promise<void> => {
     );
     process.exit(1);
   }
-  const code = await launchAgentCode(AGENTS[agent].bin, initPrompt(file));
-  if (code === WINDOWS_COMMAND_NOT_FOUND) {
-    notInstalled(agent);
-  }
+  const code = await launchAgentCode(agent, initPrompt(file));
   if (code !== 0) {
     process.exit(code);
   }