get_active_build

MANDATORY FIRST CALL for C/C++ projects. Return metadata about the most recently indexed build configuration — check index health before using any other fw-context tools.

Read-only: yes. Call at session start to check if the index exists, how many symbols it contains, and whether a reindex is needed.

Use the status field for decision-making:

• "ready" — fully up to date, no issues. Continue normally.

• "reindexing" — background reindex in progress. Index is still usable — all queries return accurate results. Continue normally.

• "reindex_needed" — compile_commands.json changed or schema mismatch. Run fw-context index, but queries still work on existing data.

• "no_index" — project initialized but no index built yet.

• "not_initialized" — project has not been initialized (fw-context init not run).

• "error" — DB corruption or access error. Use other tools.

reindex_needed is True when a structural mismatch exists: schema version outdated or compile_commands.json changed since indexing. Modified source files are auto-handled per-query and do NOT cause reindex_needed=True.

index_message is a human-readable summary of the index state.

Background reindex is managed by the startup daemon thread and the file watcher — get_active_build() is a read-only tool that does not spawn subprocesses. reindex_progress contains the last log line from the reindex subprocess when bg_reindex_running is True.

Set fast=False to include per-file stat scanning for accurate modified_files_count and header_affected_tus. The default fast=True is faster and sufficient for most session-start checks.

Args: project_root: Project root directory. Auto-detected from CWD if omitted.

Returns: dict: {config_hash, project_id, project_root, build_system, compile_commands, indexed_at (ISO timestamp), symbol_count, file_count, reference_count, modified_files_count (int), header_affected_tus (int — number of TUs with stale header dependencies), manifest_verification (str — "full" when manifest.json exists, "none" otherwise), analyzed_symbols (int), unanalyzed_symbols (int — definition symbols still needing LLM analysis), analysis_model (str or None), description (str), first_indexed_at (str), vendor_paths (list[str] — config index.vendor_paths), project_paths (list[str] — config index.project_paths), bg_reindex_running (bool), reindex_progress (str or None — last log line when reindex is running), schema_version (int — DB schema version), current_schema (int — code expects), status (str — "ready"|"reindexing"| "reindex_needed"|"no_index"|"not_initialized"|"error"), reindex_needed (bool — structural mismatch requiring a full reindex), reindex_reasons (list[str] — why reindex is needed, empty when False), stale (bool — True when reindex_needed or header_affected_tus > 0), _warning (str, optional — when manifest verification is not "full"), vec_available (bool), vec_error (str, optional), index_message (str — human-readable summary of index state)}