[Bug]: pi-fff aborts init with an `error` notification when cwd is `$HOME` and `enableHomeDirScanning` is `false`

Which fff frontend?

Other / multiple

has logs

No log file available. @ff-labs/pi-fff never passes logFilePath to FileFinder.create(), so the Node SDK writes no log. See packages/pi-fff/src/file-picker.ts, openWithDbFallback(), where InitOptions is built from { ...options, aiMode: true } plus the two db paths only.

Description

Summary

Setting "enableHomeDirScanning": false should mean "never index $HOME". Instead, when a pi session starts with cwd === $HOME, the extension still asks the native layer for a picker rooted at $HOME. The native layer correctly refuses, and the refusal is surfaced to the user as an error notification:

Error: FFF init failed: Failed to create FFF file picker for /Users/<user>: Failed to init file picker: Can not run certain FFF features in a file system root or home directories. Consider smaller per-project directories.

So the option the user set to avoid the home scan is the exact reason an error is reported. The opt-out behaves like a hard failure instead of a skip.

This looks like a gap left over from #588, which added the two flags, and #743 / #572 / #745, which motivated them.

Environment

• @ff-labs/pi-fff 0.10.6
• @ff-labs/fff-node 0.10.6
• pi (@earendil-works/pi-coding-agent) 0.85.1
• Node v24.12.0
• macOS 15.7.9, arm64

<agent-dir>/pi-fff.json:

{
  "$schema": "https://raw.githubusercontent.com/dmtrKovalenko/fff/main/packages/pi-fff/pi-fff.schema.json",
  "mode": "override",
  "enableFsRootScanning": false,
  "enableHomeDirScanning": false,
  "warnOnHomeDirScan": true,
  "followSymlinks": true
}

Steps to reproduce

1. Write the pi-fff.json above into the pi agent dir.
2. Run cd ~ && pi.
3. The error notification above appears at session start.
4. Call the grep tool. It returns the same error text instead of results.

Impact

With "mode": "override", pi-fff registers the tool names grep, find, and multi_grep, which replace pi's built-in tools of the same name. Because ensureFinder() never succeeds, every one of those calls returns the init error. The agent therefore loses both the FFF search tools and pi's built-in search tools for the whole session.

Confirmed by calling grep in an affected session:

Error: FFF init failed: Failed to create FFF file picker for /Users/<user>: Failed to init file picker: Can not run certain FFF features in a file system root or home directories. Consider smaller per-project directories.

Root cause

packages/pi-fff/src/index.ts, session_start handler:

pi.on("session_start", async (_event, ctx) => {          // 747
  try {
    prepareSession(ctx);                                  // 749
    registerAutocompleteProvider(ctx);                    // 750
    await ensureFinder(activeCwd);                        // 751  <-- no guard

    // 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);   // 755
    ...
  } catch (error: unknown) {
    reportInitFailure(ctx, error);                        // 768
  }
});

Line 751 calls ensureFinder(activeCwd) unconditionally. The isHomeDir(activeCwd) check on line 755 runs only after the call that already threw, and it only drives the high-CPU warning.

ensureFinder() then forwards enableHomeDirScanning: false together with basePath: $HOME to FilePickerFactory.create() (index.ts:481), which throws at file-picker.ts:41, which reportInitFailure() reports at "error" level (index.ts:710).

The auxiliary path already handles this correctly. packages/pi-fff/src/aux-finders.ts:

const enableHomeDirScanning = this.opts.enableHomeDirScanning ?? true;   // 97
// 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)) {               // 100
  this.opts.onHomeDirScan?.(root);
}

The main picker path is missing the equivalent guard.

Expected behavior

When cwd is $HOME and enableHomeDirScanning is false, the extension should skip creating the main picker instead of throwing. isHomeDir() is already exported from ./paths and is already imported by index.ts, so the check is available at the call site.

The user message should also change. An error is wrong for a state the user opted into. An info or warning that names the responsible setting would be clearer, for example:

(fff): cwd is $HOME and enableHomeDirScanning is false, so FFF search is disabled for this session. Start pi from a project directory, or set enableHomeDirScanning: true / --fff-enable-home-scan=true to index $HOME.

Two related points:

1. The same guard applies to enableFsRootScanning with cwd === /.
2. When the main picker is skipped in "mode": "override", registering grep / find / multi_grep leaves the agent with no working search tool at all. Either fall back to pi's built-in tools in that case, or keep the FFF tool names unregistered so the built-ins stay reachable.

Workaround

Set "mode": "tools-and-ui" so pi's built-in grep and find remain registered. The FFF init failed notification still appears at every session start.