@ishlabs/cli 0.8.3 → 0.8.5

package/README.md

@@ -41,6 +41,12 @@ The CLI resolves your auth token in this order:
 2. `ISH_TOKEN` env var
 3. Saved token from `ish login`
 
+## Testing
+
+Test plan is available at `/Users/felixweiland/ish-cli-test-plan.md`.
+
+---
+
 ## Concepts
 
 Two top-level research primitives, both consume reusable tester profiles:
@@ -49,7 +55,7 @@ Two top-level research primitives, both consume reusable tester profiles:
 Workspace (= product, top-level container)
 │
 ├── Tester Profiles        ← reusable audience personas
-│     └── Audience Sources (transcripts / audio / images that seed generation)
+│     └── Audience Sources (images/PDFs/audio/video/text transcripts that seed generation)
 │
 ├── Study  ─────────────── "structured research artifact"
 │     ├── modality (interactive | text | video | audio | image | document)

package/dist/auth.d.ts

@@ -15,11 +15,27 @@ export declare function resolveSupabaseProjectFromToken(accessToken: string | un
     anonKey: string;
 };
 export declare function decodeJwtExp(token: string): number;
+export declare function decodeJwtClaims(token: string): Record<string, unknown> | undefined;
 export declare function isTokenExpired(token: string, bufferSeconds?: number): boolean;
 export declare function login(appUrl?: string): Promise<{
     accessToken: string;
     refreshToken: string;
 }>;
