@ff-labs/pi-fff 0.10.2-nightly.fde8c52 → 0.10.3

package/README.md

@@ -134,7 +134,8 @@ Mode precedence:
 - `--fff-mode <mode>` — set mode (see above)
 - `--fff-frecency-db <path>` — path to frecency database (also: `FFF_FRECENCY_DB` env)
 - `--fff-history-db <path>` — path to query history database (also: `FFF_HISTORY_DB` env)
-- `--fff-enable-root-scan` — allow indexing when launched from `/` (also: `FFF_ENABLE_ROOT_SCAN=1` env). FFF refuses to init at the filesystem root by default. Home directory scanning is always enabled for pi.
+- `--fff-enable-root-scan` — allow indexing when launched from `/` (also: `FFF_ENABLE_ROOT_SCAN=1` env). FFF refuses to init at the filesystem root by default.
+- `--fff-enable-home-scan` — index the home directory when launched from `$HOME` (also: `FFF_ENABLE_HOME_SCAN` env). Enabled by default. Disable with `--fff-enable-home-scan=false` or `FFF_ENABLE_HOME_SCAN=0` if your `$HOME` contains huge trees (toolchains, kernel sources, build outputs) that make the background index run for a long time. When launched from `$HOME` with this enabled, pi shows a warning that the whole home tree is being indexed.
 
 ## Data
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ff-labs/pi-fff",
   "public": true,
-  "version": "0.10.2-nightly.fde8c52",
+  "version": "0.10.3",
   "description": "pi extension: FFF-powered fuzzy file and content search",
   "type": "module",
   "license": "MIT",
@@ -40,8 +40,8 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@ff-labs/fff-bun": "*",
-    "@ff-labs/fff-node": "*"
+    "@ff-labs/fff-bun": "0.10.3",
+    "@ff-labs/fff-node": "0.10.3"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",

package/src/aux-finders.ts

@@ -1,7 +1,7 @@
 import fs from "node:fs";
-import os from "node:os";
 import path from "node:path";
 import type { FileFinderApi } from "@ff-labs/fff-node";
+import { HOME_DIR } from "./paths";
 import { loadSdk, SCAN_TIMEOUT_MS } from "./sdk";
 
 export const MAX_AUX = 3;
