docs: propose active-session script publication

[thymikee]

Summary

Propose an ARMED → PUBLISHED lifecycle for ordinary .ad recordings.

session save-script publishes an open-to-destination script without closing its live session. The ADR requires exactly one initial open, a portable selector-level destination guard after the last descriptor-classified mutation, and terminal ABORTED/PUBLISHED states that cannot be re-armed through later save flags. It preserves the replay response's live-session handoff and explicitly excludes secret-bearing journeys until #1348 provides safe parameterized authoring. #1349 tracks post-resolution identity verification that does not break wait polling.

Lifecycle-free composition remains a separate decision in #1336.

Part of #1346.

Prototype evidence: https://github.com/callstack/agent-device/tree/agent/prototype-session-save-replay/scripts/prototypes/session-save-script

Validation

• Formatted the new ADR and domain vocabulary with oxfmt.
• Verified the commit diff has no whitespace errors.
• Confirmed the ADR's referenced local documents exist.
• Exercised portable-guard refusal and ARMED/ABORTED/PUBLISHED transitions in the throwaway prototype.

[github-actions]

Size Report

Metric	Base	Current	Diff
JS raw	1.8 MB	1.8 MB	-832 B
JS gzip	573.1 kB	572.4 kB	-704 B
npm tarball	687.2 kB	686.8 kB	-418 B
npm unpacked	2.4 MB	2.4 MB	-832 B

Startup median (7 runs, lower is better):

Scenario	Base	Current	Diff
CLI --version	28.4 ms	27.8 ms	-0.5 ms
CLI --help	61.1 ms	58.2 ms	-2.9 ms

Top changed chunks:

Chunk	Raw diff	Gzip diff
dist/src/cli.js	+3.0 kB	+949 B
dist/src/server.js	-569 B	-227 B

[thymikee]

Addressed the four review gaps in 30fed3b70:

1. Sensitive inputs: the ADR now states that recorded fill text is literal artifact content and explicitly excludes secret-bearing journeys from v1. Safe publish-time parameterization is tracked in Parameterize sensitive inputs before publishing .ad recordings #1348; existing native .ad ${VAR} replay substitution is the execution primitive, while Parameterize sensitive inputs before publishing .ad recordings #1348 owns safe authoring before any file/temp write.
2. Replay handoff: the consumption contract now preserves the existing behavior explicitly: no serialized close leaves the named session active, and successful ReplayCommandResult.session is the binding for subsequent commands.
3. Destination readiness: publication now requires an authored, target-bearing terminal destination guard and fails before writing when it is absent. Cold replay must complete that guard before success. V1 deliberately does not infer a screen fingerprint.
4. Vocabulary: renamed the artifact to open-to-destination script and reserved “replay” for the act/engine. I kept session save-replay; save-recording would collide with the existing screen/video recording domain.

The ADR remains scoped to one open → one guarded destination; lifecycle-free fragments and entry guards remain in #1336.

[thymikee]

Naming follow-up in 73cdff0cb: the publication action is now session save-script.

The command language consistently treats the .ad file as a script and replay as its execution:

agent-device open app --save-script=screen-x.ad  # arm and choose the script target
agent-device session save-script                 # publish now, without close
agent-device replay screen-x.ad                  # execute the script

The ADR filename/index, #1346, PR summary, and throwaway prototype are aligned. The prototype update is 911dfc217 and also exercises destination-guard refusal under the final command name.

This supersedes my earlier comment's decision to retain session save-replay.

[thymikee]

The direction is coherent, but three acceptance boundaries need to be explicit before this ADR is ready:

