fix(acp)!: preserve connection lifetimes and graceful drain

[benbrandt]

Summary

Make connection completion explicit so wrappers do not mistake an endpoint with no owned task for a finished component, hang on unrelated open input, or discard accepted final output.

This is the connection-lifetime slice only. It does not change ACP/MCP wire schemas, dependency pins, raw Channel sender/receiver types, or introduce backpressure/resource limits.

API and migration

• Breaking: ConnectTo::into_channel_and_future now returns (Channel, Option<ConnectionDriver>) instead of (Channel, BoxFuture<Result<()>>). None means an endpoint with no owned work—not EOF and not a ready-success future.
• ConnectionDriver::new(future) owns opaque work. Finite foreground completion does not indefinitely join arbitrary opaque tasks after protocol handoff.
• ConnectionDriver::with_finish(future, hook) lets built-in and custom adapters declare cooperative finish. The nonblocking one-shot hook requests stop/seal/drain; the still-polled future proves physical flush/write-half-close and reports errors. No implicit timeout is added.
• request_finish() is idempotent: true means supported and requested, including an earlier request; false means opaque. The callback runs at most once. Already-requested work retains its graceful contract across handoff.
• map_future supports tracing, error annotation, and completion cleanup without losing finish capability or requested state. Transparent wrappers preserve the original optional driver unchanged.
• Passive endpoints have no finish hook. Dropping a driver drops its owned future without requesting graceful completion; dropping only the hook does not invoke it or necessarily stop that work.

Most components implementing only connect_to keep the default conversion. Custom conversion overrides and low-level callers must handle absence explicitly. Buffered custom transports that need finite physical-drain guarantees expose the cooperative hook and coordinate it in both direct and normalized entry points.

Migration guide · Public driver API

Lifecycle fixes

• Preserve passive channel half-closes so write EOF can be followed by a final reverse response.
• Treat successful owned completion as authoritative even when sender clones escape; reject new output and drain frames already accepted.
• Drain routable builder output after successful finite foreground completion. Fail unresolved readiness-gated requests instead of publishing them after shutdown. Physical progress continues without starting unrelated queued application tasks solely for sink drain.
• Stop new application delivery after foreground success, preserve close callbacks already underway, and discard irrelevant late/queued input during physical drain without hiding genuine I/O errors.
• Explicitly flush and close physical writers, including read/write halves sharing one socket or duplex stream; do not rely only on dropping the writer.
• Apply one ownership-aware rule across protocol connectors, agent/proxy routers, and initialization rejection. Await cooperative drain, check ready errors before cancelling opaque work, and do not require independently open remote input to reach EOF.
• Retain cancellation ownership when HTTP natural cleanup has taken the router join handle, so explicit shutdown cannot detach a blocked router. Preserve the no-driver HTTP pump lifetime.

Regression evidence

Retained tests cover the previously reproduced failures: direct builder output truncation, escaped-producer completion hangs, split-stream write EOF, late input cancelling gated flush, and HTTP shutdown during router drain. Public custom-adapter coverage adds one-byte physical write backpressure, a separate flush gate, exact flush-error propagation, direct/normalized/decorated entry points, already-requested handoff, opaque cancellation, and one-shot/drop behavior.

Review order:

1. Driver API and contracts
2. Builder/transport coordination and physical writer
3. Protocol-peer consumers and HTTP connection ownership
4. Normalization regressions, public composition tests, and protocol-router finish tests

Validation

Passed locally on the committed source, with incremental compilation/debug info disabled and build warnings denied:

• Full unfiltered just test, including doctests and compile-fail coverage
• Strict workspace/all-targets/all-features Clippy (-D warnings)
• All eight CI-equivalent feature-powerset partitions
• Rust 1.88 workspace/all-targets/all-features check, plus minimal/all-feature WebAssembly configurations
• Strict Clippy for wasm32-wasip1, wasm32-wasip2, and wasm32-unknown-unknown
• docs.rs-style nightly documentation and stable WASI documentation
• Formatting, typos, mdbook build, and whitespace checks

No manifest, lockfile, or CI workflow changes. Released changelog history is preserved.

Draft pending GitHub CI on this branch and final human review. Nothing has been merged or released.