@ishlabs/cli 0.24.1 → 0.26.0

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

@@ -44,6 +44,15 @@ export interface ContextValue {
     value: string | null;
     description?: string;
 }
+/**
+ * Per-turn assignment status the agent can emit. Mirrors the backend's
+ * AssignmentStatus enum (app/db/schemas/enums/study.py) restricted to the
+ * LLM-emittable values (_LLM_EMITTABLE_STATUSES in
+ * app/interactive/instructions/output.py). The harness-only values
+ * (pending / max_steps_reached / failed) are NOT emittable per turn; the
+ * run-level AssignmentStatusUpdate sends those terminal values instead.
+ */
+export type AssignmentStatus = "in_progress" | "completed" | "abandoned";
 export interface HistoryEntry {
     comment: string;
     action_description: string;
@@ -104,6 +113,19 @@ export interface LocalStepAction {
     modifiers: string[] | null;
     key: string | null;
     tab_id: string | null;
+    orientation: string | null;
+    panel: "quick_settings" | "notifications" | null;
+    scale: number | null;
+    coordinates: {
+        x: number;
+        y: number;
+    } | null;
+    drag: {
+        startX: number;
+        startY: number;
+        endX: number;
+        endY: number;
+    } | null;
 }
 /** Raw backend step response — output is nested, actions are separate. */
 export interface LocalSimStepResponseRaw {
@@ -114,7 +136,7 @@ export interface LocalSimStepResponseRaw {
         sentiment_intensity?: number;
         current_location: string;
         effort_seconds: number;
-        assignment_completed: boolean;
+        assignment_status: AssignmentStatus;
         action: {
             actions: Array<{
                 type: string;
@@ -135,6 +157,18 @@ export interface LocalSimStepResponseRaw {
                 modifiers?: string[];
                 key?: string;
                 tab_id?: string;
+                orientation?: string;
+                panel?: "quick_settings" | "notifications";
+                scale?: number;
+                coordinates?: {
+                    x: number;
+                    y: number;
+                } | {
+                    startX: number;
+                    startY: number;
+                    endX: number;
+                    endY: number;
+                };
             }>;
         };
     };
@@ -149,6 +183,7 @@ export interface LocalSimStepResponse {
     sentiment_intensity: number;
     current_location: string;
     effort_seconds: number;
+    assignment_status: AssignmentStatus;
     assignment_completed: boolean;
     actions: LocalStepAction[];
     loop_detected: boolean;
@@ -174,6 +209,8 @@ export interface RecordInteraction {
     assignment_id: string;
     screenshot_base64?: string;
     screenshot_url?: string;
+    screen_width?: number;
+    screen_height?: number;
     frame_version_id?: string;
     timestamp_ms: number;
     comment: string | null;
@@ -181,7 +218,7 @@ export interface RecordInteraction {
     sentiment: SentimentData;
     actions: ActionData[];
     current_location: string | null;
-    assignment_completed: boolean;
+    assignment_status: AssignmentStatus;
     tabs?: LocalTabInfo[];
 }
 export interface AssignmentStatusUpdate {

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

@@ -3,4 +3,4 @@ export interface ScreenshotUploadResult {
     screenshotUrl: string;
     screenshotId: string;
 }
-export declare function uploadScreenshot(client: ApiClient, productId: string, jpegBuffer: Buffer): Promise<ScreenshotUploadResult>;
+export declare function uploadScreenshot(client: ApiClient, productId: string, imageBuffer: Buffer, contentType?: "image/jpeg" | "image/png"): Promise<ScreenshotUploadResult>;

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

@@ -1,20 +1,23 @@
 import { randomUUID } from "node:crypto";
-export async function uploadScreenshot(client, productId, jpegBuffer) {
+export async function uploadScreenshot(client, productId, imageBuffer, 
+// Browser captures JPEG; native (adb screencap) emits PNG. The signed-URL
+// request and the PUT header MUST agree so storage serves correct bytes.
+contentType = "image/jpeg") {
     const screenshotId = randomUUID();
     // Step 1: Get signed URL from backend
     const resp = await client.localSimScreenshotUpload({
         product_id: productId,
         screenshot_id: screenshotId,
-        content_type: "image/jpeg",
+        content_type: contentType,
     });
-    // Step 2: PUT raw JPEG bytes directly to Supabase Storage
+    // Step 2: PUT raw image bytes directly to Supabase Storage
     const putResp = await fetch(resp.upload_info.signed_upload_url, {
         method: "PUT",
         headers: {
-            "Content-Type": "image/jpeg",
-            "Content-Length": String(jpegBuffer.byteLength),
+            "Content-Type": contentType,
+            "Content-Length": String(imageBuffer.byteLength),
         },
-        body: jpegBuffer,
+        body: imageBuffer,
         signal: AbortSignal.timeout(30_000),
     });
     if (!putResp.ok) {

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

@@ -0,0 +1,60 @@
+/**
+ * Host-side WebDriverAgent (XCUITest) client — the iOS UI-interaction + a11y
+ * layer that replaces idb. Device LIFECYCLE (install target app, screenshot,
+ * launch/terminate target) stays on `xcrun simctl` in `simctl.ts`; this module
+ * owns ONLY the WDA surface.
+ *
+ * Mechanism (validated on the simulator, no xcodebuild): a PREBUILT WDA runner
+ * (Appium's `WebDriverAgentRunner-Runner.app`, bundle id
+ * `com.facebook.WebDriverAgentRunner.xctrunner`) is `simctl install`-ed and
+ * `simctl launch`-ed with `SIMCTL_CHILD_USE_PORT`; the xctrunner self-hosts the
+ * XCTest runtime and serves W3C WebDriver on `localhost:<port>`. We then drive
+ * taps/swipes/text via `/session/:id/actions` and read the a11y tree via
+ * `/session/:id/source?format=json` (parsed by `parseXcuiHierarchy`).
+ *
+ * API mirrors the idb functions in `simctl.ts` (udid-keyed, points space) so
+ * `ios.ts` swaps the import with a near-identical call surface. Per-udid session
+ * state (port + WDA sessionId) is held in a module map; `ensureWda` is idempotent
+ * and reuses an already-running runner.
+ */
+import { type IosScreen } from "./simctl.js";
+interface Session {
+    port: number;
+    baseUrl: string;
+    sessionId: string;
+}
+/**
+ * Resolve the prebuilt WDA `.app`, downloading it on first use:
+ * `ISH_WDA_PATH` override → `~/.ish/bin/wda/` cache → fetch Appium's prebuilt
+ * WebDriverAgent-for-simulator from its GitHub release. Mirrors
+ * `connect.ts:resolveCloudflaredBin` (which fetches cloudflared the same way).
+ */
+export declare function resolveWdaBundle(): Promise<string>;
+/**
+ * Ensure a WDA runner is up for `udid` and a session exists, idempotently. If a
+ * runner already answers on the port (a prior `ensureWda`, or an externally
+ * launched one), it is reused — only a fresh session is created. Otherwise the
+ * prebuilt runner is installed and `simctl launch`-ed.
+ */
+export declare function ensureWda(udid: string, opts?: {
+    bundleId?: string;
+}): Promise<Session>;
+/** Tear down the WDA session for `udid` (the runner is left for the next run). */
+export declare function closeWda(udid: string): Promise<void>;
+/** Screen geometry from WDA `/wda/screen` (points + retina scale). */
+export declare function describeScreen(udid: string): Promise<IosScreen>;
+/** Raw WDA `/source?format=json` string — feed to `parseXcuiHierarchy`. */
+export declare function describeAll(udid: string): Promise<string>;
+export declare function uiTap(udid: string, x: number, y: number): Promise<void>;
+export declare function uiLongPress(udid: string, x: number, y: number, durationMs?: number): Promise<void>;
+export declare function uiSwipe(udid: string, x1: number, y1: number, x2: number, y2: number, durationMs?: number): Promise<void>;
+/** Type into the focused element (the caller taps a field first). */
+export declare function uiText(udid: string, text: string): Promise<void>;
+/**
+ * Press a key. Only the idb HID Return keycode (40) is used by ios.ts today;
+ * map it to W3C ENTER. Unknown codes are a no-op-safe error.
+ */
+export declare function uiKey(udid: string, keycode: number): Promise<void>;
+/** Re-export so a future ios.ts can drop the simctl HID constant. */
+export declare const HID_KEY_RETURN = 40;
+export {};

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

@@ -0,0 +1,303 @@
+/**
+ * Host-side WebDriverAgent (XCUITest) client — the iOS UI-interaction + a11y
+ * layer that replaces idb. Device LIFECYCLE (install target app, screenshot,
+ * launch/terminate target) stays on `xcrun simctl` in `simctl.ts`; this module
+ * owns ONLY the WDA surface.
+ *
+ * Mechanism (validated on the simulator, no xcodebuild): a PREBUILT WDA runner
+ * (Appium's `WebDriverAgentRunner-Runner.app`, bundle id
+ * `com.facebook.WebDriverAgentRunner.xctrunner`) is `simctl install`-ed and
+ * `simctl launch`-ed with `SIMCTL_CHILD_USE_PORT`; the xctrunner self-hosts the
+ * XCTest runtime and serves W3C WebDriver on `localhost:<port>`. We then drive
+ * taps/swipes/text via `/session/:id/actions` and read the a11y tree via
+ * `/session/:id/source?format=json` (parsed by `parseXcuiHierarchy`).
+ *
+ * API mirrors the idb functions in `simctl.ts` (udid-keyed, points space) so
+ * `ios.ts` swaps the import with a near-identical call surface. Per-udid session
+ * state (port + WDA sessionId) is held in a module map; `ensureWda` is idempotent
+ * and reuses an already-running runner.
+ */
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { existsSync, readdirSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import * as path from "node:path";
+import { wdaDir, wdaVersionFile } from "../paths.js";
+import { IosError } from "./simctl.js";
+const execFileAsync = promisify(execFile);
+const XCRUN = "/usr/bin/xcrun";
+/** Bundle id of Appium's prebuilt WDA xctrunner (self-hosts the XCTest runtime). */
+const WDA_BUNDLE_ID = "com.facebook.WebDriverAgentRunner.xctrunner";
+/** Default WDA port; override with ISH_WDA_PORT. One device → one runner. */
+const DEFAULT_PORT = Number(process.env.ISH_WDA_PORT) || 8100;
+/** WDA's XCTest runtime cold-starts slowly; poll /status up to this long. */
+const STARTUP_TIMEOUT_MS = 75_000;
+/** W3C ENTER key (maps the idb HID Return keycode 40 used by ios.ts). */
+const W3C_ENTER = "\uE007"; // idb HID Return (40) -> W3C ENTER
+const sessions = new Map();
+// ── WDA bundle resolution (fetch is wired in the distribution phase) ──────────
+/** Appium's prebuilt WebDriverAgent simulator release we fetch + pin. */
+const WDA_PINNED_TAG = "v13.2.0";
+/**
+ * Resolve the prebuilt WDA `.app`, downloading it on first use:
+ * `ISH_WDA_PATH` override → `~/.ish/bin/wda/` cache → fetch Appium's prebuilt
+ * WebDriverAgent-for-simulator from its GitHub release. Mirrors
+ * `connect.ts:resolveCloudflaredBin` (which fetches cloudflared the same way).
+ */
+export async function resolveWdaBundle() {
+    const override = process.env.ISH_WDA_PATH;
+    if (override) {
+        if (!existsSync(override)) {
+            throw new IosError(`ISH_WDA_PATH does not exist: ${override}`);
+        }
+        return override.endsWith(".app") ? override : findApp(override);
+    }
+    const dir = wdaDir();
+    if (existsSync(dir)) {
+        try {
+            return findApp(dir);
+        }
+        catch {
+            // cache dir exists but holds no .app yet → (re)download
+        }
+    }
+    return downloadWdaBundle();
+}
+/**
+ * Fetch Appium's prebuilt WDA-for-simulator zip (just the xctrunner `.app`,
+ * which self-hosts the XCTest runtime — no xcodebuild) and unpack it into
+ * `~/.ish/bin/wda/`. arch follows the host (arm64 sims on Apple Silicon, x86_64
+ * on Intel). Logs to stderr so a run shows the one-time fetch.
+ */
+async function downloadWdaBundle() {
+    const arch = process.arch === "arm64" ? "arm64" : "x86_64";
+    const asset = `WebDriverAgentRunner-Build-Sim-${arch}.zip`;
+    const url = `https://github.com/appium/WebDriverAgent/releases/download/${WDA_PINNED_TAG}/${asset}`;
+    const dir = wdaDir();
+    console.error(`Fetching the iOS automation runner (WebDriverAgent ${WDA_PINNED_TAG}, ${arch})...`);
+    mkdirSync(dir, { recursive: true });
+    const zipPath = path.join(dir, "wda.zip");
+    let resp;
+    try {
+        resp = await fetch(url, { signal: AbortSignal.timeout(120_000) });
+    }
+    catch (e) {
+        throw new IosError(`failed to download WebDriverAgent from ${url}: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    if (!resp.ok) {
+        throw new IosError(`failed to download WebDriverAgent: HTTP ${resp.status} from ${url}`);
+    }
+    writeFileSync(zipPath, Buffer.from(await resp.arrayBuffer()));
+    try {
+        await execFileAsync("/usr/bin/unzip", ["-o", "-q", zipPath, "-d", dir], { timeout: 60_000 });
+    }
+    catch (e) {
+        throw new IosError(`failed to unpack WebDriverAgent: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    rmSync(zipPath, { force: true });
+    writeFileSync(wdaVersionFile(), `${WDA_PINNED_TAG} ${arch}\n`);
+    return findApp(dir);
+}
+/** First `*.app` directly under `dir` (or `dir` itself if it is one). */
+function findApp(dir) {
+    if (dir.endsWith(".app") && existsSync(dir))
+        return dir;
+    try {
+        const hit = readdirSync(dir).find((e) => e.endsWith(".app"));
+        if (hit)
+            return path.join(dir, hit);
+    }
+    catch {
+        /* fallthrough */
+    }
+    throw new IosError(`No WebDriverAgentRunner-Runner.app found under ${dir}`);
+}
+// ── HTTP to the runner ────────────────────────────────────────────────────
+async function wdaCall(port, method, route, body) {
+    const url = `http://localhost:${port}${route}`;
+    let resp;
+    try {
+        resp = await fetch(url, {
+            method,
+            headers: body ? { "Content-Type": "application/json" } : undefined,
+            body: body ? JSON.stringify(body) : undefined,
+            signal: AbortSignal.timeout(30_000),
+        });
+    }
+    catch (e) {
+        throw new IosError(`WDA ${method} ${route} failed: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    const text = await resp.text();
+    let json;
+    try {
+        json = text ? JSON.parse(text) : {};
+    }
+    catch {
+        throw new IosError(`WDA ${method} ${route} returned non-JSON (HTTP ${resp.status})`);
+    }
+    if (!resp.ok) {
+        const detail = json?.value?.message ?? text.slice(0, 200);
+        throw new IosError(`WDA ${method} ${route} -> HTTP ${resp.status}: ${detail}`);
+    }
+    return json;
+}
+function unwrap(json) {
+    return json && typeof json === "object" && "value" in json
+        ? json.value
+        : json;
+}
+// ── Lifecycle ─────────────────────────────────────────────────────────────
+async function simctlRun(args, timeoutMs = 180_000) {
+    try {
+        const { stdout } = await execFileAsync(XCRUN, ["simctl", ...args], {
+            timeout: timeoutMs,
+            maxBuffer: 16 * 1024 * 1024,
+        });
+        return stdout;
+    }
+    catch (e) {
+        throw new IosError(`xcrun simctl ${args[0]} failed: ${e instanceof Error ? e.message : String(e)}`);
+    }
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+async function statusOk(port) {
+    try {
+        const resp = await fetch(`http://localhost:${port}/status`, { signal: AbortSignal.timeout(2500) });
+        return resp.ok;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Ensure a WDA runner is up for `udid` and a session exists, idempotently. If a
+ * runner already answers on the port (a prior `ensureWda`, or an externally
+ * launched one), it is reused — only a fresh session is created. Otherwise the
+ * prebuilt runner is installed and `simctl launch`-ed.
+ */
+export async function ensureWda(udid, opts = {}) {
+    const existing = sessions.get(udid);
+    if (existing && (await statusOk(existing.port)))
+        return existing;
+    const port = DEFAULT_PORT;
+    if (!(await statusOk(port))) {
+        const app = await resolveWdaBundle();
+        await simctlRun(["install", udid, app]);
+        // SIMCTL_CHILD_* env passes through to the launched process; USE_PORT tells
+        // WDA which port to bind. --terminate-running-process clears a stale runner.
+        await execFileAsync(XCRUN, ["simctl", "launch", "--terminate-running-process", udid, WDA_BUNDLE_ID], { timeout: 30_000, env: { ...process.env, SIMCTL_CHILD_USE_PORT: String(port) } }).catch((e) => {
+            throw new IosError(`failed to launch WDA runner: ${e instanceof Error ? e.message : String(e)}`);
+        });
+        const deadline = Date.now() + STARTUP_TIMEOUT_MS;
+        while (!(await statusOk(port))) {
+            if (Date.now() > deadline) {
+                throw new IosError(`WDA runner did not start within ${STARTUP_TIMEOUT_MS / 1000}s`);
+            }
+            await sleep(1000);
+        }
+    }
+    const baseUrl = `http://localhost:${port}`;
+    const caps = opts.bundleId
+        ? { capabilities: { alwaysMatch: { bundleId: opts.bundleId } } }
+        : { capabilities: { alwaysMatch: {} } };
+    const resp = (await wdaCall(port, "POST", "/session", caps));
+    const sessionId = resp.sessionId ?? unwrap(resp)?.sessionId;
+    if (!sessionId)
+        throw new IosError("WDA did not return a sessionId");
+    const session = { port, baseUrl, sessionId };
+    sessions.set(udid, session);
+    return session;
+}
+async function getSession(udid) {
+    const s = sessions.get(udid);
+    if (s && (await statusOk(s.port)))
+        return s;
+    return ensureWda(udid);
+}
+/** Tear down the WDA session for `udid` (the runner is left for the next run). */
+export async function closeWda(udid) {
+    const s = sessions.get(udid);
+    sessions.delete(udid);
+    if (!s)
+        return;
+    try {
+        await wdaCall(s.port, "DELETE", `/session/${s.sessionId}`);
+    }
+    catch {
+        /* best-effort teardown */
+    }
+}
+// ── Geometry + a11y ─────────────────────────────────────────────────────────
+/** Screen geometry from WDA `/wda/screen` (points + retina scale). */
+export async function describeScreen(udid) {
+    const s = await getSession(udid);
+    const v = unwrap(await wdaCall(s.port, "GET", "/wda/screen"));
+    const pointWidth = Number(v.screenSize?.width) || 0;
+    const pointHeight = Number(v.screenSize?.height) || 0;
+    const density = Number(v.scale) || 1;
+    if (!pointWidth || !pointHeight)
+        throw new IosError("WDA /wda/screen returned no screen size");
+    return {
+        pointWidth,
+        pointHeight,
+        density,
+        pixelWidth: Math.round(pointWidth * density),
+        pixelHeight: Math.round(pointHeight * density),
+    };
+}
+/** Raw WDA `/source?format=json` string — feed to `parseXcuiHierarchy`. */
+export async function describeAll(udid) {
+    const s = await getSession(udid);
+    const json = await wdaCall(s.port, "GET", `/session/${s.sessionId}/source?format=json`);
+    return JSON.stringify(json);
+}
+// ── Gestures (W3C pointer actions; coordinates in POINTS) ────────────────────
+function pointerAction(steps) {
+    return {
+        actions: [{ type: "pointer", id: "finger1", parameters: { pointerType: "touch" }, actions: steps }],
+    };
+}
+async function performActions(udid, steps) {
+    const s = await getSession(udid);
+    await wdaCall(s.port, "POST", `/session/${s.sessionId}/actions`, pointerAction(steps));
+}
+export async function uiTap(udid, x, y) {
+    await performActions(udid, [
+        { type: "pointerMove", duration: 0, x, y },
+        { type: "pointerDown", button: 0 },
+        { type: "pause", duration: 60 },
+        { type: "pointerUp", button: 0 },
+    ]);
+}
+export async function uiLongPress(udid, x, y, durationMs = 600) {
+    await performActions(udid, [
+        { type: "pointerMove", duration: 0, x, y },
+        { type: "pointerDown", button: 0 },
+        { type: "pause", duration: durationMs },
+        { type: "pointerUp", button: 0 },
+    ]);
+}
+export async function uiSwipe(udid, x1, y1, x2, y2, durationMs = 300) {
+    await performActions(udid, [
+        { type: "pointerMove", duration: 0, x: x1, y: y1 },
+        { type: "pointerDown", button: 0 },
+        { type: "pointerMove", duration: durationMs, x: x2, y: y2 },
+        { type: "pointerUp", button: 0 },
+    ]);
+}
+/** Type into the focused element (the caller taps a field first). */
+export async function uiText(udid, text) {
+    const s = await getSession(udid);
+    await wdaCall(s.port, "POST", `/session/${s.sessionId}/wda/keys`, { value: [...text] });
+}
+/**
+ * Press a key. Only the idb HID Return keycode (40) is used by ios.ts today;
+ * map it to W3C ENTER. Unknown codes are a no-op-safe error.
+ */
+export async function uiKey(udid, keycode) {
+    if (keycode !== 40)
+        throw new IosError(`unsupported WDA keycode: ${keycode}`);
+    const s = await getSession(udid);
+    await wdaCall(s.port, "POST", `/session/${s.sessionId}/wda/keys`, { value: [W3C_ENTER] });
+}
+/** Re-export so a future ios.ts can drop the simctl HID constant. */
+export const HID_KEY_RETURN = 40;

package/dist/lib/output.js

@@ -503,7 +503,7 @@ function suggestionsForError(err) {
                     "If you didn't pass the resource explicitly, your saved active workspace/study/ask may be stale — run `ish status` to check, then `ish workspace use --clear` (or `ish study use --clear` / `ish ask use --clear`) to reset.",
                 ];
             case "insufficient_credits":
-                return ["Purchase more credits at https://app.ishlabs.io"];
+                return ["Get more credits at https://app.ishlabs.io"];
             case "usage_limit_reached": {
                 const d = structuredDetail(err);
                 const upgradeUrl = typeof d?.upgrade_url === "string" ? d.upgrade_url : "https://app.ishlabs.io/billing";
@@ -625,7 +625,7 @@ export function outputError(err, json) {
         }
         else {
             if (err.status === 402) {
-                console.error("Error: Insufficient credits. Purchase more at https://app.ishlabs.io");
+                console.error("Error: Insufficient credits. Get more credits at https://app.ishlabs.io");
             }
             else {
                 console.error(`Error: ${remapEntityName(err.message)}`);
@@ -1222,7 +1222,7 @@ export function formatStudyResults(study, participants, json) {
                 console.log(`  ${alias} (${t.name}): ${truncate(t.errorMessage, 200)}`);
             }
         }
-        console.log("\nRun `ish participant get <id> --json` for full interaction details.");
+        console.log("\nRun `ish study participant <id> --json` for full interaction details.");
     }
 }
 /**
@@ -1668,7 +1668,7 @@ export function formatSimulationPoll(results, json, isMedia = false) {
     // Pattern A (cli half): list per-participant error_message under the table so
     // agents see why a simulation failed without re-fetching every participant.
     // Truncate to 200 chars; full text is available via --json or
-    // `ish study participant get <id>`.
+    // `ish study participant <id>`.
     const failedRows = results.filter((r) => {
         const status = String(r.status || "").toLowerCase();
         return (status === "failed" || status === "errored") && r.error_message;
@@ -1689,6 +1689,43 @@ function variantLetter(index) {
         return String.fromCharCode(65 + index);
     return `V${index + 1}`;
 }
+/**
+ * Assign one stable letter per variant id across an ask's rounds — the CLI
+ * mirror of the backend's `app/asks/variant_loader.py:build_ask_label_map`.
+ *
+ * D2 fix: the LLM letters variants GLOBALLY across the whole ask. It scans
+ * rounds in `order_index` order and gives `A, B, C…` on the *first appearance*
+ * of each stable variant id, so the participant comments and round summaries
+ * say `[[A]]/[[B]]` in round 1 and `[[C]]/[[D]]` in round 2. The CLI table used
+ * to re-letter each round positionally (`variantLetter(localIndex)` → A/B every
+ * round), so a comment's `[[C]]` pointed at a row labeled `A`. Building the same
+ * id-keyed map here makes the table, the picks/winner/ratings aggregates, and
+ * the cross-round columns all agree with the `[[token]]` letters.
+ *
+ * Identity is the variant `id` (persisted variants always carry one). A variant
+ * missing an id is skipped from the map — it then falls back to the round-local
+ * positional letter at the call site, matching the backend's documented fallback
+ * for direct callers with no cross-round context.
+ */
+function buildAskLabelMap(rounds) {
+    const labelMap = new Map();
+    const ordered = [...rounds].sort((a, b) => {
+        const ai = typeof a.order_index === "number" ? a.order_index : 0;
+        const bi = typeof b.order_index === "number" ? b.order_index : 0;
+        return ai - bi;
+    });
+    for (const round of ordered) {
+        const variants = Array.isArray(round.variants) ? round.variants : [];
+        for (const v of variants) {
+            const id = v.id;
+            if (typeof id !== "string" || id.length === 0)
+                continue;
+            if (!labelMap.has(id))
+                labelMap.set(id, variantLetter(labelMap.size));
+        }
+    }
+    return labelMap;
+}
 export function formatAskList(asks, json) {
     injectAliases(asks, ALIAS_PREFIX.ask);
     if (json) {
@@ -1852,13 +1889,17 @@ export function formatRoundDetail(round, json) {
         console.log(`  ${summary.comment}`);
     }
 }
-function computeVariantStats(round) {
+function computeVariantStats(round, labelMap) {
     const variants = Array.isArray(round.variants) ? round.variants : [];
     const responses = Array.isArray(round.responses) ? round.responses : [];
     const stats = variants.map((v, i) => {
         const variant = v;
+        const id = typeof variant.id === "string" ? variant.id : undefined;
         return {
-            letter: variantLetter(i),
+            // D2: prefer the ask-global letter (id-keyed, matches the LLM's
+            // `[[token]]` letters) and only fall back to the round-local positional
+            // letter when no map entry exists (single-round / mapless callers).
+            letter: (id && labelMap?.get(id)) || variantLetter(i),
             label: variant.label ? String(variant.label) : undefined,
             kind: String(variant.kind || "-"),
             pickCount: 0,
@@ -2087,13 +2128,13 @@ export function deriveWinnerConfidence(args) {
         return "medium";
     return "high";
 }
-function buildCrossRoundSummary(rounds) {
+function buildCrossRoundSummary(rounds, labelMap) {
     if (rounds.length < 2)
         return undefined;
     const entries = [];
     for (const round of rounds) {
         const idx = typeof round.order_index === "number" ? round.order_index : 0;
-        const stats = computeVariantStats(round);
+        const stats = computeVariantStats(round, labelMap);
         const aggregates = buildAggregates(round, stats);
         const entry = {
             round_number: idx + 1,
@@ -2128,12 +2169,17 @@ export function formatAskResults(ask, json, roundFilter) {
     const filtered = roundFilter !== undefined
         ? rounds.filter((r) => (typeof r.order_index === "number" ? r.order_index : 0) === roundFilter - 1)
         : rounds;
+    // D2: build the ask-global variant→letter map from the FULL round list (not
+    // `filtered`) so that even `--round 2` still letters its variants C/D — the
+    // letter a variant earned when it debuted, matching the `[[token]]` letters
+    // in the LLM's comments and round summaries.
+    const labelMap = buildAskLabelMap(rounds);
     if (json) {
         let total = 0;
         let complete = 0;
         let errored = 0;
         const enrichedRounds = filtered.map((round) => {
-            const stats = computeVariantStats(round);
+            const stats = computeVariantStats(round, labelMap);
             const aggregates = buildAggregates(round, stats);
             const decorated = denormalizeRoundCounts(round);
             total += decorated.responses_total ?? 0;
@@ -2158,7 +2204,7 @@ export function formatAskResults(ask, json, roundFilter) {
         }
         // Pattern H2: include cross-round summary when 2+ rounds exist so agents
         // don't have to diff two `ask results` calls themselves.
-        const crossRound = buildCrossRoundSummary(filtered);
+        const crossRound = buildCrossRoundSummary(filtered, labelMap);
         if (crossRound)
             payload.cross_round_summary = crossRound;
         console.log(jsonOutput(payload));
@@ -2175,7 +2221,7 @@ export function formatAskResults(ask, json, roundFilter) {
         const completed = responses.filter((r) => r.status === "completed");
         console.log(`\nRound ${idx + 1} [${round.status || "-"}] · ${completed.length}/${responses.length} responded`);
         console.log(`  Prompt: "${truncate(String(round.prompt || ""), 100)}"`);
-        const stats = computeVariantStats(round);
+        const stats = computeVariantStats(round, labelMap);
         if (stats.length > 0 && (round.wants_pick || round.wants_ratings)) {
             const hasPick = !!round.wants_pick;
             const hasRatings = !!round.wants_ratings;
@@ -2222,7 +2268,7 @@ export function formatAskResults(ask, json, roundFilter) {
     }
     // Pattern H2: cross-round picks comparison when 2+ rounds exist. Saves
     // agents from re-running results twice and diffing aggregates by hand.
-    const crossRound = buildCrossRoundSummary(filtered);
+    const crossRound = buildCrossRoundSummary(filtered, labelMap);
     if (crossRound) {
         console.log("\nCross-round summary:");
         const letters = new Set();

package/dist/lib/paths.d.ts

@@ -12,4 +12,12 @@ export declare function binDir(): string;
 export declare function browsersDir(): string;
 export declare function simulationsDir(): string;
 export declare function cloudflaredBin(): string;
+/**
+ * Cache dir for the prebuilt iOS XCUITest runner (WebDriverAgent) bundle —
+ * the `.app` + `.xctestrun` fetched on demand for native iOS simulations,
+ * mirroring how `cloudflaredBin()` is fetched into `binDir()`.
+ */
+export declare function wdaDir(): string;
+/** Stamp file recording which CLI/runner version the cached WDA bundle is for. */
+export declare function wdaVersionFile(): string;
 export declare function connectLockPath(): string;