bug: avoid misleading symlink-resolution warnings for absent policy binaries #2883

User Story

As an OpenShell operator, I want expected absent binary candidates to avoid warning-level logs, so that supervisor warnings identify actionable policy or runtime problems.

Problem Statement

When the effective network policy contains a non-glob binary path that does not exist in the sandbox image, binary symlink resolution calls symlink_metadata through /proc/<pid>/root. An ENOENT for the candidate path is reported as though the supervisor could not access the container filesystem:

WARN openshell_supervisor_network::opa: Cannot access container filesystem for symlink resolution: path=/app/.venv/bin/python container_path=/proc/38/root/app/.venv/bin/python pid=38 error=No such file or directory (os error 2). Binary paths in policy will be matched literally. If this binary is a symlink (e.g., /usr/bin/python3 -> python3.11), use the canonical path instead, or run with CAP_SYS_PTRACE.

This conflates an expected missing compatibility candidate with a failure to traverse /proc/<pid>/root. For example, the built-in pypi profile contains both /sandbox/.venv/... and /app/.venv/... candidates, so images that use only one layout generate warnings for the other.

The resolver emits one warning per missing non-glob candidate whenever it rebuilds the OPA policy with an entrypoint PID. A policy with several candidate paths can therefore produce a large burst of warnings.

Impact / Why This Matters

The warnings make a healthy sandbox appear misconfigured and direct operators toward adding CAP_SYS_PTRACE or canonicalizing paths even when the only condition is that an optional path does not exist. Repeated messages obscure actionable supervisor warnings and make Kubernetes sandbox logs harder to interpret.

The current workaround is to ignore the messages or remove compatibility paths from the effective policy. Ignoring warning-level output is unreliable, while editing built-in provider policy solely to suppress logs is inappropriate and can reduce compatibility with other images.

Literal binary matching currently remains installed, so an absent candidate does not broaden access. If resolution genuinely fails for an existing symlink, the canonical executable may fail to match and traffic remains fail closed.

Acceptance Criteria

• A missing binary candidate below an otherwise accessible /proc/<pid>/root does not emit the container-filesystem-access or CAP_SYS_PTRACE warning.
• Permission failures and an inaccessible process root continue to produce an actionable warning.
• Warning text distinguishes process-root access failures from target-path resolution failures.
• The resolver continues to retain the original literal binary path when a candidate is absent or cannot be resolved.
• Existing symlink paths still add their canonical targets to the effective policy.
• Automated coverage distinguishes an absent candidate (NotFound) from an inaccessible process root or permission failure and prevents repeated warning noise for expected compatibility candidates.

Reproduction Steps

1. Deploy the OpenShell gateway with the Kubernetes driver using the Helm/Skaffold development environment.
2. Create a sandbox whose effective policy includes the built-in pypi profile, or another policy containing /app/.venv/bin/python.
3. Use an image that does not contain /app/.venv/bin/python (for example, one whose virtual environment is under /sandbox/.venv).
4. Start the sandbox and inspect its supervisor logs.
5. Observe a warning for each absent non-glob binary candidate, including the misleading suggestion to add CAP_SYS_PTRACE.

The effective paths can be confirmed with:

openshell policy get <sandbox> --full | rg '/app/.venv|/sandbox/.venv'

Environment

• OpenShell: development build as of 2026-08-21
• OS: local macOS host
• Runtime, deployment, or integration: Kubernetes driver on local k3s, deployed with Helm/Skaffold

Logs

WARN openshell_supervisor_network::opa: Cannot access container filesystem for symlink resolution: path=/app/.venv/bin/python container_path=/proc/38/root/app/.venv/bin/python pid=38 error=No such file or directory (os error 2). Binary paths in policy will be matched literally. If this binary is a symlink (e.g., /usr/bin/python3 -> python3.11), use the canonical path instead, or run with CAP_SYS_PTRACE.