@ishlabs/cli 0.27.0 → 0.28.0

package/dist/lib/docs.js

@@ -381,12 +381,19 @@ ish iteration create --platform figma --url https://figma.com/proto \\
     --flow-name "Onboarding A"
 
 # Native app (ios / android): --app names the target, stored as app_artifact (no URL).
+# screen_format defaults to mobile_portrait for native (vs desktop for browser).
 ish iteration create --platform ios --app com.example.app
 ish iteration create --platform ios            # --app optional; "chosen at run time"
 # drive it locally against a booted simulator / emulator — the iteration
 # remembers the app, so no --app needed on reruns:
 ish study run --local
 ish study run --local --app ./Build.app        # override with a fresh local build
+# State reset between participants: with a local .app build the runner does a
+# clean uninstall+reinstall before each participant, so state one participant
+# creates (a reminder, a saved record) does NOT leak into the next. A bare
+# bundle-id / system-app target can't be reinstalled — it relaunches and warns
+# that state may persist; pass --app <.app> or run one participant per study for
+# a guaranteed clean start. See guides/native-app.
 
 # Text/email content from a file:
 ish iteration create --content-text @./email.html --title "Newsletter"
@@ -2000,14 +2007,22 @@ Interactive study runs produce per-frame screenshots server-side. They
 let you (or an agent) see what participants actually saw alongside the
 sentiment summary.
 
-## Screenshots — remote interactive studies only
+## Screenshots — the grouped index vs. per-interaction frames
 
