fix(pi-fff): make home-dir scanning configurable, warn when indexing $HOME (#743)

[gustav-fff]

Closes #743

Root cause

pi-fff hardcoded enableHomeDirScanning: true, overriding the core default guard, so launching pi from $HOME always indexed the whole home tree with no opt-out:

• packages/pi-fff/src/index.ts:370 — main finder
• packages/pi-fff/src/aux-finders.ts:77 — aux finder pool

Only fff-enable-root-scan was configurable. @XWIlluDelu traced this to #589, which removed the home flag and forced true. The maintainer's advice "do not start pi in $HOME if you enable home indexing" was unfollowable — the extension always enabled it.

Fix

Expose it as --fff-enable-home-scan flag + FFF_ENABLE_HOME_SCAN env, default true (behavior unchanged). resolveBoolOpt now takes a fallback and accepts 0/false so the default can be turned off. Threaded through both the main finder and AuxFinderPool.

On the alerts question: pi exposes ctx.ui.notify(msg, "info" | "warning" | "error") and ctx.ui.setStatus(id, text) (footer, persists across renders) — docs extensions.md:2177, tui.md:734. Wired both: a warning notify when cwd is $HOME with scanning on, plus a footer status. After the 15s waitForScan returns, getScanProgress() is polled once; if still scanning, the footer keeps showing the live file count instead of clearing, so a long background index over a big home tree is visible.

Note: this only adds the opt-out and visibility. It does not address the other items in the report — no idle-stop, no size/count thresholds, no default excludes, no cross-process index sharing. @dmtrKovalenko those are design changes, out of scope for a triage fix.

Steps to reproduce

Pre-fix main, home scanning cannot be disabled:

git clone git@github.com:dmtrKovalenko/fff.git && cd fff
git checkout 086044f
grep -n "enableHomeDirScanning" packages/pi-fff/src/index.ts packages/pi-fff/src/aux-finders.ts
# packages/pi-fff/src/index.ts:370:        enableHomeDirScanning: true,
# packages/pi-fff/src/aux-finders.ts:77:      enableHomeDirScanning: true,

No flag exists, so launching pi from $HOME indexes the whole tree:

cd $HOME && pi   # full $HOME walk, no way to opt out

Behavioral check via the test suite:

cd packages/pi-fff && bun test test/

On pre-fix main add this test — it FAILS (Expected: false, Received: true):

test("FFF_ENABLE_HOME_SCAN=0 disables home dir scanning", async () => {
  process.env.FFF_ENABLE_HOME_SCAN = "0";
  await start();
  const opts = createCalls[0] as { enableHomeDirScanning: boolean };
  expect(opts.enableHomeDirScanning).toBe(false);
});

Post-fix it passes, and the opt-out works:

cd $HOME && FFF_ENABLE_HOME_SCAN=0 pi   # native Home guard rejects init, no scan
cd $HOME && pi                          # still scans (default true) + warning shown

How verified

• bun test test/ in packages/pi-fff — 46 pass, 0 fail.
• Confirmed the new test gates the fix: reverting enableHomeDirScanning to hardcoded true makes it fail with Expected: false, Received: true.
• bun run lint and bun run format:check produce byte-identical output to origin/main (3 warnings, 1 info, 8 format diffs — all pre-existing). No new lint/format regressions.
• ctx.ui.notify / ctx.ui.setStatus / getScanProgress verified against installed @earendil-works/pi-coding-agent 0.79.3 docs and packages/fff-node/src/fff-api.ts:603. setStatus called optionally (?.) since it is TUI/RPC-only.
• Zero Rust changes, no hot path touched.

Automated triage via Gustav. Honk-Honk 🪿

[dmtrKovalenko]

@gustav-fff iterate on revie

[dmtrKovalenko]

let's cache the os.homedir once per the process

[dmtrKovalenko]

Every time the llm is trying to spawn the aux picker in home dir we should send the notification to the user

[dmtrKovalenko]

Suggested change

	ctx.ui.setStatus?.("fff", "FFF: indexing $HOME");
	ctx.ui.setStatus?.("fff", "Agent is indexing $HOME, this can lead to high CPU");

[dmtrKovalenko]

are you sure this is actually getting called multiple times? I feel like it would be called just once so we might need to run timeout based scanning or add a callback to the ensureFinder to make sure this warning is cleaned

[gustav-fff]

[triage-bot] DIRECTED: pushed f83f9f2. All three review points addressed.

1. Cache os.homedir() — new packages/pi-fff/src/paths.ts: HOME_DIR resolved once at module load, isHomeDir(dir) helper. Both src/index.ts:632 and the ~-expansion in src/aux-finders.ts:160 now use it. import os dropped from index.ts.

2. Notify on every aux picker over $HOME — AuxOpts.onHomeDirScan?: (root: string) => void, fired in AuxFinderPool.acquire() before FileFinder.create() when the requested root covers $HOME:

if (enableHomeDirScanning && rootCovers(maybeRoot, HOME_DIR)) {
  this.opts.onHomeDirScan?.(maybeRoot);
}

Wired to the same warnHomeDirScan() the startup path uses. Fires only on picker creation, not on covering-picker reuse, and not for roots below $HOME (e.g. ~/dev/foo) — those do not walk the home tree.

3. You are right, the one-shot check was wrong. waitForScan() resolves on timeout too, so on a big $HOME the single post-wait getScanProgress() could pin a stale footer forever with no path to clearing it. Replaced with a 1s poller (trackHomeScanStatus(), src/index.ts:432) that updates the live file count and clears the status once isScanning goes false. The interval is unref()'d so it never holds the process open, and stopHomeScanStatus() runs from destroyFinder() — so session_shutdown also tears it down.

4. Footer text taken verbatim from your suggestion: Agent is indexing $HOME, this can lead to high CPU.

Tests: 53 pass, 0 fail (was 46). 7 new covering the aux notification, the polling loop with isScanning: true, shutdown cleanup, and silence when FFF_ENABLE_HOME_SCAN=0. biome check output is identical to origin/main modulo line-number shifts on the two pre-existing findings. Zero Rust changes.

Honk-Honk 🪿

[dmtrKovalenko]

@gustav-fff rebase

[gustav-fff]

[triage-bot] DIRECTED: rebased onto main (3a0ce85), force-pushed 2baa107.

Two commits squashed into one. Conflict was in packages/pi-fff/src/index.ts — #750 (695724e) reformatted the whole file. Re-applied my changes verbatim on top of the new structure; semantic diff vs main is unchanged.

aux-finders.ts auto-merged with #750's new create(root) split, but the merge left my onHomeDirScan guard referencing the old maybeRoot var which no longer exists in that scope — fixed to root:

if (enableHomeDirScanning && rootCovers(root, HOME_DIR)) {
  this.opts.onHomeDirScan?.(root);
}

Tests: 55 pass, 0 fail (was 53; picked up #750's 2 aux-dedup tests). No new tsc errors — the 5 tsc --noEmit findings (@ff-labs/fff-node module resolution, implicit-any on item/p at index.ts:230/241) are all pre-existing on main, none in my touched lines.

Honk-Honk 🪿

[dmtrKovalenko]

@copilot resolve the merge conflicts in this pull request

[Copilot]

@copilot resolve the merge conflicts in this pull request

Rebased onto main (031005e) and resolved the conflict in packages/pi-fff/src/index.ts. The conflict was a whole-file clash with the reformatting from #751. Re-applied all Gustav changes (home-scan flag, resolveBoolOpt fallback, enableHomeDirScanning variable, warnHomeDirScan, trackHomeScanStatus/stopHomeScanStatus, uiCtx capture, and the session_start warning block) on top of the new reformatted structure. Commit: 88cb82b.