dmtrKovalenko / dmtrKovalenko/fff
[Bug]: pi-fff aborts init with an `error` notification when cwd is `$HOME` and `enableHomeDirScanning` is `false`
- 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