# Operator retrieval and freshness

Use this when the session exposes operator tools such as `truthgraph.resolve_context`. They differ from customer `/api/mcp` and its account keys. Existing operator access does not require customer signup; customer failures never justify seeking an operator credential.

## Orientation and scope

Call `truthgraph.usage_guidance` once per session. Use `truthgraph.status` for requested deployment/index diagnosis, not an all-repository preflight. Partial global status does not invalidate a healthy query.

Pass the known indexed project as `system`, for example `WeeyugaWeb`. A checkout named `TruthGraph-mcp` may be indexed as `TruthGraph`. `system: Earth` selects that repository, not the portfolio. Omit system only for intentional global discovery when ownership is unknown; if a scoped miss leaves ownership uncertain, widen once instead of repeatedly searching the wrong project.

System scopes discovery's starting subject; impact can follow modeled dependencies across indexed repositories. There is no project-only impact selector: do not invent `filters.scope` or substitute a shallow depth.

## Query examples

Use advertised names/schemas; these are operator tool arguments, not Python commands.

```json
{"system":"WeeyugaWeb","intent":"lookup","query":"chat_completions","limit":5,"filters":{"search_mode":"lexical"}}
```

Use exact subjects returned by discovery or verified source identities:

```json
{"system":"WeeyugaWeb","intent":"lookup","query":"file:WeeyugaWeb:brain/app/routers/llm.py"}
```

For a change to the exact handler rather than the entire file:

```json
{"system":"WeeyugaWeb","intent":"impact","query":"symbol:WeeyugaWeb:desktop/desktop_app_clean/src/agent/device_server.py._Handler._handle_chat_completions"}
```

A constructed subject must actually resolve. Never accept a similar fallback as the exact target. Class/method IDs are extractor identities, not arbitrary import paths.

Resolve accepts `filters.search_mode=auto|lexical|semantic|hybrid`; direct `truthgraph.search_subjects` takes `search_mode` at the top level. Exact IDs bypass embeddings. Natural-language auto/hybrid discovery may use embeddings; literal routes/identifiers can already be lexical. Check the mode before repeating a literal search as an embedding workaround.

Read `discovery.requested_mode`, `mode`, `semantic_state`, source/embedding coverage, warnings and `resolution_status`. Similarity is relevance, not call-edge confidence. With `requires_subject_selection`, choose an exact subject before impact. With `retrieval.neighborhood_deferred`, select a returned candidate and repeat exact lookup. With `selection_invalidated`, discard the selection and rediscover once.

Use `ownership` for endpoint/service/contract/consumer structure, `runtime` for static versus observed evidence, and `bundle` for selected coding context. Operator-only `operational` supports `filters.path_prefix`/`path_contains` for docs/configuration/deployment orientation. Do not send these fields/intents through customer tools. Frontend routes can use `route:<Repo>:<route-path>`.

## Revisions

Configured source discovery supports current indexed source only. Omit revision for non-exact discovery, or use accepted current aliases `main`/`bootstrap/main`. Do not attach a caller commit SHA to broad lexical/semantic discovery. Discover a current exact subject, then apply supported graph revision checks and verify requested-commit source separately.

Arbitrary historical impact snapshots are unavailable. The revised service accepts the exact full current `indexed_head` in its repeatable-read snapshot. Instructions can be newer than the server: if an older server rejects a SHA matching its indexed head, report a current-SHA validation limitation, not proof that the commit is historical. For current-index work, one retry on the exact subject without a revision override is reasonable; disclose that the caller SHA was not enforced. Strict historical investigation must use commit-pinned source and preserve the graph's limitation.

Revision scope/ref, indexed head and source verification differ. A worktree scope is not a commit, and its base SHA does not prove uncommitted contents equal that commit. Compare the caller checkout separately. Primary freshness does not verify all cross-repository sources; inspect `coverage.repository_revisions` and gaps.

## Query freshness

Read `freshness.agent_decision` when present. Index age is informational if source matches. Retain indexed head, `source_state`, verification time and `verification_scope`: host-checkout verification alone does not verify remote or caller working-tree state.

| Decision | Action |
| --- | --- |
| `use_truthgraph` | Use the graph and verify critical source; another path refreshing does not justify broad grep. |
| `use_truthgraph_with_warning` | Use it, preserving warnings relevant to this task. |
| `wait_for_incremental` | Wait briefly and retry the focused read once; if still pending, use focused source and report the gap. Do not queue a scan. |
| `targeted_live_probe` | Static graph is useful; probe relevant runtime/process/WebSocket/model facts only if authorized. Do not change live state. |
| `manual_full_reindex_required` | Do not claim complete structural impact. Report the repair requirement and use requested-commit source. Reindex only when the user authorized maintenance. |

A changed file can be pending while unrelated paths remain usable. Runtime can need a probe even when source is current. Grades include `configured_in_repo`, `observed_in_logs`, `observed_live_recently`, `benchmark_artifact_exists`, `needs_live_probe`, `unknown`; configuration/old logs are not current live observation.

Missing freshness is unknown. See [retrieval.md](retrieval.md) and [impact-delivery.md](impact-delivery.md) for failures. Never run hardcoded local refresh commands or contact another agent as a missing-tool fallback.