@takara-ai/miru-code 1.0.5 → 1.1.1

package/README.md

@@ -43,11 +43,11 @@ Interactive TUI — **↑↓** move, **space** toggle, **a** all, **enter** conf
 
 | Integration | What it does |
 |-------------|----------------|
-| MCP server | `search` and `find_related` tools in the agent |
+| MCP server | `search`, `expand`, and `find_related` tools in the agent |
 | Instructions | Search policy in `CLAUDE.md` / `AGENTS.md` / `GEMINI.md` |
 | Sub-agent | Dedicated `miru-code` agent file |
 | Cursor rules | Always-on `.cursor/rules/miru-code.mdc` (Cursor only) |
-| Search hooks | Block built-in Grep/Glob and redirect to Miru MCP |
+| Search hooks *(experimental)* | Block built-in Grep/Glob and redirect to Miru MCP |
 
 Restart the IDE when done.
 
@@ -57,7 +57,7 @@ miru uninstall   # remove miru config
 
 **Supported:** Cursor · Claude Code · Gemini CLI · Kiro · OpenCode · GitHub Copilot · Codex · VS Code · Visual Studio (Windows) · Windsurf / Devin Desktop
 
-| IDE | MCP | Instructions / rules | Hooks |
+| IDE | MCP | Instructions / rules | Hooks *(experimental)* |
 |-----|-----|------------------------|-------|
 | Cursor | `~/.cursor/mcp.json` | `~/.cursor/rules/miru-code.mdc` | `~/.cursor/hooks.json` |
 | Claude Code | `~/.claude.json` | `~/.claude/CLAUDE.md` | `~/.claude/settings.json` |
@@ -70,13 +70,15 @@ miru uninstall   # remove miru config
 | Visual Studio | `%USERPROFILE%\.mcp.json` | — | `~/.copilot/hooks/miru-search.json` |
 | Windsurf | — | — | `~/.codeium/windsurf/hooks.json` |
 
-Sub-agent files are also written where supported (see `miru install` plan). Windsurf hooks only — no MCP entry yet.
+Sub-agent files are also written where supported (see `miru install` plan). Windsurf hooks only *(experimental)* — no MCP entry yet.
 
-### Search hooks
+### Search hooks *(experimental)*
+
+Search hooks are **experimental** — behavior and IDE support may change between releases.
 
 Hooks run `miru hook-guard` before built-in search tools execute. They **block** conceptual Grep/Glob/SemanticSearch and shell `rg`/`grep`/`find`, and tell the agent to use Miru MCP `search` instead. Exact literal lookups (e.g. `REDIS_HOST`, a symbol name) still pass through.
 
-Hooks are optional at install time but **on by default**. Disable them in the installer if you only want MCP + instructions.
+Hooks are optional at install time but **on by default**. Disable them in the installer if you only want MCP + instructions, or while evaluating the experimental hook integration.
 
 **Team sub-agent in a repo** (optional):
 
@@ -88,6 +90,7 @@ miru init --agent claude --force
 
 ```bash
 miru search "auth middleware" ./src
+miru expand src/auth.ts 42 ./src
 miru find-related src/auth.ts 42 ./src
 ```
 
@@ -101,14 +104,53 @@ bunx @takara-ai/miru-code search "auth middleware" ./src
 
 ## MCP tools
 
-When wired via `miru install`, your agent gets:
+When wired via `miru install`, the MCP server exposes three tools. Pass the **project root** as `repo` for local workspaces (or an `https://` git URL). The index is built on the first call and cached for the session.
+
+| Tool | When to use |
+|------|-------------|
+| `search` | Default for code exploration — hybrid semantic + keyword search. One call per question. |
+| `expand` | More context in the **same file** when a hit has `truncated: true`. |
+| `find_related` | Similar code in **other files** from a `file_path` + `anchor_line`. |
+
+### Workflow
+
+1. **`search`** with `query` + `repo` — returns compact snippets (~±15 lines) and relevance scores.
+2. If a hit has **`truncated: true`**, call **`expand`** with `file_path`, `anchor_line`, and `repo` — not another search or a full-file read.
+3. To trace similar patterns elsewhere, call **`find_related`** with the same `file_path`, `anchor_line`, and `repo`.
+4. Use your editor's **Read** on `absolute_path` only when editing or when `expand` still lacks context.
+
+Prefer these tools over Grep, Glob, or SemanticSearch when Miru MCP is connected — hooks and instructions enforce that when enabled.
+
+### Parameters
+
+**`search`**
+
+| Param | Required | Notes |
+|-------|----------|-------|
+| `query` | yes | Natural language or code query |
+| `repo` | yes | Project root or git URL |
+| `top_k` | no | Results to return (default 3, max 10) |
+| `dedupe_by_file` | no | Keep best hit per file (default `true`) |
+
+**`expand`**
 
