refactor(replay): declare the dispatch options once in contracts

The daemon's request-private half now extends ReplayDispatchOptions from
@agent-device/contracts/replay and the replay port emits the same type, so a
key renamed on either side fails to compile. The Maestro mapping keeps its
satisfies guard. SessionScope and DaemonInstallSource lose their aliases,
doc blocks sit above the functions they describe, and the handler test pins
the private-half merge order.

Author: thymikee

packages/contracts/src/daemon-wire-request.ts

@@ -1,14 +1,12 @@
 import type { CommandFlags } from './command-flags.ts';
 import type {
+  DaemonInstallSource,
   LeaseBackend,
-  DaemonInstallSource as PublicDaemonInstallSource,
   DaemonRequestMeta as PublicDaemonRequestMeta,
   DaemonRequest as WireRequest,
 } from '@agent-device/kernel/contracts';
 import type { PlatformSelector } from '@agent-device/kernel/device';
 
-export type DaemonInstallSource = PublicDaemonInstallSource;
-
 /**
  * Request metadata as a client may send it, with the two fields the daemon narrows past what the
  * wire can express and the lease coordinates the router reads. Public throughout: nothing here

packages/contracts/src/facades/command.ts

@@ -10,11 +10,7 @@ export {
 export type { DaemonBatchStep } from '../batch-step.ts';
 export type { CliFlags, DaemonExcludedCliFlag } from '../cli-flags.ts';
 export type { CommandFlags, MaestroRuntimeFlags } from '../command-flags.ts';
-export type {
-  DaemonInstallSource,
-  DaemonWireRequest,
-  DaemonWireRequestMeta,
-} from '../daemon-wire-request.ts';
+export type { DaemonWireRequest, DaemonWireRequestMeta } from '../daemon-wire-request.ts';
 export type { DispatchedCommand } from '../dispatched-command.ts';
 export { readOptionalInteger, readOptionalNumber } from '../input-validation.ts';
 export {

packages/contracts/src/facades/replay.ts

@@ -2,6 +2,8 @@ export type { RefFrameEffect } from '../ref-frame-effect.ts';
 export { REPLAY_TARGET_GUARD_MISMATCH_REASON, WAIT_LANDMARK_MISMATCH_REASON } from '../replay.ts';
 export type {
   ReplayCommandResult,
+  ReplayDispatchOptions,
+  ReplayOpenLifecycle,
   ReplayObservationAuthority,
   ReplayObservationAuthorityBinder,
   ReplayObservationCapture,

packages/contracts/src/replay.ts

@@ -1,10 +1,14 @@
 import type { DaemonError } from '@agent-device/kernel/errors';
-import type { SnapshotState } from '@agent-device/kernel/snapshot';
+import type { DaemonResponse } from '@agent-device/kernel/contracts';
+import type { Rect, SnapshotState } from '@agent-device/kernel/snapshot';
+import type { GestureExecutionProfile } from './gesture-plan-types.ts';
+import type { SessionScope } from './session-scope.ts';
 import type { SnapshotDiagnosticsSummary } from './snapshot-diagnostics.ts';
 import type {
   LocalIdentity,
   NodeStructuralDenotation,
   TargetAncestryEntry,
+  TargetAnnotationV1,
 } from './target-annotation.ts';
 import { WAIT_REASONS } from './wait.ts';
 
@@ -221,3 +225,65 @@ export type ReplayObservationAuthority = Readonly<{
  * session-store pair the binding is drawn from.
  */
 export type ReplayObservationAuthorityBinder = (signal?: AbortSignal) => ReplayObservationAuthority;
