Combined audit pass against the classifier added in the previous
commit, addressing both totality and coverage gaps:

Totality contract guards. __cause__ / __context__ /
__mro__ access is funnelled through _safe_getattr so a
metaclass or subclass that overrides any of them with a property
raising non-AttributeError cannot break classifier totality. A
non-BaseException value returned from a property-override path
terminates the cause walk rather than poisoning cycle detection;
a raising __mro__ collapses to an empty fingerprint set so the
MRO branches naturally skip and the exception falls through to the
status-code / isinstance / OTHER paths.

Coverage of litellm exception classes that subclass openai
BadRequestError but carry semantics that map to a more informative
outcome: ContextWindowExceededError now lands on CONTEXT_OVERFLOW
(was BAD_REQUEST) and ContentPolicyViolationError on
CONTENT_FILTERED (was BAD_REQUEST). Both verified against installed
litellm 1.x classes.

Documentation. LLMCallResult field docstrings expanded to spell out
the cause_chain ordering (index 0 is the surface exception, walking
toward roots), the retry_after_seconds tri-state semantics that PR-B
will branch on (None means no hint, 0.0 means retry immediately,
positive means sleep before retry), and the PR-B integration
contract.

Tests grow from 80 to 89: hostile cause / context / mro property
guards, BaseException subclass totality, litellm class fingerprints,
cause_chain ordering invariant, retry-after tri-state, per-outcome
action lookup, JSON round-trip mirroring the PR-B telemetry path.

The classifier's job is to parse Retry-After into a finite
non-negative float and surface it on LLMCallResult. The upper bound
was a policy choice without operational evidence — no provider in
the wild sends Retry-After past one hour even at abuse-protection
limits, and a legitimate two-hour backoff was being silently
mapped to None (no hint) instead of being passed through. The
consumer (a future bandit retry adapter) is the right arbiter of
a maximum acceptable sleep; the classifier just needs to keep
non-finite garbage out of the field.

BanditModelRouter overrides invoke/ainvoke to wrap the LLM dispatch
in try/except. On failure the new _inject_failure_reward helper
classifies the exception via classify_call_result and looks up the
BanditAction; INJECT_ZERO_REWARD outcomes (every non-SUCCESS variant)
normalize a zero reward and append it to the arm's window before the
original exception re-raises. Without this, _select's pull recording
already happened but the reward window never got a matching entry,
so the UCB1 confidence term shrank for the failing arm and the
bandit underexplored flaky models.

_StructuredOutputRouter grows a failure_hook callback (orthogonal to
the existing select_override) so bandit-wrapped structured-output
dispatches go through the same path. BanditModelRouter.with_structured_output
wires self._inject_failure_reward through.

Six new tests cover sync failure, async failure, repeated failures
keeping pulls and rewards in step, success-path-does-not-inject,
structured-output failure routing through the same hook, and a
direct test of the unknown-arm defensive skip in
_inject_failure_reward.

``_StructuredOutputRouter._maybe_fire_failure_hook`` used to swallow
hook exceptions silently (``except Exception: pass``). The hook is
observability-only, so re-raising would mask the real LLM failure —
but a *silent* swallow loses telemetry whenever the hook itself has a
bug, hiding bandit-side regressions. Replace ``pass`` with
``logger.warning(...)`` so the original exception still propagates,
yet a broken hook is visible in operator logs.

Audit item FusionBrainLab#2 from the PR FusionBrainLab#13 bug hunt.

