Skip to content
Frigg Docs

Work safely after edits

Use this guide after source files change and before reusing old search, navigation, or proof results.

1. Inspect freshness

Section titled “1. Inspect freshness”

Call workspace for the active repository and read freshness.post_edit.strategy. Use the nested freshness object as the authority; top-level gate fields are compatibility projections.

Strategy Action
use_snapshot Continue with indexed tools. The snapshot is ready and clean.
wait_for_refresh Wait briefly, then call workspace again. A leased watch is debouncing or refreshing.
use_live_disk_for_touched_files Read changed paths with read_file, explore, or an explicit host live-file read. Do not rely on old indexed hits for those paths.
run_cli_index Run frigg index in the repository. Do not invent an MCP indexing tool.
adopt_repo Call workspace with the repository path or visible repository id.
frigg_unavailable Restore the service or use the documented host fallback.

When tool_capabilities contains the tool you plan to call, follow its availability, path_scope, and required_recovery instead of applying a broader rule.

2. Do not wait without convergence

Section titled “2. Do not wait without convergence”

Wait only when:

  • freshness.continuous.can_converge_by_waiting is true
  • watch has an active lease
  • the continuous state is debouncing or refreshing

For mode_off, no_lease, retry, blocked, or notification-degraded states, waiting alone does not refresh the snapshot. Use live reads for touched paths or run CLI indexing when the snapshot itself is not ready.

3. Refresh proof anchors

Section titled “3. Refresh proof anchors”

Do not reuse a pre-edit result_handle and match_id for touched source. Rerun the producing search or navigation call, select the new row, then call read_match with its new pair.

If read_match returns STALE_PROOF_ANCHOR, rerun the typed origin producer. Use read_file only when current live content, rather than proof of the earlier result, is the intended evidence.

Likewise, replace stale target_ref values by rerunning their producer. Copy the new target unchanged into navigation or impact_bundle.

4. Verify the new state

Section titled “4. Verify the new state”

After watch convergence or frigg index:

  1. Call workspace again.
  2. Confirm the intended tool capability is fully fresh for the relevant scope.
  3. Repeat the exact search or navigation query.
  4. Read the selected source before drawing a conclusion.

Common cases

Section titled “Common cases”

HTTP with active watch

Section titled “HTTP with active watch”

Keep frigg serve running. A leased repository can move from debouncing to refreshing and back to a clean ready snapshot. Recheck rather than assuming the debounce interval is a completion time.

Stdio with default settings

Section titled “Stdio with default settings”

Stdio defaults watch to off. A clean ready snapshot remains valid, but after edits the normal strategy is a live read for touched files until you run frigg index or explicitly operate a watched runtime.

Semantic provider or model changed

Section titled “Semantic provider or model changed”

Run a full frigg index, not only frigg index --changed. Semantic partitions use the provider and model identity, and existing rows do not make a newly selected partition current.

Section titled “Related”

Source Anchors

Section titled “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/skills/frigg-first-code-search/SKILL.md