feat(agent): materialize a project map at task start - #3404

🟡 The rendered map is frozen after the first composition (src/gaia/agents/base/project_map.py:657)

get_project_map_system_prompt only runs inside _compose_system_prompt, and the composed prompt is cached in _system_prompt_cache. The only per-turn invalidation is _refresh_active_tool_filter → _apply_tool_filter, which recomputes only when the filter selection changes (agent.py:1288). With a stable filter the cache — and the map inside it — never moves. show_prompts composes it at construction (agent.py:888), i.e. before the first _on_task_start, which is why the run above rendered not built even on turn 2.

Adding the name to VOLATILE_PROMPT_FRAGMENTS doesn't help: that set only controls fragment ordering (agent.py:968), not recomputation.

The unit tests can't see this — test_prompt_says_building_while_the_index_is_running and test_prompt_reports_a_failed_index_instead_of_waiting_forever call get_project_map_system_prompt() directly, bypassing the cache entirely. A test that goes through the cached system_prompt property would have failed.

Fix options: call rebuild_system_prompt() from _on_task_start when the rendered fragment differs from last turn's, and again from the background thread's terminal states (_DONE / _FAILED). Cheap enough — the map is cached behind _fingerprint, so the recompose is a string join, not a walk. Whatever the fix, the claims in docs/guides/project-map.mdx ("Caching ... rebuilt when a fingerprint ... changes"), the CHANGELOG entry and SPEC.md should end up describing the shipped behaviour.

🟡 is_agent_own_source rejects any project that contains the installed gaia package (src/gaia/agents/base/project_map.py:416)

package = Path(gaia.__file__).resolve().parent
path = Path(root).resolve()
return path == package or path in package.parents

package.parents is every ancestor. For a user project with an in-tree virtualenv — /proj/.venv/lib/python3.12/site-packages/gaia — /proj is in package.parents, so resolve_project_root() returns None and logs that the user's repo is "GAIA's own source tree". That is a normal layout for anyone doing uv venv && uv pip install gaia inside their project, and it is precisely the developer-in-a-repo case the feature targets.

Tighten it to a GAIA checkout rather than any containing directory — e.g. require the package to sit at root/src/gaia or root/gaia, or bail out when a site-packages component separates root from the package:

 import gaia
 package = Path(gaia.__file__).resolve().parent
 path = Path(root).resolve()
 if path == package:
 return True
 # Only a checkout counts: an installed copy under the project's own venv
 # (``<root>/.venv/lib/.../site-packages/gaia``) must not disqualify it.
 return path in (package.parent, package.parent.parent) and (
 "site-packages" not in package.parts
 )

test_the_agents_own_source_tree_is_never_the_project passes either way (it uses parents[2] of the package, the checkout layout), so please add a case for the in-project-venv layout.

🟡 A raising _on_task_start fails the whole turn (src/gaia/agents/base/project_map.py:712)

_on_task_start → materialize_project_map → build_project_map → _fingerprint, whose bare os.scandir(root) raises if the root has been deleted, renamed, or unmounted since resolution (network share, external drive, git worktree remove). _process_query_impl doesn't guard the call (agent.py:4505), so the query dies with a FileNotFoundError instead of losing an optimisation.

Note the asymmetry: the prompt-fragment path is protected — _get_mixin_prompts catches and logs (agent.py:934). Orientation is a nicety; the hook should degrade the same way, e.g. wrap the body in except OSError and log at warning.

🟢 Nits

1. Unclosed os.scandir iterators (project_map.py:262, :324, :344) — sorted(os.scandir(p)) leaves the directory handle to the GC and emits a ResourceWarning under -W error. with os.scandir(p) as it: sorted(it, ...) is a one-line change in all three spots.

2. The guide's sample map can't be produced by the renderer (docs/guides/project-map.mdx:24) — it shows Code repository: yes (pyproject.toml, setup.py, package.json) for a Windows GAIA checkout, but render_project_map prefixes the VCS name, so a real checkout renders .git, pyproject.toml, .... The evidence bundle's captured block shows the true shape.

3. _tool_names() returns the registry, not names (project_map.py:668) — annotated Dict[str, Any] and used for membership tests, so it works, but the name reads like it returns a name collection. _tool_registry() would say what it is.

4. A typo'd off-switch value silently disables auto-index (project_map.py:592) — GAIA_PROJECT_MAP_AUTO_INDEX=ture is falsy and turns the feature off with no signal. Given the repo's fail-loudly rule, an unrecognised value is worth a warning.

5. probe_binaries drops the module's stated try/except discipline (system_context.py:81) — system_context.py's header says every collection step is wrapped so partial collection is fine; the new probe replaces a guarded shutil.which loop with an unguarded one. Low risk, but it's a documented invariant of that module.

Strengths

• The evidence bundle is the model of what this rubric asks for. It didn't just show the happy path — it drove the real gaia-agent process, planted unguessable names to prove the map is read rather than guessed, and reported two behaviours that didn't hold as observations rather than burying them. Both turned out to be real.
• The MRO guard is the right kind of defensive design (project_map.py:620). A wrong base order would produce a map that renders fine and silently never triggers indexing — the __init_subclass__ check turns a symptomless bug into a class-definition error, and test_a_wrong_base_order_fails_at_class_definition pins it.
• is_indexed() as a presence check rather than get_status() (code_index/sdk.py:512), with a test asserting get_status is never called on the prompt path. That is the difference between a cheap per-turn line and parsing tens of megabytes of metadata.
• The binary probe was unified rather than duplicated — collect_system_info and the map now share one probe_binaries with one PATH-keyed cache, and the map keeps "installed" separate from "the shell tool will accept it", which is the distinction that actually prevents a wasted call.