@ishlabs/cli 0.8.1 → 0.8.3

package/dist/commands/source.js

@@ -0,0 +1,78 @@
+/**
+ * ish source — Upload and inspect audience-generation sources.
+ *
+ * Sources (transcripts, audio, images, PDFs) are inputs to `ish profile
+ * generate`. For one-shot generation, `profile generate --source <path>`
+ * auto-uploads. Use these commands to upload once and reuse across multiple
+ * generation runs, or to inspect processing status.
+ */
+import { withClient, resolveWorkspace } from "../lib/command-helpers.js";
+import { resolveId } from "../lib/alias-store.js";
+import { formatAudienceSource } from "../lib/output.js";
+import { inferSourceKind, uploadAndProcessSource, } from "../lib/profile-sources.js";
+const VALID_KINDS = ["text_file", "audio", "image"];
+export function registerSourceCommands(program) {
+    const source = program
+        .command("source")
+        .description("Upload and inspect audience-generation sources (transcripts, audio, images)")
+        .addHelpText("after", `
+A source is an input to \`ish profile generate\` — transcript, audio, image, or PDF. Use
+\`source upload\` when you want to reuse the same source across multiple generation runs;
+otherwise pass a local path directly to \`profile generate --source\` and it auto-uploads.
+
+Concept pages: ish docs get-page concepts/source
+                ish docs get-page concepts/profile`);
+    source
+        .command("upload")
+        .description("Upload a file as an audience source and wait for processing")
+        .argument("<file>", "Local file path (transcript, audio, image, PDF, etc.)")
+        .option("--workspace <id>", "Workspace (product) ID; falls back to active workspace")
+        .option("--kind <kind>", "Source kind: text_file | audio | image (auto-detected if omitted)")
+        .option("--description <text>", "Context note attached to the source (max 500 chars)")
+        .option("--diarize", "Apply speaker diarization to audio sources (silently ignored for text/image)")
+        .option("--no-wait", "Don't poll until terminal status — return after confirm")
+        .option("--timeout <seconds>", "Poll timeout in seconds (default 300)", "300")
+        .addHelpText("after", `
+Examples:
+  $ ish source upload ./transcript.txt
+  $ ish source upload ./call.mp3 --diarize --description "Q3 churn interview"
+  $ ish source upload ./screenshot.png --kind image --no-wait`)
+        .action(async (file, opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const productId = resolveWorkspace(opts.workspace);
+            let kind;
+            if (opts.kind) {
+                if (!VALID_KINDS.includes(opts.kind)) {
+                    throw new Error(`Invalid --kind "${opts.kind}". Valid: ${VALID_KINDS.join(", ")}`);
+                }
+                kind = opts.kind;
+            }
+            else {
+                kind = inferSourceKind(file);
+            }
+            const timeoutMs = Math.max(1, parseInt(opts.timeout, 10)) * 1000;
+            const src = await uploadAndProcessSource(client, {
+                productId,
+                filePath: file,
+                kind,
+                description: opts.description,
+                diarize: opts.diarize,
+                wait: opts.wait !== false,
+                timeoutMs,
+                quiet: globals.quiet,
+            });
+            formatAudienceSource(src, globals.json);
+        });
+    });
+    source
+        .command("get")
+        .description("Get an audience source's current status")
+        .argument("<id>", "Source ID or alias")
+        .addHelpText("after", "\nExamples:\n  $ ish source get tps-3a4")
+        .action(async (id, _opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const src = await client.get(`/tester-profiles/sources/${resolveId(id)}`);
+            formatAudienceSource(src, globals.json);
+        });
+    });
+}

package/dist/commands/study-run.d.ts

@@ -0,0 +1,11 @@
+/**
+ * ish study run — Run, monitor, and cancel simulations of a study.
+ *
+ * `ish study run` creates testers for the latest (or specified) iteration
+ * and dispatches simulations. Iterations are created separately via
+ * `ish iteration create`, which carries the URL/content details.
+ *
+ * Lower-level: `study poll`, `study cancel`.
+ */
+import type { Command } from "commander";
+export declare function attachStudyRunCommands(study: Command): void;

package/dist/commands/study-run.js

