fix: stop a single transport drop cascading into a full-run failure (#237); release 0.12.0 (#238)

Two real bugs found by tracing issue #237's exact failure signature
through the executor:

1. The post-reconnect retry switch had silently drifted out of sync
with the main step-dispatch switch -- it was missing RecipeCall,
ConditionalStep, LoopStep, RetryStep, and HTTPCallStep. A connection
error surfacing from any of those could reconnect successfully but
never re-run the step: the switch matched nothing, err stayed the
stale pre-reconnect error, and the loop burned every remaining attempt
re-closing the connection tryReconnect had just re-established. Both
paths now share a single dispatchStep helper and cannot drift again.

2. if X appears treated a dead connection as 'condition not visible'
and silently took the else branch -- misrouting navigation mid-recipe
-- instead of propagating the connection error for reconnect the way
tap ... if visible already did.

Also ruled out empirically (negative results kept in the evidence
folder): neither the agent's ws.pingInterval nor the CLI's
ping/read-deadline machinery kills a busy-but-alive connection, across
four load shapes. The underlying WS drop trigger remains open in #237;
these fixes change its blast radius from 'rest of the run' to 'one
visible reconnect cycle'.

Release 0.12.0: version bump across VERSION, pubspec, agent_version,
vscode, wiki; CHANGELOGs sectioned; MCP write_test tool description
updated with this cycle's new syntax (retry/optional, native UI,
add media, deep links, element-scoped visual regression).

Author: pbertsch

CHANGELOG.md

@@ -6,6 +6,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.12.0] - 2026-08-15
+
 ### Added
 - **`retry N times` block.** Wraps an indented block of steps: on failure, re-runs the whole
   block from the top, up to N total attempts, stopping at the first success. Distinct from
@@ -48,6 +50,21 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   See `docs/evidence/n1-native-ui-android-2026-08-15/`.
 
 ### Fixed
+- **A single Android transport drop no longer cascades into failing every remaining test
+  (issue #237).** Two real bugs in the connection-error recovery path, found by tracing #237's
+  exact failure signature through the executor: (1) the post-reconnect retry switch had silently
+  drifted out of sync with the main step-dispatch switch — it was missing recipe calls,
+  conditionals, loops, retry blocks, and HTTP calls, so a connection error surfacing from any of
+  those could reconnect successfully but never re-run the step, burning the whole retry budget
+  re-closing the connection each attempt had just re-established (both paths now share one
+  dispatch function and cannot drift again); (2) `if X appears` treated a dead connection as
+  "condition not visible" and silently took the else branch — misrouting navigation mid-recipe —
+  instead of propagating the connection error for reconnect the way `tap ... if visible` already
+  did. The underlying WS drop trigger from #237 remains under investigation (needs the reporting
+  project's live Firebase load); these fixes change its blast radius from "rest of the run" to
+  "one visible reconnect cycle". Also ruled out empirically: neither side's ping/keepalive
+  machinery kills a busy-but-alive connection (four load-shape experiments, kept in the evidence
+  folder). See `docs/evidence/i237-ws-drop-investigation-2026-08-15/`.
 - **`probe migrate maestro` hardened against 2.x syntax and two real bugs (G-3).** Audited the
   converter against nect-flutter's real 76-flow suite: `setPermissions`, `retry` (with recursive
   nested-command conversion, also fixed for `repeat`), and `assertScreenshot` are now supported,

VERSION

@@ -1 +1 @@
-0.11.0
+0.12.0

docs/evidence/i237-ws-drop-investigation-2026-08-15/README.md