1. Require a portable destination guard, not merely a target-bearing wait. Ordinary recording can preserve wait @ref, while unresolved-ref rejection is repair-only and wait is not classified as selector-targeting. Require a selector/selector-chain guard or reject wait @ref before filesystem work, with a regression. Do not attach target-v1 to the wait itself, because replay pre-verification would prevent waiting for a newly appearing landmark.
2. Define the open boundary as exactly one initial recorded open. A later open --relaunch preserves the action history today, so the current 'an open' preflight can publish multiple opens. State whether a later open aborts or refuses publication, and test it.
3. Specify PUBLISHED terminality through every existing arming entry point. Today open --save-script and close --save-script=<path> can re-enable/retarget recording. Cover post-publication open --relaunch --save-script and close --save-script=<other> behavior, and derive 'last mutating action' from a declared command trait rather than a handler-local list.

The command vocabulary, repair isolation, atomic no-clobber semantics, live-session replay behavior, and explicit secret restriction otherwise look sound. CI has no failures; iOS smoke is still pending.

[thymikee]

Captured the non-blocking destination-guard limitation in 78c108c93 and linked #1349.

Current guarantee: the mandatory target-bearing wait proves that its selector matches an element. It does not yet prove that the match has the same target-v1 identity as the landmark observed during authoring, so authors must choose a selective destination-specific landmark.

Code inspection found both missing halves for wait: recording does not pass a RecordedTargetCapture, and replay's target-token extractor does not classify wait. #1349 owns both evidence capture and reuse of ADR 0012's existing fail-closed verification path. The ADR validation language now scopes current identity guarantees to ADR 0012's existing command set.

[thymikee]

Re-reviewed 78c108c: the new #1349 limitation text is useful, but the three acceptance gaps remain. (1) Calling the guard 'selector-level' does not require the recorded input to serialize as a selector/selector-chain; ordinary wait @ref is still recordable and the writer's unresolved-ref refusal excludes wait and is repair-only. Require a portable selector guard, reject @ref before filesystem work, and test it—#1349 is not a substitute. (2) The artifact says one recorded open, while preflight still requires only an open; define and test the rejection/reset rule for later relaunching opens that preserve history. (3) PUBLISHED terminality still does not cover open --save-script / close --save-script=<other> re-arming and retargeting, or derive 'last mutating action' from a declared command trait. The current macOS smoke failure appears unrelated to this docs delta, but it is a confirmed red check.

[thymikee]

Addressed the three acceptance boundaries from the latest review in 450c605da:

1. Portable destination guard: only a wait carrying a selector or selector chain qualifies. Duration waits, wait stable, and wait @ref are rejected before filesystem work. The ADR no longer relies on repair-only bare-ref refusal.
2. Exactly one initial open: ARMED is established only by a fresh session's action-zero open --save-script. A second successful plain open transitions the recording to terminal ABORTED and disarms close-time publication; open --save-script on any existing session is rejected before app dispatch.
3. Terminal publication state: ABORTED and PUBLISHED are sticky until session teardown. Repeated session save-script fails; later open --save-script and close --save-script[=<path>] are rejected before their respective side effects. Plain close remains available and writes nothing in terminal states.

The destination guard's position is now derived from a request-sensitive recording-effect trait on the central command descriptor, with a completeness gate, rather than a publisher-local command list.

I also corrected #1349: a polling wait cannot enter ADR 0012's generic pre-action target-v1 path. Any future wait identity comparison must occur after its selector resolves (or use a distinct guard mechanism) so absence-before-appearance remains valid.

Prototype evidence fe3e42fcd exercises portable-ref refusal, second-open abort, post-publication re-arm refusal, save-bearing close refusal, and plain-close recovery.

[thymikee]

Re-reviewed 450c605d: all three ADR blockers are resolved. The destination guard must serialize a portable selector/selector-chain and explicitly rejects wait @ref; the lifecycle now requires exactly one initial open and makes a later open ABORTED; ABORTED/PUBLISHED are terminal across every save-bearing open/close entry point. Guard ordering is owned by a request-sensitive CommandDescriptor mutation trait with completeness coverage. This is consistent with ADRs 0008/0012 and updated issues #1346/#1349. All checks, including rerun macOS smoke, are green. No remaining findings.

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-07-20 18:00 UTC