# Failure Recovery and Non-Blocking Observability Contract

## Purpose

Agents converge by seeing truthful results, distinguishing changed state from
unchanged state, and choosing the next experiment. Operational telemetry should
make that easier. It must not impersonate a tool result or deprive the model of
the read, edit, or verifier needed to correct its understanding.

## Failure record

For every meaningful failure, record a compact causal tuple:

```text
task epoch
action signature
normalized inputs
relevant source/environment identity
native result class and concise evidence
what changed since the prior equivalent attempt
next useful experiment, if one is known
```

“Same command name” is not the same failure. A retry is new when its
arguments, target content/version, relevant configuration, environment,
authority, or result differs in a way that could change the outcome.

## Native results first

Prefer real tool outcomes over controller narration:

- An edit mismatch is a native `not_found`/conflict result, not discovery
  failure.
- A capped or oversized search is partial success with truncation provenance,
  not a missing-path result.
- A shell command that exits nonzero is a verifier or diagnostic observation,
  not a task card by itself.
- A stale hash means the underlying file version changed; surface the current
  identity and let the next read or precise edit resolve it.
- A failed extraction means unresolved requirements, anchors, and a recovery
  query—not permission to claim complete evidence.

Keep the original error text available in a durable artifact or concise
evidence record. Do not replace it with a vague “controller blocked” outcome.

## Recovery procedure

When a tool fails:

1. classify the failure from the native result: arguments, missing
   prerequisite, source mismatch, environment, test failure, permission,
   timeout, truncation, or unknown;
2. identify the smallest observation or change that distinguishes plausible
   causes;
3. perform that action, or explain why it requires user authority; and
4. update the evidence record with what changed and whether prior proof is
   stale.

Do not run an unrelated broad exploration merely to satisfy a controller. Do
not mutate a file to manufacture progress. Diagnostic events and repeated
status messages are not substantive progress.

## Retry and stasis policy

Retries are legitimate when an input or relevant state changed, when a
transient failure is plausible, or when the prior result was truncated,
unavailable, or not actually visible to the model. A read may be repeated if
the file changed, a different range is needed, only an extract was visible, or
compaction removed the required body.

When action, inputs, relevant state, and normalized result are all unchanged:

1. emit one concise `stasis` telemetry event with the signature;
2. keep the real tool result and recovery options visible;
3. suggest a changed observation, input, or hypothesis; and
4. retain an explicit blocked state only after no authorized recovery is left.

This is a diagnosis of non-convergence, not a general admission policy. It
must never block a file read, source search, diagnostic command, or edit just
because historical telemetry says a loop exists.

## Verifier behavior

A verifier is evidence, not a lock. After a source/configuration mutation, an
agent may inspect failing source, inspect logs, edit, run a targeted diagnostic,
or rerun the declared verifier in the sequence that the evidence supports.
The system should remember the declared verifier and its latest result, but it
must not force unrelated attempts to rerun it or hide stdout behind a recovery
gate.

Proof becomes stale only when a relevant input changes. It must not be retained
as current just because the verifier name is the same, and it must not be
discarded merely because unrelated telemetry was emitted.

## Telemetry, UI, and durable artifacts

The UI should distinguish these facts:

```text
tool attempted -> native result -> evidence recorded -> proof current/stale ->
advisory/recovery state -> next model-visible context
```

Never display a queue append, cache lookup, or diagnostic event as if it were
an executed tool action. Record compaction decisions, branch-extraction
contracts, cache reuse, steering lifecycle, and stasis signatures in durable
inspectable logs. Keep only the current compact recovery fact in model context.

An operational alert that cannot be explained from a persisted event and the
request dump is incomplete observability.