@@ -0,0 +1,83 @@
+# Issue #237 investigation — Android WS drop cascade: two real bugs found and fixed, drop trigger itself still open
+
+Issue #237 reports a deterministic Android WS connection death at a specific file-to-file
+transition (7 real Firebase sign-in/sign-out cycles → next file's `goto feed`), after which
+**every remaining test fails** — 76/79 failures in one run from a single transport event, with
+auto-reconnect never recovering.
+
+This investigation did not (yet) reproduce the underlying drop itself — that genuinely needs the
+reporting project's Firebase-loaded app running live (see "Still open" below). What it did find,
+by tracing the exact reported failure signature (`probelink: write: ... use of closed network
+connection`, `Connection lost — attempt 1` repeating) through the CLI source, is that **the
+cascade after the drop — the part that turns one transport blip into 76 failures — was caused by
+two real, confirmed CLI bugs**, both now fixed.
+
+## Bug 1 — the post-reconnect retry switch had drifted out of sync with the dispatch switch
+
+`internal/runner/executor.go`'s `runStep` had two hand-maintained copies of the step-dispatch
+switch: the initial attempt (11 step kinds) and the post-reconnect retry (6 step kinds). The
+retry copy was missing `parser.RecipeCall`, `ConditionalStep`, `LoopStep`, `RetryStep`, and
+`HTTPCallStep`.
+
+Consequence, matching #237's report exactly: a connection error surfacing from a recipe call
+(`goto feed` is one) enters the retry loop, `tryReconnect` succeeds — **and then the retry switch
+matches nothing**. `err` silently keeps its stale pre-reconnect value, `isConnectionError(err)`
+stays true, and the loop calls `tryReconnect` again — whose first action is `e.client.Close()`,
+killing the connection it *just* established the attempt before. The entire retry budget burns
+without the step ever being re-run, and the connection is left in whatever state the final
+attempt happened to produce.
+
+**Fix**: both paths now call a single shared `dispatchStep` helper — the two switches are
+structurally the same switch and cannot drift apart again. Locked in by
+`internal/runner/dispatch_step_test.go`'s `TestDispatchStep_*` (each previously-missing step kind
+asserted to produce its observable side effect through the shared dispatcher, not just a nil
+error).
+
+## Bug 2 — conditionals misread a dead connection as "condition not visible"
+
+`runConditional` (the `if X appears` executor) treated **any** `See` failure as "not visible" and
+took the else branch — including connection errors. With a dead connection mid-recipe, every
+`if X appears` block silently misroutes: `goto feed`'s `otherwise: go back / go back` navigates
+*away* from a perfectly healthy screen because the visibility check couldn't be asked, not
+because the answer was no. Nothing ever reached the reconnect machinery from the check itself.
+
+`runAction`'s `if visible` suffix pre-check already handled this exact case correctly
+("propagate connection errors for auto-reconnect") — the ConditionalStep path just never got the
+same treatment.
+
+**Fix**: connection errors from the visibility check now propagate (so runStep's reconnect fires
+and the condition is re-evaluated against a live connection); ordinary not-found still takes the
+else branch. Locked in by `TestRunConditional_ConnectionErrorPropagates` and
+`TestRunConditional_OrdinaryNotFoundStillTakesElse`.
+
+## Ruled out along the way (negative results, kept honestly)
+
+The first hypothesis was the Dart agent's `ws.pingInterval = 5s` (server.dart:249 — added for
+iOS/iproxy idle-drop prevention, applied unconditionally to all connections): if the app's
+isolate is too busy (Firebase auth/listener churn) to service ping/pong for >5s, does the agent
+kill a healthy connection? **Empirically no**, across four load shapes (`ping_repro.dart`,
+`ping_repro2.dart`, both in this folder — runnable with plain `dart run`):
+
+- one continuous synchronous CPU block 4× the ping interval — connection survived;
+- a dense microtask flood (195M chained microtasks over 4× the interval) — survived;
+- repeated 200ms sync bursts with 50ms yields — survived;
+- and separately, the **real Go client** (`probelink.DialWithOptions` + its actual
+  pingLoop/read-deadline code) against a server that refused to service its read loop for 20s
+  (4× the CLI's ping interval, exceeding its 15s pong-refresh deadline) — the client kept the
+  connection open and `Connected()` true for 25+ s. (Temporary in-repo test, deleted after the
+  result was recorded — the code path it exercised is unchanged.)
+
+So neither side's keepalive machinery kills a busy-but-alive connection on a healthy transport.
+This makes an emulator/adb-forward transport-layer event (or something Android-specific not
+reproducible on a macOS host loopback) the stronger suspect for the original drop.
+
+## Still open — the drop trigger itself
+
+What actually kills the socket at that specific file transition remains unconfirmed. It needs a
+live instrumented run against the reporting project's app (real Firebase Auth + Firestore churn —
+the trigger conditions this repo's own test apps can't produce, per PT-25's earlier resolution
+note). With these two fixes, the *impact* of the next occurrence changes shape entirely: the
+first reconnect that succeeds now actually re-runs the failed step (recipe calls included), and
+conditionals no longer misroute on a dead connection — so a drop should now cost one visible
+reconnect cycle, not the rest of the run. That also makes the next live repro far more
+informative: whatever still fails after these fixes is the drop itself, not the cascade.

docs/evidence/i237-ws-drop-investigation-2026-08-15/ping_repro.dart

