fix(pi-fff): skip the picker instead of erroring when cwd scanning is opted out (#857)

[gustav-fff]

Closes #857

Root cause

packages/pi-fff/src/index.ts:751 called ensureFinder(activeCwd) unconditionally on session_start. With cwd === $HOME and enableHomeDirScanning: false, the native guard at crates/fff-core/src/file_picker.rs:881 refuses the picker, and reportInitFailure() (index.ts:710) reported that refusal at "error" level — the opt-out behaved like a hard failure. The isHomeDir() check at index.ts:755 ran only after the throw and only drove the high-CPU warning. In mode: "override" the tools were already registered as grep/find, so every search call returned the same init error and pi's built-ins were unreachable for the whole session.

Fix

scanOptOutReason(cwd) covers both opt-outs ($HOME + enableHomeDirScanning: false, / + enableFsRootScanning: false). session_start skips the picker and notifies once at "warning" level naming the responsible setting; ensureFinder() rejects with the same message instead of the native text; prepareSession() keeps ffgrep/fffind in override mode for an opted-out cwd so pi's built-in grep/find stay registered. Aux pickers for explicit out-of-workspace paths are unaffected.

Steps to reproduce

Setup (real native lib, no config file — env only, so nothing is written to the pi agent dir):

make build-c-lib
mkdir -p packages/fff-node/bin && cp target/release/libfff_c.dylib packages/fff-node/bin/
(cd packages/fff-node && bun install && bun run build)
mkdir -p packages/node_modules/@ff-labs
ln -sfn ../../fff-node packages/node_modules/@ff-labs/fff-node

Trigger, on pre-fix main:

cd ~ && FFF_ENABLE_HOME_SCAN=0 PI_FFF_MODE=override \
  pi -e <repo>/packages/pi-fff/src/index.ts -p --no-session \
  "Call the grep tool exactly once with pattern zzzqqq and no other arguments."

Actual (pre-fix), run aborts:

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

Expected: session starts, no error, FFF workspace search off, pi's built-in grep still usable.

Native refusal on its own (packages/fff-bun, bun script calling FileFinder.create):

$HOME, enableHomeDirScanning:false -> ERROR: Failed to init file picker: Can not run certain FFF features in a file system root or home directories. Consider smaller per-project directories.
/, enableFsRootScanning:false      -> ERROR: Failed to init file picker: Can not run certain FFF features in a file system root or home directories. Consider smaller per-project directories.

How verified

packages/pi-fff/test/extension.test.ts: the FileFinder.create mock now mirrors the native guard instead of always succeeding — that is why this shipped green. Three regression tests added ($HOME opt-out, / opt-out, and $HOME still indexed when not opted out).

cd packages/pi-fff && bun test test/   # 84 pass, 0 fail (2 fail on pre-fix src)
cd packages && bunx oxfmt --check . && bunx oxlint .   # clean

Post-fix, same pi command from $HOME:

0, grep

i.e. the session starts, the tool call goes to pi's built-in grep, and no FFF init failed notification is emitted. No stray fff processes left behind.

Automated triage via Gustav. Honk-Honk 🪿

Summary by CodeRabbit

• New Features

  • Added handling for sessions started in the home directory or filesystem root when scanning is disabled.
  • Displays a warning and skips FFF search initialization in opted-out locations.
  • Keeps built-in find and grep tools available when FFF search cannot run.

• Bug Fixes

  • Prevented failed search initialization in directories excluded from scanning.
  • Preserved normal indexing behavior when home-directory scanning is enabled.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Advanced

Run ID: 8096c637-7fa0-4bda-a8f7-e9526bdfe909

📥 Commits

Reviewing files that changed from the base of the PR and between d84c0a1 and 0ad661a.

📒 Files selected for processing (4)

• packages/pi-fff/README.md
• packages/pi-fff/src/index.ts
• packages/pi-fff/src/paths.ts
• packages/pi-fff/test/extension.test.ts

Included review availability: Your plan provides up to 10 included reviews per hour; 9 remain after this review.

---

📝 Walkthrough

Walkthrough

The extension now skips FFF indexing when sessions start in an opted-out home directory or filesystem root. It shows a warning, preserves built-in search tools in override mode, and documents and tests the behavior.

Changes

Scan opt-out handling

Layer / File(s)	Summary
Directory detection and initialization guard packages/pi-fff/src/paths.ts, packages/pi-fff/src/index.ts	Adds filesystem-root detection and prevents finder creation when home or root scanning is disabled.
Session fallback and validation packages/pi-fff/src/index.ts, packages/pi-fff/test/extension.test.ts, packages/pi-fff/README.md	Shows warnings, preserves built-in search tools in override mode, tests home and root opt-outs, and documents startup behavior.

Priority: ➖ Normal — Impact reflects medium issue severity.

Estimated code review effort: 2 (Simple) | ~10 minutes

Severity of issue fixed: Medium

Merge Risk: ⚪ Minimal · up to 0ad66

Starting in an opted-out home directory or filesystem root now skips FFF indexing with a clear warning while keeping built-in search tools available. The covered behavior is ready to merge.

Suggested reviewers: dmtrkovalenko, xwilludelu

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 60.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 10 functions across 3 files. (1 skipped: …	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly describes the primary fix: skip picker initialization when cwd scanning is opted out.
Linked Issues check	✅ Passed	The changes satisfy issue [#857]. They handle home and filesystem-root opt-outs, skip the main picker, show a warning, preserve built-in search tools in override mode, and add regression tests.
Out of Scope Changes check	✅ Passed	The README, implementation, path helper, and tests directly support the linked issue objectives. No unrelated changes are evident.

Full details: Docstring Coverage

Explanation

Docstring coverage is 60.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 10 functions across 3 files. (1 skipped: 1 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch triage-bot/issue-857

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}