fix(ios): document daemon scoping of the usbmux route override

The env is re-read per resolve but from the daemon's environment, which is
captured at daemon launch — a later CLI invocation cannot flip the route on
a running daemon. Correct the source comment and experiment doc, and lock
the read-point semantics with a regression test.

Author: thymikee

docs/usbmux-runner-transport-experiment.md

@@ -3,8 +3,12 @@
 Live results from 2026-07-30, thymikee-iphone (iPhone 17 Pro, iOS 26.5.2, UDID
 00008150-001849640CF8401C), macOS host with Xcode 26.2. Method: forced-route
 env override `AGENT_DEVICE_IOS_RUNNER_ROUTE=usbmux` in `runner-command-route.ts`
-(uncommitted experiment patch), isolated `--state-dir` daemons per leg, timings
-from per-request `--debug` ndjson plus wall-clock. Every timing sample was
+(committed with this doc), isolated `--state-dir` daemons per leg, timings
+from per-request `--debug` ndjson plus wall-clock. The override is
+**daemon-scoped**: the daemon captures its environment at launch, so setting
+the variable on a later CLI invocation against a running daemon silently
+keeps the previous route — every route leg needs a fresh isolated
+state-dir/daemon launched with the desired value. Every timing sample was
 validated against real command output after an early instrument artifact (see
 Pitfalls).
 
@@ -77,5 +81,9 @@ xctestrun prep (~13 s cold) and runner startup; fresh device resolution costs
   error latency is indistinguishable from a fast success unless output is
   asserted. Runner-lease contention ("already owned by another daemon")
   produced exactly this artifact.
+- The route override is daemon-scoped (env captured at daemon launch). Never
+  flip `AGENT_DEVICE_IOS_RUNNER_ROUTE` between commands against the same
+  daemon and expect the route to change — start a fresh isolated
+  state-dir/daemon per leg, then verify with `ps eww <daemon-pid>`.
 - Sessions are cwd-scoped; run every command of a leg from the same cwd.
 - Auto-Lock must be Never during measurement or the runner dies mid-series.

src/platforms/apple/core/__tests__/runner-transport.test.ts

@@ -242,6 +242,25 @@ test('sendRunnerCommandOnce routes coredevice physical devices through usbmux wh
   ]);
 });
 
+test('runner route override follows the daemon process env across resolves', async () => {
+  // The override is daemon-scoped: resolves re-read the daemon's process env,
+  // which is fixed at daemon launch. Clearing it here models a fresh daemon
+  // launched without the variable — the only way the route can change.
+  vi.stubEnv('AGENT_DEVICE_IOS_RUNNER_ROUTE', 'usbmux');
+  stubSuccessfulFetch();
+  mockRunCmd.mockImplementation(async () => ({ exitCode: 1, stdout: '', stderr: '' }));
+
+  await sendRunnerCommandOnce(iosDevice, 8100, { command: 'uptime' }, 5_000);
+  assert.equal(mockUsbmuxPostCommand.mock.calls.length, 1);
+  assert.equal(vi.mocked(fetch).mock.calls.length, 0);
+
+  vi.unstubAllEnvs();
+  await sendRunnerCommandOnce(iosDevice, 8100, { command: 'uptime' }, 5_000);
+
+  assert.equal(mockUsbmuxPostCommand.mock.calls.length, 1);
+  assert.equal(vi.mocked(fetch).mock.calls[0]?.[0], 'http://127.0.0.1:8100/command');
+});
+
 test('waitForRunner routes coredevice physical devices through usbmux when overridden', async () => {
   vi.stubEnv('AGENT_DEVICE_IOS_RUNNER_ROUTE', 'usbmux');
   const fetchMock = vi.fn();

src/platforms/apple/core/runner/runner-command-route.ts

@@ -5,8 +5,10 @@ const RUNNER_DEVICE_TUNNEL_IP_CACHE_TTL_MS = 30_000;
 
 /**
  * Experimental override for #1403: forces physical-device runner commands
- * through usbmux regardless of backend. Read per-resolve so daemon restarts
- * are not required between experiment runs.
+ * through usbmux regardless of backend. Daemon-scoped: the value is re-read
+ * on every resolve, but from the daemon's environment, which is captured at
+ * daemon launch — a later CLI invocation cannot change it. Use a fresh
+ * isolated state-dir/daemon per experiment route leg.
  */
 const RUNNER_ROUTE_OVERRIDE_ENV = 'AGENT_DEVICE_IOS_RUNNER_ROUTE';