@@ -0,0 +1,99 @@
+// Minimal, isolated repro for issue #237's leading hypothesis:
+// does a `ws.pingInterval`-configured dart:io WebSocket server close the
+// connection when the isolate's event loop is starved for longer than the
+// ping interval — even though the client and the underlying TCP socket are
+// both perfectly healthy? This mirrors probe_agent/lib/src/server.dart's
+// exact setup (ws.pingInterval = Duration(seconds: N)) at a shortened
+// interval so the test runs in seconds, not minutes.
+//
+// Two scenarios:
+//   A) baseline: server idle, no isolate starvation -> connection should stay up.
+//   B) server isolate busy (CPU-bound work occupying the event loop) for
+//      longer than pingInterval -> does the connection get force-closed?
+
+import 'dart:async';
+import 'dart:io';
+
+const pingInterval = Duration(seconds: 2);
+
+Future<void> main() async {
+  await scenario('A) baseline (idle server, no starvation)', starve: false);
+  await scenario('B) server isolate busy > pingInterval', starve: true);
+}
+
+Future<void> scenario(String label, {required bool starve}) async {
+  print('\n=== $label ===');
+  final server = await HttpServer.bind(InternetAddress.loopbackIPv4, 0);
+  final port = server.port;
+
+  WebSocket? serverSocket;
+  final serverClosedCompleter = Completer<void>();
+  var serverGotDone = false;
+
+  server.listen((req) async {
+    if (!WebSocketTransformer.isUpgradeRequest(req)) return;
+    final ws = await WebSocketTransformer.upgrade(req);
+    serverSocket = ws;
+    ws.pingInterval = pingInterval; // exact same line as ProbeServer._handleConnection
+    ws.listen(
+      (data) {},
+      onDone: () {
+        serverGotDone = true;
+        print('  [server] onDone fired (connection closed) at ${DateTime.now()}');
+        if (!serverClosedCompleter.isCompleted) serverClosedCompleter.complete();
+      },
+      onError: (e) => print('  [server] onError: $e'),
+      cancelOnError: false,
+    );
+  });
+
+  final client = await WebSocket.connect('ws://127.0.0.1:$port/probe');
+  var clientGotDone = false;
+  client.listen(
+    (data) {},
+    onDone: () {
+      clientGotDone = true;
+      print('  [client] onDone fired (connection closed), closeCode=${client.closeCode}, closeReason=${client.closeReason}');
+    },
+    onError: (e) => print('  [client] onError: $e'),
+  );
+
+  await Future<void>.delayed(const Duration(milliseconds: 300)); // let the upgrade settle
+  print('  connection established, pingInterval=$pingInterval');
+
+  if (starve) {
+    final blockFor = pingInterval * 4; // comfortably longer than one interval
+    print('  blocking the SERVER isolate synchronously for ${blockFor.inSeconds}s (simulating heavy sync/microtask work)...');
+    final stopwatch = Stopwatch()..start();
+    // Tight CPU-bound loop -- occupies the isolate, event loop cannot run
+    // timers or process I/O callbacks (including the WS ping timer/pong
+    // handling) until this returns.
+    var x = 0;
+    while (stopwatch.elapsed < blockFor) {
+      x = (x + 1) % 1000000007;
+    }
+    print('  ...unblocked after ${stopwatch.elapsed} (junk=$x)');
+  } else {
+    await Future<void>.delayed(pingInterval * 4);
+  }
+
+  // Give the event loop a moment to process anything queued during/after
+  // the block (e.g. a deferred close).
+  await Future.any([
+    serverClosedCompleter.future,
+    Future<void>.delayed(const Duration(seconds: 3)),
+  ]);
+
+  print('  RESULT: serverGotDone=$serverGotDone clientGotDone=$clientGotDone');
+  if (starve && serverGotDone) {
+    print('  ==> CONFIRMED: isolate starvation past pingInterval closes an otherwise-healthy connection.');
+  } else if (starve && !serverGotDone) {
+    print('  ==> NOT confirmed this way: connection survived the starvation window.');
+  }
+
+  await client.close();
+  if (serverSocket != null && !serverGotDone) {
+    await serverSocket!.close();
+  }
+  await server.close(force: true);
+}

docs/evidence/i237-ws-drop-investigation-2026-08-15/ping_repro2.dart

