auto-forward: surface extensions (configurable+adaptive poll, forward subcommand, exec --auto-forward)

[pofallon]

Tracked deferrals from up --auto-forward (spec 015-auto-forward-ports, tasks T060 + T056; shipped in #188). Groups the v1-surface extensions and the detection-latency question. Acceptance: added without breaking the v1 boolean --auto-forward surface.

This bundles four related, individually-small items.

---

1. Configurable poll interval

v1 uses a fixed ~1s poll (POLL_INTERVAL in crates/core/src/port_forward/daemon.rs, FR-004).

• Gotcha: trivial to expose, but a too-small interval multiplies docker exec cat /proc/net/tcp overhead; keep a sane floor.
• Path: add --auto-forward-poll-interval <ms> (plumbed to DaemonConfig), with a documented minimum.

2. Adaptive polling — the practical answer to "event-driven detection" (folds in T056)

T056 proposed netlink/inotify event-driven detection. Recommendation: don't. Hidden issues with true event-driven:

• No kernel push for "entered LISTEN": /proc/net/tcp doesn't support inotify (synthetic procfs); sock_diag/inet_diag netlink is request/response, not a subscription — so netlink is just binary polling, not events. The only real push is eBPF on listen(), which needs CAP_BPF/CAP_SYS_ADMIN + recent kernel + BTF (privileged, fragile, anti to our "no root, any image" design).
• Reintroduces the in-container-agent problem (see auto-forward: persistent in-container multiplexing relay agent (drop per-connection docker exec) #190): netlink/eBPF must run inside the container netns → ship/embed an agent + capabilities.
• The 1s poll already meets SC-002 (≤~2s) at negligible CPU, so the payoff is polish, not capability.
• Path (recommended): adaptive polling — poll fast (~200–300ms) for the first few seconds after up (when declared/expected ports are most likely to appear) then back off to the steady interval. ~90% of the perceived-latency win, a handful of lines in the supervisor loop, no agent/capabilities. Leave true event-driven detection explicitly wontfix-unless-demanded.

3. Standalone forward subcommand

Attach a forwarder to an already-running container without a full up.

• Gotcha: must reuse the exact ContainerIdentity/marker/registry/reap machinery so it composes with up/down adopt-or-reuse (no parallel lookup path). Beware the pre-existing exec/up resolution mismatch (exec/run-user-commands can't resolve up's container: configHash mismatch between up and exec #187) — a forward --workspace-folder would hit the same configHash-mismatch wall; resolve exec/run-user-commands can't resolve up's container: configHash mismatch between up and exec #187 first or resolve by --container-id/label.
• Path: deacon forward [--workspace-folder|--container-id] [--declared-port ...] that spawns/adopts the same daemon.

4. exec --auto-forward attach

Start forwarding as a side effect of exec.

• Gotcha: exec currently resolves containers via ContainerIdentity and is subject to exec/run-user-commands can't resolve up's container: configHash mismatch between up and exec #187; lower value than the others.
• Path: thin wrapper that adopt-or-spawns the forwarder for the resolved container before running the command.

---

Suggested sequencing

Do (1) + (2) first (cheap, in-loop, high perceived value). (3) after #187 is fixed (shared resolution). (4) last (lowest value). Keep --auto-forward as the stable v1 entry point throughout.