fix: PR #151 review findings — thread-safety, fail-closed availability, translator regressions

[madhakish]

Stacked on #151. Addresses the merge-blocking subset of review findings (15 critical + 9 important + test order-dependence + doc accuracy). 33 files, +397/−175.

Verification

• bundle exec rubocop: 0 offenses (490 files)
• bundle exec rspec: 3247 examples, 1 failure, 0 pending
  • Net vs base: +10 examples, −1 pending (un-skipped executor_spec.rb:576), 0 regressions
  • The 1 failure (ask_spec.rb:413 — try_defer not reached via chat_direct_governed) is pre-existing on large-yolo-refactor (verified via stash) and touches files outside this diff

Critical (C1–C15)

#	Fix	Files
C1	Availability.filter_resolutions / Candidates.select_candidates return [result, reasons/trace] instead of unsynchronized module ivars; threaded via chain.rejection_reasons	router/{availability,candidates}.rb, router.rb, executor/escalation.rb
C2	HealthTracker.known_instances wrapped in Monitor	router/health_tracker.rb
C3	rejection_reason fail-closed → :availability_check_error on exception	router/availability.rb
C4	:success health report ungated from @resolved_offering_id (half-open circuits can close)	executor/escalation.rb
C5	internal_error? guard — daemon NoMethodError/ArgumentError no longer trips provider circuits	executor/escalation.rb
C6	Remove bare /ValidationException/ from payload patterns; bedrock_availability_error? → deny/trip	executor.rb, executor/escalation.rb
C7	routing[:model] ||= body[:model] — SDK clients' model param honored	client_translators/{anthropic_messages,openai_chat,openai_responses}.rb
C8	OpenAI Chat streaming tool_calls[].index = 0-based ordinal, not global block_index	client_translators/openai_chat.rb
C9	OpenAI Responses streaming: track server_tool; only client tools → requires_action	client_translators/openai_responses.rb
C10	Anthropic: preserve thinking_blocks on assistant parse for same-provider replay	client_translators/anthropic_messages.rb
C11	Anthropic: preserve image/document as content_blocks instead of Hash#to_s	client_translators/anthropic_messages.rb
C12	parse_arguments: log non-Hash JSON + truncated raw on parse failure	call/dispatch.rb
C13	safe_call: narrow rescue Exception → NoMethodError/StandardError + RSpec guard	api/stream_assembler.rb
C14	step_tier_assignment: re-raise (fail-closed for privacy/security tier constraints)	executor/routing.rb
C15	merge_defaults: strip-and-warn deprecated :capability from settings default_intent (still raises on caller intent)	router.rb

Important (I1–I3, I6, I7, I12, I13, I16–I18)

• I1 Capabilities.normalize: canonical-replace aliases ([:tools] now satisfies required: [:function_calling])
• I2 RoutingUnavailable/TooEarly retryable? = true; FailedDependency explicit false; all carry reasons:
• I3 routing_empty_chain_error(reasons): maps actual Availability symbols (:discovery_unavailable → 425, :circuit_open/etc → 424)
• I6 resolve_chain forwards estimated_tokens/required_capabilities to chain_from_defaults
• I7 normalize_model_for_rules copies :loaded so loaded_model_bonus actually fires
• I12 handle_text_delta closes open thinking block before opening text
• I13 Puma::ConnectionError added to client-disconnect rescues (assembler + 3 routes)
• I16 0.90 context headroom unified → Availability.context_headroom (3 sites)
• I17 handle_exception on bare rescues (tools/dispatcher, tools/special, debug_formats)
• I18 Capabilities gets extend Legion::Logging::Helper

Tests

• Registry teardown in executor_escalation_circuit_spec; FakeProvider.reset! clears :fake_server_tool_round
• execution_proxy_matrix_spec: singleton_class.prepend → wrap_original (no permanent mutation)
• executor_spec.rb:576 un-skipped (root cause was Registry leak, fixed above)
• Spec updates for return-tuple signatures, canonical capability aliases, retryable contracts, C7/C15 behavior

Docs

• candidates.rb/routing.rb/escalation.rb: drop false 'verbatim/no behavior change' claims; note 0.12.20/0.12.30/0.12.35 extensions
• StreamAssembler + CLAUDE.md Invariant 5: keep-alive is single-fire on tool-open, not periodic
• Remove dangling refs (P4b/P5/G23/A7-fixture); candidates.rb:235 orphan fragment; CLAUDE.md example-count/relative-date

Deferred to follow-up (needs @Esity input)

#	Item	Why deferred
I4/I5	skip_same_tier! vs max_attempts cap; chain.size vs effective attempts	Changes escalation iteration semantics — author should decide
I8	Dispatch instance-fallback attribution	Behavior decision: fail vs fallback-with-correct-attribution
I9/I10/I11	Responses streaming reasoning shape; instructions→system; unresolved server-tool leak	G24 contract decisions
I14	Restore **_opts on Router.resolve	Intentional API tightening?
I15	Six false→true setting flips	Confirm intentional or split out
—	StreamAssembler (706L, 1 example) + ContextWindow unit suites	Test debt, separate PR
—	Fail-open → fail-closed sweep on remaining availability predicates	Policy decision
—	ask_spec.rb:413 pre-existing failure	Outside this diff