-| Tool | What it does |
-|------|----------------|
-| `search` | Query by meaning; pass `repo` (project root or `https://` git URL) |
-| `find_related` | Similar code at a `file_path` + line from a search hit |
+| Param | Required | Notes |
+|-------|----------|-------|
+| `file_path` | yes | From hit `file_path` or `absolute_path` (local repos) |
+| `anchor_line` | yes | From the search hit (`anchor_line` when truncated, else `start_line`) |
+| `repo` | yes | Same repo as the search |
+| `before` / `after` | no | Extra chunks before/after anchor (default 1 each) |
 
-Pass the **project root** as `repo` for local projects. Prefer these over Grep, Glob, or SemanticSearch when Miru MCP is connected — hooks and instructions enforce that when enabled.
+**`find_related`**
+
+| Param | Required | Notes |
+|-------|----------|-------|
+| `file_path` | yes | From a search hit |
+| `anchor_line` | yes | From the search hit |
+| `repo` | yes | Same repo as the search |
+| `top_k` | no | Related chunks to return (default 3, max 10) |
+
+Local repo hits include `absolute_path` for one-click navigation. Confirm exact literals (env var names, quoted strings) with native grep when needed.
 
 ## How it works
 
@@ -166,7 +208,7 @@ Set `MIRU_AST_CHUNKING=0` to disable AST and use structural → lines only.
 | `miru find-related <file> <line> [path]` | Related chunks |
 | `miru init --agent <id>` | Project-local sub-agent |
 | `miru clear [path]` | Drop index cache |
-| `miru hook-guard` | PreToolUse hook entrypoint (used by installers; reads JSON stdin) |
+| `miru hook-guard` | PreToolUse hook entrypoint *(experimental)*; used by installers, reads JSON stdin |
 | `miru` | Start MCP server |
 
 ## Library
@@ -194,6 +236,7 @@ const results = await index.search({ query: "BM25 tokenize", topK: 10 });
 | `MIRU_ALLOW_HTTP_GIT` | Set `1` to allow plain `http://` git clones |
 | `MIRU_MCP_WATCH` | Set `0` to disable MCP file watch |
 | `MIRU_AST_CHUNKING` | Set `0` to disable tree-sitter AST chunking |
+| `MIRU_QUIET` | Set `1` to skip the framed CLI banner (subtitle only on color terminals) |
 | `NO_COLOR` | Disable CLI colors |
 
 See `.env.example` for more.
@@ -223,6 +266,18 @@ bun test && bun run typecheck
 
 Local MCP: `"command": "bun", "args": ["/path/to/miru-code/src/cli.ts"]`
 
+### CLI banner
+
+`miru help` and setup print a framed wordmark and Takara crane on color terminals. Set `MIRU_QUIET=1` to use the subtitle line only.
+
+Crane ASCII art is committed in `src/brand-banner.ts`. To regenerate it from the SVG source (local `assets/red_crane_vector.svg`, gitignored):
+
+```bash
+bun run scripts/render-crane-art.ts
+```
+
+Copy the printed `TAKARA_CRANE` constant into `src/brand-banner.ts`. Requires ImageMagick (`magick`).
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@takara-ai/miru-code",
-  "version": "1.0.5",
+  "version": "1.1.1",
   "description": "Miru (見る) — hybrid code search for agents. Bun, TypeScript, Takara embeddings.",
   "type": "module",
   "license": "MIT",

package/src/agents.ts