@@ -0,0 +1,107 @@
+// Variant of ping_repro.dart: instead of one long synchronous CPU-bound
+// block, flood the event loop with a dense chain of microtasks/short async
+// hops (closer in shape to real Firestore-listener-churn async work) for
+// longer than pingInterval, and separately try many repeated short blocks
+// (bursty jank) rather than one continuous block.
+
+import 'dart:async';
+import 'dart:io';
+
+const pingInterval = Duration(seconds: 2);
+
+Future<void> main() async {
+  await scenario('C) dense microtask flood > pingInterval', mode: Mode.microtaskFlood);
+  await scenario('D) repeated short sync bursts (bursty jank)', mode: Mode.burstyJank);
+}
+
+enum Mode { microtaskFlood, burstyJank }
+
+Future<void> scenario(String label, {required Mode mode}) async {
+  print('\n=== $label ===');
+  final server = await HttpServer.bind(InternetAddress.loopbackIPv4, 0);
+  final port = server.port;
+
+  var serverGotDone = false;
+  final serverClosedCompleter = Completer<void>();
+
+  server.listen((req) async {
+    if (!WebSocketTransformer.isUpgradeRequest(req)) return;
+    final ws = await WebSocketTransformer.upgrade(req);
+    ws.pingInterval = pingInterval;
+    ws.listen(
+      (data) {},
+      onDone: () {
+        serverGotDone = true;
+        print('  [server] onDone fired at ${DateTime.now()}');
+        if (!serverClosedCompleter.isCompleted) serverClosedCompleter.complete();
+      },
+      onError: (e) => print('  [server] onError: $e'),
+      cancelOnError: false,
+    );
+  });
+
+  final client = await WebSocket.connect('ws://127.0.0.1:$port/probe');
+  var clientGotDone = false;
+  client.listen((data) {}, onDone: () {
+    clientGotDone = true;
+    print('  [client] onDone fired, closeCode=${client.closeCode}');
+  });
+
+  await Future<void>.delayed(const Duration(milliseconds: 300));
+  print('  connection established, pingInterval=$pingInterval');
+
+  final totalDuration = pingInterval * 4;
+  final stopwatch = Stopwatch()..start();
+
+  if (mode == Mode.microtaskFlood) {
+    print('  flooding microtask queue for ${totalDuration.inSeconds}s...');
+    // Chain millions of scheduleMicrotask calls -- keeps the event loop
+    // "running" but never lets it drain to service timers/IO callbacks
+    // (like the WS ping timer) until the chain finally empties.
+    var count = 0;
+    void pump() {
+      count++;
+      if (stopwatch.elapsed < totalDuration) {
+        scheduleMicrotask(pump);
+      }
+    }
+    final done = Completer<void>();
+    void pumpWithCompletion() {
+      count++;
+      if (stopwatch.elapsed < totalDuration) {
+        scheduleMicrotask(pumpWithCompletion);
+      } else {
+        done.complete();
+      }
+    }
+    scheduleMicrotask(pumpWithCompletion);
+    await done.future;
+    print('  ...done, scheduled $count microtasks');
+  } else {
+    print('  bursty jank: 40x (200ms sync block + 50ms yield) for ${totalDuration.inSeconds}s...');
+    while (stopwatch.elapsed < totalDuration) {
+      final burstStart = Stopwatch()..start();
+      var x = 0;
+      while (burstStart.elapsed < const Duration(milliseconds: 200)) {
+        x = (x + 1) % 1000000007;
+      }
+      await Future<void>.delayed(const Duration(milliseconds: 50));
+    }
+    print('  ...done bursting');
+  }
+
+  await Future.any([
+    serverClosedCompleter.future,
+    Future<void>.delayed(const Duration(seconds: 3)),
+  ]);
+
+  print('  RESULT: serverGotDone=$serverGotDone clientGotDone=$clientGotDone');
+  if (serverGotDone) {
+    print('  ==> CONFIRMED: this load shape closes an otherwise-healthy connection.');
+  } else {
+    print('  ==> NOT confirmed this way.');
+  }
+
+  await client.close();
+  await server.close(force: true);
+}

docs/wiki/Home.md

@@ -18,7 +18,7 @@ Welcome to the FlutterProbe wiki. This documentation covers architecture details
 
 ## Project Status
 
-FlutterProbe is in active development. Current version: **0.11.0**.
+FlutterProbe is in active development. Current version: **0.12.0**.
 
 ### Repository Structure
 

internal/mcp/server.go

@@ -186,6 +186,21 @@ Supports the full ProbeScript syntax:
                      sync "both logged in"
                      B:
                        see "Welcome"
+  Resilience:      retry N times — indented block re-runs from the top on failure,
+                     up to N attempts, stopping at first success (unlike repeat,
+                     which always runs every iteration). Trailing "optional" on
+                     tap/type/long press/double tap/clear/see — attempts the step
+                     but logs-and-continues on failure instead of failing the test.
+  Native UI:       tap native "…" / see native "…" / type native "…" into "…" —
+                     drives native (non-Flutter) UI like pickers and share sheets
+                     via uiautomator, matched by text or resource-id. Android only.
+  Device media:    add media "path/to/photo.jpg" — seeds a file into the camera
+                     roll/gallery (Android + iOS simulator).
+  Deep links:      open link "scheme://…" in the app — routes via OS intent/URL
+                     handling to the app's own registered scheme, instead of the
+                     external browser that plain open link uses.
+  Visual:          compare screenshot "name" — baseline-on-first-run comparison;
+                     add of "Widget"/#id to crop to one widget's bounds.
   Recipes:         recipe "name"(params) — reusable step sequences
   Hooks:           before each / after each / on failure / before all / after all
   Data-driven:     with examples | col1 | col2 |`,