Merge order

Either: (a) merge this into large-yolo-refactor then merge #151, or (b) merge #151 first then retarget this to main (same base commit 4aa4240).

Note: #151 is currently CODEOWNERS-deadlocked — * @Esity is the effective last-match rule and Esity is the author. Needs admin merge or CODEOWNERS fix.

[Copilot]

Pull request overview

This PR applies the merge-blocking review fixes stacked on #151, focusing on thread-safety in routing/availability, fail-closed availability behavior, and execution-proxy translator streaming regressions across OpenAI/Anthropic client dialects.

Changes:

• Remove thread-unsafe module ivars by threading candidate/availability traces and rejection reasons through routing chains, and add locking to health tracking.
• Harden routing/executor behavior (fail-closed tier assignment, typed routing errors with retryable contracts, refined circuit/deny/trip classification).
• Fix/adjust client translators + stream assembly behavior (model fallback, tool streaming semantics, thinking/modality preservation, disconnect handling) with corresponding spec and doc updates.

Reviewed changes

Copilot reviewed 33 out of 33 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
spec/support/fake_provider.rb	Reset additional thread-local fake-provider state to avoid spec leakage.
spec/legion/llm/router/multi_instance_spec.rb	Update stubs for new filter_resolutions return tuple.
spec/legion/llm/router/determinism_spec.rb	Update behavior/expectations for deprecated :capability default_intent handling and tuple returns.
spec/legion/llm/router/availability_spec.rb	Adapt specs to [filtered, reasons] return and add fail-closed availability-check error coverage.
spec/legion/llm/inference/executor_spec.rb	Re-enable previously skipped test and ensure provider teardown.
spec/legion/llm/inference/executor_escalation_circuit_spec.rb	Add registry teardown and refine empty-chain typed error expectations.
spec/legion/llm/errors_spec.rb	Add coverage for retryable and reasons:-carrying routing errors.
spec/legion/llm/capabilities_spec.rb	Update capability alias normalization semantics and add alias/canonical matching test.
spec/legion/llm/api/matrix/execution_proxy_matrix_spec.rb	Replace singleton prepend mutation with and_wrap_original to prevent order dependence.
spec/legion/llm/api/client_translators/routing_headers_spec.rb	Align routing/model semantics: body model captured and used as routing fallback when header absent.
lib/legion/llm/tools/special.rb	Add handle_exception on settings access rescue to avoid silent failures.
lib/legion/llm/tools/dispatcher.rb	Same as above for tool dispatcher settings access.
lib/legion/llm/router/health_tracker.rb	Synchronize known_instances access to circuit/latency keys.
lib/legion/llm/router/candidates.rb	Return [final, trace] instead of using shared ivars; unify context headroom constant source.
lib/legion/llm/router/availability.rb	Return [filtered, reasons], fail-closed on unexpected exceptions, adjust logging.
lib/legion/llm/router.rb	Thread rejection reasons through escalation chains; strip deprecated :capability from defaults with warning; forward caps/tokens to defaults chain-building.
lib/legion/llm/inference/route_attempts.rb	Use shared context headroom value for final context budget enforcement.
lib/legion/llm/inference/executor/routing.rb	Fail-closed tier assignment by re-raising on assigner errors.
lib/legion/llm/inference/executor/escalation.rb	Typed routing error selection using rejection reasons; refine internal/bedrock-availability classification; ensure success health reports emit.
lib/legion/llm/inference/executor.rb	Remove overly-broad ValidationException payload classification.
lib/legion/llm/errors.rb	Add reasons: plumbing and retryable semantics to routing errors.
lib/legion/llm/discovery.rb	Preserve loaded metadata for rule scoring.
lib/legion/llm/capabilities.rb	Canonicalize capability aliases (replace rather than add) and add logging helper.
lib/legion/llm/call/dispatch.rb	Improve tool-argument parsing diagnostics and truncated raw logging on parse failure.
lib/legion/llm/api/stream_assembler.rb	Add disconnect rescue for Puma, close thinking before text, safer chunk probing, updated keep-alive semantics.
lib/legion/llm/api/namespaces/openai/responses.rb	Treat Puma disconnect as client cancellation in SSE route.
lib/legion/llm/api/namespaces/openai/chat/completions.rb	Treat Puma disconnect as client cancellation in SSE route.
lib/legion/llm/api/namespaces/anthropic/messages.rb	Treat Puma disconnect as client cancellation in SSE route.
lib/legion/llm/api/debug_formats.rb	Handle write failures via handle_exception for echo-request SSE emission.
lib/legion/llm/api/client_translators/openai_responses.rb	Route model fallback from body when header absent; track server_tool and only surface actionable tools as requires_action.
lib/legion/llm/api/client_translators/openai_chat.rb	Route model fallback from body when header absent; adjust streaming tool-call indexing logic.
lib/legion/llm/api/client_translators/anthropic_messages.rb	Route model fallback from body when header absent; preserve thinking blocks and structured content blocks for replay.
CLAUDE.md	Update doc accuracy around matrix harness and keep-alive semantics.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Esity]

• fix the merge conflicts
• you need to bump the version.rb to 0.13.1
• Add a v0.13.1 CHANGELOG.md entry to match