Freshness and evidence

Frigg does not reduce freshness to a single healthy or stale flag. The workspace.freshness response separates the indexed snapshot, continuous watch activity, the safe post-edit action, working-tree scope, and each tool’s evidence source.

Freshness axes

Axis	Question it answers
`snapshot`	Is the indexed snapshot detached, missing, uninitialized, ready, erroneous, or unavailable?
`continuous`	Is watch off, unleased, active, debouncing, refreshing, retrying, blocked, or degraded, and can waiting converge?
`post_edit`	Should the client use the snapshot, use live reads for touched files, wait, run CLI indexing, adopt a repository, or treat Frigg as unavailable?
`dirty_scope`	Is the snapshot clean, stale for known paths, or affected by unknown repository-wide dirtiness?
`tool_capabilities`	Which evidence source a live tool uses, where staleness can apply, and which recovery is required?

snapshot.state=ready is meaningful even when watch is off. A clean ready snapshot can serve indexed searches and navigation on either transport.

Evidence sources

Frigg classifies the live tool surface conservatively:

Source basis	Tools
Live manifest	`list_files`
Live file	`read_file`, `explore`
Handle-bound live content	`read_match`
Snapshot index	search and navigation tools
Mixed live and indexed evidence	`document_symbols`, `inspect_syntax_tree`, `search_structural`, `impact_bundle`
Control plane	`workspace`

For known changed paths, snapshot-backed and mixed tools can be stale only for the touched scope. For unknown dirtiness, treat their repository-wide results as potentially stale. The per-tool capability row is more specific than the aggregate post-edit strategy.

When waiting helps

Waiting is valid only when a watcher lease exists and the current reason is debouncing or refreshing. In that case continuous.can_converge_by_waiting=true and the post-edit strategy is wait_for_refresh.

Do not wait on mode_off, no_lease, retry_backoff, blocked, or notify_degraded. Read touched files live and keep using the snapshot only for unaffected paths. Missing, uninitialized, or erroneous storage requires CLI frigg index; there is no public MCP reindex tool.

Evidence lifetimes

A result_handle and match_id pair identifies a result produced in the current session. read_match validates the current source revision against that proof anchor before returning bytes. If the source changed, was deleted, or can no longer be verified, Frigg returns STALE_PROOF_ANCHOR instead of substituting new bytes as historical proof.

Navigation rows can carry a target_ref. Copy that object unchanged into a navigation tool’s target input. Result-match targets are session and source scoped. Stable-symbol targets are repository and symbol-corpus scoped. Their scope values are correlation and integrity data, not authentication credentials.

After an edit or reindex:

Check workspace.freshness.
Rerun the search or navigation producer for touched code.
Use the new handle, match, or target.
Read the selected source before answering or editing further.

Product boundary

Freshness describes Frigg’s evidence, not the host’s filesystem tools or agent runtime. A child agent that did not receive Frigg through the host MCP registry must fall back to host tools; a shared HTTP service cannot create missing host registration by itself.

Source Anchors

../frigg/README.md
../frigg/crates/cli/src/mcp/types/workspace.rs
../frigg/crates/cli/src/mcp/server/workspace_freshness.rs
../frigg/crates/cli/src/mcp/server/content.rs
../frigg/crates/cli/src/mcp/types/target.rs
../frigg/skills/frigg-first-code-search/SKILL.md