Webhook poll delivery (4/4): enable the mode and prove it end to end

[Shearerbeard]

Last of four. Removes the config-validation refusal so delivery = "poll" becomes usable, and adds the end-to-end rig.

What changes:

• delivery = "poll" passes validation, and headers_from_request is accepted on poll routes now that the resolved values persist on the parked approval record. The other refusals stand: poll without [hitl.park].enabled, and a plaintext URL with an HMAC secret.
• Two feature-gated integration tests spawn a real web server per test against a file store and an in-process mock receiver. The flow test parks a gated tool call through /v1/chat/completions with a request-scoped header while the mock holds every notify POST open past the request timeout. It proves that the notify carries that header, that polling and resolution proceed even though no notify is ever acknowledged, and that a decided status lands approver identity in the durable decision record with the run still parked. The restart test kills the server between notify and decision. With nothing running, the receiver records the decision; the server then reboots onto the same store and the first tick resolves it, with at most one duplicate notify.
• docs/adr/2026-08-13-approver-identity-forwarding.md gains the config consequence: poll accepts request-derived headers while the two remaining refusals stay. It also records that only delivery enters the config fingerprint; the three poll tuning keys do not.

Not in this PR: re-execution after a decision. The rig proves the flow through durable resolve; the resume endpoint is separate work.

Tested with cargo test -p aura-web-server --features integration-hitl-header-forwarding --test poll_delivery_e2e_test with mock-mcp up, plus the header-forwarding suite.

The hosted configuration page for the new [hitl.route] keys follows as a separate PR in mezmo/documentation.

Stack: based on mshearer/271-poll-at-rest.

[greptile-apps]

Confidence Score: 5/5

The PR appears safe to merge, with one non-blocking shutdown race that can still lose final telemetry from a request accepted immediately before shutdown.

Findings

1.  Poll suite is not automated ▶

Summary

This PR enables webhook poll delivery, permits persisted request-derived headers on poll routes, adds end-to-end poll and restart coverage, and integrates that coverage into the local HITL test target.

• Removes the validation refusal for poll delivery while retaining park-mode and transport safeguards.
• Exercises notification, status polling, durable resolution, approver identity forwarding, and restart recovery.
• Updates developer testing guidance and the approver-identity ADR.
• Changes since the previous review also strengthen shutdown handling and MCP connection timeout behavior.

Diagram

sequenceDiagram
  participant Client
  participant Aura
  participant Store
  participant Receiver

  Client->>Aura: POST /v1/chat/completions
  Aura->>Store: Persist parked approval and resolved egress headers
  Aura-->>Client: Run parked
  Aura->>Receiver: POST /notify
  Note over Aura,Receiver: Notification may time out or be acknowledged
  loop Poll reconciliation
    Aura->>Receiver: "GET /status?decision_id=..."
    Receiver-->>Aura: Pending or decided
  end
  Receiver-->>Aura: Approved + approver identity header
  Aura->>Store: Persist durable decision
  opt Process restart
    Aura->>Store: Reload parked approval
    Aura->>Receiver: Poll status
    Aura->>Store: Resolve decided approval
  end

Loading

_{Reviews (4) · Last reviewed commit: "feat(hitl): enable poll delivery end to ..."}

[greptile-apps]

Poll suite is not automated

The new poll-delivery suite is not executed by make test-integration-hitl-local: that target selects only hitl_header_forwarding_tests, and the aggregate integration feature does not include this test's feature. As a result, routine integration runs will not catch regressions in the newly enabled poll and restart flows. This is non-blocking, but the suite should be added to the established integration command.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!