+
+/** Runs before an `open` dispatches; a failure response aborts the dispatch with it. */
+export type ReplayOpenLifecycle = Readonly<{
+  beforeDispatch: () => Promise<DaemonResponse | undefined>;
+}>;
+
+/**
+ * What a replay-issued dispatch asks the daemon to honor beyond the wire request. Declared once:
+ * the daemon's request-private half extends this shape, and the replay port emits it, so a key
+ * renamed on one side fails to compile on the other instead of being silently ignored.
+ */
+export type ReplayDispatchOptions = Readonly<{
+  /**
+   * PROVENANCE, set by the replay runtime on every action it dispatches from a replay plan,
+   * annotated or not. It marks the action as AUTHORED (it came from the `.ad` under repair) rather
+   * than typed out-of-band by the agent mid-repair. The repair-segment exclusion keys off its
+   * ABSENCE: an authored `get`/`is`/`find`/`snapshot` step must survive into its own healed script,
+   * while an interactive diagnostic read used only to LOCATE the repair target must not.
+   * Trustworthy because the private half is daemon-only: the transport never copies it off the
+   * wire, so no client can spoof authored provenance.
+   */
+  replayPlanStep?: boolean;
+  /**
+   * Implicit caller scope resolved before a nested dispatch replaces the public session name with
+   * its effective scoped key.
+   */
+  resolvedSessionScope?: SessionScope;
+  /**
+   * ADR 0012 step 4 post-resolution guard: the verified target member's normalized local identity
+   * AND structural denotation (document order + sibling ordinal), set ONLY by the replay step loop
+   * when dispatching an annotated action whose pre-action verification passed. Interaction handlers
+   * thread it into command options as `expectedResolvedTarget`; dispatch's own resolution refuses
+   * (pre-action) when its winner differs in local identity OR structural position.
+   */
+  replayTargetGuard?: ReplayTargetGuardDenotation;
+  /** Dual-endpoint counterpart of `replayTargetGuard` for target-authored drag. */
+  replayTargetGuards?: Readonly<{
+    source: ReplayTargetGuardDenotation;
+    destination: ReplayTargetGuardDenotation;
+  }>;
+  /**
+   * ADR 0012 / #1349 deferred (post-resolution) identity verification: the recorded `target-v1`
+   * landmark of an annotated selector `wait`, set ONLY by the replay step loop. The wait dispatch
+   * threads it into the polling loop as `recordedLandmark`; success then requires a selector match
+   * carrying this identity, and a timeout with rejected candidates surfaces the
+   * `WAIT_LANDMARK_MISMATCH_REASON` refusal the step loop converts into an identity-mismatch
+   * divergence.
+   */
+  replayLandmarkGuard?: TargetAnnotationV1;
+  openLifecycle?: ReplayOpenLifecycle;
+  /** Terminate the targeted app without ending the owning daemon session. */
+  closeAppOnly?: boolean;
+  /**
+   * Daemon-composed hierarchy capture used as operational evidence only. It must not issue or
+   * replace client ref authority.
+   */
+  observationOnly?: true;
+  /** Provider-owned viewport already resolved while normalizing a nested gesture command. */
+  gestureViewport?: Rect;
+  /** Maestro-compat execution profile for timed coordinate swipes projected to `gesture pan`. */
+  gestureExecutionProfile?: GestureExecutionProfile;
+}>;

src/daemon/__tests__/daemon-request-wire.test.ts

@@ -2,6 +2,7 @@ import { expect, test } from 'vitest';
 import type { DeviceLease } from '@agent-device/contracts/device';
 import type { DaemonRequest } from '../daemon-request.ts';
 import type { DaemonWireRequest } from '@agent-device/contracts/command';
