fix(pi-fff): aux finder pool for out-of-workspace path constraints (#463)

[gustav-fff]

Closes #463

Hotfix prototype per maintainer request: when the agent passes an absolute path outside the workspace cwd to ffgrep/fffind, instead of throwing Path constraint must be relative to the workspace, route the call to a small rotating pool of additional FileFinder instances rooted at the requested path.

Root cause

packages/pi-fff/src/query.ts:13-17 rejects any absolute path that resolves outside cwd. The single workspace FileFinder only knows about files under its basePath, so historically there was nowhere to send those queries.

Fix

New packages/pi-fff/src/aux-finders.ts (~125 LOC) adds an AuxFinderPool:

• Max 3 concurrent aux finders (MAX_AUX = 3), LRU-evicted on overflow.
• Idle TTL 5 minutes (IDLE_TTL_MS = 5 * 60 * 1000); swept on every acquire.
• routePathConstraint(path, cwd) returns { root, suffix } when path is absolute and resolves outside cwd, else null. resolveAuxRoot walks back to the longest non-glob existing directory prefix; the remainder becomes a relative constraint inside the aux finder.

packages/pi-fff/src/index.ts:

• resolveFinderForPath() decides per-call whether to use the workspace finder or acquire an aux finder. Used by both ffgrep and fffind.
• Find pagination cursor carries auxRoot so a resumed page reuses the same aux finder.
• destroyFinder() tears the pool down on session_shutdown.

No changes to top-level Rust/Lua/C/bun APIs. Workspace finder behavior is unchanged for in-workspace paths. Aux finders are created with the same frecencyDbPath/historyDbPath/enableFsRootScanning as the main finder and aiMode: true, enableHomeDirScanning: true.

Diff size: 215 insertions, 5 deletions across 3 files (within the requested 200-300 LOC budget).

Steps to reproduce

cd packages/pi-fff
bun test
# 23 passing, including new aux-finders.test.ts covering routing decisions.

End-to-end (manual, requires pi runtime):

# In a pi session whose cwd is /tmp/workspace:
# Before the fix:
ffgrep pattern: "skills" path: "/Users/<you>/.pi/"
# -> Error: Path constraint must be relative to the workspace: /Users/<you>/.pi/

# After the fix:
ffgrep pattern: "skills" path: "/Users/<you>/.pi/"
# -> matches from the aux finder rooted at /Users/<you>/.pi

How verified

• bun test in packages/pi-fff passes 23/23 (17 prior + 6 new in aux-finders.test.ts).
• New tests cover: relative paths bypassed, in-workspace absolute bypassed, out-of-workspace absolute routed, glob-suffix split, missing-prefix returns null.

@dmtrKovalenko marking this as a prototype — open questions for review:

1. Aux finders currently share the workspace's frecency/history DBs. That means cross-root paths can collide on frecency keys (relative paths under different roots map to the same key). If that's undesirable, each aux root should get a derived DB path. Flagging because the change is one line and policy-dependent.
2. Mention autocomplete (getMentionItems) is not routed through the aux pool — only the ffgrep/fffind tools are. Easy to extend if you want @/abs/path/... mentions to work too.
3. resolveAuxRoot does a statSync to find the longest existing prefix. Sync is fine for hotfix prototype (one call per tool invocation, ms-scale) but could go async if it ever shows up in profiles.

Automated triage via Gustav. Honk-Honk 🪿