@ishlabs/cli 0.25.0 → 0.26.1

package/dist/commands/doctor.d.ts

@@ -0,0 +1,42 @@
+/**
+ * ish check / ish setup — environment diagnostics + dependency setup for
+ * local web and native (iOS/Android) simulations. (`doctor` is a kept alias.)
+ *
+ * `check [platform]` runs read-only checks and prints a flutter-doctor-style
+ * checklist (or `--json`), scoped to one platform's group + Account when a
+ * platform is given (ios|android|web), else everything. `setup`
+ * fetches/installs what it can (Chromium today; the iOS XCUITest runner once
+ * the artifact pipeline lands) and prints guidance for the rest, then re-runs
+ * the checks.
+ *
+ * Design notes:
+ *  - Device probes are light, NON-throwing `execFile` calls reimplemented here
+ *    (not imported from the local-sim drivers): doctor must never throw on a
+ *    missing tool, and must not pull the playwright/local-sim module graph.
+ *  - The Chromium check/setup is a DYNAMIC import of `install.ts` — that module
+ *    deep-imports a non-exported playwright path that crashes at module load on
+ *    the npm-installed CLI, so it can only be loaded lazily (same reason
+ *    `study run --local` imports it dynamically).
+ *  - iOS UI automation is migrating from idb to Apple's XCUITest (a prebuilt
+ *    WebDriverAgent runner fetched into `wdaDir()`); the runner row reflects
+ *    that target. Until the artifact ships, point `ISH_WDA_PATH` at a local
+ *    build.
+ */
+import type { Command } from "commander";
+export type CheckStatus = "pass" | "warn" | "fail" | "skip";
+export interface Check {
+    /** Stable machine key (for --json). */
+    key: string;
+    /** Human label. */
+    name: string;
+    /** Coarse grouping for the human checklist. */
+    group: "iOS" | "Android" | "Web" | "Account";
+    status: CheckStatus;
+    message?: string;
+    /** One-line remediation hint shown on warn/fail. */
+    fix?: string;
+}
+export declare function runChecks(): Promise<Check[]>;
+export declare function scopeChecks(checks: Check[], platform?: string): Check[];
+export declare function overall(checks: Check[]): CheckStatus;
+export declare function registerDoctorCommands(program: Command): void;

package/dist/commands/doctor.js