+import type { ExecutionPlan } from '../execution-plan.ts';
 import type { SessionState } from '../session-state.ts';
 
 /**
@@ -53,7 +54,10 @@ const wireCannotReachDeviceLease: IsExactly<Reaches<DaemonWireRequest, DeviceLea
 
 // Positive controls: without these, a walk that simply never finds anything would pass above.
 const requestHasInternalKey: IsExactly<Extract<keyof DaemonRequest, 'internal'>, 'internal'> = true;
-const requestReachesSessionState: IsExactly<Reaches<DaemonRequest, SessionState>, true> = true;
+// The private half no longer names `SessionState` itself (its open-lifecycle hook takes no
+// session since the replay dispatch options moved to contracts); the batch execution plan is the
+// daemon-only shape it still carries, so it stands as the second positive control.
+const requestReachesExecutionPlan: IsExactly<Reaches<DaemonRequest, ExecutionPlan>, true> = true;
 const requestReachesDeviceLease: IsExactly<Reaches<DaemonRequest, DeviceLease>, true> = true;
 
 test('the wire request shape carries no daemon-only half', () => {
@@ -65,7 +69,7 @@ test('the wire request shape carries no daemon-only half', () => {
 });
 
 test('the daemon request shape does reach both, so the walk above can find them', () => {
-  expect([requestHasInternalKey, requestReachesSessionState, requestReachesDeviceLease]).toEqual([
+  expect([requestHasInternalKey, requestReachesExecutionPlan, requestReachesDeviceLease]).toEqual([
     true,
     true,
     true,

src/daemon/__tests__/session-routing.test.ts

@@ -7,7 +7,8 @@ import type { DeviceInfo } from '@agent-device/kernel/device';
 import { SessionStore } from '../session-store.ts';
 import { resolveEffectiveSessionName, resolveSessionScope } from '../session-routing.ts';
 import type { DaemonRequest } from '../daemon-request.ts';
-import type { SessionScope, SessionState } from '../session-state.ts';
+import type { SessionState } from '../session-state.ts';
+import type { SessionScope } from '@agent-device/contracts/session';
 import { mkdtempForTestSync } from '../../__tests__/test-utils/tmp-dir.ts';
 
 function makeSession(name: string): SessionState {

src/daemon/daemon-request.ts

@@ -1,19 +1,13 @@
 import type { ExecutionPlan } from './execution-plan.ts';
-import type { GestureExecutionProfile } from '@agent-device/contracts/gesture-plan-types';
 import type { PreresolvedInteractionTarget } from '@agent-device/contracts/interaction';
 import type { DeviceLease } from '@agent-device/contracts/device';
-import type {
-  ReplayTargetGuardDenotation,
-  TargetAnnotationV1,
-} from '@agent-device/contracts/replay';
+import type { ReplayDispatchOptions } from '@agent-device/contracts/replay';
 import type {
   DaemonArtifact as PublicDaemonArtifact,
   DaemonResponse as PublicDaemonResponse,
   DaemonResponseData as PublicDaemonResponseData,
 } from '@agent-device/kernel/contracts';
-import type { Rect } from '@agent-device/kernel/snapshot';
 import type { DaemonWireRequest } from '@agent-device/contracts/command';
-import type { SessionState } from './session-state.ts';
 
 /**
  * The daemon's own request and response vocabulary: the wire shape from `@agent-device/contracts/command` (`DaemonWireRequest`)
@@ -24,11 +18,12 @@ import type { SessionState } from './session-state.ts';
 export type DaemonArtifact = PublicDaemonArtifact;
 export type DaemonResponseData = PublicDaemonResponseData;
 
-export type DaemonOpenLifecycle = {
-  beforeDispatch?: (session: SessionState) => Promise<DaemonResponse | undefined>;
-};
-
-type DaemonRequestInternal = {
+/**
+ * What only the daemon may see on a request: the replay dispatch options (declared once in
+ * `@agent-device/contracts/replay`, so the port and the daemon cannot drift), plus the callbacks,
+ * plan and lease the daemon composes for itself.
+ */
+type DaemonRequestInternal = ReplayDispatchOptions & {
   /**
    * What an `open` spent from its `--wait` budget while it waited for this device outside the
    * device execution lock. The refusal the open ends with has to say the budget was spent, and
@@ -37,7 +32,6 @@ type DaemonRequestInternal = {
    */
   openDeviceWait?: { waitedMs: number };
   publicNetworkOnly?: true;
-  openLifecycle?: DaemonOpenLifecycle;
   /**
    * The steps a batch still has ahead of this one. The open seam derives platform readiness
    * policy (runner demand) from it; the transport strips `internal`, so it never arrives from a
@@ -51,50 +45,6 @@ type DaemonRequestInternal = {
    */
   retainDeviceExecutionLock?: (deviceId: string) => Promise<void>;
   admittedLease?: DeviceLease;
-  /**
-   * Daemon-composed hierarchy capture used as operational evidence only.
-   * It must not issue or replace client ref authority.
-   */
-  observationOnly?: true;
-  /**
-   * Implicit caller scope resolved before a nested dispatch replaces the
-   * public session name with its effective scoped key.
-   */
-  resolvedSessionScope?: SessionState['sessionScope'];
-  /** Terminate the targeted app without ending the owning daemon session. */
-  closeAppOnly?: boolean;
-  /** Provider-owned viewport already resolved while normalizing a nested gesture command. */
-  gestureViewport?: Rect;
-  /** Maestro-compat execution profile for timed coordinate swipes projected to `gesture pan`. */
-  gestureExecutionProfile?: GestureExecutionProfile;
-  /**
-   * ADR 0012 step 4 post-resolution guard: the verified target member's
-   * normalized local identity AND structural denotation (document order +
-   * sibling ordinal), set ONLY by the replay step loop when dispatching an
-   * annotated action whose pre-action verification passed. Interaction
-   * handlers thread it into command options as `expectedResolvedTarget`;
-   * dispatch's own resolution refuses (pre-action) when its winner differs in
-   * local identity OR structural position — the latter distinguishes a
-   * different same-identity duplicate.
-   */
-  replayTargetGuard?: ReplayTargetGuardDenotation;
-  /** Dual-endpoint counterpart of replayTargetGuard for target-authored drag. */
-  replayTargetGuards?: {
-    source: ReplayTargetGuardDenotation;
-    destination: ReplayTargetGuardDenotation;
-  };
-  /**
-   * ADR 0012 / #1349 deferred (post-resolution) identity verification: the
-   * recorded `target-v1` landmark of an annotated selector `wait`, set ONLY
-   * by the replay step loop. The wait dispatch threads it into the polling
-   * loop as `recordedLandmark`; success then requires a selector match
-   * carrying this identity, and a timeout with rejected candidates surfaces
-   * the `WAIT_LANDMARK_MISMATCH_REASON` refusal the step loop converts into
-   * an identity-mismatch divergence. Never used by the generic pre-dispatch
-   * verification path — a wait's landmark may legitimately be absent when
-   * the step starts.
-   */
-  replayLandmarkGuard?: TargetAnnotationV1;
   /**
    * ADR 0014 / #1654: the complete ref/node/tree target a mutating `find`
    * resolved against its fresh capture. Its presence both marks the ref as
@@ -104,32 +54,11 @@ type DaemonRequestInternal = {
    * side-effect seam and expires the frame.
    */
   findResolvedTarget?: PreresolvedInteractionTarget;
-  /**
-   * #1271 stage 2 (ADR 0012 decision 6 amendment): PROVENANCE — set by the
-   * replay runtime (`invokeResolvedReplayAction`,
-   * `session-replay-action-runtime.ts`) on every action it dispatches from a
-   * replay plan, annotated or not. It marks the action as AUTHORED (it came
-   * from the `.ad` under repair) rather than typed out-of-band by the agent
-   * mid-repair.
-   *
-   * The repair-segment exclusion keys off its ABSENCE: an authored
-   * `get`/`is`/`find`/`snapshot` step must survive into its own healed script
-   * (silently dropping it would make the heal quietly stop asserting what the
-   * original flow asserted), while an interactive diagnostic read used only to
-   * LOCATE the repair target must not. Command class alone cannot tell those
-   * apart — they are the same command — so provenance is the discriminator and
-   * `--record` is only for deliberately inserting an interactive read.
-   *
-   * Trustworthy because `internal` is daemon-only: `toDaemonRequest`
-   * (`server/http-server.ts`) never copies it off the wire, so no client can
-   * spoof authored provenance. Same channel as `replayTargetGuard` above.
-   */
-  replayPlanStep?: boolean;
 };
 
 /**
  * The server-side request: `DaemonWireRequest` plus what only the daemon may see. `internal`
- * carries `SessionState` callbacks and the admitted lease — which is why this type stays in the
+ * carries the admitted lease, the execution plan and request-owned callbacks — which is why this type stays in the
  * daemon and why the wire half is declared separately. Zones below it that only need to classify
  * a command take `contracts/dispatched-command.ts` instead.
  */

