feat(relay): add policy overrides and idempotency-aware retry gating

memory-bank/change-log.md

@@ -1263,3 +1263,40 @@ Validation:
 Follow-ups:
 
 - Optional next step: map these lifecycle fields into central dashboards/alerts (retry rate, status-class distribution, p95 elapsedMs).
+
+---
+
+### CL-034: TASK22242 per-endpoint relay overrides + idempotency-aware retry gating
+
+date: 2026-03-24
+author: Cline
+scope: `pages/api/middleware/relayForwarding.js`, `tests/phase21/relay-forwarding-hardening.test.cjs`
+type: change
+rationale: Deliver the next functional relay enhancement by enabling route-level retry tuning while adding safe-by-default retry gating for non-idempotent methods.
+impact: Improves control and safety of relay retries without breaking existing endpoint contracts.
+status: completed
+
+Summary:
+
+- Added **relay policy override support** (`relayPolicy`) to shared relay helpers (`relayGet`, `relayGetData`, `forwardGetData`):
+    - per-call override of `timeoutMs`, `maxRetries`, `retryBaseDelayMs`, `retryMaxDelayMs`
+    - optional method override via `relayPolicy.method`
+- Added **idempotency-aware retry gating scaffolding**:
+    - retries allowed by default only for idempotent methods (`GET`, `HEAD`, `OPTIONS`)
+    - non-idempotent retry behavior controlled by:
+        - env flag `RELAY_ALLOW_NON_IDEMPOTENT_RETRIES` (default false)
+        - per-call override `relayPolicy.allowNonIdempotentRetries`
+- Extended relay telemetry fields to include method and non-idempotent policy posture in start/failure/retry events.
+- Preserved existing route behavior:
+    - existing GET endpoint flows continue to use retries per configured bounds
+    - no endpoint response contract changes
+
+Validation:
+
+- `node tests/phase21/relay-forwarding-hardening.test.cjs` -> pass (10/10)
+- `node tests/phase21/endpoint-handler-contract.test.cjs` -> pass (152/152)
+- `npm run lint` -> warnings only (pre-existing `react-hooks/exhaustive-deps`; no new lint errors)
+
+Follow-ups:
+
+- Future non-GET relay adoption should explicitly opt in/out per route using `relayPolicy` and include targeted negative-path tests.