If ``_bandit.select()`` raises before ``record_pull`` runs, no pull is
recorded and the try/except inside ``invoke``/``ainvoke`` never engages
to inject a zero reward — the ledger invariant ("pulls and rewards
stay in step") therefore holds vacuously. Codify this so a future
refactor that moves ``record_pull`` outside ``_select`` (or hoists the
try/except above ``_select``) doesn't break the invariant silently.

Audit item FusionBrainLab#3 from the PR FusionBrainLab#13 bug hunt — verification, no code change.

When the bandit-wrapped LLM call inside an agent fails, the mutation
operator catches the exception and constructs a StageError via
StageError.from_exception(). Provider exception text occasionally carries
lone UTF-16 surrogate code points (typically tokenizer artefacts that
emit half of an astral pair without its partner). They survive str(exc)
unchanged into StageError.message / StageError.traceback, then crash
the downstream Redis-write path with TypeError: str is not valid UTF-8:
surrogates not allowed when gigaevo.utils.json.dumps (= orjson) tries
to encode the program blob.

Add idempotent field validators that replace lone surrogates with U+FFFD
at the StageError boundary so every downstream consumer (orjson, asyncpg
TEXT, migration-bus payload) is safe regardless of where the StageError
travels next.

The fix is local to the StageError schema and does not modify the
exception-classifier behavior or any LLM-side code.

Coverage: 7 tests under tests/test_program.py — positive case (high and
low surrogates scrubbed, downstream dumps succeeds), negative cases
(real astral emoji preserved, validator idempotent on revalidation),
end-to-end via StageError.from_exception and Program.to_dict.

Adds two integration-level test classes that pin invariants the
classifier wiring depends on, neither of which was covered by the
existing per-method tests:

* TestBanditNoDoubleInjectionOnFailure verifies the boundary between
  the failure-path _inject_failure_reward (fires inside ainvoke) and
  the deferred on_mutation_outcome (fires only for persisted
  programs). A failed mutation never reaches storage, so
  on_program_ingested never runs, so the bandit window receives
  exactly one entry per failed call. A future refactor that
  persists a placeholder program for failed mutations would
  silently introduce double-injection without these tests.

* TestBanditConcurrentMixedDispatch stresses ainvoke under 32-way
  concurrent dispatch with a deterministic success/failure mix and
  asserts the ledger invariant total_pulls == N and
  window_size == failure_count. Catches regressions in the task-id
  keyed _task_model_map that would leak one task's outcome into
  another's reward window, plus pure all-fail and all-succeed
  shapes for boundary coverage.

The migration bus serializes program_data via stdlib json.dumps, which
escapes lone UTF-16 surrogate code points as \\uD800 JSON literals. The
receiver json.loads them back into Python str form and eventually
attempts to persist the migrated Program through
gigaevo.utils.json.dumps (= orjson). orjson rejects surrogates with
TypeError: str is not valid UTF-8: surrogates not allowed, which would
crash the migration handler mid-restore.

When a Program migrates from process A (whose LLM call produced an
exception text with a tokenizer-artefact surrogate that propagated into
StageError.message via Program.to_dict, or carries an arm name with a
surrogate, or a code blob with one) to process B, the surrogate must be
sanitized at the publish boundary so every consumer downstream sees an
orjson-safe payload.

Add _scrub_surrogates that walks the JSON-shaped program_data tree and
replaces every lone surrogate with U+FFFD on str leaves. Also scrub
source_run_id and program_id directly. The transform is idempotent so
forward/retry paths that re-envelope a consumed message are safe.

Coverage: 6 tests under tests/evolution/bus/test_transport.py — top-level
program_data leaf, nested metadata + stage_results + tag list,
source_run_id/program_id, surrogate-free identity, real astral emoji
preserved, idempotency on republish.

Add an integration-level test module that exercises the agent layer
(`MutationAgent`, `InsightsAgent`, `LineageAgent`, `ScoringAgent`) on top
of a real `BanditModelRouter`. Existing coverage in
`tests/evolution/test_bandit.py` only checks the router in isolation
with synthetic mocks; the agent <-> router contract had no end-to-end
test.

The new module verifies that:

* On transport failure the bandit's failure hook fires exactly once
  even though `MutationAgent.acall_llm` swallows the exception into
  `state["error"]`, so the ledger stays in step
  (`total_pulls == window_size`).
* Repeated failures keep the ledger in step across many calls.
* On the success path the bandit defers the reward to
  `on_mutation_outcome` (window stays empty) and no double-injection
  happens in the agent layer.
* `InsightsAgent`/`LineageAgent`/`ScoringAgent` propagate failures out
  of `agent.arun` (they inherit `base.acall_llm`, which does not catch
  exceptions) while the bandit hook still fires before the exception
  escapes.

A regression that adds an internal retry/fallback wrapper to any agent
(e.g. `Runnable.with_retry` or `with_fallbacks`) would surface here as
a `window_size` mismatch.

The module also documents an out-of-slice gap (FU12): when
`_StructuredOutputRouter._process` receives the langchain
`include_raw=True` response shape with `parsed=None` and a non-None
`parsing_error`, it returns `None` without firing the failure hook,
leaving `total_pulls` incremented but `window_size` unchanged. The
fix belongs in `gigaevo/llm/models.py` and is queued for a follow-up.
The regression-lock test pins the current (broken) behaviour so the
follow-up can flip the assertion when the gap closes.

The extractor assumed every layer of the provider usage payload is a
dict with int counts:

  - response.response_metadata is a dict
  - response_metadata["token_usage"] (or "usage") is a dict
  - usage["completion_tokens_details"] is a dict
  - every *_tokens count is an int

A hostile or malformed provider that returns a string in place of any
nested dict crashed the extractor with AttributeError ("str has no get").
The bandit's _safe_track wrapper already swallows the failure, but
direct callers (MultiModelRouter.invoke in gigaevo/llm/models.py) have
no second-level guard, so an exception there propagates to the LLM call
site and loses the response.

Harden the extractor itself: isinstance-check every container layer
before .get(), and coerce every count through _coerce_int (which accepts
int/bool/float/str and defaults to 0 on anything else or on parse
failure). Token telemetry is observability-only and must always return
either a valid TokenUsage or None — never raise.

Coverage: 7 tests under tests/llm/test_llm_routing.py — string in place
of completion_tokens_details, string token_usage, string
response_metadata, string-encoded counts, None counts, float counts,
garbage string counts.

…m_fields"

This reverts commit 7fbf680.

The defence is now redundant against PR FusionBrainLab#10
(fix/llm-output-sanitization), which introduces
``gigaevo.utils.text_sanitize.deep_sanitize_for_json`` and applies it
at the same migration-bus boundary with broader coverage (ANSI / BIDI
/ control characters, not only surrogates).  Keeping the local
``_scrub_str`` / ``_scrub_surrogates`` helpers here forces a merge
conflict with FusionBrainLab#10 regardless of merge order; removing them lets either
PR merge independently against ``main``.

If FusionBrainLab#10 is rejected, this commit should be reverted (or the original
content cherry-picked back) to restore the defence on the bus.

… fields"

This reverts commit a25678f.

The defence is now redundant against PR FusionBrainLab#10
(fix/llm-output-sanitization), which adds ``sanitize_for_log`` field
validators on ``StageError`` (covering ANSI / BIDI / control
characters / surrogates).  Keeping the local ``_scrub_surrogates``
validators here forces a merge conflict with FusionBrainLab#10 regardless of merge
order; removing them lets either PR merge independently against
``main``.

If FusionBrainLab#10 is rejected, this commit should be reverted (or the original
content cherry-picked back) to restore the defence on
``StageError``.