src/daemon/handlers/__tests__/session-replay-command.test.ts

@@ -8,7 +8,8 @@ import {
 import { createScreenRecordingAdmissionLedger } from '@agent-device/capture-kit/screen-recording-admission-ledger';
 import { platformResourceCleanup } from '../../../platform-runtime-resource-cleanup.ts';
 import type { SessionCommandParams } from '../session-command-input.ts';
-import { handleReplayTestCommand } from '../session-replay-command.ts';
+import { handleReplayTestCommand, replayInvoke } from '../session-replay-command.ts';
+import type { DaemonRequest } from '../../daemon-request.ts';
 import { makeSessionStore } from './session-test-harness.ts';
 import { mkdtempForTestSync } from '../../../__tests__/test-utils/tmp-dir.ts';
 
@@ -51,3 +52,63 @@ test('replay test handler threads the complete video owner into the application
   expect(response.error.code).toBe('INVALID_ARGS');
   expect(response.error.message).not.toContain('Screen-recording runtime is not configured');
 });
+
+test('replayInvoke re-attaches the originating private half, then folds the dispatch bag over it', async () => {
+  const base: DaemonRequest = {
+    token: 'token',
+    session: 'default',
+    command: 'replay',
+    positionals: [],
+    internal: {
+      publicNetworkOnly: true,
+      replayTargetGuard: {
+        identity: { role: 'button', label: 'Old' },
+        structural: { documentOrder: 0, sibling: 0 },
+      },
+    },
+  };
+  const invoked: DaemonRequest[] = [];
+  const invoke = replayInvoke(async (request) => {
+    invoked.push(request);
+    return { ok: true, data: {} };
+  }, base);
+
+  await invoke({
+    token: 'token',
+    session: 'default',
+    command: 'tap',
+    positionals: ['@e1'],
+    dispatch: {
+      replayPlanStep: true,
+      replayTargetGuard: {
+        identity: { role: 'button', label: 'New' },
+        structural: { documentOrder: 1, sibling: 0 },
+      },
+    },
+  });
+  await invoke({ token: 'token', session: 'default', command: 'snapshot', positionals: [] });
+
+  expect(invoked[0]?.internal).toEqual({
+    publicNetworkOnly: true,
+    replayPlanStep: true,
+    replayTargetGuard: {
+      identity: { role: 'button', label: 'New' },
+      structural: { documentOrder: 1, sibling: 0 },
+    },
+  });
+  expect(invoked[0]).not.toHaveProperty('dispatch');
+  expect(invoked[1]?.internal).toEqual(base.internal);
+});
+
+test('replayInvoke sends no private half when neither side carries one', async () => {
+  const invoked: DaemonRequest[] = [];
+  const invoke = replayInvoke(
+    async (request) => {
+      invoked.push(request);
+      return { ok: true, data: {} };
+    },
+    { token: 'token', session: 'default', command: 'replay', positionals: [] },
+  );
+  await invoke({ token: 'token', session: 'default', command: 'snapshot', positionals: [] });
+  expect(invoked[0]).not.toHaveProperty('internal');
+});