+/**
+ * Thrown by `refreshTokens` when the refresh attempt failed permanently and
+ * the local config can't recover (e.g. Supabase `refresh_token_not_found`,
+ * `invalid_grant`, or any 400-class response). Callers should treat this as
+ * "user must run `ish login` again" — retrying won't help.
+ *
+ * Transient failures (network errors, 5xx, timeouts) are NOT this error and
+ * may be worth retrying.
+ */
+export declare class AuthRefreshPermanentError extends Error {
+    readonly httpStatus: number;
+    readonly errorCode: string | undefined;
+    readonly body: string;
+    constructor(httpStatus: number, body: string, errorCode: string | undefined);
+}
 export declare function refreshTokens(refreshToken: string, options?: {
     /** The (possibly expired) access token. Used to pick the correct Supabase project. */
     accessToken?: string;

package/dist/auth.js

@@ -93,6 +93,15 @@ export function decodeJwtExp(token) {
         return 0;
     }
 }
+export function decodeJwtClaims(token) {
+    try {
+        const payload = token.split(".")[1];
+        return JSON.parse(Buffer.from(payload, "base64url").toString());
+    }
+    catch {
+        return undefined;
+    }
+}
 export function isTokenExpired(token, bufferSeconds = 300) {
     const exp = decodeJwtExp(token);
     if (!exp)
@@ -104,10 +113,10 @@ export async function login(appUrl) {
     const url = appUrl ?? getAppUrl();
     const state = crypto.randomBytes(32).toString("hex");
     const loginUrl = `${url}/auth/plugin?state=${state}`;
-    console.log("Opening browser to sign in...");
-    console.log(`If the browser doesn't open, visit:\n  ${loginUrl}\n`);
+    console.error("Opening browser to sign in...");
+    console.error(`If the browser doesn't open, visit:\n  ${loginUrl}\n`);
     openBrowser(loginUrl);
-    console.log("Waiting for authentication...");
+    console.error("Waiting for authentication...");
     const deadline = Date.now() + LOGIN_TIMEOUT;
     while (Date.now() < deadline) {
         await new Promise((r) => setTimeout(r, POLL_INTERVAL));
@@ -130,6 +139,43 @@ export async function login(appUrl) {
     throw new Error("Login timed out. Please try again.");
 }
 // --- Token refresh ---
+/**
+ * Thrown by `refreshTokens` when the refresh attempt failed permanently and
+ * the local config can't recover (e.g. Supabase `refresh_token_not_found`,
+ * `invalid_grant`, or any 400-class response). Callers should treat this as
+ * "user must run `ish login` again" — retrying won't help.
+ *
+ * Transient failures (network errors, 5xx, timeouts) are NOT this error and
+ * may be worth retrying.
+ */
+export class AuthRefreshPermanentError extends Error {
+    httpStatus;
+    errorCode;
+    body;
+    constructor(httpStatus, body, errorCode) {
+        const detail = errorCode ? ` ${errorCode}` : "";
+        super(`Token refresh failed permanently (HTTP ${httpStatus}${detail}): ${body}`);
+        this.name = "AuthRefreshPermanentError";
+        this.httpStatus = httpStatus;
+        this.errorCode = errorCode;
+        this.body = body;
+    }
+}
+function parseRefreshErrorCode(body) {
+    try {
+        const parsed = JSON.parse(body);
+        if (parsed && typeof parsed === "object") {
+            if (typeof parsed.error_code === "string")
+                return parsed.error_code;
+            if (typeof parsed.error === "string")
+                return parsed.error;
+        }
+    }
+    catch {
+        // not JSON — fall through
+    }
+    return undefined;
+}
 export async function refreshTokens(refreshToken, options) {
     const project = options?.supabaseUrl && options?.anonKey
         ? { url: options.supabaseUrl, anonKey: options.anonKey }
@@ -145,6 +191,9 @@ export async function refreshTokens(refreshToken, options) {
     });
     if (!resp.ok) {
         const body = await resp.text().catch(() => "");
+        if (resp.status >= 400 && resp.status < 500) {
+            throw new AuthRefreshPermanentError(resp.status, body, parseRefreshErrorCode(body));
+        }
         throw new Error(`Token refresh failed (HTTP ${resp.status}): ${body}`);
     }
     const data = await resp.json();

package/dist/commands/ask.js

@@ -139,7 +139,7 @@ Concept pages: ish docs get-page concepts/ask
         .option("--variants <file.json>", "JSON manifest of variants (alternative to --variant)")
         .option("--wants-pick", "Each tester picks a favourite variant (compatible with --wants-ratings; can be set together).")
         .option("--wants-ratings", "Each tester rates every variant 1–5 (compatible with --wants-pick; can be set together). If neither is set, testers leave a free-form comment only.")
-        .option("--questions <file.json>", `Questions JSON file: [{"question":"...","type":"open_ended"|"slider"|"choice"|"likert"}]`)
+        .option("--questions <file.json>", `Questions JSON file: [{"question":"...","type":"text"|"slider"|"likert"|"single-choice"|"multiple-choice"|"number"}]`)
         .option("--language <code>", "2-letter language code (with --new only)", "en");
     addAudienceFilterFlags(askRun, {
         allFlagName: "--all-simulatable",
@@ -285,7 +285,7 @@ Examples:
         .option("--variants <file.json>", "JSON manifest of variants (alternative to --variant)")
         .option("--wants-pick", "Each tester picks a favourite variant (compatible with --wants-ratings; can be set together).")
         .option("--wants-ratings", "Each tester rates every variant 1–5 (compatible with --wants-pick; can be set together). If neither is set, testers leave a free-form comment only.")
-        .option("--questions <file.json>", `Questions JSON file: [{"question":"...","type":"open_ended"|"slider"|"choice"|"likert"}]`)
+        .option("--questions <file.json>", `Questions JSON file: [{"question":"...","type":"text"|"slider"|"likert"|"single-choice"|"multiple-choice"|"number"}]`)
         .option("--language <code>", "2-letter language code", "en");
     addAudienceFilterFlags(askCreate, {
         allFlagName: "--all-simulatable",
@@ -323,9 +323,13 @@ Examples:
 
 Minimal --questions JSON (server keys: "question" + "type"):
   [
-    { "question": "What stood out?", "type": "open_ended" },
+    { "question": "What stood out?", "type": "text" },
     { "question": "Rate it 1-5", "type": "slider" }
   ]
+
+Picks come back with a \`pick_confidence\` (0..1) score per tester when
+\`--wants-pick\` is set — read it off \`pick.confidence\` in the response. See
+\`ish docs get-page concepts/ask\` for interpretation.
 `)
         .action(async (opts, cmd) => {
         await withClient(cmd, async (client, globals) => {
@@ -362,14 +366,47 @@ Minimal --questions JSON (server keys: "question" + "type"):
     // ---- get ----------------------------------------------------------------
     ask
         .command("get")
-        .description("Get full ask detail including rounds and responses")
-        .argument("[id]", "Ask alias or UUID (defaults to active ask from `ish ask use`)")
-        .option("--ask <id>", "Ask ID; alternative to positional argument")
-        .option("--round <n>", "Show only round N (1-indexed)")
-        .addHelpText("after", "\nExamples:\n  $ ish ask get a-6ec\n  $ ish ask get a-6ec --round 2 --json")
-        .action(async (id, opts, cmd) => {
+        .description("Get full ask detail (accepts multiple IDs for batched lookup)")
+        .argument("[ids...]", "Ask alias(es)/UUID(s); defaults to active ask from `ish ask use`")
+        .option("--ask <id>", "Ask ID; alternative to a single positional argument")
+        .option("--round <n>", "Show only round N (1-indexed); single-ask only")
+        .addHelpText("after", `
+Examples:
+  $ ish ask get a-6ec
+  $ ish ask get a-6ec --round 2 --json
+  $ ish ask get a-6ec a-7c2 a-9d3
+  $ ish ask get a-6ec,a-7c2 --fields alias,name,testers_count,responses_total
+
+With multiple IDs, returns a {items:[...], total:N} envelope and uses the
+list table layout in human mode. --ask and --round only apply to single-ask
+lookups.`)
+        .action(async (ids, opts, cmd) => {
         await withClient(cmd, async (client, globals) => {
-            const aid = resolveAsk(pickAskRef(id, opts.ask));
+            const flat = (ids ?? []).flatMap((s) => s.split(",").map((x) => x.trim()).filter(Boolean));
+            if (flat.length > 1) {
+                if (opts.ask) {
+                    throw new Error("Pass either --ask or multiple positional ids, not both.");
+                }
+                if (opts.round !== undefined) {
+                    throw new Error("--round only applies when fetching a single ask.");
+                }
+                const results = await Promise.all(flat.map(async (raw) => {
+                    const aid = resolveId(raw);
+                    const data = await client.get(`/asks/${aid}`);
+                    const r = data;
+                    if (r.id)
+                        r.alias = tagAlias(ALIAS_PREFIX.ask, String(r.id));
+                    return r;
+                }));
+                if (globals.json) {
+                    output({ items: results, total: results.length }, true);
+                }
+                else {
+                    formatAskList(results, false);
+                }
+                return;
+            }
+            const aid = resolveAsk(pickAskRef(flat[0], opts.ask));
             const data = await client.get(`/asks/${aid}`);
             if (opts.round !== undefined) {
                 const target = parseInt(opts.round, 10);
@@ -397,7 +434,14 @@ Minimal --questions JSON (server keys: "question" + "type"):
         .argument("[id]", "Ask alias or UUID (defaults to active ask)")
         .option("--ask <id>", "Ask ID; alternative to positional argument")
         .option("--round <n>", "Show only round N (1-indexed; default: all rounds)")
-        .addHelpText("after", "\nExamples:\n  $ ish ask results a-6ec\n  $ ish ask results a-6ec --round 1 --json")
+        .addHelpText("after", `
+Examples:
+  $ ish ask results a-6ec
+  $ ish ask results a-6ec --round 1 --json
+
+Each pick has a \`pick_confidence\` field (0..1, when --wants-pick was set) —
+the model's self-reported confidence in its variant choice. See
+\`ish docs get-page concepts/ask\` for how to use it for ranking ties.`)
         .action(async (id, opts, cmd) => {
         await withClient(cmd, async (client, globals) => {
             const aid = resolveAsk(pickAskRef(id, opts.ask));
@@ -468,12 +512,13 @@ Minimal --questions JSON (server keys: "question" + "type"):
         .description("Append a new round to an existing ask (max 5 per ask)")
         .argument("[id]", "Ask alias or UUID (defaults to active ask)")
         .option("--ask <id>", "Ask ID; alternative to positional argument")
+        .option("--workspace <id>", "Workspace ID; accepted for consistency (workspace is inferred from the ask)")
         .requiredOption("--prompt <prompt>", "Round prompt")
         .option("--variant <kind:value>", "Variant flag (repeatable; same syntax as `ask create`)", collectRepeatable, [])
         .option("--variants <file.json>", "JSON manifest of variants")
         .option("--wants-pick", "Each tester picks a favourite variant (compatible with --wants-ratings; can be set together).")
         .option("--wants-ratings", "Each tester rates every variant 1–5 (compatible with --wants-pick; can be set together). If neither is set, testers leave a free-form comment only.")
-        .option("--questions <file.json>", `Questions JSON file: [{"question":"...","type":"open_ended"|"slider"|"choice"|"likert"}]`)
+        .option("--questions <file.json>", `Questions JSON file: [{"question":"...","type":"text"|"slider"|"likert"|"single-choice"|"multiple-choice"|"number"}]`)
         .option("--wait", "Wait until the new round completes")
         .option("--timeout <s>", "Wait timeout in seconds (default 300)")
         .addHelpText("after", "\nExamples:\n  $ ish ask add-round a-6ec --prompt \"And now?\" --variant text:\"Hello\" --variant text:\"Hi\" --wait")
@@ -499,31 +544,54 @@ Minimal --questions JSON (server keys: "question" + "type"):
     // ---- add-questions ------------------------------------------------------
     ask
         .command("add-questions")
-        .description("Append questionnaire questions to a round (resets responses, re-dispatches)")
+        .description("Append questionnaire questions to a round. Default: additive re-dispatch (prior picks/comments/ratings preserved; only the new questions are answered). Pass --redispatch-all to fully reset and re-run the round from scratch.")
         .argument("[id]", "Ask alias or UUID (defaults to active ask)")
         .option("--ask <id>", "Ask ID; alternative to positional argument")
         .requiredOption("--round <n|round-id>", "Round number (1-indexed) or round id/alias")
-        .requiredOption("--questions <file.json>", `Questions JSON file: [{"question":"...","type":"open_ended"|"slider"|"choice"|"likert"}]`)
+        .requiredOption("--questions <file.json>", `Questions JSON file: [{"question":"...","type":"text"|"slider"|"likert"|"single-choice"|"multiple-choice"|"number"}]`)
+        .option("--redispatch-all", "Clear prior phase-1 outputs (comment, pick, ratings) and re-run the entire round from scratch (legacy behavior). Default is additive — only the new questions are answered.", false)
+        .option("--wait", "Wait until the round completes (or errors)")
+        .option("--timeout <s>", "Wait timeout in seconds (default 300)")
         .addHelpText("after", `
 Examples:
+  # Additive (default): preserves prior picks/ratings/comments.
   $ ish ask add-questions a-6ec --round 1 --questions ./qs.json
 
+  # Wait for the round to finish before returning.
+  $ ish ask add-questions a-6ec --round 1 --questions ./qs.json --wait
+
+  # Legacy reset: re-runs the whole round; prior picks may shift.
+  $ ish ask add-questions a-6ec --round 1 --questions ./qs.json --redispatch-all --wait
+
 Minimal valid --questions JSON:
   [
-    { "question": "What stood out?", "type": "open_ended" },
+    { "question": "What stood out?", "type": "text" },
     { "question": "Rate it 1-5", "type": "slider" }
   ]
 
 Note: the server requires the key "question" (not "text"). Valid type values:
-open_ended, slider, choice, likert.`)
+text, slider, likert, single-choice, multiple-choice, number.`)
         .action(async (id, opts, cmd) => {
         await withClient(cmd, async (client, globals) => {
             const aid = resolveAsk(pickAskRef(id, opts.ask));
             const ask = await client.get(`/asks/${aid}`);
             const round = getRoundByIndexOrId(ask, opts.round);
             const questions = loadQuestionsManifest(opts.questions);
-            const body = { questions };
+            const body = {
+                questions,
+                ...(opts.redispatchAll && { redispatch_all: true }),
+            };
             const updated = await client.post(`/asks/${aid}/rounds/${round.id}/questions`, body);
+            if (opts.wait) {
+                const timeoutMs = parseWaitTimeout(opts.timeout);
+                await pollUntilRoundDone(client, aid, updated.order_index, timeoutMs, !!globals.quiet);
+                const refreshed = await client.get(`/asks/${aid}`);
+                const target = refreshed.rounds.find((r) => r.id === updated.id);
+                if (target) {
+                    formatRoundDetail(target, globals.json);
+                    return;
+                }
+            }
             if (!globals.json || globals.verbose) {
                 formatRoundDetail(updated, globals.json);
                 return;
@@ -545,6 +613,7 @@ open_ended, slider, choice, likert.`)
         .description("Add testers to an existing ask (optionally backfill prior rounds)")
         .argument("[id]", "Ask alias or UUID (defaults to active ask)")
         .option("--ask <id>", "Ask ID; alternative to positional argument")
+        .option("--workspace <id>", "Workspace ID; accepted for consistency (workspace is inferred from the ask)")
         .requiredOption("--round <n|round-id>", "Round to add testers to (required)");
     addAudienceFilterFlags(askAddTesters, {
         allFlagName: "--all-simulatable",

package/dist/commands/iteration.js

@@ -5,7 +5,7 @@
  * content/file for media). Create one before `ish study run` dispatches
  * simulations against it.
  */
-import { withClient, resolveStudy } from "../lib/command-helpers.js";
+import { withClient, resolveStudy, resolveWorkspace } from "../lib/command-helpers.js";
 import { resolveId, tagAlias, ALIAS_PREFIX } from "../lib/alias-store.js";
 import { output, formatIterationList } from "../lib/output.js";
 import { resolveContentUrl, resolveContentUrls, resolveTextContent } from "../lib/upload.js";
@@ -101,9 +101,12 @@ Concept pages: ish docs get-page concepts/iteration
         .command("list")
         .description("List iterations for a study")
         .option("--study <id>", "Study ID")
+        .option("--workspace <id>", "Workspace ID; accepted for consistency (workspace is inferred from the study)")
         .addHelpText("after", "\nExamples:\n  $ ish iteration list --study <id>\n  $ ish iteration list --study <id> --json")
         .action(async (opts, cmd) => {
         await withClient(cmd, async (client, globals) => {
+            if (opts.workspace)
+                resolveWorkspace(opts.workspace);
             const data = await client.get(`/studies/${resolveStudy(opts.study)}/iterations`);
             const rows = data;
             if (globals.json) {
@@ -122,7 +125,9 @@ Concept pages: ish docs get-page concepts/iteration
                     order_index: it.order_index ?? null,
                     created_at: it.created_at ?? null,
                 }));
-                output(projected, true, { preProjected: true });
+                // Synthesized pagination metadata — backend returns a flat array.
+                const total = projected.length;
+                output({ items: projected, total, returned: total, limit: total, offset: 0, has_more: false }, true, { preProjected: true });
                 return;
             }
             formatIterationList(rows, globals.json);
@@ -132,6 +137,7 @@ Concept pages: ish docs get-page concepts/iteration
         .command("create")
         .description("Create a new iteration with run-time content/URL")
         .option("--study <id>", "Study ID (or set via `ish study use`)")
+        .option("--workspace <id>", "Workspace ID; accepted for consistency (workspace is inferred from the study)")
         .option("--name <name>", "Iteration name (auto-generated if omitted)")
         .option("--description <description>", "Iteration description")
         // Interactive
@@ -198,6 +204,8 @@ workspace's public storage bucket. Validation now happens before upload.
 Next: \`ish study run\` to dispatch simulations against this iteration.`)
         .action(async (opts, cmd) => {
         await withClient(cmd, async (client, globals) => {
+            if (opts.workspace)
+                resolveWorkspace(opts.workspace);
             const studyId = resolveStudy(opts.study);
             let details;
             if (opts.detailsJson) {
@@ -283,16 +291,42 @@ Next: \`ish study run\` to dispatch simulations against this iteration.`)
     });
     iteration
         .command("get")
-        .description("Get iteration details")
-        .argument("<id>", "Iteration ID")
-        .addHelpText("after", "\nExamples:\n  $ ish iteration get <id>\n  $ ish iteration get <id> --json")
-        .action(async (id, _opts, cmd) => {
+        .description("Get iteration details (accepts multiple IDs for batched lookup)")
+        .argument("<ids...>", "Iteration ID(s) — one or more aliases/UUIDs (space- or comma-separated)")
+        .addHelpText("after", `
+Examples:
+  $ ish iteration get i-d4e
+  $ ish iteration get i-d4e --json
+  $ ish iteration get i-d4e i-f0a i-9c7
+  $ ish iteration get i-d4e,i-f0a --fields alias,label,name
+
+With multiple IDs, returns a {items:[...], total:N} envelope.`)
+        .action(async (ids, _opts, cmd) => {
         await withClient(cmd, async (client, globals) => {
-            const data = await client.get(`/iterations/${resolveId(id)}`);
-            const result = data;
-            if (result.id)
-                result.alias = tagAlias(ALIAS_PREFIX.iteration, String(result.id));
-            output(result, globals.json);
+            const flat = ids.flatMap((s) => s.split(",").map((x) => x.trim()).filter(Boolean));
+            if (flat.length === 0)
+                throw new Error("Provide at least one iteration id.");
+            if (flat.length === 1) {
+                const data = await client.get(`/iterations/${resolveId(flat[0])}`);
+                const result = data;
+                if (result.id)
+                    result.alias = tagAlias(ALIAS_PREFIX.iteration, String(result.id));
+                output(result, globals.json);
+                return;
+            }
+            const results = await Promise.all(flat.map(async (raw) => {
+                const data = await client.get(`/iterations/${resolveId(raw)}`);
+                const r = data;
+                if (r.id)
+                    r.alias = tagAlias(ALIAS_PREFIX.iteration, String(r.id));
+                return r;
+            }));
+            if (globals.json) {
+                output({ items: results, total: results.length }, true);
+            }
+            else {
+                formatIterationList(results, false);
+            }
         });
     });
     iteration

package/dist/commands/profile.js

@@ -40,15 +40,19 @@ Examples:
   $ ish profile list
   $ ish profile list --search "engineer" --country US
   $ ish profile list --gender female --gender male --country US --country GB
-  $ ish profile list --type all --json`)
+  $ ish profile list --type all --json
+
+  # Pagination — default --limit is 50; iterate with --offset:
+  $ ish profile list --limit 100
+  $ ish profile list --limit 100 --offset 100   # next page
+  # When more results exist, a stderr hint surfaces the next --offset / --limit.`)
         .action(async (opts, cmd) => {
         await withClient(cmd, async (client, globals) => {
             const params = {
                 limit: opts.limit,
                 offset: opts.offset,
+                product_id: resolveWorkspace(opts.workspace),
             };
-            if (opts.workspace)
-                params.product_id = resolveWorkspace(opts.workspace);
             if (opts.search)
                 params.search = opts.search;
             if (opts.type !== "all")
@@ -63,6 +67,29 @@ Examples:
                 params.max_age = opts.maxAge;
             const data = await client.get("/tester-profiles", params);
             formatTesterProfileList(data, globals.json, parseInt(opts.limit, 10));
+            // Pattern H1: when there's more data, surface a stderr hint so agents
+            // know `--limit / --offset` exist without re-reading help. Stderr only,
+            // so it doesn't pollute machine-readable stdout — that means we DON'T
+            // gate on globals.json (auto-flips on pipe and would silence the hint
+            // exactly when the agent needs it most). --quiet is the explicit
+            // opt-out for progress chatter.
+            //
+            // The raw `/tester-profiles` envelope is `{items, total, limit, offset}`
+            // — `has_more` and `returned` are synthesized client-side by `wrapList`
+            // only when the response is rendered. Compute them locally here so the
+            // hint actually fires; reading `data.has_more` directly would always
+            // see undefined and silently skip.
+            if (!globals.quietExplicit && typeof data === "object" && data !== null) {
+                const d = data;
+                const items = Array.isArray(d.items) ? d.items : [];
+                const returned = items.length;
+                const total = typeof d.total === "number" ? d.total : returned;
+                const offset = typeof d.offset === "number" ? d.offset : parseInt(opts.offset, 10) || 0;
+                const hasMore = total > offset + returned;
+                if (hasMore && returned > 0) {
+                    console.error(`\n  showing ${offset + 1}–${offset + returned} of ${total}; pass --offset ${offset + returned} --limit ${returned} for more.`);
+                }
+            }
         });
     });
     profile
@@ -74,8 +101,9 @@ Examples:
         .action(async (opts, cmd) => {
         await withClient(cmd, async (client, globals) => {
             const body = await readJsonFileOrStdin(opts.file);
-            if (opts.workspace)
+            if (opts.workspace || body.product_id == null) {
                 body.product_id = resolveWorkspace(opts.workspace);
+            }
             const data = await client.post("/tester-profiles", body);
             const result = data;
             if (result.id)
@@ -195,8 +223,18 @@ Examples:
                 }
                 body.count = n;
             }
+            // Pattern D1: emit stderr progress before the LLM call so agents (and
+            // humans) see something is happening during the ~10–20s wait. Mirrors
+            // the `--wait` ergonomics on `ask create` / `study run`.
+            if (!globals.quiet) {
+                const target = body.count ? `${body.count} profile${body.count === 1 ? "" : "s"}` : "profiles";
+                console.error(`  generating ${target}...`);
+            }
             // /generate is LLM-backed and slow.
             const profiles = await client.post("/tester-profiles/generate", body, { timeout: 180_000 });
+            if (!globals.quiet) {
+                console.error(`  generated ${profiles.length} profile${profiles.length === 1 ? "" : "s"}`);
+            }
             // simulation_config is the inlined system prompt + model settings — ~3.5KB
             // of mostly-identical boilerplate per profile. Strip it from the default
             // JSON output; users who need it can pass --include-simulation-config or
@@ -212,16 +250,43 @@ Examples:
     });
     profile
         .command("get")
-        .description("Get profile details")
-        .argument("<id>", "Profile ID")
-        .addHelpText("after", "\nExamples:\n  $ ish profile get <id>\n  $ ish profile get <id> --json")
-        .action(async (id, _opts, cmd) => {
+        .description("Get profile details (accepts multiple IDs for batched lookup)")
+        .argument("<ids...>", "Profile ID(s) — one or more aliases/UUIDs (space- or comma-separated)")
+        .addHelpText("after", `
+Examples:
+  $ ish profile get tp-1b9
+  $ ish profile get tp-1b9 --json
+  $ ish profile get tp-1b9 tp-fc1 tp-2fc
+  $ ish profile get tp-1b9,tp-fc1,tp-2fc --fields alias,name,country,occupation
+
+With multiple IDs, returns a {items:[...], total:N} envelope and uses the
+list table layout in human mode. Use --fields to project per-item.`)
+        .action(async (ids, _opts, cmd) => {
         await withClient(cmd, async (client, globals) => {
-            const data = await client.get(`/tester-profiles/${resolveId(id)}`);
-            const result = data;
-            if (result.id)
-                result.alias = tagAlias(ALIAS_PREFIX.testerProfile, String(result.id));
-            output(result, globals.json);
+            const flat = ids.flatMap((s) => s.split(",").map((x) => x.trim()).filter(Boolean));
+            if (flat.length === 0)
+                throw new Error("Provide at least one profile id.");
+            if (flat.length === 1) {
+                const data = await client.get(`/tester-profiles/${resolveId(flat[0])}`);
+                const result = data;
+                if (result.id)
+                    result.alias = tagAlias(ALIAS_PREFIX.testerProfile, String(result.id));
+                output(result, globals.json);
+                return;
+            }
+            const results = await Promise.all(flat.map(async (raw) => {
+                const data = await client.get(`/tester-profiles/${resolveId(raw)}`);
+                const r = data;
+                if (r.id)
+                    r.alias = tagAlias(ALIAS_PREFIX.testerProfile, String(r.id));
+                return r;
+            }));
+            if (globals.json) {
+                output({ items: results, total: results.length }, true);
+            }
+            else {
+                formatTesterProfileList(results, false);
+            }
         });
     });
     profile
@@ -287,6 +352,7 @@ flags override values from --file.`)
         .command("delete")
         .description("Delete a profile")
         .argument("<id>", "Profile ID")
+        .option("--workspace <id>", "Workspace ID; accepted for consistency (workspace is inferred from the profile)")
         .addHelpText("after", "\nExamples:\n  $ ish profile delete <id>")
         .action(async (id, _opts, cmd) => {
         await withClient(cmd, async (client, globals) => {

package/dist/commands/study-run.js

@@ -29,6 +29,43 @@ function parseSlowMo(value) {
 function isMediaModality(modality) {
     return !!modality && MEDIA_MODALITIES.includes(modality);
 }
+/**
+ * Pattern F (Issue #9): an iteration without content is a footgun.
+ * `ish study generate` auto-creates an empty iteration "A" that becomes
+ * `study run`'s default target unless `--iteration` is explicit; agents
+ * silently dispatch against it. This predicate is the gate that lets
+ * study run refuse with a clear suggestion instead of silent failure.
+ */
+function iterationHasContent(details, modality) {
+    if (!details || typeof details !== "object")
+        return false;
+    if (modality === "text") {
+        return typeof details.content_text === "string" && details.content_text.length > 0;
+    }
+    if (modality === "video" || modality === "audio" || modality === "document") {
+        return typeof details.content_url === "string" && details.content_url.length > 0;
+    }
+    if (modality === "image") {
+        const urls = details.image_urls;
+        if (Array.isArray(urls))
+            return urls.length > 0;
+        if (typeof urls === "string")
+            return urls.length > 0;
+        return false;
+    }
+    // interactive (default)
+    return typeof details.url === "string" && details.url.length > 0;
+}
+function describeRequiredContentFlag(modality) {
+    if (modality === "text")
+        return "--content-text <text-or-@file>";
+    if (modality === "video" || modality === "audio" || modality === "document") {
+        return "--content-url <url-or-file>";
+    }
+    if (modality === "image")
+        return "--image-urls <comma-separated>";
+    return "--url <url>";
+}
 const POLL_INTERVAL_MS = 5_000;
 const TERMINAL_STATUSES = new Set(["completed", "errored", "failed", "cancelled", "canceled"]);
 function flattenTesterStatuses(iterations, only) {
@@ -187,6 +224,18 @@ Examples:
             }
             const iterationId = iteration.id;
             const iterationLabel = iteration.label || iteration.name || iterationId.slice(0, 8);
+            // Pattern F (Issue #9): refuse on empty iteration. `study generate`
+            // auto-creates an empty iteration A; agents who don't pass
+            // --iteration silently dispatch against it. Detect and refuse with
+            // a clear suggestion rather than masking the problem.
+            if (!iterationHasContent(iteration.details, modality)) {
+                const flagHint = describeRequiredContentFlag(modality);
+                const iterAlias = tagAlias(ALIAS_PREFIX.iteration, iterationId);
+                throw new Error(`Iteration "${iterationLabel}" (${iterAlias}) has no ${isMedia ? "content" : "URL"} configured yet. ` +
+                    `Add ${isMedia ? "content" : "a URL"} with ` +
+                    `\`ish iteration create --study ${resolvedStudy} ${flagHint}\` ` +
+                    `(or update the existing iteration via \`ish iteration update ${iterAlias} --details-json '{...}'\`), then retry.`);
+            }
             const detailsView = readIterationDetails(iteration.details);
             // Step 2: Resolve audience.
             // - If any audience flag is set (--profile / --sample / --all / filter flags),