feat(driver-vm): let operators set how soon a supervisor sees a policy change #4361

User Story

I use OpenShell's VM driver to run agent sandboxes for a service that grants each sandbox network access per request: a sandbox boots with a restrictive policy, and when it is handed to a workload the service adds that workload's allowed endpoints to its policy. I need the new policy loaded before the workload starts, so that its first connection is not denied.

Problem Statement

A supervisor picks up a changed sandbox policy only when it next polls GetSandboxConfig. The interval is OPENSHELL_POLICY_POLL_INTERVAL_SECS, default 10 s (openshell-supervisor/src/lib.rs). The VM driver starts each supervisor with a cleared environment (isolate_host_control_environment, openshell-driver-vm/src/driver.rs) and passes no interval, so an operator cannot change it. Every policy change waits for up to 10 s before it is enforced.

Impact / Why This Matters

The wait sits on the critical path of every request that changes a sandbox's network policy. With the default interval we measured 6.1 s from request start to a ready sandbox (v0.1.2, VM driver), most of it this wait.

Current workaround: put the destinations known in advance into every sandbox's boot policy, so most requests need no change. That widens what every sandbox can reach, including sandboxes not yet assigned to anyone, and does nothing for destinations known only at request time.

Proposed Design

Two options, which are not exclusive:

1. Operator setting. A VM driver setting for the supervisor's poll interval, passed to each supervisor the driver launches. Unset keeps today's behaviour exactly. A shorter interval costs more GetSandboxConfig calls per sandbox. Draft PR feat(driver-vm): configurable supervisor policy poll interval #4362 implements this option.
2. Push. The gateway tells a supervisor over its existing ConnectSupervisor session that its configuration changed, so it polls at once; the timed poll stays as the fallback. Policy changes would load without waiting and without raising steady-state polling.

Suggested UX (if applicable)

[openshell.drivers.vm]
# Seconds between each supervisor's polls for a changed policy or settings
# (1-600). Omit to keep the default of 10 s.
supervisor_policy_poll_interval_secs = 1

The driver accepts the same value as --supervisor-policy-poll-interval-secs / OPENSHELL_VM_SUPERVISOR_POLICY_POLL_INTERVAL_SECS; out-of-range values fail gateway start-up with a message naming the setting.

Acceptance Criteria

• An operator can make a policy change take effect in a VM sandbox in well under 10 s.
• With the new setting absent, supervisor behaviour and the gateway's request rate are unchanged.
• An invalid value is rejected at gateway start-up with a message naming the setting.

Alternatives Considered

• Pre-loading every destination in the boot policy: the current workaround, with the costs above.
• Setting the variable on the gateway or driver process: it does not reach the supervisor, whose environment the driver clears on purpose.
• Lowering the default for everyone: raises configuration traffic on every deployment to fix a latency only some need.

Agent Investigation

Read on main at a991b8e: the supervisor's poll loop sleeps the interval between poll_settings calls (run_policy_poll_loop_with_client); isolate_host_control_environment calls env_clear() before the driver sets its own variables; GatewayMessage has no configuration-changed message today.