fix(proxy): one event name per thing that actually failed

[xizhuomengcontin]

Orca-Code-Review — push 1

Severity	Count
P0	0
P1	0
P2	0
P3	0

✅ no blocking findings

tls.handshake_failed was every failure interception could produce. Seven call sites; four of
them are not handshakes at all:

what happened	reported as
a WebSocket upgrade declined rather than half-relayed	tls.handshake_failed
an h2 session to the origin that would not open	tls.handshake_failed
an h2 session or stream faulting after it was up	tls.handshake_failed
a request or response body that would not decode (four of the seven)	tls.handshake_failed
the client refusing the certificate orca presented	tls.handshake_failed

Why the last one is the reason to fix this

It happens on the client side of the proxy. But "handshake failed" with an h2 session:
prefix reads as a problem between orca and the origin — so the operator goes looking at the
network, the upstream, the proxy variables. The remedy is on the other side of the connection
entirely: this run's CA is not in the agent's trust store.

Meanwhile nothing from that host is recorded, and the trace looks quiet rather than broken —
which is the failure mode --tls-intercept exists to prevent.

The change

InterceptFailure carries the kind the call site already knew, and each kind gets the name it
deserves:

client_handshake  →  tls.handshake_failed   + where the CA actually has to go
upstream_session  →  tls.upstream_failed
session           →  tls.session_error
body_opaque       →  net.body_opaque        + "the exchange is recorded"
upgrade_refused   →  net.upgrade_refused

body_opaque is worth calling out: a body kept as it arrived is not a connection failure and
loses nothing. Reporting it as a handshake sent people to the TLS layer for a non-problem.

Driven for real

An agent that trusts only Node's root store, pointed through --tls-intercept:

  客户端 UNABLE_TO_VERIFY_LEAF_SIGNATURE
warn tls.handshake_failed host=api.anthropic.com port=443
     reason="h2 handshake: Error: socket hang up"
     cause="the agent refused the certificate orca presented — this run’s CA is not in its trust store"
     effect="nothing from api.anthropic.com is being recorded; the trace will simply be missing it"
     next="trust the run CA in the agent: NODE_EXTRA_CA_CERTS, REQUESTS_CA_BUNDLE, SSL_CERT_FILE,
           or the language runtime’s own store — `orca record --tls-intercept` prints the path"

Before this change the same run said:

warn tls.handshake_failed host=api.anthropic.com port=443 reason="h2 session: Error: socket hang up"

All five kinds were also exercised directly and each lands on its own event name.

Scope

The name is what people grep and alert on, so the name is what had to be true. Nothing outside
tls-capture.ts used the old one — no docs, no tests, no contract — so this renames a diagnostic
and changes nothing else.

Suite: 10 failed / 2444 passed / 40 skipped, identical to a freshly measured main baseline, no
new failures and none resolved. prettier --check, tsc --build, scripts/conformance.mjs
(63 events, 0 failures) and scripts/fidelity.mjs --check (0 regressions) all clean.

The four new tests fail on main for the right reason — reportInterceptFailure does not exist
there yet.

🤖 Generated with Claude Code

[orcacode-review]

🐳 OrcaCode Review

✅ No findings — nothing to flag in this PR. Great work!

_{OrcaCode Review — Route Smarter. Ship Safer. Spend Less.
Engine-reported: 534 calls · 41.6M tokens · 99% cached}

❤️ Share · Install OrcaCode Review

Free on GitHub — the review runs on your own OrcaRouter key. If it helped, a shout-out goes a long way.

Share: X · Reddit · LinkedIn
Follow: X · Discord · LinkedIn · OrcaRouter