fix(podman): resolve local callbacks to loopback on Linux

[politerealism]

Summary

On Linux, the Podman driver's automatic local-callback path negotiated a bridge-network gateway address (rootful) or the host's default-route interface (rootless pasta), and aliased host.containers.internal/host.openshell.internal through Podman's host-gateway resolver. Since RFC 0012 (#2942), the callback-capable supervisor always runs in the host network namespace and shares loopback with the gateway, so on multi-homed hosts these two independent interface selections can disagree, leaving the supervisor unable to reach the gateway.

Related Issue

Fixes #3412

Changes

• driver.rs: automatic Linux callback path now always requests a loopback gateway listener, for both rootful and rootless Podman; removed the now-obsolete bridge-gateway-IP discovery and rootless-pasta-only gating. Explicit host_gateway_ip override path is simplified and now works uniformly regardless of rootless network helper.
• container.rs: host aliases resolve to 127.0.0.1 directly on Linux instead of Podman's host-gateway magic value, matching the requested loopback listener. macOS Podman Machine behavior (gvproxy host-loopback forwarding) is unchanged.
• client.rs: removed the now-dead network_gateway_ip bridge-inspection method (no remaining callers).
• config.rs, NETWORKING.md, architecture/gateway.md, docs/reference/gateway-config.mdx, docs/reference/sandbox-compute-drivers.mdx, skills/debug-openshell-cluster/SKILL.md: updated to describe the new loopback-based default and troubleshooting guidance.

Out of scope (left for follow-up, per the issue's own implementation plan): removing PR #2874's delayed-bind protobuf/server machinery (a separate, wire-breaking proto cleanup), and the misleading ContainerExited: code 0 diagnostic when the supervisor exits before the workload.

Testing

• mise run pre-commit passes
• Unit tests added/updated (crates/openshell-driver-podman/src/driver.rs, container.rs) — 224 passing, including new/updated coverage for: rootful and rootless automatic loopback selection, explicit override still works with any rootless helper, constructor no longer inspects the bridge network for local callbacks.
• cargo fmt --all -- --check and cargo clippy -p openshell-driver-podman --all-targets -- -D warnings clean
• mise run markdown:lint clean
• E2E tests added/updated (not applicable — no existing multi-homed-host CI lane to extend; issue reproduction requires a real multi-interface host)

Checklist

• Follows Conventional Commits
• Commits are signed off (DCO)
• Architecture docs updated

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[drew]

With the new split, I think I we can actually remove all the callback machinery and remove this class of bug. Could you see if #3365 resolve your issue?

[politerealism]

Manual verification

Beyond the unit tests, I ran this against a real local Podman-backed gateway built from this branch to confirm the fix end-to-end.

Test 1 — default config (loopback-bound gateway):

$ openshell sandbox create --name loopback-test ...
Phase: Ready
Conditions: Ready: True (DependenciesReady) - Supervisor session connected

Inspected the supervisor container directly:

$ podman inspect openshell-supervisor-<id> --format '{{json .HostConfig.ExtraHosts}}'
["host.containers.internal:127.0.0.1","host.openshell.internal:127.0.0.1"]

Test 2 — gateway primary listener bound to a real interface IP (172.16.21.61), reproducing the topology from the bug report where the primary listener doesn't cover loopback:

Gateway log:

Gateway listener bound address=172.16.21.61:18080 listener_purpose="primary"
Gateway listener bound address=127.0.0.1:18080 listener_purpose="compute-driver-callback" driver=podman reason="Podman supervisor callback shares the host network namespace with the gateway"

The reason string is the exact string from the new gateway_listener_requirements() path in driver.rs, confirming the LoopbackInterface selector is what's actually exercised (not the old bridge-gateway/default-route negotiation).

Sandbox creation against that gateway also reached Ready:

$ openshell sandbox create --gateway-endpoint http://172.16.21.61:18080 --name loopback-test-2 ...
Phase: Ready

Supervisor container again showed host.containers.internal:127.0.0.1 / host.openshell.internal:127.0.0.1, NetworkMode: host.

Cleaned up both test sandboxes and the local gateway afterward; no leftover containers.

[politerealism]

Closing as superseded by #3365 (fix(ci)!: remove gateway callback listener dependency, merged 2026-09-18 — one day after this PR was opened).

#3365 resolved the underlying #3412 bug through a more fundamental change than this PR was making: it removed the entire callback-listener-negotiation mechanism (GetGatewayListenerRequirements/GatewayListenerRequirement — deleted from the protobuf API entirely) and replaced it with an unconditional rule. Current main's Podman driver already does exactly what this PR set out to do:

impl PodmanEndpointEnvironment {
    const fn gateway_host(self) -> &'static str {
        match self {
            Self::LinuxHost => "127.0.0.1",
            Self::PodmanMachine => "host.containers.internal",
        }
    }
}

Loopback is used unconditionally on Linux for both rootful and rootless Podman, with no listener negotiation required at all, since RFC 0012 guarantees the supervisor and gateway always share loopback now.

This branch predates #3365 and its diff actually reintroduces GatewayListenerRequirement/GatewayCallbackRoute/gateway_callback_endpoint, which #3365 deliberately removed — rebasing would mean re-adding complexity that's intentionally gone, not resolving a merge conflict. No further action needed here.