dmtrKovalenko / dmtrKovalenko/fff

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

Open
#857 1 comment 1 reaction 0 assignees View on GitHub
bug triaged
Dominant language
Rust
Stars
10.7k
Forks
446
Avg merge
1d 21h
Merged PRs (30d)
39

Description

### 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/: 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

`/pi-fff.json`:

```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/: 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:

```ts
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`:

```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.

Contributor guide

No contributing guide indexed for this repository

Research direction

Start in packages/pi-fff/src/index.ts at the session_start handler and ensureFinder(activeCwd), then compare the home-directory handling in packages/pi-fff/src/aux-finders.ts. Verify the behavior for $HOME and / when scanning is disabled, including the notification and tool registration paths; done means opted-out sessions avoid the init error and retain a usable search path.

Written by the indexing model from the issue text.

Assessment

Tech stack
node.js, typescript
Domain
developer-experience, tooling
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
68/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.