-Screenshots are produced by remote interactive runs only — chat / video /
-text studies don't have them. **Local runs** (\`ish study run --local\`,
-including ios/android) don't push screenshots to the server either; they
-write a per-step HTML debug report to \`~/.ish/debug/sim-*.html\` (the path is
-printed at the end of the run). \`ish study screenshots list\` on a local-only
-study therefore returns nothing useful — open the debug report instead.
+\`ish study screenshots list\` reads the **frame-grouped index**
+(\`/screenshots/grouped\`), a remote-interactive-run artifact keyed by frame —
+chat / video / text studies don't populate it, and neither do local runs. On a
+local-only study this endpoint currently 500s rather than returning an empty
+index, so \`screenshots list\` isn't the way to view a local run.
+
+**Local runs DO still capture per-interaction screenshots** (\`ish study run
+--local\`, including ios/android). They live on the participant interaction rows,
+not in the grouped index — read them two ways:
+
+- \`ish study get <id>\` — each interaction carries a \`screenshot_url\` (a public
+  storage URL you can fetch directly).
+- the per-step HTML debug report at \`~/.ish/debug/sim-*.html\` (path printed at
+  the end of each local run).
 
 ### CLI
 
@@ -2180,6 +2195,12 @@ The CLI guarantees these contracts so agents can chain safely:
   \`--fields\` set, you can identify the affected resource. Default
   write-path JSON is compact (\`{id, alias, name, updated_at,
   ...changed_fields}\`); pass \`--verbose\` for the full server payload.
+- **Active-context setters emit a capturable object on stdout.** The
+  \`use\` commands (\`study use\`, \`workspace use\`, \`ask use\`) write their
+  human "Active … set to …" confirmation to **stderr** and, under
+  \`--json\`, an \`{id, alias, name, active}\` object to **stdout** — so
+  \`ish study use s-b2c --json --get alias\` is capturable. (\`--clear\`
+  is a stderr-only confirmation.)
 - **Write-path echoes keep collection arrays even when empty.** On a
   create/update echo (e.g. \`study create\`/\`study update\`), entity
   collections like \`assignments\`, \`interview_questions\`, and
@@ -2528,6 +2549,15 @@ from envelopes that don't originate from an HTTP response (Commander
 parse errors, local validation failures, alias-resolution errors). Do
 not branch on \`status: 0\` — that value is never emitted as of 0.20.
 
+A **\`report\`** field appears on *genuine faults* — uncategorized
+client errors, \`server\`/5xx, network failures, and unknown throws —
+carrying the suggested \`ish feedback "…"\` invocation to report the
+bug. It is deliberately **absent** on user-actionable failures (usage /
+validation exit 2, auth exit 3, not-found exit 4, \`usage_limit_reached\`)
+so agents don't report their own input mistakes. In human mode the same
+nudge prints as a \`→ Looks like a bug? Report it: …\` line on stderr.
+See \`guides/feedback\`.
+
 ## Conventions
 
 - Successful commands exit 0 and print one JSON object/array on stdout.
@@ -3203,22 +3233,26 @@ request time, for any client, is the backend's \`TIER_LIMITS\` dict in
 
 ## Limits enforced
 
-| Limit                       | Free | Media | Starter | Pro | Enterprise |
-|-----------------------------|------|-------|---------|-----|------------|
-| \`maxProducts\`               | 1    | 1     | ∞       | ∞   | ∞          |
-| \`maxStudiesPerProduct\`      | 3    | ∞     | ∞       | ∞   | ∞          |
-| \`maxIterationsPerStudy\`     | 2    | ∞     | ∞       | ∞   | ∞          |
-| \`maxCustomPersons\`          | 3    | 10    | 10      | ∞   | ∞          |
-| \`maxConcurrentParticipants\` | 3    | 3     | 10      | 50  | ∞          |
-| \`maxWorkspaceMembers\`       | 1    | 1     | 1       | 10  | ∞          |
+| Limit                       | Free | Starter | Pro | Enterprise |
+|-----------------------------|------|---------|-----|------------|
+| \`maxProducts\`               | 1    | 3       | ∞   | ∞          |
+| \`maxStudiesPerProduct\`      | 3    | 15      | ∞   | ∞          |
+| \`maxAsksPerProduct\`         | 3    | 15      | ∞   | ∞          |
+| \`maxIterationsPerStudy\`     | 2    | 5       | ∞   | ∞          |
+| \`maxCustomPersons\`          | 3    | 10      | ∞   | ∞          |
+| \`maxConcurrentParticipants\` | 3    | 10      | 50  | ∞          |
+| \`maxSeats\`                  | 1    | 1       | 10  | ∞          |
 
 Commands that may hit a limit: \`ish workspace create\`,
-\`ish study create\`, \`ish study generate\`, \`ish iteration create\`,
+\`ish study create\`, \`ish study generate\`, \`ish ask create\`
+(and \`ish ask run --new\`), \`ish iteration create\`,
 \`ish person create\`, \`ish person generate\`.
 
-\`maxConcurrentParticipants\` gates how many participants can be in-flight
-at once per dispatch. \`maxWorkspaceMembers\` gates workspace membership
-(seats). Both are enforced server-side.
+\`maxConcurrentParticipants\` caps how many participants a single run can
+include — cumulative per iteration for studies, per ask for asks — and is
+enforced when participants are created/added, not at dispatch. \`maxSeats\`
+gates workspace membership (active members + pending invitations). Both are
+enforced server-side.
 
 ## What you see when a limit is hit
 
@@ -3270,6 +3304,7 @@ upgrade or delete an existing resource to free up headroom.
   that page is about *how many credits each run draws*).
 - \`concepts/workspace\` — \`maxProducts\` is per-account.
 - \`concepts/study\`     — \`maxStudiesPerProduct\` gates study creation.
+- \`concepts/ask\`       — \`maxAsksPerProduct\` gates ask creation.
 - \`concepts/iteration\` — \`maxIterationsPerStudy\` gates iteration creation.
 - \`concepts/person\`   — \`maxCustomPersons\` gates person creation.
 - \`reference/json-mode\` — full error envelope shape and exit codes.
@@ -4340,6 +4375,178 @@ The viewer is only as good as the run behind it. Before sharing, make sure:
 - \`concepts/active-context\` — \`ish study share\` defaults to the active study.
 - \`reference/json-mode\` — the \`{ token, share_url, … }\` envelope.
 `;
