refactor(daemon): give generic leaves their own execution vocabulary

scripts/depgraph/README.md

@@ -48,7 +48,7 @@ gate rejects value-import cycles (R4) and spine back-edges (R5); the graph addit
   not attempt. ~2300 of them: a place to look, never a work list. They are exactly the value
   edges the transitive reduction drops. A value-import cycle (an R4 failure) makes the reduction
   undefined, so the report then lists the cycle and leaves this count uncomputed.
-- **type-only and dynamic cycles** — 23 of them, all outside R4 by design (a type-only import is
+- **type-only and dynamic cycles** — 22 of them, all outside R4 by design (a type-only import is
   free at runtime, a dynamic one is a deliberate cold-start seam). Worth reading when a module
   feels hard to reason about.
 

src/daemon/__tests__/back-runtime.test.ts

@@ -19,7 +19,7 @@ import { createTestDeviceInventoryGateways } from '../../__tests__/test-utils/de
 import { LeaseRegistry } from '../lease-registry.ts';
 import { activateCompleteRefFrame, refFrameState } from '../ref-frame.ts';
 import type { BindDeviceRuntime, InspectDeviceRuntimeFacts } from '../request-runtime-binding.ts';
-import type { GenericPlatformExecutionParams } from '../request-generic-dispatch.ts';
+import type { GenericPlatformExecutionParams } from '../generic-leaf-execution.ts';
 import { resolveBoundBackRuntime } from '../back-runtime.ts';
 import { expectRefusesUnavailableExactOwnerFact } from './runtime-binding-conformance.ts';
 import { createRequestHandler } from './test-device-runtime-gateway.ts';

src/daemon/__tests__/focus-runtime.test.ts

@@ -19,7 +19,7 @@ import { createTestDeviceInventoryGateways } from '../../__tests__/test-utils/de
 import { LeaseRegistry } from '../lease-registry.ts';
 import { activateCompleteRefFrame, refFrameState } from '../ref-frame.ts';
 import type { BindDeviceRuntime, InspectDeviceRuntimeFacts } from '../request-runtime-binding.ts';
-import type { GenericPlatformExecutionParams } from '../request-generic-dispatch.ts';
+import type { GenericPlatformExecutionParams } from '../generic-leaf-execution.ts';
 import { readFocusPoint, resolveBoundFocusRuntime } from '../focus-runtime.ts';
 import { expectRefusesUnavailableExactOwnerFact } from './runtime-binding-conformance.ts';
 import { createRequestHandler } from './test-device-runtime-gateway.ts';

src/daemon/__tests__/fold-runtime.test.ts

@@ -19,7 +19,7 @@ import {
 import { deviceShape, type DeviceInfo } from '@agent-device/kernel/device';
 import { makeSession } from '../../__tests__/test-utils/session-factories.ts';
 import type { BindDeviceRuntime, InspectDeviceRuntimeFacts } from '../request-runtime-binding.ts';
-import type { GenericPlatformExecutionParams } from '../request-generic-dispatch.ts';
+import type { GenericPlatformExecutionParams } from '../generic-leaf-execution.ts';
 import { readRequestedFoldPose, resolveBoundFoldRuntime } from '../fold-runtime.ts';
 import { expectRefusesUnavailableExactOwnerFact } from './runtime-binding-conformance.ts';
 

src/daemon/__tests__/orientation-runtime.test.ts

@@ -41,7 +41,7 @@ import { createTestDeviceInventoryGateways } from '../../__tests__/test-utils/de
 import { LeaseRegistry } from '../lease-registry.ts';
 import { activateCompleteRefFrame, refFrameState } from '../ref-frame.ts';
 import type { BindDeviceRuntime, InspectDeviceRuntimeFacts } from '../request-runtime-binding.ts';
-import type { GenericPlatformExecutionParams } from '../request-generic-dispatch.ts';
+import type { GenericPlatformExecutionParams } from '../generic-leaf-execution.ts';
 import {
   readRequestedOrientation,
   resolveBoundOrientationRuntime,

src/daemon/__tests__/runtime-binding-conformance.ts

@@ -19,7 +19,7 @@ import { resolveBoundFocusRuntime } from '../focus-runtime.ts';
 import { resolveBoundFoldRuntime } from '../fold-runtime.ts';
 import { resolveBoundGestureRuntime } from '../gesture-runtime.ts';
 import { resolveBoundOrientationRuntime } from '../orientation-runtime.ts';
-import type { ResolvedGenericExecution } from '../request-generic-dispatch.ts';
+import type { ResolvedGenericExecution } from '../generic-leaf-execution.ts';
 import type {
   BindDeviceRuntime,
   InspectDeviceRuntimeFacts,

src/daemon/__tests__/screenshot-runtime.test.ts

@@ -6,7 +6,7 @@ import { SCREENSHOT_CROP_REASONS } from '@agent-device/contracts/capture';
 import type { RawSnapshotNode } from '@agent-device/kernel/snapshot';
 import { ANDROID_EMULATOR, IOS_SIMULATOR } from '../../__tests__/test-utils/device-fixtures.ts';
 import { makeSession } from '../../__tests__/test-utils/session-factories.ts';
-import type { GenericPlatformExecutionParams } from '../request-generic-dispatch.ts';
+import type { GenericPlatformExecutionParams } from '../generic-leaf-execution.ts';
 import { resolveScreenshotGenericExecution } from '../screenshot-runtime.ts';
 import { screenshotRuntimeFixture, writeSolidPng } from './screenshot-runtime-fixture.ts';
 import type { DaemonRequest } from '../daemon-request.ts';

src/daemon/__tests__/scroll-runtime.test.ts

@@ -5,7 +5,7 @@ import { AppError } from '@agent-device/kernel/errors';
 import type { CommandFlags } from '@agent-device/contracts/command';
 import type { DaemonRequest } from '../daemon-request.ts';
 import type { SessionState } from '../session-state.ts';
-import type { GenericPlatformExecutionParams } from '../request-generic-dispatch.ts';
+import type { GenericPlatformExecutionParams } from '../generic-leaf-execution.ts';
 import type { SnapshotNode } from '@agent-device/kernel/snapshot';
 import type { BoundDeviceRuntime, RuntimeFacts } from '@agent-device/contracts/platform-runtime';
 import {

src/daemon/__tests__/system-button-runtime.test.ts

@@ -22,7 +22,7 @@ import { createTestDeviceInventoryGateways } from '../../__tests__/test-utils/de
 import { LeaseRegistry } from '../lease-registry.ts';
 import { activateCompleteRefFrame, refFrameState } from '../ref-frame.ts';
 import type { BindDeviceRuntime, InspectDeviceRuntimeFacts } from '../request-runtime-binding.ts';
-import type { GenericPlatformExecutionParams } from '../request-generic-dispatch.ts';
+import type { GenericPlatformExecutionParams } from '../generic-leaf-execution.ts';
 import {
   resolveBoundSystemButtonRuntime,
   type SystemButtonCommand,

src/daemon/__tests__/tv-remote-runtime.test.ts

@@ -19,7 +19,7 @@ import { createTestDeviceInventoryGateways } from '../../__tests__/test-utils/de
 import { LeaseRegistry } from '../lease-registry.ts';
 import { activateCompleteRefFrame, refFrameState } from '../ref-frame.ts';
 import type { BindDeviceRuntime, InspectDeviceRuntimeFacts } from '../request-runtime-binding.ts';
-import type { GenericPlatformExecutionParams } from '../request-generic-dispatch.ts';
+import type { GenericPlatformExecutionParams } from '../generic-leaf-execution.ts';
 import { resolveBoundTvRemoteRuntime } from '../tv-remote-runtime.ts';
 import { expectRefusesUnavailableExactOwnerFact } from './runtime-binding-conformance.ts';
 import { createRequestHandler } from './test-device-runtime-gateway.ts';

src/daemon/__tests__/viewport-runtime.test.ts

@@ -19,7 +19,7 @@ import { createTestDeviceInventoryGateways } from '../../__tests__/test-utils/de
 import { LeaseRegistry } from '../lease-registry.ts';
 import { activateCompleteRefFrame, refFrameState } from '../ref-frame.ts';
 import type { BindDeviceRuntime, InspectDeviceRuntimeFacts } from '../request-runtime-binding.ts';
-import type { GenericPlatformExecutionParams } from '../request-generic-dispatch.ts';
+import type { GenericPlatformExecutionParams } from '../generic-leaf-execution.ts';
 import { resolveBoundViewportRuntime } from '../viewport-runtime.ts';
 import { expectRefusesUnavailableExactOwnerFact } from './runtime-binding-conformance.ts';
 import { createRequestHandler } from './test-device-runtime-gateway.ts';

src/daemon/back-runtime.ts

@@ -5,7 +5,7 @@ import type { BoundDeviceRuntime } from '@agent-device/contracts/platform-runtim
 import type { DeviceInfo } from '@agent-device/kernel/device';
 import { successText } from '@agent-device/kernel/success-text';
 import type { DaemonCommandContext } from './context.ts';
-import type { ResolvedGenericExecution } from './request-generic-dispatch.ts';
+import type { ResolvedGenericExecution } from './generic-leaf-execution.ts';
 import { resolveBoundGenericRuntime, type RuntimeAdmissionBindings } from './runtime-admission.ts';
 import { runtimeExecutionFromContext } from './snapshot-runtime-capture-input.ts';
 

src/daemon/focus-runtime.ts

@@ -5,7 +5,7 @@ import type { Point } from '@agent-device/kernel/snapshot';
 import { successText } from '@agent-device/kernel/success-text';
 import { readPointPositionals } from '@agent-device/kernel/validation';
 import type { DaemonCommandContext } from './context.ts';
-import type { ResolvedGenericExecution } from './request-generic-dispatch.ts';
+import type { ResolvedGenericExecution } from './generic-leaf-execution.ts';
 import { resolveBoundGenericRuntime, type RuntimeAdmissionBindings } from './runtime-admission.ts';
 import { runtimeExecutionFromContext } from './snapshot-runtime-capture-input.ts';
 

src/daemon/fold-runtime.ts

@@ -9,7 +9,7 @@ import { foldRuntimeUse } from '@agent-device/contracts/platform-runtime-operati
 import type { BoundDeviceRuntime } from '@agent-device/contracts/platform-runtime';
 import type { DeviceInfo } from '@agent-device/kernel/device';
 import { successText } from '@agent-device/kernel/success-text';
-import type { ResolvedGenericExecution } from './request-generic-dispatch.ts';
+import type { ResolvedGenericExecution } from './generic-leaf-execution.ts';
 import { resolveBoundGenericRuntime, type RuntimeAdmissionBindings } from './runtime-admission.ts';
 
 /** `fold <pose>`, parsed with the same aliases the CLI reader accepts. */

src/daemon/generic-leaf-execution.ts

@@ -0,0 +1,40 @@
+// Shared by the generic dispatcher and its leaves; leaves must not import the dispatcher.
+
+import type { DaemonCommandContext } from './context.ts';
+import type { DaemonRequest, DaemonResponse } from './daemon-request.ts';
+import type { SessionState } from './session-state.ts';
+
+export type GenericPlatformExecutionParams = {
+  session: SessionState;
+  sessionName: string;
+  logPath: string;
+  command: string;
+  request: DaemonRequest;
+  positionals: string[];
+  out: string | undefined;
+  dispatchContext: DaemonCommandContext;
+};
+
+/**
+ * What actually performs a generic leaf's platform work: the already-admitted, already-bound
+ * closure the leaf's own runtime resolution supplied (ADR 0019). R58 retired the legacy
+ * alternative, so this is the only shape.
+ */
+export type GenericPlatformExecution = (
+  params: GenericPlatformExecutionParams,
+) => Promise<Record<string, unknown> | void>;
+
+/**
+ * What the session action records for this request. A runtime-owned leaf may normalize its
+ * arguments (a screenshot destination is a user-typed path) and records the normalized form.
+ */
+export type RecordedGenericRequest = Readonly<{
+  positionals: string[];
+  flags: Record<string, unknown>;
+}>;
+
+/** What a runtime-owned generic leaf resolves to before the dispatcher runs: a refusal, or the
+ * bound execution plus whatever the session action should record for it. */
+export type ResolvedGenericExecution =
+  | Readonly<{ ok: false; response: DaemonResponse }>
+  | Readonly<{ ok: true; execute: GenericPlatformExecution; recorded?: RecordedGenericRequest }>;

src/daemon/generic-runtime-execution.ts

@@ -1,4 +1,4 @@
-import type { ResolvedGenericExecution } from './request-generic-dispatch.ts';
+import type { ResolvedGenericExecution } from './generic-leaf-execution.ts';
 import { resolveBoundFocusRuntime } from './focus-runtime.ts';
 import { resolveScreenshotGenericExecution } from './screenshot-runtime.ts';
 import { resolveBoundScrollRuntime } from './scroll-runtime.ts';

src/daemon/keyboard-runtime.ts

@@ -35,7 +35,7 @@ type KeyboardRuntimeAction = 'status' | 'dismiss' | 'enter';
 
 /**
  * `keyboard`'s resolve/execute split (mirrors {@link ResolvedGenericExecution} from
- * `request-generic-dispatch.ts`), but scoped to what the session route actually has: a resolved
+ * `generic-leaf-execution.ts`), but scoped to what the session route actually has: a resolved
  * command context, never a full {@link SessionState} — `keyboard status`/`dismiss` run sessionless
  * through an explicit selector, so a handler that required one would be proving something false.
  */

src/daemon/orientation-runtime.ts

@@ -5,7 +5,7 @@ import type { BoundDeviceRuntime } from '@agent-device/contracts/platform-runtim
 import type { DeviceInfo } from '@agent-device/kernel/device';
 import { successText } from '@agent-device/kernel/success-text';
 import type { DaemonCommandContext } from './context.ts';
-import type { ResolvedGenericExecution } from './request-generic-dispatch.ts';
+import type { ResolvedGenericExecution } from './generic-leaf-execution.ts';
 import { resolveBoundGenericRuntime, type RuntimeAdmissionBindings } from './runtime-admission.ts';
 import { runtimeExecutionFromContext } from './snapshot-runtime-capture-input.ts';
 

src/daemon/request-generic-dispatch.ts

@@ -23,41 +23,7 @@ import {
 import { isActiveProviderDevice } from './provider-device-admission.ts';
 import { buildActionEventResult } from '@agent-device/session-journal/session-event-action-presentation';
 import type { AndroidObservationAdapter } from '@agent-device/contracts/android-observation';
-
-export type GenericPlatformExecutionParams = {
-  session: SessionState;
-  sessionName: string;
-  logPath: string;
-  command: string;
-  request: DaemonRequest;
-  positionals: string[];
-  out: string | undefined;
-  dispatchContext: DaemonCommandContext;
-};
-
-/**
- * What actually performs a generic leaf's platform work: the already-admitted, already-bound
- * closure the leaf's own runtime resolution supplied (ADR 0019). R58 retired the legacy
- * alternative, so this is the only shape.
- */
-export type GenericPlatformExecution = (
-  params: GenericPlatformExecutionParams,
-) => Promise<Record<string, unknown> | void>;
-
-/**
- * What the session action records for this request. A runtime-owned leaf may normalize its
- * arguments (a screenshot destination is a user-typed path) and records the normalized form.
- */
-export type RecordedGenericRequest = Readonly<{
-  positionals: string[];
-  flags: Record<string, unknown>;
-}>;
-
-/** What a runtime-owned generic leaf resolves to before the dispatcher runs: a refusal, or the
- * bound execution plus whatever the session action should record for it. */
-export type ResolvedGenericExecution =
-  | Readonly<{ ok: false; response: DaemonResponse }>
-  | Readonly<{ ok: true; execute: GenericPlatformExecution; recorded?: RecordedGenericRequest }>;
+import type { GenericPlatformExecution, RecordedGenericRequest } from './generic-leaf-execution.ts';
 
 export async function dispatchGenericCommand(params: {
   req: DaemonRequest;

src/daemon/runtime-admission.ts

@@ -14,7 +14,7 @@ import type {
 } from './request-runtime-binding.ts';
 import { ensureBoundDeviceReady } from './request-runtime-binding.ts';
 import type { DaemonCommandContext } from './context.ts';
-import type { ResolvedGenericExecution } from './request-generic-dispatch.ts';
+import type { ResolvedGenericExecution } from './generic-leaf-execution.ts';
 import { type DaemonFailureResponse, errorResponse } from '@agent-device/kernel/contracts';
 
 /** Builds the failure a command reports when its exact device cell does not admit an operation. */

src/daemon/screenshot-runtime.ts

@@ -25,10 +25,7 @@ import { runtimeExecutionFromContext } from './snapshot-runtime-capture-input.ts
 import type { DaemonCommandContext } from './context.ts';
 import { captureSnapshotData } from './snapshot-capture.ts';
 import { buildSnapshotState } from '@agent-device/capture-kit/snapshot-state';
-import type {
-  RecordedGenericRequest,
-  ResolvedGenericExecution,
-} from './request-generic-dispatch.ts';
+import type { RecordedGenericRequest, ResolvedGenericExecution } from './generic-leaf-execution.ts';
 import { createReadonlyRuntimeSessionStore } from './runtime-session.ts';
 import { assertScreenshotCropPolicy } from './screenshot-crop-target.ts';
 import { buildScreenshotCropWarnings, cropScreenshotToSelector } from './screenshot-crop.ts';

src/daemon/scroll-runtime.ts

@@ -34,7 +34,7 @@ import type { CommandFlags } from '@agent-device/contracts/command';
 import { withSuccessText } from '@agent-device/kernel/success-text';
 import type { DaemonCommandContext } from './context.ts';
 import type { SessionState } from './session-state.ts';
-import type { ResolvedGenericExecution } from './request-generic-dispatch.ts';
+import type { ResolvedGenericExecution } from './generic-leaf-execution.ts';
 import { resolveBoundGenericRuntime, type RuntimeAdmissionBindings } from './runtime-admission.ts';
 import {
   observeScrollMovement,

src/daemon/system-button-runtime.ts

@@ -12,7 +12,7 @@ import type {
 import type { DeviceInfo } from '@agent-device/kernel/device';
 import { successText } from '@agent-device/kernel/success-text';
 import type { DaemonCommandContext } from './context.ts';
-import type { ResolvedGenericExecution } from './request-generic-dispatch.ts';
+import type { ResolvedGenericExecution } from './generic-leaf-execution.ts';
 import { resolveBoundGenericRuntime, type RuntimeAdmissionBindings } from './runtime-admission.ts';
 import { runtimeExecutionFromContext } from './snapshot-runtime-capture-input.ts';
 

src/daemon/tv-remote-runtime.ts

@@ -7,7 +7,7 @@ import { AppError } from '@agent-device/kernel/errors';
 import { successText } from '@agent-device/kernel/success-text';
 import { requireIntInRange } from '@agent-device/kernel/validation';
 import type { DaemonCommandContext } from './context.ts';
-import type { ResolvedGenericExecution } from './request-generic-dispatch.ts';
+import type { ResolvedGenericExecution } from './generic-leaf-execution.ts';
 import { resolveBoundGenericRuntime, type RuntimeAdmissionBindings } from './runtime-admission.ts';
 import { runtimeExecutionFromContext } from './snapshot-runtime-capture-input.ts';
 

src/daemon/viewport-runtime.ts

@@ -1,7 +1,7 @@
 import { readViewportDimensions } from '@agent-device/contracts/capture';
 import { viewportRuntimeUse } from '@agent-device/contracts/platform-runtime-operations';
 import type { DeviceInfo } from '@agent-device/kernel/device';
-import type { ResolvedGenericExecution } from './request-generic-dispatch.ts';
+import type { ResolvedGenericExecution } from './generic-leaf-execution.ts';
 import { admitRuntimeUse, type RuntimeAdmissionBindings } from './runtime-admission.ts';
 
 export async function resolveBoundViewportRuntime(