@@ -0,0 +1,359 @@
+/**
+ * ish check / ish setup — environment diagnostics + dependency setup for
+ * local web and native (iOS/Android) simulations. (`doctor` is a kept alias.)
+ *
+ * `check [platform]` runs read-only checks and prints a flutter-doctor-style
+ * checklist (or `--json`), scoped to one platform's group + Account when a
+ * platform is given (ios|android|web), else everything. `setup`
+ * fetches/installs what it can (Chromium today; the iOS XCUITest runner once
+ * the artifact pipeline lands) and prints guidance for the rest, then re-runs
+ * the checks.
+ *
+ * Design notes:
+ *  - Device probes are light, NON-throwing `execFile` calls reimplemented here
+ *    (not imported from the local-sim drivers): doctor must never throw on a
+ *    missing tool, and must not pull the playwright/local-sim module graph.
+ *  - The Chromium check/setup is a DYNAMIC import of `install.ts` — that module
+ *    deep-imports a non-exported playwright path that crashes at module load on
+ *    the npm-installed CLI, so it can only be loaded lazily (same reason
+ *    `study run --local` imports it dynamically).
+ *  - iOS UI automation is migrating from idb to Apple's XCUITest (a prebuilt
+ *    WebDriverAgent runner fetched into `wdaDir()`); the runner row reflects
+ *    that target. Until the artifact ships, point `ISH_WDA_PATH` at a local
+ *    build.
+ */
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { existsSync, readdirSync } from "node:fs";
+import * as path from "node:path";
+import { runInline } from "../lib/command-helpers.js";
+import { output } from "../lib/output.js";
+import { reportReadiness } from "../lib/report-readiness.js";
+import { loadConfig } from "../config.js";
+import { decodeJwtClaims, isTokenExpired } from "../auth.js";
+import { wdaDir, adbBin } from "../lib/paths.js";
+import pkg from "../../package.json" with { type: "json" };
+const execFileAsync = promisify(execFile);
+const XCRUN = "/usr/bin/xcrun";
+const isMac = process.platform === "darwin";
+async function tryExec(cmd, args, timeoutMs = 8000) {
+    try {
+        const { stdout, stderr } = await execFileAsync(cmd, args, {
+            timeout: timeoutMs,
+            maxBuffer: 8 * 1024 * 1024,
+        });
+        return { ok: true, stdout, stderr };
+    }
+    catch (e) {
+        const err = e;
+        return {
+            ok: false,
+            stdout: err.stdout ?? "",
+            stderr: err.stderr ?? err.message ?? String(e),
+        };
+    }
+}
+/** adb path, mirroring the device layer's resolution (ISH_ADB → SDK → Homebrew → our download cache → PATH). */
+function resolveAdb() {
+    for (const v of [process.env.ISH_ADB, process.env.ADB]) {
+        if (v && existsSync(v))
+            return v;
+    }
+    for (const home of [process.env.ANDROID_HOME, process.env.ANDROID_SDK_ROOT]) {
+        if (home) {
+            const p = path.join(home, "platform-tools", "adb");
+            if (existsSync(p))
+                return p;
+        }
+    }
+    if (existsSync("/opt/homebrew/bin/adb"))
+        return "/opt/homebrew/bin/adb";
+    if (existsSync(adbBin()))
+        return adbBin();
+    return "adb";
+}
+// ── Individual checks ──────────────────────────────────────────────────────
+function checkAuth() {
+    const cfg = loadConfig();
+    const token = cfg.access_token || cfg.token;
+    if (!token) {
+        return { key: "auth", name: "Account", group: "Account", status: "fail", message: "not logged in", fix: "ish login" };
+    }
+    const claims = decodeJwtClaims(token);
+    const email = claims?.email ?? "authenticated";
+    if (isTokenExpired(token)) {
+        // Expired access tokens auto-refresh via the refresh_token on the next API
+        // call, so this is a warn, not a hard fail.
+        return { key: "auth", name: "Account", group: "Account", status: "warn", message: `${email} (token expired — refreshes on next call)`, fix: "ish login (if refresh fails)" };
+    }
+    return { key: "auth", name: "Account", group: "Account", status: "pass", message: email };
+}
+function checkWorkspace() {
+    const cfg = loadConfig();
+    if (cfg.workspace) {
+        return { key: "workspace", name: "Active workspace", group: "Account", status: "pass", message: cfg.workspace };
+    }
+    return { key: "workspace", name: "Active workspace", group: "Account", status: "warn", message: "none set", fix: "ish workspace use <id>" };
+}
+async function checkXcode() {
+    if (!isMac) {
+        return { key: "xcode", name: "Xcode / xcrun", group: "iOS", status: "skip", message: "iOS simulations require macOS" };
+    }
+    const r = await tryExec(XCRUN, ["--version"]);
+    if (r.ok) {
+        const ver = r.stdout.trim().split("\n")[0] || "xcrun present";
+        return { key: "xcode", name: "Xcode / xcrun", group: "iOS", status: "pass", message: ver };
+    }
+    return { key: "xcode", name: "Xcode / xcrun", group: "iOS", status: "fail", message: "xcrun not found", fix: "Install Xcode from the App Store, then `xcodebuild -runFirstLaunch`" };
+}
+async function checkSimulator() {
+    if (!isMac) {
+        return { key: "ios_simulator", name: "iOS simulator", group: "iOS", status: "skip" };
+    }
+    const r = await tryExec(XCRUN, ["simctl", "list", "devices", "booted", "-j"]);
+    if (!r.ok) {
+        return { key: "ios_simulator", name: "iOS simulator", group: "iOS", status: "fail", message: "could not query simctl", fix: "Install Xcode" };
+    }
+    let booted = [];
+    try {
+        const parsed = JSON.parse(r.stdout);
+        booted = Object.values(parsed.devices ?? {})
+            .flat()
+            .filter((d) => d.state === "Booted")
+            .map((d) => ({ name: d.name, udid: d.udid }));
+    }
+    catch {
+        return { key: "ios_simulator", name: "iOS simulator", group: "iOS", status: "fail", message: "could not parse simctl output" };
+    }
+    if (booted.length === 1) {
+        return { key: "ios_simulator", name: "iOS simulator", group: "iOS", status: "pass", message: `${booted[0].name} (booted)` };
+    }
+    if (booted.length === 0) {
+        return { key: "ios_simulator", name: "iOS simulator", group: "iOS", status: "warn", message: "none booted", fix: "Open Simulator.app (Xcode ships simulators) or `xcrun simctl boot <udid>`" };
+    }
+    return { key: "ios_simulator", name: "iOS simulator", group: "iOS", status: "warn", message: `${booted.length} booted — native runs drive exactly one`, fix: "Shut down the extras" };
+}
+/** True when the prebuilt XCUITest runner (WebDriverAgent `.app`) is present. */
+function wdaBundlePresent() {
+    const override = process.env.ISH_WDA_PATH;
+    if (override)
+        return existsSync(override);
+    const dir = wdaDir();
+    if (!existsSync(dir))
+        return false;
+    try {
+        return readdirSync(dir).some((e) => e.endsWith(".app"));
+    }
+    catch {
+        return false;
+    }
+}
+function checkXcuitestRunner() {
+    if (!isMac) {
+        return { key: "xcuitest_runner", name: "XCUITest runner", group: "iOS", status: "skip" };
+    }
+    if (wdaBundlePresent()) {
+        return { key: "xcuitest_runner", name: "XCUITest runner", group: "iOS", status: "pass", message: process.env.ISH_WDA_PATH ? "ISH_WDA_PATH" : wdaDir() };
+    }
+    return { key: "xcuitest_runner", name: "XCUITest runner", group: "iOS", status: "warn", message: "not installed", fix: "ish setup (or set ISH_WDA_PATH to a local WebDriverAgent build)" };
+}
+async function checkAdb() {
+    const adbPath = resolveAdb();
+    const r = await tryExec(adbPath, ["devices"]);
+    if (!r.ok) {
+        const adb = { key: "adb", name: "Android adb", group: "Android", status: "warn", message: "not found (only needed for Android)", fix: "ish setup (fetches adb), or install Android platform-tools" };
+        const emulator = { key: "android_emulator", name: "Android emulator", group: "Android", status: "skip" };
+        return { adb, emulator };
+    }
+    const adb = { key: "adb", name: "Android adb", group: "Android", status: "pass", message: adbPath };
+    // Lines after the "List of devices attached" header, in "device" state.
+    const devices = r.stdout
+        .split("\n")
+        .slice(1)
+        .map((l) => l.trim())
+        .filter((l) => l.endsWith("\tdevice"));
+    const emulator = devices.length === 1
+        ? { key: "android_emulator", name: "Android emulator", group: "Android", status: "pass", message: devices[0].split("\t")[0] }
+        : devices.length === 0
+            ? { key: "android_emulator", name: "Android emulator", group: "Android", status: "warn", message: "none online", fix: "Create + boot an AVD in Android Studio > Device Manager (or `emulator -avd <name>`)" }
+            : { key: "android_emulator", name: "Android emulator", group: "Android", status: "warn", message: `${devices.length} online — native runs drive exactly one`, fix: "Stop the extras" };
+    return { adb, emulator };
+}
+async function checkChromium() {
+    try {
+        const { isBrowserInstalled } = await import("../lib/local-sim/install.js");
+        return isBrowserInstalled()
+            ? { key: "chromium", name: "Chromium (web local)", group: "Web", status: "pass", message: "installed" }
+            : { key: "chromium", name: "Chromium (web local)", group: "Web", status: "warn", message: "not installed", fix: "ish setup" };
+    }
+    catch {
+        return { key: "chromium", name: "Chromium (web local)", group: "Web", status: "skip", message: "unavailable in this build" };
+    }
+}
+function checkCli() {
+    return { key: "cli", name: "ish CLI", group: "Account", status: "pass", message: `v${pkg.version}` };
+}
+export async function runChecks() {
+    const { adb, emulator } = await checkAdb();
+    return [
+        await checkXcode(),
+        await checkSimulator(),
+        checkXcuitestRunner(),
+        adb,
+        emulator,
+        await checkChromium(),
+        checkAuth(),
+        checkWorkspace(),
+        checkCli(),
+    ];
+}
+// ── Rendering ───────────────────────────────────────────────────────────────
+const MARK = { pass: "[ OK ]", warn: "[WARN]", fail: "[FAIL]", skip: "[ -- ]" };
+const GROUP_ORDER = ["iOS", "Android", "Web", "Account"];
+const GROUP_LABEL = {
+    iOS: "iOS (native simulations)",
+    Android: "Android (native simulations)",
+    Web: "Web (local browser simulations)",
+    Account: "Account",
+};
+// `ish check <platform>` scopes the report to one platform's group + Account,
+// so an Android study never nags about Xcode and an iOS study never about adb.
+const PLATFORM_GROUPS = {
+    ios: ["iOS", "Account"],
+    android: ["Android", "Account"],
+    web: ["Web", "Account"],
+};
+export function scopeChecks(checks, platform) {
+    if (!platform)
+        return checks;
+    const groups = PLATFORM_GROUPS[platform];
+    return groups ? checks.filter((c) => groups.includes(c.group)) : checks;
+}
+export function overall(checks) {
+    if (checks.some((c) => c.status === "fail"))
+        return "fail";
+    if (checks.some((c) => c.status === "warn"))
+        return "warn";
+    return "pass";
+}
+function renderHuman(checks) {
+    const lines = ["", "ish check — local & native simulation environment", ""];
+    const width = Math.max(...checks.map((c) => c.name.length)) + 2;
+    for (const group of GROUP_ORDER) {
+        const inGroup = checks.filter((c) => c.group === group);
+        if (inGroup.length === 0)
+            continue;
+        lines.push(`  ${GROUP_LABEL[group]}`);
+        for (const c of inGroup) {
+            const label = c.name.padEnd(width, " ");
+            let line = `    ${MARK[c.status]}  ${label}${c.message ?? ""}`;
+            lines.push(line.trimEnd());
+            if ((c.status === "warn" || c.status === "fail") && c.fix) {
+                lines.push(`            ↳ ${c.fix}`);
+            }
+        }
+        lines.push("");
+    }
+    const o = overall(checks);
+    const fails = checks.filter((c) => c.status === "fail").length;
+    const warns = checks.filter((c) => c.status === "warn").length;
+    if (o === "pass") {
+        lines.push("Everything checks out.");
+    }
+    else {
+        const parts = [fails ? `${fails} blocking` : "", warns ? `${warns} optional` : ""].filter(Boolean);
+        lines.push(`${parts.join(", ")} issue(s). Run \`ish setup\` to fetch what's fetchable.`);
+    }
+    console.log(lines.join("\n"));
+}
+// ── Commands ──────────────────────────────────────────────────────────────
+export function registerDoctorCommands(program) {
+    program
+        .command("check [platform]")
+        .alias("doctor")
+        .description("Check your local simulation setup for a platform (ios | android | web), or everything")
+        .action(async (platform, _opts, cmd) => {
+        await runInline(cmd, async (globals) => {
+            const scope = platform?.toLowerCase();
+            if (scope && !PLATFORM_GROUPS[scope]) {
+                throw new Error(`Unknown platform "${platform}". Use one of: ios, android, web.`);
+            }
+            const checks = scopeChecks(await runChecks(), scope);
+            const aggregate = overall(checks);
+            if (globals.json) {
+                output({ checks, overall: aggregate }, true);
+            }
+            else {
+                renderHuman(checks);
+            }
+            // Best-effort: when scoped to a native platform, report readiness to
+            // the backend so the web app can render a live native-readiness panel
+            // (the native analog of `ish connect` registering a tunnel). Never for
+            // the no-arg `ish check` (no single platform) or `web`. Awaited so a
+            // short-lived `ish check` doesn't drop the in-flight request before
+            // exit — `reportReadiness` is fully best-effort and never throws or
+            // blocks meaningfully (5s ceiling).
+            if (scope === "ios" || scope === "android") {
+                await reportReadiness(scope, checks, aggregate, globals);
+            }
+        });
+    });
+    program
+        .command("setup")
+        .description("Fetch/install local-simulation dependencies (Chromium, iOS runner, adb) and show what's left to do")
+        .action(async (_opts, cmd) => {
+        await runInline(cmd, async (globals) => {
+            const quiet = globals.json;
+            const log = (m) => { if (!quiet)
+                console.error(m); };
+            // 1. Chromium (web local) — auto-fetchable.
+            try {
+                const { isBrowserInstalled, ensureBrowser } = await import("../lib/local-sim/install.js");
+                if (isBrowserInstalled()) {
+                    log("Chromium: already installed.");
+                }
+                else {
+                    log("Chromium: fetching for local web simulations...");
+                    await ensureBrowser({ quiet, skipPrompt: true });
+                }
+            }
+            catch (e) {
+                log(`Chromium: could not install (${e instanceof Error ? e.message : String(e)}).`);
+            }
+            // 2. iOS XCUITest runner (WebDriverAgent) — auto-fetchable on macOS.
+            if (isMac) {
+                try {
+                    if (wdaBundlePresent()) {
+                        log("iOS runner: already installed.");
+                    }
+                    else {
+                        log("iOS runner: fetching WebDriverAgent...");
+                        const { resolveWdaBundle } = await import("../lib/local-sim/xcuitest.js");
+                        await resolveWdaBundle();
+                    }
+                }
+                catch (e) {
+                    log(`iOS runner: could not fetch (${e instanceof Error ? e.message : String(e)}).`);
+                }
+            }
+            // 3. Android adb — auto-fetchable (Google's standalone platform-tools).
+            try {
+                const { ensureAdb } = await import("../lib/local-sim/adb.js");
+                await ensureAdb();
+                log("Android adb: ready.");
+            }
+            catch (e) {
+                log(`Android adb: could not fetch (${e instanceof Error ? e.message : String(e)}).`);
+            }
+            // 4. Re-run checks so the user sees the resulting state, and hand back
+            //    the structured result on --json.
+            const checks = await runChecks();
+            if (globals.json) {
+                output({ checks, overall: overall(checks) }, true);
+            }
+            else {
+                renderHuman(checks);
+            }
+        });
+    });
+}

