trading: recovery receipts carry the engine's error message and its context

[seathatflowsinourveins]

Scope

• What this PR changes: a recovery receipt now records why recovery failed, not only the exception type.
• Why: account 2's 2026-10-06 recovery receipts said only TransportError, which hid a stream-readiness and quote-freshness failure.
• Base commit: origin/main at branch time.
• Lane: lane:trading.
• Owned paths touched:
  • blueprints/us-equities/adaptive-paper/recovery.py;
  • blueprints/us-equities/adaptive-paper/transport.py;
  • blueprints/us-equities/adaptive-paper/source-hashes.json;
  • tests/test_adaptive_paper_recovery.py;
  • manifests/evidence.json (the last commit).

What changes:

• recovery.py. errors keeps its stable codes, so every consumer and test is unchanged. A new error_details list gives each failure's:
  • code (the same as the errors entry) and type;
  • message, only when the engine authored it (a transport or safety exception);
  • context_type of the chained or suppressed context. Raising from None still keeps __context__. The context's message follows the same engine-only rule.
• What never enters a receipt: foreign exception text (SDK, network, OS). It can quote a request or a credential; the existing no-secret test (test_ambiguous_exit_is_retained_never_retried_or_rejected) enforces this.
• Redaction (_text): home paths and long tokens are redacted over the whole text, and only then is the text stopped at 300 characters, so a token that crosses the cut never survives as a fragment. The engine's own words stay readable: lowercase words joined by _ or /, such as quotes_subscription_rejected or authentication/subscription/quote. Any other long token, with digits, capitals, +, = or -, is redacted.
• Cancellation records {"code": "recovery_cancelled", "type": "CancelledError"}, so every errors entry has a detail.
• transport.py:
  • the start-readiness failure names its health freeze reasons, for example quotes_disconnected,quote_stale;
  • snapshot() still raises from None, now with a comment saying why. No caller's traceback or log prints the failing read's foreign text, and __context__ still gives the receipt that read's type.
• source-hashes.json: pins the changed engine files and tests.

The frozen trial engine (dca821cc) is unchanged. This takes effect only for a later engine pin.

SOTA sources

• The engine's own recovery and transport contracts:
  • blueprints/us-equities/adaptive-paper/README-recovery.md (receipts, needs_attention);
  • README-transport.md (health freeze reasons);
  • the existing receipt tests in tests/test_adaptive_paper_recovery.py.
• Python's exception-chaining semantics (raise ... from, __cause__, __context__, __suppress_context__): https://docs.python.org/3.13/library/exceptions.html#exception-context
• The incident: the command center's items task-native-agent-stack-5f-20261006T212903Z (item 4) and task-native-agent-stack-5f-20261006T213803Z (item 4). A diagnostic run of the frozen engine with only the error label formatted showed the hidden reasons: stream authentication/subscription/quote readiness failed, quotes_disconnected, quote_stale, and SafetyError: recovery_quote_not_fresh.

Evidence-class table

Claim	Evidence class	Command / receipt
error_details carries engine messages and contexts, and redacts foreign text	local_integration	tests/test_adaptive_paper_recovery.py: test_receipt_carries_the_message_and_its_context (chained and suppressed), test_engine_authored_context_is_kept_and_redacted, test_a_clean_recovery_has_no_error_details
The review fixes: each subscription reason survives in the receipt; unknown long tokens are still redacted; redaction runs before the cap; cancellation has a detail, also with a teardown failure	local_integration	test_readiness_failure_keeps_each_subscription_reason (all three reasons), test_engine_codes_stay_and_other_long_tokens_are_redacted, test_redaction_runs_before_the_length_cap (message and context_message), test_task_cancellation_stops_transport_and_retains_ambiguity, test_cancellation_then_teardown_failure_keeps_both_details
A snapshot failure keeps the foreign read out of tracebacks	local_integration (engine venv with alpaca-py; CI skips it)	tests/test_adaptive_paper_transport.py: test_snapshot_failure_keeps_the_foreign_read_out_of_tracebacks (__cause__ None, context suppressed, traceback.format_exception without the foreign text)
The new tests detect the reviewed defects	negative control	the new test files against the previous head 2cdd1faaf: 8 recovery assertions fail (the three reasons, the token rule, both boundary fields, both cancellation details), and the transport test fails on the chained ConnectionError
No existing behavior changes	local_integration	CI-equivalent venv: all adaptive-paper modules, 1248 tests, with the 5 credential_race failures below; engine venv: the transport module, 117 tests, with 3 errors that are identical on main (no exchange_calendars in that venv); trading gates and source hashes: 63 OK
5 test_adaptive_paper_credential_race mutation-driver failures are environmental	local_integration	the same 5 fail on a fresh origin/main worktree in this host's venv; CI is the authority

Local commands run

$ <CI-equivalent venv>/bin/python -m unittest discover -s tests -t . -p "test_adaptive_paper_*.py"
Ran 1248 tests ... FAILED (failures=5, skipped=358)   # the 5 credential_race mutation-driver failures, also on main
$ python3 scripts/validate.py
{"components": 69, "hashed_files": 10355, "profiles": 4, "receipts": 214, "status": "passed"}
$ python3 scripts/evidence_manifest.py --check
{"files": 10355, "status": "passed"}

Decision record

The command center's items cited above, and its review of this PR at 2cdd1faaf (ACK after one P2 and two P3 fixes, and a check that foreign causes stay out of logs). The stream self-close fix is separate: #812.

🤖 Generated with Claude Code

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-06T21:51:04.397933Z	2cdd1fa	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 2cdd1faafe

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[seathatflowsinourveins]

Claude session native-agent-stack-5f: landing at head 2df943bd2f1113b997bfc74d372bc23958aa4fdf. The command center (wsl-architecture-design) gave its ACK at this exact head; under the user's 2026-10-04 decision it owns merges that touch the hot registry. The read-only cross-family review (GPT-6.1 Sol max, the packaged Codex SDK worker) returned ACCEPT at this exact head, with no P1 item.

Observed main d9eb68750311d5f888adec140723da174f9fe10c. coordination/merge_tree_landing_check.py (sha256 a11649fcf2e5844c…) exit 0:

main d9eb68750311d5f888adec140723da174f9fe10c head 2df943bd2f1113b997bfc74d372bc23958aa4fdf base b4e1fa6df6048436e3f756965de38d9507dd5722 merged-tree c9ac92fc44d4349998a995b05b5284a39bd61acc merge-tree-exit 0
ok   1: clean three-way merge
ok   2: merged-vs-main paths 6, outside PR-owned 0 []
ok   3: main drift 72 paths, overlap with PR-owned inputs (registry excluded) []
ok   4: registry foreign rows equal True, order preserved True, PR-owned rows 5, unowned top-level keys differing []
ok   5: merged files[] sorted by path with no duplicates: True (10381 rows)
LANDABLE
condition 5: merged files[] sorted and unique (tree c9ac92fc44d4349998a995b05b5284a39bd61acc)

Required checks at this head: 7 pass . Unresolved review threads: 0.

[seathatflowsinourveins]

Claude session native-agent-stack-5f: post-merge observation. Landed as 0c4d32868f2b7b1d294d73cbbd0d5d3e41664c3d (parent d9eb68750311d5f888adec140723da174f9fe10c), tree c9ac92fc44d4349998a995b05b5284a39bd61acc. The landed tree equals the checked merged tree and the parent is the observed main.