feat: keep replay session active on request (#1554)

* feat: keep replay session active on request

* test: cover replay keep-session provider route

* fix: make replay session handoff reliable

* refactor(daemon): extract the replay terminal-lifecycle policy module (#1554 review)

session-replay-runtime.ts was already over the 500-line extract-before-adding-behavior
tripwire before this PR; the keep-session/repair terminal-close decision, its
live-session postcondition, and the dispatched-action count pushed it further past
budget. Move that policy into a focused session-replay-terminal-lifecycle.ts
(isExecutableReplayAction, resolveSuppressedTerminalCloseIndex,
countExecutedReplayActions, requireLiveSessionForKeepSession) so the runtime file
stays orchestration-only, and mirror its PR-added unit tests into
session-replay-terminal-lifecycle.test.ts. Pure extraction: no assertions changed.

Author: thymikee

packages/contracts/src/cli-flags.ts

@@ -136,6 +136,8 @@ export type CliFlags = CloudProviderProfileFields &
     replayShellEnv?: Record<string, string>;
     replayFrom?: number;
     replayPlanDigest?: string;
+    /** Replay: leave the session active by suppressing an authored terminal close in native .ad. */
+    replayKeepSession?: boolean;
     failFast?: boolean;
     timeoutMs?: number;
     retries?: number;

packages/contracts/src/client-replay.ts

@@ -30,6 +30,8 @@ export type ReplayRunOptions = AgentDeviceRequestOverrides &
     resumeFrom?: number;
     /** The `resume.planDigest` from the divergence report `resumeFrom` came from. */
     resumePlanDigest?: string;
+    /** Leave the session active by suppressing an authored terminal `close` in native `.ad`. */
+    keepSession?: boolean;
     /**
      * ADR 0012 decision 6, R1/R6: arms agent-supervised re-record repair
      * from this replay attempt onward. Optional string value is the healed

packages/contracts/src/client-request.ts

@@ -56,6 +56,7 @@ export type CommandExecutionOptions = Partial<ScreenshotRequestFlags> & {
   replayShellEnv?: Record<string, string>;
   replayFrom?: number;
   replayPlanDigest?: string;
+  replayKeepSession?: boolean;
   failFast?: boolean;
   timeoutMs?: number;
   retries?: number;

packages/contracts/src/replay.ts

@@ -7,10 +7,10 @@ export type ReplayCommandResult = {
   session: string;
   /**
    * True iff `session` still exists in the daemon's session store when the
-   * response is built — i.e. the replayed script had no terminal `close`
-   * (ADR 0016's consumption contract). The client uses this, not script
-   * parsing, to decide whether an owned one-shot daemon must stay alive so
-   * the caller can keep addressing this session.
+   * response is built. This remains true when replay suppresses an authored
+   * terminal `close` for an explicit live-session handoff. The client uses
+   * this, not script parsing, to decide whether an owned one-shot daemon must
+   * stay alive so the caller can keep addressing this session.
    */
   sessionActive: boolean;
   artifactPaths: string[];

scripts/integration-progress-model.ts

@@ -182,6 +182,7 @@ function summarizeProviderScenarioFlagCoverage(files) {
     ['replayEnv', 'replay/test variable injection', ['env']],
     ['replayFrom', 'replay resume skips completed steps (ADR 0012)', ['resumeFrom']],
     ['replayPlanDigest', 'replay resume plan-digest preflight binding', ['resumePlanDigest']],
+    ['replayKeepSession', 'native replay terminal-close suppression', ['keepSession']],
     ['failFast', 'test suite stops after first failure'],
     ['timeoutMs', 'wait/test timeout flags'],
     ['retries', 'test suite retry budget flows through request path'],

src/cli/parser/cli-help.ts

@@ -358,7 +358,7 @@ Validation and evidence:
     agent-device screenshot
     agent-device press 124 817
     agent-device snapshot -i
-  Startup/CPU/memory/frame first pass: perf metrics --json (bare perf and metrics are aliases). Focused frame/jank health: perf frames --json. Memory-only sample: perf memory sample --json returns compact JSON with bounded top offenders. Heap/memgraph artifact escalation: perf memory snapshot --out heap.artifact; use --kind android-hprof on Android or --kind memgraph on supported Apple simulator/macOS app sessions. Android native profiling: perf cpu profile start|stop|report --kind simpleperf --out <path>; Android native traces: perf trace start|stop --kind perfetto --out <path>. Artifact collectors return compact state/path/size metadata only; raw heap/profile/trace files stay on disk. Treat native perf output as the agent evidence: for example, a Perfetto stop can return state=stopped, outPath=/tmp/app.perfetto-trace, sizeBytes=5392410, and method=adb-shell-perfetto while the 5.3 MB raw trace stays in the artifact. This is better than raw dumps for agents because it is stable, bounded, and keeps large artifacts out of context. heapprofd is deferred until Perfetto plumbing is available. Replay divergence and resume: a failing replay/test step returns REPLAY_DIVERGENCE with a bounded report (screen digest, ranked selector suggestions, resume). Repair app state, then resume with replay --from <n> --plan-digest <sha256> (both from the report's resume field) to continue from the failed step without re-running earlier ones; resume never re-executes skipped steps, so app state is the caller's responsibility, and it is rejected with INVALID_ARGS when the plan digest is stale, --from is out of range, or the skipped range/target touches runtime control flow. The plan digest binds the script, its includes, the effective --platform/--target, and per-action runtime/identity. Native .ad interpolation is late-bound after planning, so changing only its values keeps the digest; Maestro environment substitution occurs during compatibility parsing and can change action inputs, includes, or control expansion, so it can change the digest. --from is replay-only; test rejects it. --update/-u no longer rewrites the script (ADR 0012) — it is a no-op kept for compatibility; every divergence already carries the same ranked suggestions. Agent-supervised repair (heal-by-doing): arm replay <file>.ad --save-script[=<out>] before step 1 (armed once; --from continuations do not need it again). Every divergence carries a repairHint: record-and-heal means press the correct control via a blessed @ref from the divergence's screen.refs, recorded (no --no-record), then continue with replay --from <n+1> --plan-digest <sha256>; state-repair means the script is correct but app state is not, so fix state with --no-record actions, then replay --from <n> --plan-digest <sha256> to re-run the unchanged step; caution means something already matches the recorded selector, so a blind re-press may repeat the mistake; manual means no safe automated repair could be proven. (If close --save-script is run before a required resume, the repair is aborted and no script is written). While armed, read-only inspection YOU run to locate the repair target (snapshot -i, get attrs, find, is) is excluded from the healed script by default — no --no-record needed; the script's own authored get/is/find steps are unaffected and stay in the heal. If the step you are repairing is itself a read, pass --record on that one command so it lands in the heal (--record is accepted only on snapshot/get/is and a read-only find; it is mutually exclusive with --no-record). Ending the repair with close --save-script[=<out>] writes only the steps recorded since the arming replay as <out>, defaulting to the <file> sibling <stem>.healed.ad — review its diff before promoting it over the original.
+  Startup/CPU/memory/frame first pass: perf metrics --json (bare perf and metrics are aliases). Focused frame/jank health: perf frames --json. Memory-only sample: perf memory sample --json returns compact JSON with bounded top offenders. Heap/memgraph artifact escalation: perf memory snapshot --out heap.artifact; use --kind android-hprof on Android or --kind memgraph on supported Apple simulator/macOS app sessions. Android native profiling: perf cpu profile start|stop|report --kind simpleperf --out <path>; Android native traces: perf trace start|stop --kind perfetto --out <path>. Artifact collectors return compact state/path/size metadata only; raw heap/profile/trace files stay on disk. Treat native perf output as the agent evidence: for example, a Perfetto stop can return state=stopped, outPath=/tmp/app.perfetto-trace, sizeBytes=5392410, and method=adb-shell-perfetto while the 5.3 MB raw trace stays in the artifact. This is better than raw dumps for agents because it is stable, bounded, and keeps large artifacts out of context. heapprofd is deferred until Perfetto plumbing is available. Replay divergence and resume: a failing replay/test step returns REPLAY_DIVERGENCE with a bounded report (screen digest, ranked selector suggestions, resume). Repair app state, then resume with replay --from <n> --plan-digest <sha256> (both from the report's resume field) to continue from the failed step without re-running earlier ones; resume never re-executes skipped steps, so app state is the caller's responsibility, and it is rejected with INVALID_ARGS when the plan digest is stale, --from is out of range, or the skipped range/target touches runtime control flow. The plan digest binds the script, its includes, the effective --platform/--target, and per-action runtime/identity. Native .ad interpolation is late-bound after planning, so changing only its values keeps the digest; Maestro environment substitution occurs during compatibility parsing and can change action inputs, includes, or control expansion, so it can change the digest. --from is replay-only; test rejects it. Native .ad session takeover: replay <file>.ad --keep-session suppresses exactly an authored terminal close and returns the surviving session for continued commands; interior closes still run, close-less scripts are unchanged, and test/Maestro reject the option. --update/-u no longer rewrites the script (ADR 0012) — it is a no-op kept for compatibility; every divergence already carries the same ranked suggestions. Agent-supervised repair (heal-by-doing): arm replay <file>.ad --save-script[=<out>] before step 1 (armed once; --from continuations do not need it again). Every divergence carries a repairHint: record-and-heal means press the correct control via a blessed @ref from the divergence's screen.refs, recorded (no --no-record), then continue with replay --from <n+1> --plan-digest <sha256>; state-repair means the script is correct but app state is not, so fix state with --no-record actions, then replay --from <n> --plan-digest <sha256> to re-run the unchanged step; caution means something already matches the recorded selector, so a blind re-press may repeat the mistake; manual means no safe automated repair could be proven. (If close --save-script is run before a required resume, the repair is aborted and no script is written). While armed, read-only inspection YOU run to locate the repair target (snapshot -i, get attrs, find, is) is excluded from the healed script by default — no --no-record needed; the script's own authored get/is/find steps are unaffected and stay in the heal. If the step you are repairing is itself a read, pass --record on that one command so it lands in the heal (--record is accepted only on snapshot/get/is and a read-only find; it is mutually exclusive with --no-record). Ending the repair with close --save-script[=<out>] writes only the steps recorded since the arming replay as <out>, defaulting to the <file> sibling <stem>.healed.ad — review its diff before promoting it over the original.
   Recording: record start/stop. The default scope is app and expects an active session created by open <app>; this keeps app proof videos tied to the intended app session. Use record start --scope device/system to explicitly request whole-screen capture where the selected backend supports it, such as recordings that intentionally span multiple apps, home screen, settings, or app transitions. Use --max-size to cap the longest edge and --quality medium|high to choose output quality across Android and Apple targets. By default, stop burns touch overlays into the video; use record start --hide-touches for the fastest raw recording. Android record start publishes a durable device manifest. Android adb screenrecord has a 180s platform limit, so longer Android recordings are returned as multiple MP4 chunks while the daemon stays alive; after daemon restart, record stop recovers only manifest-owned chunks and warns when gesture overlays are unavailable. For gesture-heavy iOS simulator proof videos, prefer --hide-touches because overlay timing depends on a stable runner session while gestures are executing. Tracing: trace start ./trace.log, trace stop ./trace.log. Paths are positional.
   Stable known flow: batch ./steps.json, not workflow batch.
   Inline batch JSON example:

src/commands/cli-grammar/flag-definitions-workflow.ts

@@ -30,6 +30,14 @@ export const WORKFLOW_FLAG_DEFINITIONS: readonly FlagDefinition[] = [
       'Replay: the plan digest a --from resume must match (from a prior divergence report); mismatch, ' +
       'edits, or include/platform-expansion changes fail INVALID_ARGS before any action',
   },
+  {
+    key: 'replayKeepSession',
+    names: ['--keep-session'],
+    type: 'boolean',
+    usageLabel: '--keep-session',
+    usageDescription:
+      'Replay: leave the session active by suppressing exactly an authored terminal close in a native .ad script; replay only, not test or Maestro YAML',
+  },
   {
     key: 'replayMaestro',
     names: ['--maestro'],

src/commands/cli-grammar/types.ts

@@ -37,6 +37,7 @@ export type CommandInput = Omit<InternalRequestOptions, 'batchSteps' | 'target'>
     from?: PointInput;
     include?: CliFlags['networkInclude'];
     kind?: string;
+    keepSession?: boolean;
     locator?: string;
     mode?: 'in-app' | 'system' | 'full' | 'limited';
     button?: ClickButton;

src/commands/command-flags.ts

@@ -103,6 +103,7 @@ function buildFlags(options: InternalRequestOptions): CommandFlags {
     replayShellEnv: options.replayShellEnv,
     replayFrom: options.replayFrom,
     replayPlanDigest: options.replayPlanDigest,
+    replayKeepSession: options.replayKeepSession,
     failFast: options.failFast,
     timeoutMs: options.timeoutMs,
     retries: options.retries,

src/commands/replay/index.test.ts

@@ -228,6 +228,26 @@ describe('replay resume (ADR 0012 decision 4 / migration step 5)', () => {
   });
 });
 
+describe('replay --keep-session', () => {
+  test('projects the CLI flag through structured replay input and the daemon request', () => {
+    const input = replayCliReader(['./checkout.ad'], flags({ replayKeepSession: true }));
+    expect(input).toMatchObject({ path: './checkout.ad', keepSession: true });
+    expect(replayDaemonWriter(input)).toMatchObject({
+      command: 'replay',
+      positionals: ['./checkout.ad'],
+      options: { replayKeepSession: true },
+    });
+    expect(replayCommandMetadata.inputSchema.properties).toHaveProperty('keepSession');
+  });
+
+  test('test exposes and forwards no keep-session option', () => {
+    const input = testCliReader(['./suite.ad'], flags({ replayKeepSession: true } as never));
+    expect(input).not.toHaveProperty('keepSession');
+    expect(testCommandMetadata.inputSchema.properties).not.toHaveProperty('keepSession');
+    expect(testDaemonWriter(input).options).not.toHaveProperty('replayKeepSession');
+  });
+});
+
 describe('replay --save-script arming (ADR 0012 decision 6, R1/R6)', () => {
   test('reads --save-script as a boolean flag', () => {
     expect(replayCliReader(['./checkout.ad'], flags({ saveScript: true }))).toMatchObject({