package/dist/commands/iteration.js

@@ -23,6 +23,15 @@ function readTextOrAtFile(value) {
     }
     return value;
 }
+/**
+ * Native (ios/android) interactive platforms. For these the real target app is
+ * supplied at run time via `ish study run --app <bundle>`, so the iteration's
+ * `url` is just a placeholder — we don't force the user to invent one.
+ * Mirrors `isNativePlatform` in `lib/local-sim/loop.ts`.
+ */
+function isNativePlatform(platform) {
+    return platform === "ios" || platform === "android";
+}
 /**
  * Parse a JSON-blob flag that also supports `@filepath` (read from disk).
  * Used for participant_pair `--role-criteria-a/-b` and any future blob inputs.
@@ -282,7 +291,7 @@ function buildIterationDetails(modality, opts) {
             };
         }
         default:
-            if (!opts.url) {
+            if (!opts.url && !isNativePlatform(opts.platform)) {
                 throw new Error("Interactive iterations require --url. Provide the URL to test.");
             }
             if (opts.platform === "figma" && (!opts.fileKey || !opts.startNodeId)) {
@@ -296,10 +305,18 @@ function buildIterationDetails(modality, opts) {
                 }
                 screenFormat = normalized;
             }
+            // Native (ios/android) names its target via app_artifact (a bundle id /
+            // package name, or a local .app/.apk path) and carries no url. We accept
+            // the target from --app (preferred) or a --url passed out of habit. When
+            // neither is given, app_artifact is omitted = "chosen at run time".
+            const isNative = isNativePlatform(opts.platform);
+            const nativeTarget = isNative ? (opts.app ?? opts.url)?.trim() : undefined;
             return {
                 type: "interactive",
                 platform: opts.platform || "browser",
-                url: opts.url,
+                ...(isNative
+                    ? (nativeTarget ? { app_artifact: nativeTarget } : {})
+                    : { url: opts.url }),
                 screen_format: screenFormat,
                 ...(opts.locale && { locale: opts.locale }),
                 ...(opts.fileKey && { file_key: opts.fileKey }),
@@ -365,8 +382,9 @@ Concept pages: ish docs get-page concepts/iteration
         .option("--name <name>", "Iteration name (defaults to the next position letter A/B/C… if omitted)")
         .option("--description <description>", "Iteration description")
         // Interactive
-        .option("--platform <platform>", "Platform (browser, android, figma, code) — interactive only")
-        .option("--url <url>", "URL to test — interactive only")
+        .option("--platform <platform>", "Platform (browser, android, ios, figma, code) — interactive only")
+        .option("--url <url>", "URL to test — interactive only (optional for ios/android native apps)")
+        .option("--app <id>", "Native app bundle id (or .app/.apk path) — ios/android; supplies the iteration target so --url isn't required")
         .option("--screen-format <format>", "Screen format (mobile_portrait, desktop) — interactive only; hyphen/underscore variants accepted")
         .option("--locale <locale>", "Locale code (e.g. en-US) — interactive only")
         .option("--file-key <key>", "Figma file key — required when --platform=figma")
@@ -596,7 +614,7 @@ Next: \`ish study run\` to dispatch simulations against this iteration.`)
                         break;
                     }
                     default:
-                        if (!opts.url) {
+                        if (!opts.url && !isNativePlatform(opts.platform)) {
                             throw new Error("Interactive iterations require --url. Provide the URL to test.");
                         }
                 }

package/dist/commands/study-participant.js

@@ -109,7 +109,7 @@ Tips:
         .option("--study <id>", "Study ID; resolves to the latest iteration on that study (alternative to --iteration)")
         .requiredOption("--person <id>", "Participant profile ID")
         .option("--language <lang>", "Language code (e.g. en, sv)")
-        .option("--platform <platform>", "Platform (browser, android, figma, code)")
+        .option("--platform <platform>", "Platform (browser, android, ios, figma, code)")
         .option("--participant-type <type>", "Participant type (ai, human)", "ai")
         .addHelpText("after", "\nExamples:\n  $ ish study participant create --iteration <id> --person <id>\n  $ ish study participant create --study s-XXX --person p-XXX\n  $ ish study participant create --iteration <id> --person <id> --platform android --json")
         .action(async (opts, cmd) => {

package/dist/commands/study-run.js

@@ -24,6 +24,8 @@ import { isMediaModality, isChatModality, iterationHasContent, describeRequiredC
 // just `study run --local`. The bun-compiled binary bundles the deep
 // path so it doesn't hit Node's resolver; only the npm path is sensitive.
 import { estimateChatPair, estimateChatSolo, estimateMediaRun } from "../lib/billing.js";
+import { reportReadiness } from "../lib/report-readiness.js";
+import { runChecks, scopeChecks, overall } from "./doctor.js";
 function parseMaxInteractions(value) {
     const n = parseInt(value, 10);
     if (isNaN(n) || n < 1)
@@ -262,6 +264,7 @@ function readIterationDetails(details) {
         ...(screenFormat && { screenFormat }),
         ...(typeof details.locale === "string" && { locale: details.locale }),
         ...(typeof details.title === "string" && { title: details.title }),
+        ...(typeof details.app_artifact === "string" && { appArtifact: details.app_artifact }),
     };
 }
 /**
@@ -760,6 +763,24 @@ Examples:
                 ?? platformFromApp
                 ?? detailsView.platform
                 ?? "browser";
+            // Best-effort native-readiness report. When this is a LOCAL native run
+            // (iOS/Android driven on this developer's machine), fire-and-forget a
+            // fresh, platform-scoped `runChecks()` to the backend so the web app
+            // can render a live native-readiness panel — the native analog of how
+            // `ish connect` registers a tunnel. Fully decoupled from the run:
+            // never awaited (must not delay dispatch), never blocks, never throws.
+            // Browser local runs and all remote runs are skipped (remote runs use
+            // Browserbase, so this machine's device readiness is irrelevant there).
+            if (opts.local && (resolvedPlatform === "ios" || resolvedPlatform === "android")) {
+                const readinessPlatform = resolvedPlatform;
+                void (async () => {
+                    const scoped = scopeChecks(await runChecks(), readinessPlatform);
+                    await reportReadiness(readinessPlatform, scoped, overall(scoped), globals, { debug: !!opts.debug });
+                })().catch(() => {
+                    // Belt-and-suspenders: reportReadiness already swallows everything,
+                    // but runChecks() / scopeChecks() must not bubble either.
+                });
+            }
             if (isPair && pairConfig) {
                 // Pair-mode flow mirrors the MCP (`ish-mcp` `_run_pair_mode`):
                 //   1. If the iteration already carries `conversations[]` from a
@@ -884,7 +905,11 @@ Examples:
                     debug: opts.debug,
                     parallel: opts.parallel ? parseInt(opts.parallel, 10) : undefined,
                     platform: resolvedPlatform,
-                    ...(opts.app && { appPath: opts.app }),
+                    // Native target: --app overrides; otherwise default from the
+                    // iteration's remembered app_artifact so reruns need no --app.
+                    ...((opts.app ?? detailsView.appArtifact) && {
+                        appPath: opts.app ?? detailsView.appArtifact,
+                    }),
                     quiet: globals.quiet,
                     json: globals.json,
                 });

package/dist/commands/study-screenshots.js

@@ -21,6 +21,36 @@ import { dirname, extname, join } from "node:path";
 import { withClient, resolveStudy } from "../lib/command-helpers.js";
 import { resolveId } from "../lib/alias-store.js";
 import { output, printTable } from "../lib/output.js";
+import { ApiError } from "../lib/api-client.js";
+/**
+ * Server-side screenshots are produced by remote interactive runs only. A
+ * study whose only runs were local (`ish study run --local`) has none — and the
+ * grouped endpoint currently 500s instead of returning an empty index. Tag this
+ * hint onto the error so the bare 500 points the user at the local debug report.
+ */
+const LOCAL_RUN_SCREENSHOT_HINT = [
+    "Screenshots are produced by remote runs only.",
+    "Ran this study locally (--local)? The per-step screenshots are in the HTML debug report under ~/.ish/debug/ (path printed at the end of each local run).",
+];
+/**
+ * GET the frame-grouped screenshot index, tagging the local-run hint onto any
+ * ApiError before it propagates to `outputError` (which merges `.suggestions`).
+ */
+async function getGroupedScreenshots(client, studyId) {
+    try {
+        return await client.get(`/studies/${studyId}/screenshots/grouped`);
+    }
+    catch (err) {
+        if (err instanceof ApiError) {
+            const tagged = err;
+            tagged.suggestions = [
+                ...(Array.isArray(tagged.suggestions) ? tagged.suggestions : []),
+                ...LOCAL_RUN_SCREENSHOT_HINT,
+            ];
+        }
+        throw err;
+    }
+}
 function projectScreenshot(s) {
     return {
         id: s.id,
@@ -106,9 +136,12 @@ Examples:
   $ ish study screenshots download <study-id> --id <scid> --out shot.png
   $ ish study screenshots download <study-id> --all --out ./shots/
 
-Screenshots are produced server-side by interactive runs only — chat / video /
-text studies don't have them. Each row's storage URL is self-credentialed,
-so the CLI fetches bytes without forwarding your bearer.`);
+Screenshots are produced server-side by remote interactive runs only — chat /
+video / text studies don't have them, and neither do local runs
+(\`ish study run --local\`), which instead write a per-step HTML debug report to
+~/.ish/debug/ (the path is printed at the end of each local run). Each row's
+storage URL is self-credentialed, so the CLI fetches bytes without forwarding
+your bearer.`);
     screenshots
         .command("list", { isDefault: true })
         .description("List screenshots for a study (frame-grouped).")
@@ -117,7 +150,7 @@ so the CLI fetches bytes without forwarding your bearer.`);
         .action(async (id, _opts, cmd) => {
         await withClient(cmd, async (client, globals) => {
             const studyId = resolveStudy(id);
-            const raw = await client.get(`/studies/${studyId}/screenshots/grouped`);
+            const raw = await getGroupedScreenshots(client, studyId);
             const listing = projectListing(studyId, raw);
             if (globals.json) {
                 output(listing, true, { preProjected: true });
@@ -172,7 +205,7 @@ so the CLI fetches bytes without forwarding your bearer.`);
             }
             // --all: walk the index, fetch each row, save under --out dir.
             const outDir = opts.out ?? "./screenshots";