+const GUIDE_NATIVE_APP = `# guide: native app studies (ios / android)
+
+Run an interactive study against a **native iOS or Android app** on a local
+simulator/emulator, driven step-by-step by AI participants — the native
+counterpart of a browser (URL) interactive study.
+
+## 1. Check the local toolchain
+
+\`\`\`
+ish check ios        # Xcode/xcrun, a booted simulator, the WDA runner, auth
+ish check android    # adb, a running emulator
+ish setup            # fetch/install whatever's missing (WDA runner, etc.)
+\`\`\`
+
+\`check\` must be green before a run — it verifies the whole chain (simulator
+booted → automation runner installed → logged in), so you don't discover a
+missing piece mid-run.
+
+## 2. Create the study, then a native iteration
+
+The study (assignments + questionnaire) is platform-agnostic. The **iteration**
+names the platform and the app:
+
+\`\`\`
+ish study create --name "Onboarding" --modality interactive \\
+    --assignment "Explore:Open the app and look around" \\
+    --question "How clear was it?"
+
+# --app is a bundle id (already-installed / system app) OR a local .app/.apk path.
+ish iteration create --platform ios --app com.acme.app          # installed bundle id
+ish iteration create --platform ios --app ./Build/MyApp.app     # local build (installed for you)
+ish iteration create --platform android --app ./app-debug.apk
+\`\`\`
+
+The target is stored as \`app_artifact\`; no \`--url\` is needed. \`screen_format\`
+defaults to **mobile_portrait** for native (vs desktop for browser).
+
+## 3. Run locally
+
+\`\`\`
+ish study run --local --platform ios --person p-913 --wait
+ish study run --local --platform ios --all --wait        # whole matching cohort
+\`\`\`
+
+The platform defaults to the iteration's; \`--app\` on \`study run\` overrides the
+stored target with a fresh local build. The WebDriverAgent runner cold-starts
+slowly the first time (~30-60s) and is then reused across participants.
+
+## 3b. Parallel runs — \`--parallel N\` (iOS + Android)
+
+\`\`\`
+ish study run --local --platform ios     --all --parallel 5 --wait
+ish study run --local --platform android --all --parallel 5 --wait
+\`\`\`
+
+Native runs can drive a **pool of N devices** at once, one participant per
+device:
+- **iOS** reuses any booted simulators and **auto-creates + boots** the
+  shortfall, then deletes the simulators it created (reused ones are left alone).
+- **Android** reuses online emulators and **auto-launches headless emulators**
+  (tuned low-RAM), then stops the ones it started. You only need **one AVD**: the
+  pool **clones it** (a fast file-copy — no avdmanager/JDK needed) to as many as
+  it needs, and deletes the clones afterward. Make one AVD in Android Studio ›
+  Device Manager.
+
+N is **auto-sized to the host's RAM** —
+default 1, capped at 5. A small machine runs fewer concurrently and queues the
+rest rather than erroring, so the same command works everywhere, scaled to the
+machine. Each participant still gets a clean device per the reset rules below.
+
+## 4. State reset between participants (important)
+
+Participants share one simulator, run **sequentially** for native. A
+terminate+relaunch alone does NOT clear app data, so:
+
+- **Local \`.app\`/\`.apk\` build** → the runner does a clean **uninstall+reinstall**
+  before each participant. State one participant creates (a saved record, a new
+  reminder) does NOT leak into the next.
+- **Bare bundle-id / system app** (e.g. \`com.apple.reminders\`) → can't be
+  reinstalled, so it relaunches and **warns once** that earlier-participant state
+  may persist. For a guaranteed clean start, pass \`--app <.app>\` or run one
+  participant per study.
+
+## 5. Locale / keyboard
+
+The simulator uses the host machine's keyboard locale. A non-English keyboard
+can derail text entry — pin a locale on the iteration (\`--locale en-US\`) for
+reproducible runs.
+
+## 6. Results, screenshots, transcripts
+
+- \`ish study results <id>\` — sentiment + interview answers, same as any study.
+- **Per-interaction screenshots** are captured even for local runs — read them
+  via \`ish study get <id>\` (each interaction carries a \`screenshot_url\`) or the
+  per-step HTML debug report at \`~/.ish/debug/sim-*.html\` (path printed at the
+  end of the run). Note \`ish study screenshots list\` reads the *remote-run*
+  frame index and won't show local frames — see reference/screenshots.
+
+## Related
+
+- \`concepts/iteration\` — \`app_artifact\`, screen_format, platforms.
+- \`reference/screenshots\` — grouped index vs per-interaction frames.
+- \`guides/first-study\` — the browser-URL version of this flow.
+`;
+const GUIDE_FEEDBACK = `# guide: report a bug or send feedback
+
+\`ish feedback\` files a bug report, feature request, or general note
+straight from the terminal — to the same place the web app's "Send
+feedback" dialog goes. As the agent operating the CLI, you usually see
+a failure first; this is how you hand it to the team without leaving
+the shell.
+
+\`\`\`bash
+ish feedback "the save button on the profile page does nothing"
+ish feedback --type feature "let me export interactions as CSV"
+ish feedback --type other "the guided setup was great"
+\`\`\`
+
+## The message
+
+Pass the body as the positional argument, or read it from elsewhere —
+the same idioms as other text fields:
+
+- \`ish feedback @bug-report.md\` — read the body from a file.
+- \`… 2>err.txt; ish feedback @err.txt\` — attach a failing command's output.
+- \`some-cmd 2>&1 | ish feedback -\` — read the body from stdin.
+
+The body must be at least 10 characters. \`--title\` is optional; by
+default the first line of the message becomes the title.
+
+## Type
+
+\`--type\` is one of \`bug\` (default), \`feature\`, or \`other\` — the same
+three the web dialog offers.
+
+## Diagnostics (help whoever debugs it)
+
+To give the debugger as much grounded signal as possible, the report
+auto-attaches an environment + account block: ish CLI version, OS,
+node, the logged-in account, and your active workspace/study/ask. Opt
+out with \`--no-diagnostics\`.
+
+\`--health\` adds more for simulation/setup bugs: it runs the \`ish check\`
+setup checklist (Xcode, simulators, adb, Chromium, account) and
+attaches the tail of \`~/.ish/local-sim.log\` when present. Use it
+whenever the bug involves \`study run --local\` or native device setup.
+
+\`--dry-run\` prints exactly what would be sent (message + diagnostics)
+without submitting — preview it first if you're unsure.
+
+## When the CLI nudges you to report
+
+On a *genuine fault* (uncategorized client error, 5xx/\`server\`, network
+failure, unknown throw) the CLI appends a hint: a \`report\` field in the
+\`--json\` error envelope, and a \`→ Looks like a bug? Report it: …\` line
+on stderr in human mode. It is intentionally **silent** on
+user-actionable failures (usage, validation, auth, not-found,
+usage-limit) so the nudge stays high-signal. When you see it, that
+error is worth an \`ish feedback\` — paste what you were doing and add
+\`--health\` if it was a local/native run.
+
+## Where it lands
+
+Sends as the logged-in user (run \`ish login\` first) through the ish
+backend, so reports show up alongside web feedback in the team's review
+surface. Output is the created row \`{id, type, title, status}\`.
+
+## Related
+
+- \`reference/json-mode\` — the \`report\` field + error envelope.
+- \`guides/native-app\` — when to reach for \`--health\`.
+`;
 const PAGES = [
     {
         slug: "overview",
@@ -4503,12 +4710,24 @@ const PAGES = [
         description: "Iterative probe loop for one specific persona: person suggest-scenarios returns LLM probes; answer them locally; person evidence add persists answers; person evidence list reads them back.",
         body: GUIDE_BUILD_SPECIFIC_PERSON,
     },
+    {
+        slug: "guides/native-app",
+        title: "guide: native app studies (ios / android)",
+        description: "Run an interactive study against a native iOS or Android app on a local simulator/emulator: check ios/android, create a --platform ios/android iteration with --app (bundle id or .app/.apk), run --local, per-participant state reset, locale/keyboard, and where local screenshots live.",
+        body: GUIDE_NATIVE_APP,
+    },
     {
         slug: "guides/mcp-add",
         title: "guide: wire ish into your AI clients (`ish mcp add`)",
         description: "One command wires the hosted ish MCP server into Cursor, VS Code, Claude Code, Claude Desktop, and Windsurf. Idempotent, atomic, preserves unrelated keys, no tokens written.",
         body: GUIDE_MCP_ADD,
     },
+    {
+        slug: "guides/feedback",
+        title: "guide: report a bug or send feedback (`ish feedback`)",
+        description: "File a bug/feature/other report from the terminal: message via arg/@file/stdin, --type, auto-attached environment+account diagnostics (--no-diagnostics to opt out), --health for setup checks + local-sim logs, --dry-run preview. Also: the `report` hint the CLI appends to genuine-fault errors.",
+        body: GUIDE_FEEDBACK,
+    },
 ];
 const PAGES_BY_SLUG = new Map(PAGES.map((p) => [p.slug, p]));
 export function listPages() {

package/dist/lib/local-sim/actions.d.ts

@@ -10,15 +10,31 @@
  * lives there, not here.
  */
 import type { Page } from "playwright-core";
-import type { LocalStepAction, ActionResult, ContextValue, TreeData } from "./types.js";
+import type { LocalStepAction, ActionResult, ContextValue, WireContextValue, TreeData } from "./types.js";
 import type { TabManager } from "./tabs.js";
 /**
  * Execute a single action on the page.
  */
 export declare function executeAction(page: Page, action: LocalStepAction, treeData: TreeData, contextValues: ContextValue[], tabs?: TabManager): Promise<ActionResult>;
+/**
+ * Normalize the backend's wire context-value shape ({@link WireContextValue}:
+ * `{key, requires_resolution, …}`) into the internal {@link ContextValue}
+ * ({name, type, …}) the executors and {@link resolveTextValue} consume.
+ *
+ * This mapping is the fix for a long-standing silent break: the backend has
+ * always sent `key`/`requires_resolution`, the CLI has always read `name`/`type`,
+ * and nothing mapped between them — so var/secret lookups never matched and the
+ * agent typed the literal key (e.g. `LOGIN_USERNAME`) into login fields on web,
+ * iOS and Android alike. `requires_resolution` is true for secrets (resolved at
+ * runtime) and false for preloaded variables.
+ */
+export declare function normalizeContextValues(wire: WireContextValue[]): ContextValue[];
 /**
  * Resolve the actual text to type from an action, handling var/secret value types.
- * Exported so the native (Android) executor can resolve values the same way.
+ * Exported so the native (Android/iOS) executors can resolve values the same way.
+ *
+ * `contextValues` must already be normalized via {@link normalizeContextValues}
+ * — the lookup matches on `name`, which is the backend's `key` post-mapping.
  */
 export declare function resolveTextValue(action: LocalStepAction, contextValues: ContextValue[]): string;
 /**

package/dist/lib/local-sim/actions.js

@@ -376,9 +376,32 @@ async function executeKeyboardShortcut(page, action) {
     await page.keyboard.press(combo);
 }
 // --- Helpers ---
+/**
+ * Normalize the backend's wire context-value shape ({@link WireContextValue}:
+ * `{key, requires_resolution, …}`) into the internal {@link ContextValue}
+ * ({name, type, …}) the executors and {@link resolveTextValue} consume.
+ *
+ * This mapping is the fix for a long-standing silent break: the backend has
+ * always sent `key`/`requires_resolution`, the CLI has always read `name`/`type`,
+ * and nothing mapped between them — so var/secret lookups never matched and the
+ * agent typed the literal key (e.g. `LOGIN_USERNAME`) into login fields on web,
+ * iOS and Android alike. `requires_resolution` is true for secrets (resolved at
+ * runtime) and false for preloaded variables.
+ */
+export function normalizeContextValues(wire) {
+    return wire.map(cv => ({
+        name: cv.key,
+        type: cv.requires_resolution ? "secret" : "var",
+        value: cv.value,
+        ...(cv.description != null && { description: cv.description }),
+    }));
+}
 /**
  * Resolve the actual text to type from an action, handling var/secret value types.
- * Exported so the native (Android) executor can resolve values the same way.
+ * Exported so the native (Android/iOS) executors can resolve values the same way.
+ *
+ * `contextValues` must already be normalized via {@link normalizeContextValues}
+ * — the lookup matches on `name`, which is the backend's `key` post-mapping.
  */
 export function resolveTextValue(action, contextValues) {
     if (action.value_type === "var" || action.value_type === "secret") {

package/dist/lib/local-sim/adb.d.ts

@@ -10,12 +10,16 @@
  * backend's 0-1000 coordinates against the screencap pixel size and taps
  * directly. (Verified by the Layer-1 driver smoke; see scripts/mobile-e2e.)
  */
+/** Run `fn` with all its adb calls pinned to `serial` (parallel pool path). */
+export declare function withAdbSerial<T>(serial: string | undefined, fn: () => Promise<T>): Promise<T>;
+/** `["-s", serial]` or `[]` — the device-targeting prefix. Pure (tested). */
+export declare function serialArgs(serial: string | undefined): string[];
 /** Resolve adb, downloading Google's platform-tools on first use if not found. */
 export declare function ensureAdb(): Promise<string>;
 export declare class AdbError extends Error {
     constructor(message: string);
 }
-/** Run `adb <args>` and return trimmed stdout. Throws AdbError on failure. */
+/** Run `adb [-s serial] <args>` and return trimmed stdout. Throws AdbError on failure. */
 export declare function adb(args: string[], timeoutMs?: number): Promise<string>;
 /** Run `adb shell <args>` and return trimmed stdout. */
 export declare function adbShell(args: string[], timeoutMs?: number): Promise<string>;
@@ -62,7 +66,20 @@ export declare function currentActivity(): Promise<string>;
  * output. Returns the PNG buffer at full device resolution.
  */
 export declare function screencapPng(): Promise<Buffer>;
-/** Assert exactly one device/emulator is in the `device` state. */
+/**
+ * Parse `adb devices` output into {serial, state} rows. Pure (tested). Skips the
+ * "List of devices attached" header and blank lines.
+ */
+export declare function parseAdbDevices(out: string): Array<{
+    serial: string;
+    state: string;
+}>;
+/** List online (state==="device") serials. */
+export declare function listOnlineSerials(): Promise<string[]>;
+/**
+ * Assert the target device is online. With a serial in effect (pool path or
+ * ANDROID_SERIAL), confirm THAT serial is online. Otherwise require exactly one.
+ */
 export declare function requireOneDevice(): Promise<void>;
 export declare function inputTap(x: number, y: number): Promise<void>;
 export declare function inputSwipe(x1: number, y1: number, x2: number, y2: number, durationMs?: number): Promise<void>;

package/dist/lib/local-sim/adb.js

@@ -14,8 +14,32 @@ import { execFile, execFileSync } from "node:child_process";
 import { existsSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
 import { join } from "node:path";
 import { promisify } from "node:util";
+import { AsyncLocalStorage } from "node:async_hooks";
 import { binDir, adbBin } from "../paths.js";
 const execFileAsync = promisify(execFile);
+/**
+ * The adb serial to target for the current async call chain. A parallel run
+ * drives N emulators in ONE process; every adb call must hit the right device,
+ * but the CLI targets devices via the `adb -s <serial>` prefix, not a per-call
+ * argument threaded through ~25 functions. AsyncLocalStorage carries the serial
+ * implicitly through the call stack so `adb()` / `screencapPng()` pick it up,
+ * and two concurrent `withAdbSerial(A, …)` / `withAdbSerial(B, …)` chains stay
+ * isolated. Single-device runs leave the store empty and fall back to
+ * ANDROID_SERIAL / the one online device (unchanged behavior).
+ */
+const serialStore = new AsyncLocalStorage();
+/** Run `fn` with all its adb calls pinned to `serial` (parallel pool path). */
+export function withAdbSerial(serial, fn) {
+    return serialStore.run(serial?.trim() || undefined, fn);
+}
+/** The serial in effect for this call chain: store → ANDROID_SERIAL → none. */
+function activeSerial() {
+    return serialStore.getStore() ?? (process.env.ANDROID_SERIAL?.trim() || undefined);
+}
+/** `["-s", serial]` or `[]` — the device-targeting prefix. Pure (tested). */
+export function serialArgs(serial) {
+    return serial ? ["-s", serial] : [];
+}
 // Resolve adb without depending on the caller's PATH: ISH_ADB/ADB override → the
 // Android SDK → Homebrew → our own download cache → PATH. If none is found,
 // ensureAdb() fetches Google's standalone platform-tools (a small zip) into
@@ -105,11 +129,12 @@ export class AdbError extends Error {
         this.name = "AdbError";
     }
 }
-/** Run `adb <args>` and return trimmed stdout. Throws AdbError on failure. */
+/** Run `adb [-s serial] <args>` and return trimmed stdout. Throws AdbError on failure. */
 export async function adb(args, timeoutMs = DEFAULT_TIMEOUT_MS) {
     const bin = await ensureAdb();
+    const full = [...serialArgs(activeSerial()), ...args];
     try {
-        const { stdout } = await execFileAsync(bin, args, {
+        const { stdout } = await execFileAsync(bin, full, {
             timeout: timeoutMs,
             maxBuffer: 4 * 1024 * 1024,
         });
@@ -117,7 +142,7 @@ export async function adb(args, timeoutMs = DEFAULT_TIMEOUT_MS) {
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
-        throw new AdbError(`adb ${args.join(" ")} failed: ${msg}`);
+        throw new AdbError(`adb ${full.join(" ")} failed: ${msg}`);
     }
 }
 /** Run `adb shell <args>` and return trimmed stdout. */
@@ -191,8 +216,9 @@ export async function currentActivity() {
  */
 export async function screencapPng() {
     const bin = await ensureAdb();
+    const full = [...serialArgs(activeSerial()), "exec-out", "screencap", "-p"];
     try {
-        const { stdout } = await execFileAsync(bin, ["exec-out", "screencap", "-p"], {
+        const { stdout } = await execFileAsync(bin, full, {
             timeout: SCREENCAP_TIMEOUT_MS,
             maxBuffer: SCREENCAP_MAX_BUFFER,
             encoding: "buffer",
@@ -204,40 +230,62 @@ export async function screencapPng() {
         throw new AdbError(`adb exec-out screencap failed: ${msg}`);
     }
 }
-/** Assert exactly one device/emulator is in the `device` state. */
+/**
+ * Parse `adb devices` output into {serial, state} rows. Pure (tested). Skips the
+ * "List of devices attached" header and blank lines.
+ */
+export function parseAdbDevices(out) {
+    return out
+        .split("\n")
+        .slice(1)
+        .map((l) => l.trim())
+        .filter(Boolean)
+        .map((l) => {
+        const [serial, state] = l.split("\t");
+        return { serial: serial ?? "", state: state ?? "" };
+    })
+        .filter((d) => d.serial);
+}
+/** `adb devices` WITHOUT a serial prefix (the list is global, not per-device). */
+async function devicesRaw() {
+    const bin = await ensureAdb();
+    const { stdout } = await execFileAsync(bin, ["devices"], {
+        timeout: DEFAULT_TIMEOUT_MS,
+        maxBuffer: 1024 * 1024,
+    });
+    return stdout.trim();
+}
+/** List online (state==="device") serials. */
+export async function listOnlineSerials() {
+    return parseAdbDevices(await devicesRaw())
+        .filter((d) => d.state === "device")
+        .map((d) => d.serial);
+}
+/**
+ * Assert the target device is online. With a serial in effect (pool path or
+ * ANDROID_SERIAL), confirm THAT serial is online. Otherwise require exactly one.
+ */
 export async function requireOneDevice() {
-    let out;
+    let online;
     try {
-        out = await adb(["devices"]);
+        online = await listOnlineSerials();
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
         throw new AdbError(`Could not run adb (looked for "${findAdb() ?? "adb"}"). Run \`ish check android\` to check your setup. ${msg}`);
     }
-    // Output: "List of devices attached\n<serial>\tdevice\n..."
-    const online = out
-        .split("\n")
-        .slice(1)
-        .map((l) => l.trim())
-        .filter((l) => l && l.endsWith("\tdevice"));
     if (online.length === 0) {
         throw new AdbError("No Android device/emulator online. Run `ish check android` to check your setup and how to boot one.");
     }
-    // Honor ANDROID_SERIAL (the standard adb convention): when it names an online
-    // device, pin to it instead of failing on "more than one device". The adb
-    // wrapper inherits process.env, so every subsequent `adb` call already targets
-    // that serial — this lets multiple emulators run in parallel, each driven by a
-    // CLI invocation with its own ANDROID_SERIAL.
-    const pinned = process.env.ANDROID_SERIAL?.trim();
+    const pinned = activeSerial();
     if (pinned) {
-        if (online.some((l) => l.startsWith(`${pinned}\t`)))
+        if (online.includes(pinned))
             return;
-        throw new AdbError(`ANDROID_SERIAL=${pinned} is set but that device is not online. ` +
-            `Online: ${online.map((l) => l.split("\t")[0]).join(", ") || "none"}.`);
+        throw new AdbError(`Android device ${pinned} is not online. Online: ${online.join(", ") || "none"}.`);
     }
     if (online.length > 1) {
         throw new AdbError(`Expected exactly one Android device, found ${online.length}. ` +
-            `Stop the extras, or set ANDROID_SERIAL=<serial> to pin one (parallel runs).`);
+            `Stop the extras, or run with --parallel to pool them.`);
     }
 }
 // --- Input gestures (all in screencap pixel space) ---

package/dist/lib/local-sim/android.js

@@ -403,10 +403,15 @@ export class AndroidDevice {
             await settle(250);
         }
         const text = resolveTextValue(action, this.contextValues);
-        if (action.mode === "click_type") {
+        // Clear before typing by default — ADBKeyboard's type broadcast APPENDS, so
+        // a retried or app-pre-filled field would otherwise accumulate text. This is
+        // the replace-on-type semantic the browser (select-all+type) and iOS paths
+        // also use; previously only click_type cleared. Skip the clear+type entirely
+        // when there's nothing to type so an empty no-op can't wipe the field.
+        if (text) {
             await adbKeyboardClear();
+            await adbKeyboardType(text);
         }
-        await adbKeyboardType(text);
         if (action.submit) {
             await settle(150);
             await pressKeyEvent("KEYCODE_ENTER");