refactor: deepen runner disposal (#714)

* refactor: deepen runner disposal

* docs: clarify PR descriptions

Author: thymikee

AGENTS.md

@@ -295,9 +295,9 @@ Command-only flags (like `find --first`) that do not flow to the platform layer
 - Open a ready-for-review PR by default. Use a draft PR only when the user explicitly asks for one or the work is intentionally incomplete.
 - Run required checks for touched scope from **Testing Matrix**.
 - PR body must be short and include:
-  - `## Summary`: describe the user-visible or reviewer-relevant change as before/after when useful, and include the issue closed by the PR using `Closes #123` when applicable.
+  - `## Summary`: lead with benefits and reviewer-relevant outcomes. Prefer a compact before/after when it makes the improvement clearer. Include the issue closed by the PR using `Closes #123` when applicable.
   - `## Validation`: answer this prompt in concise prose: "How did you verify the change, and what passed or changed on screen?" Prefer evidence over command dumps; mention the relevant check category or scenario, and include screenshots when visual/UI behavior is relevant.
-- Call out known gaps/follow-ups explicitly.
+- Call out real tradeoffs, known gaps, or follow-ups explicitly; omit boilerplate when there are none.
 - Include touched-file count and note if scope expanded beyond initial command family.
 
 ## Priority Order

src/daemon/__tests__/daemon-command-registry.test.ts

@@ -13,6 +13,7 @@ import {
   shouldLockSessionExecution,
   shouldPreferExplicitDeviceOverExistingSession,
   shouldValidateSessionSelector,
+  resolveProviderDeviceResolutionIntent,
   usesSessionlessDefaultProviderDevice,
 } from '../daemon-command-registry.ts';
 import type { DaemonRequest } from '../types.ts';
@@ -155,6 +156,40 @@ test('daemon command registry preserves provider device resolution traits', () =
     usesSessionlessDefaultProviderDevice(makeRequest(PUBLIC_COMMANDS.record, ['stop'])),
     false,
   );
+  assert.equal(
+    resolveProviderDeviceResolutionIntent(makeRequest(PUBLIC_COMMANDS.test), {
+      hasExistingSession: false,
+      hasExplicitDeviceSelector: false,
+    }),
+    'skip',
+  );
+  assert.equal(
+    resolveProviderDeviceResolutionIntent(
+      {
+        ...makeRequest(PUBLIC_COMMANDS.test),
+        flags: { shardAll: 2 },
+      },
+      {
+        hasExistingSession: false,
+        hasExplicitDeviceSelector: true,
+      },
+    ),
+    'skip',
+  );
+  assert.equal(
+    resolveProviderDeviceResolutionIntent(makeRequest(PUBLIC_COMMANDS.open), {
+      hasExistingSession: false,
+      hasExplicitDeviceSelector: false,
+    }),
+    'sessionless-default-device',
+  );
+  assert.equal(
+    resolveProviderDeviceResolutionIntent(makeRequest(PUBLIC_COMMANDS.apps), {
+      hasExistingSession: true,
+      hasExplicitDeviceSelector: true,
+    }),
+    'explicit-device',
+  );
 });
 
 function makeRequest(command: string, positionals: string[] = []): DaemonRequest {

src/daemon/__tests__/request-platform-providers.test.ts

@@ -92,6 +92,39 @@ test('request platform provider scope follows explicit apps selector for existin
   assert.deepEqual(seenDevices, [`default:${OTHER_IOS_SIMULATOR.id}`]);
 });
 