@@ -0,0 +1,552 @@
+/**
+ * ish study run — Run, monitor, and cancel simulations of a study.
+ *
+ * `ish study run` creates testers for the latest (or specified) iteration
+ * and dispatches simulations. Iterations are created separately via
+ * `ish iteration create`, which carries the URL/content details.
+ *
+ * Lower-level: `study poll`, `study cancel`.
+ */
+import * as readline from "node:readline/promises";
+import { withClient, getWebUrl, terminalLink, resolveWorkspace, resolveStudy, parseWaitTimeout, resolveAudienceProfileIds, addAudienceFilterFlags, hasAudienceFlags, } from "../lib/command-helpers.js";
+import { resolveId, tagAlias, ALIAS_PREFIX } from "../lib/alias-store.js";
+import { output, formatSimulationPoll } from "../lib/output.js";
+import { MEDIA_MODALITIES } from "../lib/types.js";
+import { runLocalSimulations } from "../lib/local-sim/loop.js";
+import { ensureBrowser } from "../lib/local-sim/install.js";
+function parseMaxInteractions(value) {
+    const n = parseInt(value, 10);
+    if (isNaN(n) || n < 1)
+        throw new Error(`Invalid --max-interactions value: ${value}`);
+    return n;
+}
+function parseSlowMo(value) {
+    const n = parseInt(value, 10);
+    if (isNaN(n) || n < 0)
+        throw new Error(`Invalid --slow-mo value: ${value}`);
+    return n;
+}
+function isMediaModality(modality) {
+    return !!modality && MEDIA_MODALITIES.includes(modality);
+}
+const POLL_INTERVAL_MS = 5_000;
+const TERMINAL_STATUSES = new Set(["completed", "errored", "failed", "cancelled", "canceled"]);
+function flattenTesterStatuses(iterations, only) {
+    const rows = [];
+    for (const iteration of iterations ?? []) {
+        for (const t of iteration.testers ?? []) {
+            if (only && !only.has(t.id))
+                continue;
+            rows.push({
+                id: t.id,
+                status: t.status,
+                tester_name: t.tester_profile?.name || "Unknown",
+                interaction_count: Array.isArray(t.interactions) ? t.interactions.length : 0,
+                ...(t.error && { error: t.error }),
+                ...(t.failure_reason && { error: t.failure_reason }),
+            });
+        }
+    }
+    return rows;
+}
+async function pollStudyUntilDone(client, opts) {
+    const start = Date.now();
+    let lastReported = "";
+    while (true) {
+        const study = await client.get(`/studies/${opts.studyId}`, undefined, { timeout: 60_000 });
+        const isMedia = isMediaModality(study.modality);
+        let iterations = study.iterations;
+        if (opts.iterationId) {
+            iterations = (iterations ?? []).filter((it) => it.id === opts.iterationId);
+        }
+        const rows = flattenTesterStatuses(iterations, opts.testerIds);
+        const total = rows.length;
+        const done = rows.filter((r) => TERMINAL_STATUSES.has(r.status)).length;
+        const errored = rows.filter((r) => r.status === "errored" || r.status === "failed").length;
+        const summary = `${done}/${total} done${errored > 0 ? `, ${errored} errored/failed` : ""}`;
+        if (!opts.quiet && summary !== lastReported) {
+            process.stderr.write(`  ${summary}\n`);
+            lastReported = summary;
+        }
+        if (total > 0 && done === total) {
+            return { rows, isMedia };
+        }
+        if (Date.now() - start > opts.timeoutMs) {
+            throw new Error(`Timed out after ${Math.round(opts.timeoutMs / 1000)}s waiting for simulations. ` +
+                `Run \`ish study poll --study ${opts.studyId}\` to check status.`);
+        }
+        await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
+    }
+}
+function readIterationDetails(details) {
+    if (!details)
+        return {};
+    const screenFormat = typeof details.screen_format === "string"
+        ? details.screen_format
+        : typeof details.screenFormat === "string" ? details.screenFormat : undefined;
+    return {
+        ...(typeof details.platform === "string" && { platform: details.platform }),
+        ...(typeof details.url === "string" && { url: details.url }),
+        ...(screenFormat && { screenFormat }),
+        ...(typeof details.locale === "string" && { locale: details.locale }),
+        ...(typeof details.title === "string" && { title: details.title }),
+    };
+}
+export function attachStudyRunCommands(study) {
+    // --- Primary: `study run` ---
+    const studyRun = study
+        .command("run")
+        .description("Run a study (creates testers for the latest iteration and dispatches simulations)")
+        .option("--workspace <id>", "Workspace ID")
+        .option("--study <id>", "Study ID")
+        .option("--iteration <id>", "Iteration to run (defaults to latest on the study)");
+    addAudienceFilterFlags(studyRun, {
+        allFlagName: "--all",
+        allFlagDescription: "Use every AI profile matching the filters (workspace-wide if no filters set)",
+    })
+        .option("--config <id>", "Simulation config ID (required for media unless every profile has one)")
+        .option("--max-interactions <n>", "Max interactions per tester")
+        .option("--language <lang>", "Language code (e.g. en, sv)")
+        .option("--wait", "Wait for all simulations to reach a terminal state before returning")
+        .option("--timeout <s>", "Wait timeout in seconds (default 300; only with --wait)")
+        .option("-y, --yes", "Skip confirmation prompt")
+        // Local simulation options
+        .option("--local", "Run simulation with local browser (Playwright) instead of remote")
+        .option("--headed", "Show browser window (local mode only)")
+        .option("--slow-mo <ms>", "Slow down actions by ms (local mode only)")
+        .option("--devtools", "Open Chrome DevTools (local mode only)")
+        .option("--debug", "Enable detailed debug logging to stderr and ~/.ish/local-sim.log")
+        .option("--parallel <n>", "Run N testers in parallel (local mode only, default: all)")
+        .addHelpText("after", `
+Note: --workspace and --study are optional if you have set active context
+  via \`ish workspace use <alias>\` and \`ish study use <alias>\`.
+
+  Iterations carry the URL/content. If the study has none, create one
+  first with \`ish iteration create\`.
+
+  Audience: pass nothing to reuse the iteration's existing testers. Pass
+  --profile to use specific profiles, or filter flags (--country, --gender,
+  --min-age, --max-age, --search, --visibility) with --sample <N> or --all
+  to seed a fresh audience from the workspace pool.
+
+Examples:
+  # Run the latest iteration, reusing its testers:
+  $ ish study run -y
+
+  # Run with an explicit audience:
+  $ ish study run --profile tp-795,tp-af2
+
+  # Run with a demographic-filtered sample (3 Swedish profiles aged 35–50):
+  $ ish study run --country SE --min-age 35 --max-age 50 --sample 3
+
+  # Run with every female profile in the workspace:
+  $ ish study run --gender female --all
+
+  # Run a specific iteration:
+  $ ish study run --iteration i-d4e
+
+  # Override the simulation config (e.g. for a media study):
+  $ ish study run --config c-c3c
+
+  # Block until all simulations finish (or timeout):
+  $ ish study run --wait
+  $ ish study run --wait --timeout 600
+
+  # Local browser simulation (no remote Browserbase):
+  $ ish study run --local
+  $ ish study run --local --headed --slow-mo 500`)
+        .action(async (opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const log = (msg) => { if (!globals.quiet)
+                console.error(msg); };
+            const resolvedWorkspace = resolveWorkspace(opts.workspace);
+            const resolvedStudy = resolveStudy(opts.study);
+            // Step 0: Fetch study (with its iterations + their existing testers)
+            const study = await client.get(`/studies/${resolvedStudy}`);
+            const modality = study.modality || "interactive";
+            const isMedia = isMediaModality(modality);
+            if (!study.assignments || study.assignments.length === 0) {
+                throw new Error("Study has no assignments. Add tasks with --assignments when creating the study, or use `ish study generate`.");
+            }
+            // Step 1: Pick iteration (explicit --iteration, or latest on study)
+            const iterations = study.iterations || [];
+            let iteration;
+            if (opts.iteration) {
+                const wantedId = resolveId(opts.iteration);
+                iteration = iterations.find((it) => it.id === wantedId);
+                if (!iteration) {
+                    throw new Error(`Iteration ${opts.iteration} not found on this study.`);
+                }
+            }
+            else if (iterations.length > 0) {
+                iteration = iterations[iterations.length - 1];
+            }
+            else {
+                throw new Error("Study has no iterations. Create one first:\n" +
+                    `  ish iteration create --study ${resolvedStudy} ${isMedia ? "--content-url <file>" : "--url <url>"}`);
+            }
+            const iterationId = iteration.id;
+            const iterationLabel = iteration.label || iteration.name || iterationId.slice(0, 8);
+            const detailsView = readIterationDetails(iteration.details);
+            // Step 2: Resolve audience.
+            // - If any audience flag is set (--profile / --sample / --all / filter flags),
+            //   resolve a fresh ID list from the workspace pool via the shared helper.
+            // - Otherwise reuse the iteration's existing testers.
+            const profileNames = new Map();
+            const profileIds = [];
+            const existingTesters = [];
+            const audienceSet = hasAudienceFlags(opts);
+            if (audienceSet) {
+                const resolved = await resolveAudienceProfileIds(client, resolvedWorkspace, opts, { requireSimulatable: false, allFlagName: "--all" });
+                profileIds.push(...resolved);
+            }
+            else if (iteration.testers && iteration.testers.length > 0) {
+                for (const t of iteration.testers) {
+                    const pid = t.tester_profile_id || t.tester_profile?.id;
+                    const name = t.tester_profile?.name;
+                    if (pid && !profileNames.has(pid)) {
+                        profileNames.set(pid, name || "");
+                        profileIds.push(pid);
+                    }
+                    if (t.id) {
+                        existingTesters.push({ id: t.id, tester_profile: { name: name || "Unknown" } });
+                    }
+                }
+            }
+            const reuseExistingTesters = !audienceSet && existingTesters.length > 0;
+            if (profileIds.length === 0) {
+                throw new Error(`Iteration "${iterationLabel}" has no testers and no audience flags were given. ` +
+                    "Pass --profile <ids>, or filter flags (--country, --gender, --min-age, --max-age, --search, --visibility) with --sample <N> or --all.");
+            }
+            // Step 3: Resolve simulation config (per-profile fallback for media)
+            const resolvedConfigOverride = opts.config ? resolveId(opts.config) : undefined;
+            const profileConfigMap = new Map();
+            if (isMedia && !resolvedConfigOverride) {
+                for (const pid of profileIds) {
+                    const profile = await client.get(`/tester-profiles/${pid}`);
+                    if (profile.simulation_config_id) {
+                        profileConfigMap.set(pid, profile.simulation_config_id);
+                    }
+                    else {
+                        throw new Error(`Profile ${profileNames.get(pid) || pid} has no simulation config assigned.\n` +
+                            "Use --config <id> to specify one, or assign a config to the profile.\n" +
+                            "List configs with: ish config list");
+                    }
+                }
+            }
+            // Step 4: Confirmation
+            if (!globals.json && !opts.yes) {
+                log("");
+                log("  Run settings:");
+                log(`    Iteration:      ${iterationLabel}`);
+                log(`    Modality:       ${modality}`);
+                if (study.content_type)
+                    log(`    Content type:   ${study.content_type}`);
+                if (!isMedia) {
+                    log(`    Platform:       ${detailsView.platform || "browser"}`);
+                    log(`    Screen format:  ${detailsView.screenFormat || "desktop"}`);
+                    if (detailsView.url)
+                        log(`    URL:            ${detailsView.url}`);
+                }
+                else if (detailsView.title) {
+                    log(`    Title:          ${detailsView.title}`);
+                }
+                if (resolvedConfigOverride)
+                    log(`    Config:         ${resolvedConfigOverride}`);
+                if (opts.language)
+                    log(`    Language:       ${opts.language}`);
+                log(`    Profiles (${profileIds.length}):`);
+                for (const pid of profileIds) {
+                    const name = profileNames.get(pid);
+                    log(`      - ${name ? `${name} (${pid})` : pid}`);
+                }
+                log("");
+                const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+                const answer = await rl.question("  Proceed? [Y/n] ");
+                rl.close();
+                if (answer && !["y", "yes", ""].includes(answer.toLowerCase().trim())) {
+                    log("Aborted.");
+                    process.exit(0);
+                }
+                log("");
+            }
+            if (opts.local) {
+                await ensureBrowser({ quiet: globals.quiet, skipPrompt: globals.json });
+            }
+            // Step 5: Either reuse the iteration's testers or batch-create new ones
+            let createdTesters;
+            if (reuseExistingTesters && existingTesters.length > 0) {
+                createdTesters = existingTesters;
+                log(`Reusing ${createdTesters.length} existing tester${createdTesters.length > 1 ? "s" : ""} from iteration "${iterationLabel}"`);
+            }
+            else {
+                const testerInputs = profileIds.map((profileId) => ({
+                    tester_profile_id: profileId,
+                    tester_type: "ai",
+                    status: "draft",
+                    ...(opts.language && { language: opts.language }),
+                    ...(!isMedia && { platform: detailsView.platform || "browser" }),
+                }));
+                log(`Creating ${testerInputs.length} tester${testerInputs.length > 1 ? "s" : ""}...`);
+                const batchResult = await client.post(`/iterations/${iterationId}/testers/batch`, { testers: testerInputs });
+                createdTesters = batchResult.testers;
+                log(`Created ${createdTesters.length} tester${createdTesters.length > 1 ? "s" : ""}`);
+            }
+            // Step 6: Dispatch
+            if (opts.local) {
+                if (isMedia) {
+                    throw new Error("Local mode is only supported for interactive simulations.");
+                }
+                const testerNameMap = new Map();
+                for (const t of createdTesters) {
+                    testerNameMap.set(t.id, t.tester_profile?.name ?? "Unknown");
+                }
+                await runLocalSimulations(client, {
+                    workspaceId: resolvedWorkspace,
+                    studyId: resolvedStudy,
+                    iterationId,
+                    testerIds: createdTesters.map((t) => t.id),
+                    testerNames: testerNameMap,
+                    url: detailsView.url,
+                    screenFormat: detailsView.screenFormat,
+                    locale: detailsView.locale,
+                    maxInteractions: opts.maxInteractions ? parseMaxInteractions(opts.maxInteractions) : undefined,
+                    headed: !!opts.headed,
+                    slowMo: opts.slowMo ? parseSlowMo(opts.slowMo) : undefined,
+                    devtools: opts.devtools,
+                    debug: opts.debug,
+                    parallel: opts.parallel ? parseInt(opts.parallel, 10) : undefined,
+                    quiet: globals.quiet,
+                    json: globals.json,
+                });
+                if (globals.json) {
+                    const testersOut = createdTesters.map((t) => ({
+                        id: t.id,
+                        alias: tagAlias(ALIAS_PREFIX.tester, String(t.id)),
+                        profile_name: t.tester_profile?.name,
+                    }));
+                    output({
+                        iteration_id: iterationId,
+                        testers: testersOut,
+                        tester_ids: testersOut.map((t) => t.id),
+                        tester_aliases: testersOut.map((t) => t.alias),
+                        mode: "local",
+                    }, true);
+                }
+                return;
+            }
+            log(`Starting ${createdTesters.length} simulation${createdTesters.length > 1 ? "s" : ""}...`);
+            let simResults;
+            if (isMedia) {
+                const mediaBatchItems = createdTesters.map((t, i) => ({
+                    study_id: resolvedStudy,
+                    tester_id: t.id,
+                    config_id: resolvedConfigOverride || profileConfigMap.get(profileIds[i]),
+                    ...(opts.language && { language: opts.language }),
+                }));
+                const simResult = await client.post("/simulation/media/start/batch", {
+                    product_id: resolvedWorkspace,
+                    simulations: mediaBatchItems,
+                    ...(opts.maxInteractions && { max_interactions: parseMaxInteractions(opts.maxInteractions) }),
+                }, { timeout: 60_000 });
+                simResults = simResult.results;
+            }
+            else {
+                const simItems = createdTesters.map((t) => ({
+                    study_id: resolvedStudy,
+                    tester_id: t.id,
+                    ...(resolvedConfigOverride && { config_id: resolvedConfigOverride }),
+                    ...(opts.language && { language: opts.language }),
+                    ...(detailsView.locale && { locale: detailsView.locale }),
+                }));
+                const simResult = await client.post("/simulation/interactive/start/batch", {
+                    product_id: resolvedWorkspace,
+                    simulations: simItems,
+                    platform: detailsView.platform || "browser",
+                    ...(detailsView.url && { url: detailsView.url }),
+                    screen_format: detailsView.screenFormat || "desktop",
+                    ...(opts.maxInteractions && { max_interactions: parseMaxInteractions(opts.maxInteractions) }),
+                }, { timeout: 60_000 });
+                simResults = simResult.results;
+            }
+            if (!opts.wait) {
+                if (globals.json) {
+                    const testersOut = createdTesters.map((t) => ({
+                        id: t.id,
+                        alias: tagAlias(ALIAS_PREFIX.tester, String(t.id)),
+                        profile_name: t.tester_profile?.name,
+                    }));
+                    output({
+                        iteration_id: iterationId,
+                        testers: testersOut,
+                        tester_ids: testersOut.map((t) => t.id),
+                        tester_aliases: testersOut.map((t) => t.alias),
+                        simulations: simResults,
+                    }, true);
+                }
+                else {
+                    for (let i = 0; i < simResults.length; i++) {
+                        const tester = createdTesters[i];
+                        const profileName = tester?.tester_profile?.name || "Unknown";
+                        log(`  ${profileName.padEnd(24)} QUEUED`);
+                    }
+                    const url = getWebUrl(globals, `/${resolvedWorkspace}/${resolvedStudy}/timeline`);
+                    log(`\n  ${terminalLink(url, "Open in browser ↗")}\n`);
+                    log(`Run \`ish study poll --study ${resolvedStudy}\` (or --wait next time) to check progress.`);
+                }
+                return;
+            }
+            // --wait: block until all dispatched testers reach a terminal state
+            const timeoutMs = parseWaitTimeout(opts.timeout);
+            const dispatchedIds = new Set(createdTesters.map((t) => t.id));
+            log(`Waiting for ${dispatchedIds.size} simulation${dispatchedIds.size > 1 ? "s" : ""} to finish...`);
+            const { rows, isMedia: pollIsMedia } = await pollStudyUntilDone(client, {
+                studyId: resolvedStudy,
+                testerIds: dispatchedIds,
+                timeoutMs,
+                quiet: globals.quiet,
+            });
+            if (globals.json) {
+                const testersOut = createdTesters.map((t) => ({
+                    id: t.id,
+                    alias: tagAlias(ALIAS_PREFIX.tester, String(t.id)),
+                    profile_name: t.tester_profile?.name,
+                }));
+                output({
+                    iteration_id: iterationId,
+                    testers: testersOut,
+                    tester_ids: testersOut.map((t) => t.id),
+                    tester_aliases: testersOut.map((t) => t.alias),
+                    simulations: simResults,
+                    results: rows,
+                }, true);
+            }
+            else {
+                formatSimulationPoll(rows, false, pollIsMedia);
+                const url = getWebUrl(globals, `/${resolvedWorkspace}/${resolvedStudy}/timeline`);
+                log(`\n  ${terminalLink(url, "Open in browser ↗")}\n`);
+            }
+        });
+    });
+    // --- Poll: check simulation progress ---
+    study
+        .command("poll")
+        .description("Check simulation progress for a study")
+        .argument("[tester_id]", "Tester ID (alias or UUID; from `ish study run --json`.tester_aliases[])")
+        .option("--study <id>", "Study ID (poll all simulations for study)")
+        .option("--workspace <id>", "Workspace ID; accepted for consistency (workspace is inferred from --study/--iteration/<tester_id>)")
+        .addHelpText("after", "\nExamples:\n  $ ish study poll --study <study_id>\n  $ ish study poll <tester_id> --json\n\nGet tester IDs from `ish study run --json` (.tester_aliases[] / .tester_ids[]).")
+        .action(async (testerId, opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            if (testerId) {
+                const data = await client.get(`/simulation/status/${resolveId(testerId)}`);
+                output(data, globals.json);
+            }
+            else if (opts.study) {
+                const rid = resolveId(opts.study);
+                const study = await client.get(`/studies/${rid}`);
+                const isMedia = isMediaModality(study.modality);
+                const allTesters = [];
+                for (const iteration of study.iterations || []) {
+                    for (const tester of iteration.testers || []) {
+                        allTesters.push({
+                            id: tester.id,
+                            status: tester.status,
+                            tester_name: tester.tester_profile?.name || "Unknown",
+                            interaction_count: Array.isArray(tester.interactions) ? tester.interactions.length : 0,
+                            ...(tester.error && { error: tester.error }),
+                            ...(tester.failure_reason && { error: tester.failure_reason }),
+                        });
+                    }
+                }
+                formatSimulationPoll(allTesters, globals.json, isMedia);
+                if (!globals.json && study.product_id) {
+                    const url = getWebUrl(globals, `/${study.product_id}/${rid}/timeline`);
+                    console.error(`\n  ${terminalLink(url, "Open in browser ↗")}\n`);
+                }
+            }
+            else {
+                throw new Error("Provide a tester_id argument or --study flag");
+            }
+        });
+    });
+    // --- Wait: poll until simulations reach a terminal state ---
+    study
+        .command("wait")
+        .description("Poll until simulations reach a terminal state (completed/errored/failed/cancelled)")
+        .argument("[tester_id]", "Tester ID (alias or UUID; from `ish study run --json`.tester_aliases[])")
+        .option("--study <id>", "Study ID (wait for all testers in the study)")
+        .option("--iteration <id>", "Iteration ID (wait for testers in this iteration only)")
+        .option("--timeout <s>", "Max seconds to wait (default 300)")
+        .option("--workspace <id>", "Workspace ID; accepted for consistency (workspace is inferred from --study/--iteration/<tester_id>)")
+        .addHelpText("after", "\nExamples:\n  $ ish study wait                         # wait on the active study\n  $ ish study wait --iteration i-d4e\n  $ ish study wait <tester_id> --timeout 600\n\nGet tester IDs from `ish study run --json` (.tester_aliases[] / .tester_ids[]).")
+        .action(async (testerId, opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const timeoutMs = parseWaitTimeout(opts.timeout);
+            if (testerId) {
+                const start = Date.now();
+                let lastStatus = "";
+                while (true) {
+                    const data = await client.get(`/simulation/status/${resolveId(testerId)}`, undefined, { timeout: 60_000 });
+                    const status = String(data.status ?? "unknown");
+                    if (!globals.quiet && status !== lastStatus) {
+                        process.stderr.write(`  ${status}\n`);
+                        lastStatus = status;
+                    }
+                    if (TERMINAL_STATUSES.has(status)) {
+                        output(data, globals.json);
+                        return;
+                    }
+                    if (Date.now() - start > timeoutMs) {
+                        throw new Error(`Timed out after ${Math.round(timeoutMs / 1000)}s waiting for tester ${testerId}.`);
+                    }
+                    await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
+                }
+            }
+            // When --iteration is given, derive the parent study from the iteration
+            // itself rather than falling back to the active study config. An
+            // iteration's study_id is authoritative for "what study does this
+            // iteration belong to" — using the active config here would happily
+            // poll the wrong study when the user is checking on a sibling.
+            let studyId;
+            let iterationId;
+            if (opts.iteration) {
+                iterationId = resolveId(opts.iteration);
+                const iter = await client.get(`/iterations/${iterationId}`);
+                if (!iter.study_id) {
+                    throw new Error(`Iteration ${opts.iteration} has no study_id.`);
+                }
+                studyId = iter.study_id;
+                if (opts.study) {
+                    const explicitStudy = resolveId(opts.study);
+                    if (explicitStudy !== studyId) {
+                        throw new Error(`--iteration ${opts.iteration} belongs to study ${studyId}, but --study ${opts.study} was passed. Drop --study or pass the matching one.`);
+                    }
+                }
+            }
+            else {
+                studyId = resolveStudy(opts.study);
+            }
+            const { rows, isMedia } = await pollStudyUntilDone(client, {
+                studyId,
+                iterationId,
+                timeoutMs,
+                quiet: globals.quiet,
+            });
+            formatSimulationPoll(rows, globals.json, isMedia);
+        });
+    });
+    // --- Cancel ---
+    study
+        .command("cancel")
+        .description("Cancel a running simulation")
+        .argument("<tester_id>", "Tester ID (alias or UUID; from `ish study run --json`.tester_aliases[])")
+        .option("--workspace <id>", "Workspace ID; accepted for consistency (workspace is inferred from <tester_id>)")
+        .addHelpText("after", "\nExamples:\n  $ ish study cancel t-072\n  $ ish study cancel <uuid>\n\nGet tester IDs from `ish study run --json` (.tester_aliases[] / .tester_ids[]).")
+        .action(async (testerId, _opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const data = await client.post(`/simulation/cancel/${resolveId(testerId)}`);
+            output(data, globals.json);
+        });
+    });
+}

package/dist/commands/study-tester.d.ts

@@ -0,0 +1,8 @@
+/**
+ * ish study tester — Inspect and manage testers (low-level; usually
+ * created via `ish study run`).
+ *
+ * Default action: `ish study tester <id>` shows tester details and results.
+ */
+import type { Command } from "commander";
+export declare function attachStudyTesterCommands(study: Command): void;