@@ -1,5 +1,4 @@
-import { mkdir, readFile } from "node:fs/promises";
-import { dirname, join } from "node:path";
+import { join } from "node:path";
 import { buildSubagentBody, type NativeToolNames } from "./installer/search-policy.ts";
 
 export type AgentId = "claude" | "copilot" | "cursor" | "gemini" | "kiro" | "opencode";
@@ -45,7 +44,7 @@ export function agentDestination(agent: AgentId): string {
 }
 
 export async function loadAgentTemplate(agent: AgentId): Promise<string> {
-  const frontmatter = (await readFile(join(AGENTS_DIR, `${agent}.md`), "utf-8")).trim();
+  const frontmatter = (await Bun.file(join(AGENTS_DIR, `${agent}.md`)).text()).trim();
   const body = buildSubagentBody(AGENT_NATIVE_TOOLS[agent]);
   return `${frontmatter}\n\n${body}\n`;
 }
@@ -59,7 +58,6 @@ export async function writeAgentFile(
   if (existing && !options.force) {
     throw new Error(`${dest} already exists. Run with --force to overwrite.`);
   }
-  await mkdir(dirname(dest), { recursive: true });
   const content = await loadAgentTemplate(agent);
   await Bun.write(dest, content);
   return dest;

package/src/brand-banner.ts

@@ -0,0 +1,151 @@
+/**
+ * Framed CLI banner: wordmark + Takara crane art + subtitle.
+ * Shown on interactive help/setup when the output stream is a color TTY.
+ * Regenerate crane rows with: bun run scripts/render-crane-art.ts
+ */
+import packageJson from "../package.json";
+import {
+  brandColor,
+  colorEnabled,
+  dim,
+  displayWidth,
+  hexToRgb,
+  padLineToWidth,
+} from "./terminal.ts";
+
+const BRAND_SUBTITLE = "hybrid code search for agents by takara.ai";
+const BRAND_INDENT = "  ";
+const BRAND_WELCOME = "Welcome to Miru";
+const COLUMN_GAP = 4;
+const BANNER_MIN_COLUMNS = 72; // below this width, print subtitle only (compact mode)
+
+// Takara brand palette — hex is source of truth; RGB derived for ANSI SGR.
+const BRAND_HEX = {
+  grey: "#4a4d4e",
+  red: "#d91009",
+} as const;
+
+const BRAND_RGB = {
+  grey: hexToRgb(BRAND_HEX.grey),
+  red: hexToRgb(BRAND_HEX.red),
+} as const satisfies Record<string, readonly [number, number, number]>;
+
+const MIRU_WORDMARK = [
+  "███╗   ███╗ ██╗ ██████╗  ██╗   ██╗",
+  "████╗ ████║ ██║ ██╔══██╗ ██║   ██║",
+  "██╔████╔██║ ██║ ██████╔╝ ██║   ██║",
+  "██║╚██╔╝██║ ██║ ██╔══██╗ ██║   ██║",
+  "██║ ╚═╝ ██║ ██║ ██║  ██║ ╚██████╔╝",
+  "╚═╝     ╚═╝ ╚═╝ ╚═╝  ╚═╝  ╚═════╝ ",
+] as const;
+
+// Padded rows preserve crane silhouette when merged beside the wordmark.
+// Do not crop per-row leading spaces — that breaks the half-block shape.
+const TAKARA_CRANE = [
+  "█▄                    ",
+  " ▀█▄          ▄▄██    ",
+  "  ▀██       ▄████▀    ",
+  "   ▀██▄  ▄███████     ",
+  "     ███████████ ▄██▄ ",
+  "     ▄█████████▄██▀▀█▄",
+  "    ▄████████████▀   ▀",
+  "    ███████████▀      ",
+  "   ███████▀  ▀        ",
+  "  ▄████▀              ",
+  "  ██▀                 ",
+];
+
+export function isQuietBrand(): boolean {
+  // MIRU_QUIET=1 skips the framed banner on narrow or scripted terminals.
+  const value = process.env.MIRU_QUIET?.trim().toLowerCase();
+  return value === "1" || value === "true" || value === "yes";
+}
+
+function colorCell(
+  plain: string,
+  width: number,
+  rgb: readonly [number, number, number],
+  stream: NodeJS.WriteStream,
+): string {
+  if (!plain) {
+    return " ".repeat(width);
+  }
+  return padLineToWidth(brandColor(plain, rgb, stream), width);
+}
+
+function mergeArt(
+  stream: NodeJS.WriteStream,
+  leftWidth: number,
+  rightWidth: number,
+  wordmarkStart: number,
+): string[] {
+  // Crane is taller than the wordmark; offset wordmark rows so both are vertically centered.
+  const height = Math.max(wordmarkStart + MIRU_WORDMARK.length, TAKARA_CRANE.length);
+  const gap = " ".repeat(COLUMN_GAP);
+  const rows: string[] = [];
+
+  for (let i = 0; i < height; i++) {
+    const wordmark =
+      i >= wordmarkStart && i < wordmarkStart + MIRU_WORDMARK.length
+        ? (MIRU_WORDMARK[i - wordmarkStart] ?? "")
+        : "";
+    const crane = i < TAKARA_CRANE.length ? (TAKARA_CRANE[i] ?? "") : "";
+    rows.push(
+      colorCell(wordmark, leftWidth, BRAND_RGB.grey, stream) +
+        gap +
+        colorCell(crane, rightWidth, BRAND_RGB.red, stream),
+    );
+  }
+
+  return rows;
+}
+
+function frameLine(prefix: string, suffix: string, frameWidth: number): string {
+  const pad = Math.max(0, frameWidth - displayWidth(prefix) - displayWidth(suffix));
+  return `${prefix}${" ".repeat(pad)}${suffix}`;
+}
+
+export function formatBrandBannerLines(stream: NodeJS.WriteStream = process.stdout): string[] {
+  const versionLabel = `Version ${packageJson.version}`;
+  const leftWidth = Math.max(...MIRU_WORDMARK.map(displayWidth));
+  const rightWidth = Math.max(...TAKARA_CRANE.map(displayWidth));
+  // Frame must fit art and corner labels (welcome top-left, version bottom-right).
+  const frameWidth = Math.max(
+    leftWidth + COLUMN_GAP + rightWidth,
+    displayWidth(`┌ ${BRAND_WELCOME}`) + 1,
+    displayWidth(`└ ${versionLabel} ┘`),
+  );
+  const wordmarkStart = Math.max(0, Math.floor((TAKARA_CRANE.length - MIRU_WORDMARK.length) / 2));
+
+  const lines = [
+    frameLine(`┌ ${dim(BRAND_WELCOME, stream)}`, "┐", frameWidth),
+    ...mergeArt(stream, leftWidth, rightWidth, wordmarkStart).map((line) =>
+      padLineToWidth(line, frameWidth),
+    ),
+    frameLine("└", `${dim(versionLabel, stream)} ┘`, frameWidth),
+    "",
+    padLineToWidth(dim(BRAND_SUBTITLE, stream), frameWidth),
+  ];
+
+  return lines.map((line) => (line.length > 0 ? `${BRAND_INDENT}${line}` : line));
+}
+
+export function printBrandBanner(
+  stream: NodeJS.WriteStream = process.stdout,
+  compact = false,
+): void {
+  // No ANSI on pipes, CI logs, or when NO_COLOR is set.
+  if (!colorEnabled(stream)) {
+    return;
+  }
+
+  const useCompact = compact || (stream.columns ?? 80) < BANNER_MIN_COLUMNS || isQuietBrand();
+  if (useCompact) {
+    stream.write(`${dim(BRAND_SUBTITLE, stream)}\n`);
+    return;
+  }
+
+  for (const line of formatBrandBannerLines(stream)) {
+    stream.write(`${line}\n`);
+  }
+}

package/src/cache.ts

@@ -1,4 +1,11 @@
-import { createHash } from "node:crypto";
+/**
+ * On-disk index cache: location resolution, cache-key hashing, validation, and load.
+ *
+ * Each indexed source (local directory path or git URL + ref) maps to a SHA-256
+ * subdirectory under the Miru cache folder. `MiruIndex.fromPath` / `fromGit` call
+ * `getValidatedCache` before rebuilding; on hit they hydrate via `loadCachedIndex`.
+ */
+
 import { rm } from "node:fs/promises";
 import { join } from "node:path";
 import { resolveEmbeddingDimensions, resolveEmbeddingModel } from "./embeddings/openai.ts";
@@ -15,6 +22,7 @@ import { chunkFromDict } from "./types.ts";
 import { computeSourceCacheKey } from "./utils.ts";
 import { indexCacheEpoch } from "./version.ts";
 
+/** Platform cache root; override with `MIRU_CACHE_HOME`. */
 export function resolveCacheFolder(): string {
   const override = process.env.MIRU_CACHE_HOME?.trim();
   if (override) {
@@ -36,12 +44,21 @@ export function resolveCacheFolder(): string {
   return base;
 }
 
+/**
+ * Path to the saved index bundle for a source.
+ *
+ * `path` is a resolved local directory or a git cache key (`url` or `url@ref`).
+ * The on-disk folder name is SHA-256 of that key so paths stay short and safe.
+ */
 export function findIndexCachePath(path: string, ref?: string | null): string {
   const normalized = computeSourceCacheKey(path, ref);
-  const subdir = createHash("sha256").update(normalized, "utf-8").digest("hex");
+  const hasher = new Bun.CryptoHasher("sha256");
+  hasher.update(normalized);
+  const subdir = hasher.digest("hex");
   return join(resolveCacheFolder(), subdir, "index");
 }
 
+/** True when saved metadata still matches the requested index configuration. */
 function metadataMatches(
   metadata: Record<string, unknown>,
   embeddingModel: string,
@@ -80,6 +97,15 @@ function metadataMatches(
   }
 }
 
+/**
+ * Return a cache directory path when a complete, compatible bundle exists; otherwise `null`.
+ *
+ * Checks persisted files, metadata (epoch, model, content types, vector storage),
+ * semantic index shape, and — for local indexes — that `root_path` and listed
+ * `file_paths` still exist (needed for incremental `applyFileChanges`).
+ *
+ * Stale `index_epoch` entries are deleted; other mismatches are left on disk.
+ */
 export async function getValidatedCache(
   path: string,
   embeddingModel: string | undefined,
@@ -132,6 +158,7 @@ export async function getValidatedCache(
   return indexPath;
 }
 
+/** Load BM25, semantic vectors, chunks, and metadata from a validated cache path. */
 export async function loadCachedIndex(indexPath: string): Promise<{
   bm25: Awaited<ReturnType<typeof loadBm25>>;
   semantic: Awaited<ReturnType<typeof loadSemantic>>;
@@ -147,6 +174,7 @@ export async function loadCachedIndex(indexPath: string): Promise<{
   return { bm25, semantic, chunks, metadata };
 }
 
+/** Remove the cached index bundle for a source (same key as `findIndexCachePath`). */
 export async function clearCache(path: string): Promise<void> {
   const indexPath = findIndexCachePath(path);
   await rm(indexPath, { recursive: true, force: true });

package/src/cli-ui.ts

@@ -1,66 +1,26 @@
+import { printBrandBanner } from "./brand-banner.ts";
+import { bold, colorEnabled, cyan, dim, green, magenta, red, yellow } from "./terminal.ts";
 import type { SearchResult } from "./types.ts";
 import { formatRelevanceScore } from "./utils.ts";
 
-const ANSI = {
-  reset: "\x1b[0m",
-  bold: "\x1b[1m",
-  dim: "\x1b[2m",
-  cyan: "\x1b[36m",
-  green: "\x1b[32m",
-  red: "\x1b[31m",
-  yellow: "\x1b[33m",
-  magenta: "\x1b[35m",
-} as const;
-
-function colorEnabled(stream: NodeJS.WriteStream = process.stdout): boolean {
-  return stream.isTTY && process.env.NO_COLOR === undefined;
-}
-
-function paint(text: string, code: string, stream?: NodeJS.WriteStream): string {
-  if (!colorEnabled(stream)) {
-    return text;
-  }
-  return `${code}${text}${ANSI.reset}`;
-}
-
-export function bold(text: string, stream?: NodeJS.WriteStream): string {
-  return paint(text, ANSI.bold, stream);
-}
-
-export function dim(text: string, stream?: NodeJS.WriteStream): string {
-  return paint(text, ANSI.dim, stream);
-}
-
-export function cyan(text: string, stream?: NodeJS.WriteStream): string {
-  return paint(text, ANSI.cyan, stream);
-}
-
-export function green(text: string, stream?: NodeJS.WriteStream): string {
-  return paint(text, ANSI.green, stream);
-}
-
-export function red(text: string, stream?: NodeJS.WriteStream): string {
-  return paint(text, ANSI.red, stream);
-}
-
-export function yellow(text: string, stream?: NodeJS.WriteStream): string {
-  return paint(text, ANSI.yellow, stream);
-}
-
-export function magenta(text: string, stream?: NodeJS.WriteStream): string {
-  return paint(text, ANSI.magenta, stream);
-}
-
-export function isInteractiveStdout(): boolean {
-  return process.stdout.isTTY && process.env.NO_COLOR === undefined;
-}
+export { formatBrandBannerLines, isQuietBrand, printBrandBanner } from "./brand-banner.ts";
+// Re-export terminal + banner APIs for existing cli-ui consumers.
+export {
+  bold,
+  cyan,
+  dim,
+  green,
+  magenta,
+  red,
+  yellow,
+} from "./terminal.ts";
 
 export function prefersJsonOutput(jsonFlag: boolean): boolean {
   return jsonFlag || !process.stdout.isTTY;
 }
 
 export function brandTitle(): string {
-  return bold("Miru", process.stderr) + dim(" (見る)", process.stderr);
+  return bold("MIRU", process.stderr) + dim(" (見る)", process.stderr);
 }
 
 export function writeStdout(line = ""): void {
@@ -72,15 +32,33 @@ export function writeStderr(line = ""): void {
 }
 
 export function divider(char = "─", width = 52, stream: NodeJS.WriteStream = process.stdout): void {
-  const line = char.repeat(width);
-  stream.write(`${dim(line, stream)}\n`);
+  stream.write(`${dim(char.repeat(width), stream)}\n`);
+}
+
+function showBanner(stream: NodeJS.WriteStream = process.stdout): boolean {
+  // Full banner replaces the plain "MIRU · title" header on color TTYs.
+  if (!colorEnabled(stream)) {
+    return false;
+  }
+  printBrandBanner(stream);
+  return true;
+}
+
+export function header(): void {
+  writeStdout("");
+  if (!showBanner()) {
+    writeStdout(brandTitle());
+  }
+  divider();
 }
 
-export function header(title: string, subtitle?: string): void {
+export function commandHeader(name: string, summary: string): void {
   writeStdout("");
-  writeStdout(brandTitle() + (title ? dim(` · ${title}`) : ""));
-  if (subtitle) {
-    writeStdout(dim(subtitle));
+  if (!showBanner()) {
+    writeStdout(`${brandTitle()} ${name}`);
+    writeStdout(summary);
+  } else {
+    writeStdout(summary);
   }
   divider();
 }
@@ -176,7 +154,8 @@ export function formatSearchResultsPretty(query: string, results: SearchResult[]
     }
   }
 
-  if (isInteractiveStdout()) {
+  if (colorEnabled(process.stdout)) {
+    // Only nudge interactive users; JSON output should stay machine-clean.
     lines.push("");
     lines.push(dim("Tip: add --json for machine-readable output"));
   }

package/src/cli.ts

@@ -44,7 +44,7 @@ import {
 } from "./utils.ts";
 import { maybeNotifyUpdate, miruVersion } from "./version.ts";
 
-loadEnvFiles();
+await loadEnvFiles();
 normalizeTakaraApiKeyEnv();
 await loadStoredCredentials();
 
@@ -158,7 +158,7 @@ async function runSearch(
 
   const index = await withSpinner("Indexing and searching", async () => {
     const built = await MiruIndex.fromSource(path, content);
-    await built.saveToDefaultCache(path);
+    await built.saveToCache(path);
     const results = await built.search({ query, topK });
     return { index: built, results };
   });
@@ -188,7 +188,7 @@ async function runExpand(
       before,
       after,
     );
-    await built.saveToDefaultCache(path);
+    await built.saveToCache(path);
     return formatExpandResults(filePath, line, anchor, expanded, {
       repoRoot,
       before,
@@ -231,7 +231,7 @@ async function runFindRelated(
       throw new RelatedChunkNotFoundError(filePath, line);
     }
     const hits = await built.findRelated(chunk, topK);
-    await built.saveToDefaultCache(path);
+    await built.saveToCache(path);
     return {
       results: hits,
       label: formatRelatedHeader(filePath, line),

package/src/concurrency.ts

@@ -1,15 +1,25 @@
-import { availableParallelism, cpus } from "node:os";
+/**
+ * Concurrency helpers for indexing and embedding pipelines.
+ *
+ * Caps parallel file parsing, BM25 scoring, and embed batching so Miru stays
+ * responsive on laptops and shared CI runners without starving the OS.
+ */
+import { availableParallelism } from "node:os";
 
-const DEFAULT_RESERVE_CORES = 2;
+/** Cores left for the event loop, MCP stdio, and other host processes during indexing. */
+export const DEFAULT_RESERVE_CORES = 2;
 
-export function resolveCpuCount(): number {
-  if (typeof availableParallelism === "function") {
-    return availableParallelism();
-  }
-  return cpus().length;
+function workerCount(concurrency: number, itemCount: number): number {
+  return Math.max(1, Math.min(concurrency, itemCount));
 }
 
-/** Worker pool size: logical CPUs minus 2, minimum 1. Override with MIRU_CONCURRENCY. */
+/**
+ * Worker pool size for file parsing and other CPU-bound index work.
+ *
+ * Default: `availableParallelism() - DEFAULT_RESERVE_CORES`, floored at 1.
+ * Override with `MIRU_CONCURRENCY` or legacy alias `MIRU_WORKERS`.
+ * Invalid env values are ignored so a typo does not crash indexing.
+ */
 export function resolveWorkerConcurrency(): number {
   const raw = process.env.MIRU_CONCURRENCY ?? process.env.MIRU_WORKERS;
   if (raw) {
@@ -18,37 +28,34 @@ export function resolveWorkerConcurrency(): number {
       return Math.floor(n);
     }
   }
-  return Math.max(1, resolveCpuCount() - DEFAULT_RESERVE_CORES);
+  return Math.max(1, availableParallelism() - DEFAULT_RESERVE_CORES);
 }
 
-/** Run async work over items with at most `concurrency` tasks in flight. Results keep input order. */
+/**
+ * Bounded parallel map: at most `concurrency` workers run `worker` at once.
+ *
+ * Unlike `Promise.all(items.map(worker))`, this limits in-flight tasks when
+ * `items` is large (e.g. thousands of source files). Output order matches
+ * input order because each result is stored at its original index.
+ *
+ * Workers share a single `items.entries()` iterator; each claims the next
+ * `[index, item]` pair until the input is exhausted.
+ */
 export async function mapPool<T, R>(
   items: readonly T[],
   concurrency: number,
   worker: (item: T, index: number) => Promise<R>,
 ): Promise<R[]> {
-  if (items.length === 0) {
-    return [];
-  }
-
-  const limit = Math.max(1, Math.min(concurrency, items.length));
   const results = new Array<R>(items.length);
-  let nextIndex = 0;
+  const pending = items.entries();
 
-  async function drain(): Promise<void> {
-    while (true) {
-      const i = nextIndex++;
-      if (i >= items.length) {
-        return;
+  await Promise.all(
+    Array.from({ length: workerCount(concurrency, items.length) }, async () => {
+      for (const [i, item] of pending) {
+        results[i] = await worker(item, i);
       }
-      const item = items[i];
-      if (item === undefined) {
-        continue;
-      }
-      results[i] = await worker(item, i);
-    }
-  }
+    }),
+  );
 
-  await Promise.all(Array.from({ length: limit }, () => drain()));
   return results;
 }