src/daemon/install-source-resolution.ts

@@ -1,7 +1,6 @@
 import { AppError } from '@agent-device/kernel/errors';
-import type { LocalInstallSource } from '@agent-device/kernel/contracts';
+import type { DaemonInstallSource, LocalInstallSource } from '@agent-device/kernel/contracts';
 import { cleanupUploadedArtifact, prepareUploadedArtifact } from './artifact-tracking.ts';
-import type { DaemonInstallSource } from '@agent-device/contracts/command';
 import type { DaemonRequest } from './daemon-request.ts';
 
 function assertUnsupportedInstallSource(source: never): never {

src/daemon/replay/internal/__tests__/session-test-suite-command-video.test.ts

@@ -289,8 +289,7 @@ test('test finalizes replay video exactly once when cancellation arrives after s
       if (nestedReq.command === 'open') {
         const provisionalSession = makeIosSession(nestedReq.session);
         sessionStore.set(nestedReq.session, provisionalSession);
-        const hookResponse =
-          await nestedReq.internal?.openLifecycle?.beforeDispatch?.(provisionalSession);
+        const hookResponse = await nestedReq.internal?.openLifecycle?.beforeDispatch?.();
         if (hookResponse && !hookResponse.ok) return hookResponse;
         events.push('open:dispatch');
       }