@@ -15,10 +15,17 @@ interface AuxPicker {
 
 export interface AuxOpts {
   enableFsRootScanning: boolean;
+  enableHomeDirScanning?: boolean;
+  // Called before a newly spawned aux picker starts a scan that covers $HOME.
+  onHomeDirScan?: (root: string) => void;
 }
 
 export class AuxFinderPool {
   private entries: AuxPicker[] = [];
+  // In-flight creations keyed by root. Concurrent acquire() calls for the same
+  // (or a covering) root share one finder/scan instead of each starting a full
+  // duplicate traversal — issue #746. Mirrors the main finder's finderPromise.
+  private pending = new Map<string, Promise<AuxPicker>>();
   constructor(private opts: AuxOpts) {}
 
   destroy(): void {
@@ -27,6 +34,7 @@ export class AuxFinderPool {
     }
 
     this.entries = [];
+    this.pending.clear();
   }
 
   private sweepIdle(now = Date.now()): void {
@@ -58,32 +66,60 @@ export class AuxFinderPool {
       return { finder: covering.finder, root: covering.root };
     }
 
+    // Coalesce concurrent creations for the same root so we scan once. A slow
+    // full-home scan started by one call is awaited by the others instead of
+    // each spawning its own traversal (#746).
+    const inflight = this.pending.get(maybeRoot);
+    if (inflight) {
+      const e = await inflight;
+      e.lastUsed = Date.now();
+      return { finder: e.finder, root: e.root };
+    }
+
+    const creation = this.create(maybeRoot).finally(() => {
+      this.pending.delete(maybeRoot);
+    });
+    this.pending.set(maybeRoot, creation);
+    const entry = await creation;
+    return { finder: entry.finder, root: entry.root };
+  }
+
+  private async create(root: string): Promise<AuxPicker> {
     if (this.entries.length >= MAX_AUX) {
       let oldest = this.entries[0];
-      for (const e of this.entries)
-        if (e.lastUsed < oldest.lastUsed) oldest = e;
+      for (const e of this.entries) if (e.lastUsed < oldest.lastUsed) oldest = e;
       if (!oldest.finder.isDestroyed) oldest.finder.destroy();
       this.entries = this.entries.filter((e) => e !== oldest);
     }
 
+    const enableHomeDirScanning = this.opts.enableHomeDirScanning ?? true;
+    // A fresh picker rooted at (or above) $HOME walks the whole home tree, so
+    // the user gets told every time the agent spawns one — see issue #743.
+    if (enableHomeDirScanning && rootCovers(root, HOME_DIR)) {
+      this.opts.onHomeDirScan?.(root);
+    }
+
     const { FileFinder } = await loadSdk();
     // LMDB env can only be opened once per process; the main finder already
     // owns the frecency/history DBs. Aux finders are transient and run without
     // persistent scoring — see issue #700.
     const result = FileFinder.create({
-      basePath: maybeRoot,
+      basePath: root,
       aiMode: true,
-      enableHomeDirScanning: true,
+      enableHomeDirScanning,
       enableFsRootScanning: this.opts.enableFsRootScanning,
     });
     if (!result.ok)
-      throw new Error(
-        `Failed to create aux file finder for ${maybeRoot}: ${result.error}`,
-      );
+      throw new Error(`Failed to create aux file finder for ${root}: ${result.error}`);
 
     await result.value.waitForScan(SCAN_TIMEOUT_MS);
-    this.entries.push({ root: maybeRoot, finder: result.value, lastUsed: Date.now() });
-    return { finder: result.value, root: maybeRoot };
+    const entry: AuxPicker = {
+      root,
+      finder: result.value,
+      lastUsed: Date.now(),
+    };
+    this.entries.push(entry);
+    return entry;
   }
 
   size(): number {
@@ -96,9 +132,7 @@ export class AuxFinderPool {
 // remainder usable as a fuzzy path constraint relative to that root. Glob and
 // nonexistent segments both go into the suffix: we walk up to the nearest
 // existing ancestor so partially-wrong paths still resolve to a search root.
-export function resolveAuxRoot(
-  absPath: string,
-): { root: string; suffix: string } | null {
+export function resolveAuxRoot(absPath: string): { root: string; suffix: string } | null {
   const trimmed = path.normalize(absPath.trim()).replace(/\/+$/, "") || "/";
   if (!path.isAbsolute(trimmed)) return null;
   if (trimmed === path.sep) return { root: path.sep, suffix: "" };
@@ -147,7 +181,7 @@ export function routePathConstraint(
   let candidate = pathConstraint.trim();
   if (!candidate) return null;
   if (candidate === "~" || candidate.startsWith("~/"))
-    candidate = path.join(os.homedir(), candidate.slice(1));
+    candidate = path.join(HOME_DIR, candidate.slice(1));
   if (!path.isAbsolute(candidate)) {
     // Plain workspace-relative constraints stay on the workspace finder.
     if (candidate !== ".." && !candidate.startsWith("../")) return null;
@@ -158,7 +192,6 @@ export function routePathConstraint(
   return resolveAuxRoot(candidate);
 }
 
-
 export function rootCovers(root: string, target: string): boolean {
   if (root === target) return true;
   const prefix = root.endsWith(path.sep) ? root : root + path.sep;

package/src/index.ts

@@ -23,6 +23,7 @@ import type {
 import { Type } from "@sinclair/typebox";
 import { AuxFinderPool, routePathConstraint } from "./aux-finders";
 import { buildQuery } from "./query";
+import { isHomeDir } from "./paths";
 import { loadSdk, SCAN_TIMEOUT_MS } from "./sdk";
 
 export { SCAN_TIMEOUT_MS } from "./sdk";
@@ -36,6 +37,14 @@ const DEFAULT_FIND_LIMIT = 30;
 const GREP_MAX_LINE_LENGTH = 500;
 const MENTION_MAX_RESULTS = 20;
 
+// If we exceed 10 seconds for indexed grep - something is definitely off
+const GREP_TIME_BUDGET_MS = 10_000;
+
+const HOME_SCAN_STATUS_KEY = "fff";
+const HOME_SCAN_POLL_MS = 1_000;
+const HOME_SCAN_DISABLE_HINT =
+  "You can prevent home dir indexing with --fff-enable-home-scan=false (or FFF_ENABLE_HOME_SCAN=0).";
+
 type FffMode = "tools-and-ui" | "tools-only" | "override";
 
 const VALID_MODES: FffMode[] = ["tools-and-ui", "tools-only", "override"];
@@ -261,9 +270,7 @@ function createFffMentionProvider(
 
       const query = prefix.startsWith('@"') ? prefix.slice(2) : prefix.slice(1);
       const items = await getItems(query, options.signal);
-      return options.signal.aborted || items.length === 0
-        ? null
-        : { items, prefix };
+      return options.signal.aborted || items.length === 0 ? null : { items, prefix };
     },
     applyCompletion(_lines, cursorLine, cursorCol, item, prefix) {
       const currentLine = _lines[cursorLine] || "";
@@ -272,11 +279,7 @@ function createFffMentionProvider(
       const newLine = before + item.value + after;
       const newCursorCol = cursorCol - prefix.length + item.value.length;
       return {
-        lines: [
-          ..._lines.slice(0, cursorLine),
-          newLine,
-          ..._lines.slice(cursorLine + 1),
-        ],
+        lines: [..._lines.slice(0, cursorLine), newLine, ..._lines.slice(cursorLine + 1)],
         cursorLine,
         cursorCol: newCursorCol,
       };
@@ -316,20 +319,32 @@ export default function fffExtension(pi: ExtensionAPI) {
     process.env.FFF_HISTORY_DB ??
     undefined;
 
-  // Root scanning opt-in: flag (boolean) > env ("1"/"true") > false.
-  // FFF refuses to init at / unless this is set. Home dir scanning is on by
-  // default for pi — launching pi from $HOME is a normal flow.
-  function resolveBoolOpt(flagName: string, envName: string): boolean {
+  // flag (boolean) > env ("1"/"true", or "0"/"false") > default.
+  function resolveBoolOpt(
+    flagName: string,
+    envName: string,
+    fallback = false,
+  ): boolean {
     const flag = pi.getFlag(flagName);
     if (typeof flag === "boolean") return flag;
     if (typeof flag === "string") return flag === "true" || flag === "1";
     const env = process.env[envName];
-    return env === "1" || env === "true";
+    if (env === "1" || env === "true") return true;
+    if (env === "0" || env === "false") return false;
+    return fallback;
   }
+  // Root scanning opt-in: FFF refuses to init at / unless this is set.
   const enableFsRootScanning = resolveBoolOpt(
     "fff-enable-root-scan",
     "FFF_ENABLE_ROOT_SCAN",
   );
+  // Home dir scanning is on by default (launching pi from $HOME is a normal
+  // flow), but configurable so users with huge $HOME trees can opt out.
+  const enableHomeDirScanning = resolveBoolOpt(
+    "fff-enable-home-scan",
+    "FFF_ENABLE_HOME_SCAN",
+    true,
+  );
 
   function getMode(): FffMode {
     return currentMode;
@@ -343,8 +358,27 @@ export default function fffExtension(pi: ExtensionAPI) {
     return currentMode !== "tools-only";
   }
 
+  // Set on session_start; the only handle to the UI outside an event handler.
+  // setStatus is TUI/RPC-only, hence optional.
+  let uiCtx: {
+    ui: {
+      notify: (message: string, type?: "info" | "warning" | "error") => void;
+      setStatus?: (key: string, text: string | undefined) => void;
+    };
+  } | null = null;
+  let homeScanTimer: ReturnType<typeof setInterval> | null = null;
+
+  function warnHomeDirScan(root: string): void {
+    uiCtx?.ui.notify(
+      `(fff): Your cwd (${root}) is too large. Indexing will take additional time and resources.\n${HOME_SCAN_DISABLE_HINT}`,
+      "warning",
+    );
+  }
+
   let auxPool = new AuxFinderPool({
     enableFsRootScanning,
+    enableHomeDirScanning,
+    onHomeDirScan: warnHomeDirScan,
   });
 
   // in case cwd changes we need to figure this out
@@ -367,7 +401,7 @@ export default function fffExtension(pi: ExtensionAPI) {
         frecencyDbPath,
         historyDbPath,
         aiMode: true,
-        enableHomeDirScanning: true,
+        enableHomeDirScanning,
         enableFsRootScanning,
       });
 
@@ -385,7 +419,40 @@ export default function fffExtension(pi: ExtensionAPI) {
     return finderPromise;
   }
 
+  function stopHomeScanStatus(): void {
+    if (homeScanTimer) {
+      clearInterval(homeScanTimer);
+      homeScanTimer = null;
+    }
+    uiCtx?.ui.setStatus?.(HOME_SCAN_STATUS_KEY, undefined);
+  }
+
+  // waitForScan() resolves on timeout too, so the scan can still be running.
+  // Poll the live progress until it settles, then clear the footer.
+  function trackHomeScanStatus(): void {
+    stopHomeScanStatus();
+    if (!uiCtx?.ui.setStatus) return;
+
+    const tick = () => {
+      const progress = mainFinder?.getScanProgress?.();
+      if (!progress?.ok || !progress.value.isScanning) {
+        stopHomeScanStatus();
+        return;
+      }
+      uiCtx?.ui.setStatus?.(
+        HOME_SCAN_STATUS_KEY,
+        `Agent is indexing $HOME (${progress.value.scannedFilesCount} files), this can lead to high CPU`,
+      );
+    };
+
+    homeScanTimer = setInterval(tick, HOME_SCAN_POLL_MS);
+    // Must not hold the process open once pi is done.
+    (homeScanTimer as { unref?: () => void }).unref?.();
+    tick();
+  }
+
   function destroyFinder() {
+    stopHomeScanStatus();
     if (mainFinder && !mainFinder.isDestroyed) {
       mainFinder.destroy();
       mainFinder = null;
@@ -407,9 +474,7 @@ export default function fffExtension(pi: ExtensionAPI) {
     const aux = await auxPool.acquire(route.root);
     // A broader covering picker may have been reused; rebase the suffix so the
     // constraint stays relative to the picker's actual root.
-    const rebase = nodePath
-      .relative(aux.root, route.root)
-      .replaceAll(nodePath.sep, "/");
+    const rebase = nodePath.relative(aux.root, route.root).replaceAll(nodePath.sep, "/");
     const suffix = [rebase, route.suffix].filter(Boolean).join("/");
     const query = buildQuery(suffix || undefined, pattern, exclude, aux.root);
     return { finder: aux.finder, query, root: aux.root };
@@ -426,22 +491,20 @@ export default function fffExtension(pi: ExtensionAPI) {
     const result = f.mixedSearch(query, { pageSize: MENTION_MAX_RESULTS });
     if (!result.ok) return [];
 
-    return result.value.items
-      .slice(0, MENTION_MAX_RESULTS)
-      .map((mixed: MixedItem) => {
-        if (mixed.type === "directory") {
-          return {
-            value: buildAtCompletionValue(mixed.item.relativePath),
-            label: mixed.item.dirName,
-            description: mixed.item.relativePath,
-          };
-        }
+    return result.value.items.slice(0, MENTION_MAX_RESULTS).map((mixed: MixedItem) => {
+      if (mixed.type === "directory") {
         return {
           value: buildAtCompletionValue(mixed.item.relativePath),
-          label: mixed.item.fileName,
+          label: mixed.item.dirName,
           description: mixed.item.relativePath,
         };
-      });
+      }
+      return {
+        value: buildAtCompletionValue(mixed.item.relativePath),
+        label: mixed.item.fileName,
+        description: mixed.item.relativePath,
+      };
+    });
   }
 
   function registerAutocompleteProvider(ctx: {
@@ -477,21 +540,11 @@ export default function fffExtension(pi: ExtensionAPI) {
           return current.getSuggestions(lines, cursorLine, cursorCol, options);
         },
         applyCompletion(lines, cursorLine, cursorCol, item, prefix) {
-          return current.applyCompletion(
-            lines,
-            cursorLine,
-            cursorCol,
-            item,
-            prefix,
-          );
+          return current.applyCompletion(lines, cursorLine, cursorCol, item, prefix);
         },
         shouldTriggerFileCompletion(lines, cursorLine, cursorCol) {
           return (
-            current.shouldTriggerFileCompletion?.(
-              lines,
-              cursorLine,
-              cursorCol,
-            ) ?? true
+            current.shouldTriggerFileCompletion?.(lines, cursorLine, cursorCol) ?? true
           );
         },
       };
@@ -506,14 +559,12 @@ export default function fffExtension(pi: ExtensionAPI) {
   });
 
   pi.registerFlag("fff-frecency-db", {
-    description:
-      "Path to the frecency database (overrides FFF_FRECENCY_DB env)",
+    description: "Path to the frecency database (overrides FFF_FRECENCY_DB env)",
     type: "string",
   });
 
   pi.registerFlag("fff-history-db", {
-    description:
-      "Path to the query history database (overrides FFF_HISTORY_DB env)",
+    description: "Path to the query history database (overrides FFF_HISTORY_DB env)",
     type: "string",
   });
 
@@ -523,9 +574,16 @@ export default function fffExtension(pi: ExtensionAPI) {
     type: "boolean",
   });
 
+  pi.registerFlag("fff-enable-home-scan", {
+    description:
+      "Index the home dir when launched from $HOME (default true; disable with --fff-enable-home-scan=false or FFF_ENABLE_HOME_SCAN=0)",
+    type: "boolean",
+  });
+
   pi.on("session_start", async (_event, ctx) => {
     try {
       activeCwd = ctx.cwd;
+      uiCtx = ctx as unknown as typeof uiCtx;
 
       // Restore persisted mode from session entries. This handles session
       // resume after process restart where env vars are lost, and ensures
@@ -552,6 +610,21 @@ export default function fffExtension(pi: ExtensionAPI) {
 
       registerAutocompleteProvider(ctx);
       await ensureFinder(activeCwd);
+
+      // Warn when launched from $HOME with home scanning on: indexing a large
+      // home tree can run for a long time in the background (issue #743).
+      const atHome = enableHomeDirScanning && isHomeDir(activeCwd);
+      if (atHome) {
+        warnHomeDirScan(activeCwd);
+        ctx.ui.setStatus?.(
+          HOME_SCAN_STATUS_KEY,
+          "Agent is indexing $HOME, this can lead to high CPU",
+        );
+      }
+
+      // waitForScan() also resolves on timeout, so poll until the scan really
+      // settles before clearing the footer.
+      if (atHome) trackHomeScanStatus();
     } catch (e: unknown) {
       ctx.ui.notify(
         `FFF init failed: ${e instanceof Error ? e.message : String(e)}`,
@@ -573,20 +646,15 @@ export default function fffExtension(pi: ExtensionAPI) {
     context: any,
     maxLines = 15,
   ) => {
-    const text =
-      (context.lastComponent as Text | undefined) ?? new Text("", 0, 0);
-    const output =
-      result.content?.find((c) => c.type === "text")?.text?.trim() ?? "";
+    const text = (context.lastComponent as Text | undefined) ?? new Text("", 0, 0);
+    const output = result.content?.find((c) => c.type === "text")?.text?.trim() ?? "";
     if (!output) {
       text.setText(theme.fg("muted", "No output"));
       return text;
     }
 
     const lines = output.split("\n");
-    const displayLines = lines.slice(
-      0,
-      options.expanded ? lines.length : maxLines,
-    );
+    const displayLines = lines.slice(0, options.expanded ? lines.length : maxLines);
     let content = `\n${displayLines.map((line: string) => theme.fg("toolOutput", line)).join("\n")}`;
     if (lines.length > displayLines.length) {
       content += theme.fg(
@@ -641,10 +709,10 @@ export default function fffExtension(pi: ExtensionAPI) {
     description: `Grep file contents. Smart-case, auto-detects regex vs literal, git-aware. Results are ranked by frecency (most-accessed files first); matches within a file stay in source order. Default limit ${DEFAULT_GREP_LIMIT}.`,
     promptSnippet: "Grep contents",
     promptGuidelines: [
-      "Prefer bare identifiers as patterns. Literal queries are most efficient.",
-      "Use path for include ('src/', '*.ts') and exclude for noise ('test/,*.min.js').",
-      "caseSensitive: true when you need exact case (smart-case otherwise).",
-      "After 1-2 greps, read the top match instead of more greps.",
+      `${toolNames.grep}: prefer bare identifiers as patterns. Literal queries are most efficient.`,
+      `${toolNames.grep}: use path for include ('src/', '*.ts') and exclude for noise ('test/,*.min.js').`,
+      `${toolNames.grep}: caseSensitive: true when you need exact case (smart-case otherwise).`,
+      `${toolNames.grep}: after 1-2 greps, read the top match instead of more greps.`,
     ],
     parameters: grepSchema,
 
@@ -652,11 +720,7 @@ export default function fffExtension(pi: ExtensionAPI) {
       if (signal?.aborted) throw new Error("Operation aborted");
 
       const pattern = params.pattern;
-      const aux = await resolveFinderForPath(
-        params.path,
-        pattern,
-        params.exclude,
-      );
+      const aux = await resolveFinderForPath(params.path, pattern, params.exclude);
 
       const picker = aux ? aux.finder : await ensureFinder(activeCwd);
       const effectiveLimit = Math.max(1, params.limit ?? DEFAULT_GREP_LIMIT);
@@ -667,8 +731,7 @@ export default function fffExtension(pi: ExtensionAPI) {
       // Auto-detect: regex if the pattern has regex metacharacters AND parses
       // as a valid regex, otherwise plain literal. The fuzzy fallback below
       // only kicks in for plain mode — regex queries are intentional.
-      const hasRegexSyntax =
-        pattern !== pattern.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+      const hasRegexSyntax = pattern !== pattern.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 
       let mode: GrepMode = hasRegexSyntax ? "regex" : "plain";
       if (mode === "regex") {
@@ -713,6 +776,7 @@ export default function fffExtension(pi: ExtensionAPI) {
         beforeContext: params.context ?? 0,
         afterContext: params.context ?? 0,
         classifyDefinitions: true,
+        timeBudgetMs: GREP_TIME_BUDGET_MS,
       });
 
       if (!grepResult.ok) throw new Error(grepResult.error);
@@ -720,8 +784,14 @@ export default function fffExtension(pi: ExtensionAPI) {
       let result = grepResult.value;
       let fuzzyNotice: string | null = null;
 
-      // automatic fuzzy fallback allows to broad the queries and find different cases
-      if (result.items.length === 0 && !params.cursor && mode !== "regex") {
+      // if we hit the timeout do not run the fuzzy fallback
+      // cause it will only consumer more time
+      if (
+        result.items.length === 0 &&
+        !result.nextCursor &&
+        !params.cursor &&
+        mode !== "regex"
+      ) {
         // When the caller pinned a specific file (path has an extension), the
         // fuzzy fallback broadens across the whole picker — the file may just
         // be misnamed. For directory constraints (or no path), we keep the
@@ -738,6 +808,7 @@ export default function fffExtension(pi: ExtensionAPI) {
           beforeContext: 0,
           afterContext: 0,
           classifyDefinitions: true,
+          timeBudgetMs: GREP_TIME_BUDGET_MS,
         });
 
         if (fuzzy.ok && fuzzy.value.items.length > 0) {
@@ -749,14 +820,10 @@ export default function fffExtension(pi: ExtensionAPI) {
       let output = formatGrepOutput(result);
       const notices: string[] = [];
       if (result.regexFallbackError) {
-        notices.push(
-          `Invalid regex: ${result.regexFallbackError}, used literal match`,
-        );
+        notices.push(`Invalid regex: ${result.regexFallbackError}, used literal match`);
       }
       if (result.nextCursor) {
-        notices.push(
-          `Continue with cursor="${storeCursor(result.nextCursor)}"`,
-        );
+        notices.push(`Continue with cursor="${storeCursor(result.nextCursor)}"`);
       }
 
       if (notices.length > 0) output += `\n\n[${notices.join(". ")}]`;
@@ -772,8 +839,7 @@ export default function fffExtension(pi: ExtensionAPI) {
     },
 
     renderCall(args, theme, context) {
-      const text =
-        (context.lastComponent as Text | undefined) ?? new Text("", 0, 0);
+      const text = (context.lastComponent as Text | undefined) ?? new Text("", 0, 0);
       const pattern = args?.pattern ?? "";
       const path = args?.path ?? ".";
       let content =
@@ -828,12 +894,12 @@ export default function fffExtension(pi: ExtensionAPI) {
     description: `Fuzzy path search and glob search. Matches against the whole repo-relative path, not just the filename. Frecency-ranked, git-aware. Multi-word = narrower (AND). Default limit ${DEFAULT_FIND_LIMIT}.`,
     promptSnippet: "Find files by path or glob",
     promptGuidelines: [
-      "Matches the WHOLE path, not just the filename — `profile` hits `chrome/browser/profiles/x.cc` too.",
-      "Keep queries to 1-2 terms; extra words narrow.",
-      "Use for paths, not content. Use grep for content.",
-      "For exact path matches use a glob in `path` — e.g. path: '**/profile.h' for exact filename, or path: 'src/**/profile.h' scoped to a subtree. Bare patterns are fuzzy.",
-      "To list everything inside a directory, pass path: 'dir/**' with an empty or wildcard pattern instead of using pattern alone.",
-      "Use exclude: 'test/,*.min.js' to cut noise in large repos.",
+      `${toolNames.find}: matches the WHOLE path, not just the filename — \`profile\` hits \`chrome/browser/profiles/x.cc\` too.`,
+      `${toolNames.find}: keep queries to 1-2 terms; extra words narrow.`,
+      `${toolNames.find}: use for paths, not content. Use ${toolNames.grep} for content.`,
+      `${toolNames.find}: for exact path matches use a glob in \`path\` — e.g. path: '**/profile.h' for exact filename, or path: 'src/**/profile.h' scoped to a subtree. Bare patterns are fuzzy.`,
+      `${toolNames.find}: to list everything inside a directory, pass path: 'dir/**' with an empty or wildcard pattern instead of using pattern alone.`,
+      `${toolNames.find}: use exclude: 'test/,*.min.js' to cut noise in large repos.`,
     ],
     parameters: findSchema,
 
@@ -845,16 +911,11 @@ export default function fffExtension(pi: ExtensionAPI) {
       const aux = resumed
         ? resumed.auxRoot
           ? {
-              finder: (await auxPool.acquire(resumed.auxRoot, { exact: true }))
-                .finder,
+              finder: (await auxPool.acquire(resumed.auxRoot, { exact: true })).finder,
               root: resumed.auxRoot,
             }
           : null
-        : await resolveFinderForPath(
-            params.path,
-            params.pattern,
-            params.exclude,
-          );
+        : await resolveFinderForPath(params.path, params.pattern, params.exclude);
 
       const picker = aux ? aux.finder : await ensureFinder(activeCwd);
       const effectiveLimit = resumed
@@ -886,8 +947,7 @@ export default function fffExtension(pi: ExtensionAPI) {
       // shown so far there's another page to fetch.
       const shownSoFar = pageIndex * effectiveLimit + result.items.length;
       const hasMore =
-        result.items.length >= effectiveLimit &&
-        result.totalMatched > shownSoFar;
+        result.items.length >= effectiveLimit && result.totalMatched > shownSoFar;
 
       const notices: string[] = [];
       if (formatted.weak && formatted.shownCount > 0)
@@ -922,8 +982,7 @@ export default function fffExtension(pi: ExtensionAPI) {
     },
 
     renderCall(args, theme, context) {
-      const text =
-        (context.lastComponent as Text | undefined) ?? new Text("", 0, 0);
+      const text = (context.lastComponent as Text | undefined) ?? new Text("", 0, 0);
       const pattern = args?.pattern ?? "";
       const path = args?.path ?? ".";
       let content =
@@ -956,9 +1015,7 @@ export default function fffExtension(pi: ExtensionAPI) {
       constraints: Type.Optional(
         Type.String({ description: "File filter, e.g. '*.{ts,tsx} !test/'" }),
       ),
-      context: Type.Optional(
-        Type.Number({ description: "Context lines before+after" }),
-      ),
+      context: Type.Optional(Type.Number({ description: "Context lines before+after" })),
       limit: Type.Optional(
         Type.Number({
           description: `Max matches (default ${DEFAULT_GREP_LIMIT})`,
@@ -974,9 +1031,9 @@ export default function fffExtension(pi: ExtensionAPI) {
         "Search file contents for ANY of multiple literal patterns (OR, SIMD Aho-Corasick). Faster than regex alternation.",
       promptSnippet: "Multi-pattern OR content search",
       promptGuidelines: [
-        "Use when searching for several identifiers at once.",
-        "Include all naming-convention variants (snake/camel/Pascal).",
-        "Patterns are literal. Use constraints for file filters.",
+        `${toolNames.multiGrep}: use when searching for several identifiers at once.`,
+        `${toolNames.multiGrep}: include all naming-convention variants (snake/camel/Pascal).`,
+        `${toolNames.multiGrep}: patterns are literal. Use constraints for file filters.`,
       ],
       parameters: multiGrepSchema,
 
@@ -1024,8 +1081,7 @@ export default function fffExtension(pi: ExtensionAPI) {
       },
 
       renderCall(args, theme, context) {
-        const text =
-          (context.lastComponent as Text | undefined) ?? new Text("", 0, 0);
+        const text = (context.lastComponent as Text | undefined) ?? new Text("", 0, 0);
         const patterns = args?.patterns ?? [];
         const constraints = args?.constraints;
         let content =
@@ -1047,8 +1103,7 @@ export default function fffExtension(pi: ExtensionAPI) {
   // --- commands ---
 
   pi.registerCommand("fff-mode", {
-    description:
-      "Show or set FFF mode: /fff-mode [tools-and-ui | tools-only | override]",
+    description: "Show or set FFF mode: /fff-mode [tools-and-ui | tools-only | override]",
     handler: async (args, ctx) => {
       const arg = (args || "").trim();
 
@@ -1062,10 +1117,7 @@ export default function fffExtension(pi: ExtensionAPI) {
 
       // Validate and set mode
       if (!VALID_MODES.includes(arg as FffMode)) {
-        ctx.ui.notify(
-          `Usage: /fff-mode [${VALID_MODES.join(" | ")}]`,
-          "warning",
-        );
+        ctx.ui.notify(`Usage: /fff-mode [${VALID_MODES.join(" | ")}]`, "warning");
         return;
       }
 

package/src/paths.ts

@@ -0,0 +1,9 @@
+import os from "node:os";
+import path from "node:path";
+
+// Resolved once per process: os.homedir() hits the env/passwd on every call.
+export const HOME_DIR = path.resolve(os.homedir());
+
+export function isHomeDir(dir: string): boolean {
+  return path.resolve(dir) === HOME_DIR;
+}

package/src/query.ts

@@ -10,11 +10,7 @@ export function normalizePathConstraint(
   if (path.isAbsolute(trimmed)) {
     const relative = path.relative(cwd, trimmed).replaceAll(path.sep, "/");
     if (relative === "") return null;
-    if (
-      relative.startsWith("../") ||
-      relative === ".." ||
-      path.isAbsolute(relative)
-    ) {
+    if (relative.startsWith("../") || relative === ".." || path.isAbsolute(relative)) {
       throw new Error(
         `Path constraint must be relative to the workspace: ${pathConstraint}`,
       );