+test('request platform provider scope skips sharded test orchestration requests', async () => {
+  let providerCalls = 0;
+
+  const result = await withTargetDeviceResolutionScope(
+    async () => {
+      throw new Error('Sharded test orchestration should not resolve a provider device');
+    },
+    async () =>
+      await withRequestPlatformProviderScope(
+        {
+          req: {
+            ...request('test'),
+            flags: {
+              platform: 'ios',
+              shardAll: 2,
+            },
+          },
+          existingSession: undefined,
+          providers: {
+            appleToolProvider: () => {
+              providerCalls += 1;
+              return createLocalAppleToolProvider();
+            },
+          },
+        },
+        async () => 'unscoped',
+      ),
+  );
+
+  assert.equal(result, 'unscoped');
+  assert.equal(providerCalls, 0);
+});
+
 test('request platform provider scopes stay isolated across concurrent requests', async () => {
   const androidCalls: string[] = [];
   const appleCalls: string[] = [];

src/daemon/daemon-command-registry.ts

@@ -27,8 +27,15 @@ type DaemonCommandDescriptor = {
   androidBlockingDialogGuard?: boolean;
   preferExplicitDeviceOverExistingSession?: boolean;
   allowSessionlessDefaultDevice?: (req: DaemonRequest) => boolean;
+  skipSessionlessProviderDevice?: (req: DaemonRequest) => boolean;
 };
 
+export type DaemonProviderDeviceResolutionIntent =
+  | 'existing-session'
+  | 'explicit-device'
+  | 'sessionless-default-device'
+  | 'skip';
+
 const REQUEST_EXECUTION_EXEMPT = {
   leaseAdmissionExempt: true,
   sessionExecutionLockExempt: true,
@@ -78,7 +85,7 @@ const DAEMON_COMMAND_DESCRIPTORS = [
   ),
   ...descriptors(
     'session',
-    { sessionKind: 'replay' },
+    { sessionKind: 'replay', skipSessionlessProviderDevice: isShardedTestRequest },
     PUBLIC_COMMANDS.replay,
     PUBLIC_COMMANDS.test,
   ),
@@ -212,6 +219,20 @@ export function usesSessionlessDefaultProviderDevice(req: DaemonRequest): boolea
   return typeof allow === 'function' ? allow(req) : false;
 }
 
+export function resolveProviderDeviceResolutionIntent(
+  req: DaemonRequest,
+  params: { hasExistingSession: boolean; hasExplicitDeviceSelector: boolean },
+): DaemonProviderDeviceResolutionIntent {
+  if (params.hasExistingSession) {
+    return shouldPreferExplicitDeviceOverExistingSession(req) && params.hasExplicitDeviceSelector
+      ? 'explicit-device'
+      : 'existing-session';
+  }
+  if (shouldSkipSessionlessProviderDevice(req)) return 'skip';
+  if (params.hasExplicitDeviceSelector) return 'explicit-device';
+  return usesSessionlessDefaultProviderDevice(req) ? 'sessionless-default-device' : 'skip';
+}
+
 function descriptor(
   command: string,
   route: DaemonCommandRoute,
@@ -252,3 +273,15 @@ function buildDaemonCommandRegistry(descriptors: readonly DaemonCommandDescripto
 function isRecordStartRequest(req: DaemonRequest): boolean {
   return (req.positionals?.[0] ?? '').toLowerCase() === 'start';
 }
+
+function shouldSkipSessionlessProviderDevice(req: DaemonRequest): boolean {
+  const skip = getDaemonCommandDescriptor(req.command)?.skipSessionlessProviderDevice;
+  return typeof skip === 'function' ? skip(req) : false;
+}
+
+function isShardedTestRequest(req: DaemonRequest): boolean {
+  return (
+    req.command === PUBLIC_COMMANDS.test &&
+    (typeof req.flags?.shardAll === 'number' || typeof req.flags?.shardSplit === 'number')
+  );
+}

src/daemon/request-platform-providers.ts

@@ -14,10 +14,7 @@ import type { AppLogProvider } from './app-log.ts';
 import { hasExplicitDeviceSelector } from './device-selector-intent.ts';
 import type { RecordingProvider } from './recording-provider.ts';
 import type { DaemonRequest, SessionState } from './types.ts';
-import {
-  shouldPreferExplicitDeviceOverExistingSession,
-  usesSessionlessDefaultProviderDevice,
-} from './daemon-command-registry.ts';
+import { resolveProviderDeviceResolutionIntent } from './daemon-command-registry.ts';
 
 export type PlatformProviderRequestSession = Pick<
   SessionState,
@@ -279,35 +276,19 @@ async function resolveScopedProviderDevice(
   req: DaemonRequest,
   existingSession: SessionState | undefined,
 ): Promise<DeviceInfo | undefined> {
-  if (existingSession) {
-    return await resolveExistingSessionProviderDevice(req, existingSession);
+  const intent = resolveProviderDeviceResolutionIntent(req, {
+    hasExistingSession: Boolean(existingSession),
+    hasExplicitDeviceSelector: hasExplicitDeviceSelector(req.flags),
+  });
+  switch (intent) {
+    case 'existing-session':
+      return existingSession?.device;
+    case 'explicit-device':
+    case 'sessionless-default-device':
+      return await resolveTargetDevice(req.flags ?? {});
+    case 'skip':
+      return undefined;
   }
-  if (shouldSkipSessionlessProviderDevice(req)) return undefined;
-  return await resolveTargetDevice(req.flags ?? {});
-}
-
-async function resolveExistingSessionProviderDevice(
-  req: DaemonRequest,
-  existingSession: SessionState,
-): Promise<DeviceInfo> {
-  if (!shouldResolveExplicitProviderDevice(req)) return existingSession.device;
-  return await resolveTargetDevice(req.flags ?? {});
-}
-
-function shouldResolveExplicitProviderDevice(req: DaemonRequest): boolean {
-  return shouldPreferExplicitDeviceOverExistingSession(req) && hasExplicitDeviceSelector(req.flags);
-}
-
-function shouldSkipSessionlessProviderDevice(req: DaemonRequest): boolean {
-  if (isShardedReplayTestRequest(req)) return true;
-  return !hasExplicitDeviceSelector(req.flags) && !usesSessionlessDefaultProviderDevice(req);
-}
-
-function isShardedReplayTestRequest(req: DaemonRequest): boolean {
-  return (
-    req.command === 'test' &&
-    (typeof req.flags?.shardAll === 'number' || typeof req.flags?.shardSplit === 'number')
-  );
 }
 
 async function requestPlatformProviderScopeWrappers(