feat(flow): add an idle condition that waits for the screen to stop moving

packages/argent-cli/src/flow.ts

@@ -25,9 +25,13 @@ export interface StepReport {
   status: "pass" | "fail" | "skip" | "error";
   reason?: string;
   /**
-   * Legacy: older tool-servers passed a snapshot that adopted a missing
-   * baseline and annotated it with this caveat (a missing baseline now fails
-   * the step). Rendered for wire compat with a not-yet-updated server.
+   * A step that passed in a way that weakens it as proof — raised today by
+   * `await: { idle: true }`, which never fails a run and says here what its
+   * green actually bought (see StepReport.warning in the tool-server's
+   * flow-run). Also carries the caveat older tool-servers put on a snapshot
+   * that adopted a missing baseline, which now fails the step instead. Live
+   * either way: dropping the field would silently delete the only thing the
+   * readiness check reports.
    */
   warning?: string;
   tool?: string;
@@ -340,14 +344,19 @@ export function renderArtifactLines(report: FlowReport): string[] {
  * Batch mode prints only what needs attention: each fail/error step with its
  * under-lines, numbered by walking the full step list so the numbers match a
  * single-mode rerun of the same flow.
+ *
+ * A PASSING step carrying a warning needs attention too. `await: { idle: true }`
+ * only ever warns on a step that passed, and renderSummary counts every warning
+ * whatever its status — so skipping those here printed "1 warning" with the
+ * text nowhere on screen, which is the whole of what the step reports.
  */
 export function renderFailedSteps(report: FlowReport): string[] {
   const lines: string[] = [];
   let n = 0;
   for (const s of report.steps) {
     if (s.kind === "echo") continue;
     n++;
-    if (s.status !== "fail" && s.status !== "error") continue;
+    if (s.status !== "fail" && s.status !== "error" && !s.warning) continue;
     lines.push(renderStepLine(s, n, report.flow));
     if (s.warning) lines.push(renderUnderStepLine(s, n, `⚠ ${s.warning}`));
     if (s.artifacts && typeof s.artifacts === "object") {

packages/argent-cli/test/flow-render.test.ts

@@ -296,6 +296,21 @@ describe("flow report rendering", () => {
     expect(renderFailedSteps(mkReport([{ index: 0, kind: "tap", status: "pass" }]))).toEqual([]);
   });
 
+  it("renderFailedSteps prints a passing step's warning, which renderSummary counts", () => {
+    // `await: { idle: true }` only ever warns on a step that PASSED, and the
+    // summary counts warnings whatever the status — so a directory run used to
+    // report "1 warning" with the text nowhere on screen.
+    const report = mkReport([
+      { index: 0, kind: "tap", status: "pass" },
+      { index: 1, kind: "idle", status: "pass", warning: "the screen never held still" },
+    ]);
+    expect(renderFailedSteps(report)).toEqual([
+      "  ⚠  2 idle",
+      "       ⚠ the screen never held still",
+    ]);
+    expect(renderSummary(report)).toContain("1 warning");
+  });
+
   it("renderBatchSummary mirrors the step summary's verdict shape", () => {
     expect(renderBatchSummary({ total: 3, passed: 2, failed: 1, skipped: 0 })).toBe(
       "FAIL — 3 flows: 2 passed, 1 failed, 0 skipped"

packages/argent-mcp/src/content.ts

@@ -211,9 +211,13 @@ export type FlowStepResult = {
   status?: "pass" | "fail" | "skip" | "error";
   reason?: string;
   /**
-   * Legacy: older tool-servers passed a snapshot that adopted a missing
-   * baseline and annotated it with this caveat (a missing baseline now fails
-   * the step). Rendered for wire compat with a not-yet-updated server.
+   * A step that passed in a way that weakens it as proof — raised today by
+   * `await: { idle: true }`, which never fails a run and says here what its
+   * green actually bought (see StepReport.warning in the tool-server's
+   * flow-run). Also carries the caveat older tool-servers put on a snapshot
+   * that adopted a missing baseline, which now fails the step instead. Live
+   * either way: dropping the field would silently delete the only thing the
+   * readiness check reports.
    */
   warning?: string;
   tool?: string;

packages/skills/skills/argent-create-flow/SKILL.md

@@ -31,7 +31,7 @@ Beyond raw `tool:` steps and `echo:`, flows support declarative directives inter
 | `scroll-to`  | `- scroll-to: "Order #1234"` (scrolls down) or `- scroll-to: { target: …, direction: right, within: … }`                                                             | momentum-free scroll until the target is visible                                                                                                                                                                              |
 | `pinch`      | `- pinch: { on: "Map", scale: 3 }` or `- pinch: { scale: 0.5 }`                                                                                                      | two-finger zoom in (`scale` > 1) or out (`< 1`); big scales chain gestures; `on` optional — defaults to screen center; open-loop — assert the visible result                                                                  |
 | `rotate`     | `- rotate: { on: "Map", by: 90 }` or `- rotate: { by: -45 }`                                                                                                         | two-finger rotation by degrees (+ CW, − CCW, within ±3000°; options map only); `on` optional — screen center default; not `tool: rotate` (orientation)                                                                        |
-| `await`      | `- await: { visible: Home }`                                                                                                                                         | wait for a UI condition                                                                                                                                                                                                       |
+| `await`      | `- await: { visible: Home }` or `- await: { idle: true }`                                                                                                            | wait for a UI condition, or for the screen to stop moving                                                                                                                                                                     |
 | `wait`       | `- wait: 500`                                                                                                                                                        | pause for a fixed number of milliseconds (last resort — prefer `await`)                                                                                                                                                       |
 | `assert`     | `- assert: { visible: Welcome }`                                                                                                                                     | check a condition, hard-fail if it never holds                                                                                                                                                                                |
 | `snapshot`   | `- snapshot: home` or `- snapshot: { name: home, maxMismatch: 0.5, cropOn: { id: order-summary } }`                                                                  | diff a screenshot — or one element's region — against a stored baseline                                                                                                                                                       |
@@ -85,6 +85,20 @@ This condition-as-key form is the only spelling. `await` also accepts an optiona
 
 For a custom poll interval or bundleId, drop to an explicit `- tool: await-ui-element` step — but the raw tool polls the trimmed `describe` tree, so a testID it reports as not found can still resolve fine as an `await:` directive (see Selectors). Prefer the directive.
 
+**`await: { idle: true }` — the one condition with no selector.** It waits until the screen has content and stops moving in **both** the UI tree and the rendered pixels. Options: `minStableMs` (how long stillness must hold, default 250) and `timeout` (default 7500, and it has to leave room for the hold plus the 600ms a settle costs — three reads spanning two 200ms polls, plus the 200ms of budget the closing round has to have left to be allowed to start — or the parser rejects the step). Reach for it when a transition's motion is invisible to the tree — an iOS push or modal dismissal commits its hierarchy up front and then animates a layer for a few hundred milliseconds, and a cross-fade or scrim moves no node at all — which is exactly when an element `await:` returns while the screen is still sliding, and the next tap lands on a moving target.
+
+It **never fails a run.** Readiness is not an acceptance criterion, so every outcome short of a clean settle passes carrying a `warning` on the step — read it rather than stepping over it:
+
+- **the screen never held still** — it spent the timeout and went ahead. Plenty of healthy screens never stop (a video, a shimmer, a carousel, live-updating text); a screen that never finished loading looks the same from here.
+- **a small part of it was still changing** — a spinner, a caret, a progress dot, moving during the stretch of stillness the step settled on. Too small to be the screen moving, so the settle completed anyway; if it is a loading spinner, the screen was still loading when this step returned.
+- **the tree stayed empty** — the screen rendered no accessible content. Sometimes the app (a canvas, a video surface), sometimes a screen that never arrived.
+- **settled on the UI tree alone** — the screen could not be screenshotted often enough to compare a pair, so presentation-layer motion (a push, a fade, a dismissing modal) was not waited out.
+- **the screen came back with content on too few reads** — a settle takes three of them spanning two polls, and this step got fewer, so it ended without ever being able to tell whether the screen was moving. A slow tree source, or a window that was blank for most of the wait.
+
+Only a tree source that cannot be read stops the run, as an `error` — one that fails outright, one that answers and then wedges, or one that never answers at all within the step (that last one may simply be slow: raise the step's `timeout` before suspecting the app). That is a broken window, not a verdict about the app: the run is not ok and every later step is skipped.
+
+It is **not** a screen check either: a dropped tap leaves the source screen perfectly idle. Put it **after** the element `await:` that names the destination, never instead of one. There is no `assert` form (waiting is the whole point), no `when:` form, and the recorder cannot emit one — every `idle` step is hand-written. Do not sprinkle it after every step: each one costs a settle, and it cannot fail, so a flow full of them is slower without being stricter.
+
 ### `type` and `scroll-to`
 
 `type` presses Enter after typing to commit the value and dismiss the keyboard, so it can't cover later targets. For a chained form whose fields feed one explicit submit — e.g. email then password then a `tap: "Log in"` — set `submit: false` on the intermediate fields so a premature Enter doesn't fire the form early: `type: { into: password, text: "hunter2", submit: false }`.