-            const grouped = await client.get(`/studies/${studyId}/screenshots/grouped`);
+            const grouped = await getGroupedScreenshots(client, studyId);
             const all = [
                 ...(grouped.groups ?? []).flatMap((g) => g.screenshots ?? []),
                 ...(grouped.uncategorized ?? []),

package/dist/index.js

@@ -19,6 +19,7 @@ import { registerDocsCommands } from "./commands/docs.js";
 import { registerInitCommands } from "./commands/init.js";
 import { registerMcpCommands } from "./commands/mcp.js";
 import { registerSecretCommands } from "./commands/secret.js";
+import { registerDoctorCommands } from "./commands/doctor.js";
 import { AGENT_HELP_FOOTER } from "./lib/docs.js";
 import { runInline, EXIT_USAGE, injectGlobalWorkspaceOption } from "./lib/command-helpers.js";
 import { resolveApiUrl, resolveToken, verifyToken } from "./lib/auth.js";
@@ -510,6 +511,7 @@ registerDocsCommands(program);
 registerInitCommands(program);
 registerMcpCommands(program);
 registerSecretCommands(program);
+registerDoctorCommands(program);
 program
     .command("upgrade")
     .description("Update ish to the latest version")

package/dist/lib/api-client.d.ts

@@ -40,6 +40,7 @@ export declare class ApiClient {
         iteration_id: string;
     }): Promise<import("./local-sim/types.js").LocalSimInitResponse>;
     localSimStep(body: import("./local-sim/types.js").LocalSimStepRequest): Promise<import("./local-sim/types.js").LocalSimStepResponseRaw>;
