Troubleshoot freshness and storage

Use workspace.freshness before treating a search miss as a ranking problem. It distinguishes a usable snapshot from watch activity and reports the safe recovery.

Results miss a recent edit

Call workspace for the repository.
Read freshness.post_edit.strategy and the intended tool’s tool_capabilities row.
For wait_for_refresh, wait briefly and recheck.
For use_live_disk_for_touched_files, read only the changed paths live.
For run_cli_index, run:

frigg index

There is no public MCP reindex tool. Do not invent workspace_index or workspace_reindex from internal type names.

Watch does not converge

Continuous state	Response
`mode_off`	Expected for default stdio. Use live reads or operate a watched HTTP service.
`no_lease`	Keep an active session adopted to the repository or use live reads. Waiting alone will not refresh it.
`debouncing`	Wait for the debounce window, then recheck.
`refreshing`	Wait for the active refresh, then recheck.
`retry_backoff`	Inspect service logs and fix the failed dependency before the retry.
`blocked` or `notify_degraded`	Use live reads for touched paths and inspect logs; waiting is not sufficient.

The default debounce is 2000 ms and retry delay is 5000 ms. Those are scheduling intervals, not completion guarantees.

A proof handle is stale

STALE_PROOF_ANCHOR means the source revision no longer matches the result that issued the handle. Rerun the original search or navigation producer and use its new result_handle and match_id.

Do not retry the old pair, combine ids from different handles, or use read_file as proof of the historical result. Use read_file only when current content is the intended evidence.

After repository detach, reindex, or relevant watch changes, rerun producers before reusing targets or proof handles.

SQLite reports `database is locked`

Frigg stores repository state in .frigg/storage.sqlite3. Multiple writers can contend for the same database.

Prefer one shared frigg serve process for multiple clients and subagents.
Stop duplicate stdio processes indexing the same repository.
Increase FRIGG_SQLITE_BUSY_TIMEOUT_MS when transient contention is expected. Its default is 30000 ms.
Disable built-in watch when another process intentionally owns refreshes.

Storage is missing or incompatible

For missing or uninitialized state:

frigg init
frigg index

For incompatible or irrecoverable regenerable state, stop active Frigg writers before removing or rebuilding .frigg/. Prefer the CLI’s reported recovery and operator runbook over editing SQLite files manually.

Restored CI caches must still pass frigg init and an index refresh. After a provider, model, or semantic document-envelope change, use full frigg index rather than a changed-only refresh.

Frigg is missing only in a child agent

If the parent can call Frigg but a new child cannot see it in the live tool list, this is host MCP registration or inheritance, not index freshness. Use the host fallback for that child and repair the host configuration. A running HTTP endpoint shares state only after the host registers it for the child.

Source Anchors

../frigg/README.md
../frigg/docs/operator-runbook.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/settings/watch.rs
../frigg/crates/cli/src/storage/db_runtime.rs
../frigg/skills/frigg-first-code-search/SKILL.md