compare:flows --before DIR --after DIR [--output FILE] pairs the checkpoints of two runs by
flow and checkpoint name and diffs each pair with the review's screenshot diff, setting aside
the status bar and home indicator as a review does. Each checkpoint is unchanged, changed
(with the regions that differ), missing (no picture on one side, with why), different-size
(another device or orientation, so not diffed), added or removed.
The runs' conditions that differ (app, platform, device, OS version, locale, orientation,
appearance) are listed rather than refused, so an iPhone run and an Android run still line
up. On a foldable the status bar is not set aside, because a run does not record which panel
was in use; the result says so.
The pairing is a pure function in contracts/flow-comparison.ts; the diff is in
review/flow-comparison.ts. cli now imports review, which ARCHITECTURE lists.
runSessionExploration now chooses its strategy before it knows the platform, so the #74 change
is ported onto strategyInputs: a flows run without --platform reads its secrets once the
session reports its platform.
From a second review of #74:
- A checkpoint was marked attempted before the explorer answered, so a screen, turn or time
budget that stopped the run during the call dropped it from exploration.flows. It is now
marked once the call returns, and recorded as "The run stopped before it." otherwise.
- A described step's 40-call limit relied on the session's maxTurns, which a Codex session
does not have: one step could spend the whole run's budgets. runGoal now counts the calls
and fails the step at the limit.
- A checkpoint on a screen that withholds its picture (a secret on it, a blocked screenshot)
is recorded without one and its flow goes on, as the code did; the README said it ended the
flow. The docs now say so, and the run's summary lists such checkpoints.
- A flow with no checkpoint on the platform being run is skipped, and its steps need no model
or secrets.
- explore:session --flows without --platform required every platform's secrets. It now checks
them once the session reports its platform, still before any device work.
- A test runs a described step through runBoundedSession, which rejects with AGENT_CANCELLED
when step_done ends the step, as the real sessions do.
From a review of #74 and an adversarial review of its fixes:
- A checkpoint reused the picture taken on arriving at a screen even after a relaunch, or after
the model looked again. The arrival picture now lasts only until the next look at the app.
- Flows and checkpoints went missing from exploration.flows: a flow whose relaunch failed, a
checkpoint whose observation threw (its flow still said completed), and on a budget stop,
everything not reached. start_flow now creates the record before relaunching; a checkpoint
that throws is recorded as missing and fails its flow; and when the run ends, the explorer
asks the strategy which checkpoints it never attempted and records them as missing. A run
blocked at launch records every flow as failed.
- explore:session's first flow started wherever the app was. The first open relaunches when
the run follows flows, before the check that the app stays open.
- A flow's journey stopped at the first screen change that was not a transition. The walk now
goes on as another journey of the flow (journeyIds).
- A launch-URL error, at the start or during a relaunch, was a plain error that ended the run
without its secrets removed. Both are wrapped through failureText. After two relaunches fail
in a row, the flows stop.
- A described step or a secret limited to another platform no longer needs a model or a value.
- assertFlowsFit counts the tool calls the flows take, as assertReplayFits does.
binary/strategy.ts holds what explore:binary and explore:session each branched on: chooseStrategy
checks the options before any device starts (a model, a replay plan or a flows file),
strategyInputs reads the {{secret:NAME}} inputs they need, and startStrategy returns the session
that drives the explorer's tools, with how the report names it. A new strategy is one more case
there. assertAppUrl moves to binary/app-url.ts so strategy.ts does not import run.ts.
explore:binary and explore:session take --flows FILE: named flows, each a list of exact actions
(the --replay format), steps described in words ({"do": …}) and named checkpoints. Each flow after
the first starts from a relaunched app. A model carries out each described step on its own, with
only observe and act, so the explorer still records and blocks what it always does.
The explorer offers start_flow, checkpoint and end_flow to a flows run. A checkpoint is always
recorded, reusing the picture taken on arrival when nothing has happened since. A flow becomes a
journey of the map, named after the flow, and the exploration report lists each flow with its
status and its checkpoints in order (exploration.flows, optional). A failed step ends its flow
and names the checkpoints it did not reach; the next flow still runs.
Capture iPhone Duo on EAS Simulator with eas simulator:control, for both controllers
- eas-cli 25.2.0: app.approveUrlScheme after install, appearance.set for Argent on
iOS EAS sessions, and springboard.restart as the last fold recovery step. The
controller's own tools come first; these only fill what neither controller has.
- iPhone Duo on EAS: both controllers' folds are verified (Argent by its tree,
agent-device by its screenshot) and recovered by restarting SpringBoard and
folding again, once; never by stopping the session's tool-server.
- agent-device opens the app before folding on EAS, as it does locally.
- agent-device pinned to 0.21.29-nightly.20261018.74 for callstack/agent-device#3776,
which stops @expo/ui sliders on a regular-width display from wedging its runner.
- A session EAS fails to start is replaced, up to five times within 30 minutes,
with a growing wait, only when the failure is provably EAS's.
- doctor warns about Argent's single appearance only for Android EAS sessions.
The example report reuses one token and the same fixture reports, so an alias
still pointing at the previous deployment serves the token page and the same
report bytes; only its reports.json (an older Viewer's listing) differed, and
that mismatch failed the job as PREVIEW_VERIFY_FAILED. The alias now counts as
moved only once it serves this deployment's listing and reports, and an alias
that never does is PREVIEW_ALIAS_BEHIND: the verified deployment is linked
with a warning. The deployment's own origin is still checked strictly.
The README's "Run it yourself" now opens with the two ways to use Explore and
which one needs an Expo account.
explore:binary --simulator local explores a build on a simulator or emulator
it creates on this Mac, with no EAS login: the same devices capture uses,
recorded for the startup sweep, driven by agent-device with its own daemon or
by a local Argent tool-server. The report opens in the local Viewer; --upload
hosts it.
The README now covers local repack and local simulators, a single-path quick
start that reviews a change or explores a build, targets, and requirements
split by what each path needs. The explore-binary, explore-setup and
readme-refresh skills follow.
Capture on this machine (local iOS simulators and Android emulators, with agent-device or Argent) as well as on EAS Simulator; name several capture targets per config (a phone, a foldable closed and open, Android) and review them in parallel with shared builds; repack locally with a local simulator; and make captures faster and harder to break: controller fault containment, an Argent fold recovery, upright captures of an opened iPhone Duo, a settle after each root reset, a route retry after an adb drop, emulator port reservation, a startup sweep of what interrupted captures leave running, and agent-device 0.21.28.
Brent Vatne