+    localSimRecordInteraction(body: import("./local-sim/types.js").LocalSimInteractionRequest): Promise<import("./local-sim/types.js").LocalSimInteractionResponse>;
     localSimRecord(body: import("./local-sim/types.js").LocalSimRecordRequest): Promise<import("./local-sim/types.js").LocalSimRecordResponse>;
     localSimMatchFrame(body: {
         product_id: string;
@@ -50,6 +51,8 @@ export declare class ApiClient {
         screen_format?: string;
         full_page_screenshot_base64?: string;
         platform?: string;
+        previous_frame_version_id?: string;
+        same_screen_continuation?: boolean;
     }): Promise<{
         frame_version_id: string;
     }>;

package/dist/lib/api-client.js

@@ -260,8 +260,13 @@ export class ApiClient {
     async localSimStep(body) {
         return this.post("/simulation/local/step", body, { timeout: 60_000 });
     }
+    async localSimRecordInteraction(body) {
+        return this.post("/simulation/local/interaction", body, { timeout: 30_000 });
+    }
     async localSimRecord(body) {
-        return this.post("/simulation/local/record", body, { timeout: 60_000 });
+        // Finalize now runs the pre/post survey + participant summary inline
+        // server-side, so it can take materially longer than a plain DB write.
+        return this.post("/simulation/local/record", body, { timeout: 180_000 });
     }
     async localSimMatchFrame(body) {
         return this.post("/simulation/local/match-frame", body, { timeout: 30_000 });