@ishlabs/cli 0.14.1 → 0.16.0

package/README.md

@@ -308,6 +308,16 @@ ish ask run --new --name "newsletter" \
 
 **Audience flags** (`--profile`, `--sample`, `--all-simulatable`, `--country`, `--gender`, `--min-age`, `--max-age`, `--search`, `--visibility`, `--name`, `--description`, `--workspace`) only apply with `--new` — the audience is fixed at ask creation.
 
+**`--visibility` values** (same set everywhere it's accepted):
+
+| Value | Selects |
+|---|---|
+| `workspace` | Profiles owned by your workspace (default scope). |
+| `shared` | Community-published profiles visible across workspaces. |
+| `platform` | Admin-curated profiles from the platform pool. |
+
+Old values `private` (now `workspace`) and `public` (now `platform`) keep working until the next release; the server logs a deprecation warning and maps them to the new vocabulary.
+
 **Other ask verbs:**
 
 ```bash

package/dist/commands/profile.js

@@ -7,7 +7,7 @@ import { resolveId, tagAlias, ALIAS_PREFIX } from "../lib/alias-store.js";
 import { formatTesterProfileList, formatGeneratedProfileList, output, } from "../lib/output.js";
 import { resolveTextContent } from "../lib/upload.js";
 import { isUuid, resolveSourceRef } from "../lib/profile-sources.js";
-import { assertEnumValue, EDUCATION_LEVELS, HOUSEHOLDS, LOCALE_TYPES, INCOME_LEVELS, EMPLOYMENT_STATUSES, } from "../lib/enums.js";
+import { assertEnumValue, EDUCATION_LEVELS, EVIDENCE_SOURCES, HOUSEHOLDS, LOCALE_TYPES, INCOME_LEVELS, EMPLOYMENT_STATUSES, } from "../lib/enums.js";
 import { validateAccessibilityProfile } from "../lib/accessibility-profile.js";
 function collect(value, prev) {
     return prev.concat(value);
@@ -393,6 +393,242 @@ Schema: https://ishlabs.io/spec/accessibility-profile-schema.v1.json`)
             output({ id: rid, alias: tagAlias(ALIAS_PREFIX.testerProfile, rid), message: "Profile deleted" }, globals.json, { writePath: true });
         });
     });
+    profile
+        .command("suggest-scenarios")
+        .description("Ask the LLM for scenario probes to craft a specific simulated tester")
+        .option("--workspace <id>", "Workspace (product) ID; falls back to active workspace")
+        .option("--context <text>", "What you already know about this tester. Use @path to read from file.")
+        .option("--context-file <path>", "Read --context from a file")
+        .option("--count <n>", "Number of scenarios to return (1-10, default 5)")
+        .option("--previous-answers <json-or-@path>", "Answers already collected this session. Inline JSON, @/path/to.json, or - for stdin. Array of {type, prompt, answer}; max 40.")
+        .option("--already-surfaced <json-or-@path>", "Prompt labels already shown this session, so the LLM avoids paraphrasing them. Inline JSON, @/path, or -. Array of strings; max 40.")
+        .addHelpText("after", `
+Examples:
+  # Bare invocation: 5 scenarios from a free-form context blob
+  $ ish profile suggest-scenarios --context "Mid-career engineer who handles oncall for a Stripe-using fintech"
+
+  # Load context from a file, ask for 3 scenarios
+  $ ish profile suggest-scenarios --context-file ./persona-notes.md --count 3
+
+  # Follow-up probe: skip prompts already shown, build on prior answers
+  $ ish profile suggest-scenarios \\
+      --context "$(cat notes.md)" \\
+      --count 3 \\
+      --already-surfaced '["How do you triage 02:00 pages?"]' \\
+      --previous-answers @./answers.json
+
+  # Capture just the first scenario's type
+  $ ish profile suggest-scenarios --context "..." --count 1 --get scenarios[0].type
+
+The loop: suggest → answer locally → persist via \`ish profile evidence add <id>\` (read back with \`evidence list\`).
+See \`ish docs get-page guides/build-specific-tester\` for the full workflow.`)
+        .action(async (opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const productId = resolveWorkspace(opts.workspace);
+            let context;
+            if (opts.context)
+                context = resolveTextContent(opts.context);
+            if (opts.contextFile)
+                context = resolveTextContent(`@${opts.contextFile}`);
+            if (!context) {
+                throw new Error("Provide --context (text or @path) or --context-file.");
+            }
+            const trimmed = context.trim();
+            if (trimmed.length === 0) {
+                throw new Error("--context cannot be empty.");
+            }
+            if (trimmed.length > 20_000) {
+                throw new Error(`--context is ${trimmed.length} chars; backend max is 20000. Trim before retrying.`);
+            }
+            const body = {
+                product_id: productId,
+                context: trimmed,
+            };
+            if (opts.count !== undefined) {
+                const n = parseInt(opts.count, 10);
+                if (Number.isNaN(n) || n < 1 || n > 10) {
+                    throw new Error("--count must be an integer between 1 and 10.");
+                }
+                body.count = n;
+            }
+            if (opts.previousAnswers) {
+                const parsed = await parseJsonFlag(opts.previousAnswers, "--previous-answers");
+                if (!Array.isArray(parsed)) {
+                    throw new Error("--previous-answers must be a JSON array of {type, prompt, answer}.");
+                }
+                if (parsed.length > 40) {
+                    throw new Error(`--previous-answers max 40 entries (got ${parsed.length}).`);
+                }
+                for (let i = 0; i < parsed.length; i++) {
+                    const row = parsed[i];
+                    if (!row || typeof row !== "object") {
+                        throw new Error(`--previous-answers[${i}]: expected object {type, prompt, answer}.`);
+                    }
+                    if (typeof row.type !== "string" || typeof row.prompt !== "string" || typeof row.answer !== "string") {
+                        throw new Error(`--previous-answers[${i}]: missing or non-string {type, prompt, answer}.`);
+                    }
+                    assertEnumValue(row.type, EVIDENCE_SOURCES, `--previous-answers[${i}].type`);
+                }
+                body.previous_answers = parsed;
+            }
+            if (opts.alreadySurfaced) {
+                const parsed = await parseJsonFlag(opts.alreadySurfaced, "--already-surfaced");
+                if (!Array.isArray(parsed) || parsed.some((s) => typeof s !== "string")) {
+                    throw new Error("--already-surfaced must be a JSON array of strings.");
+                }
+                if (parsed.length > 40) {
+                    throw new Error(`--already-surfaced max 40 entries (got ${parsed.length}).`);
+                }
+                body.already_surfaced_prompts = parsed;
+            }
+            if (!globals.quiet) {
+                const target = body.count ?? 5;
+                console.error(`  suggesting ${target} scenario${target === 1 ? "" : "s"}...`);
+            }
+            const data = await client.post("/tester-profiles/suggest-scenarios", body, { timeout: 180_000 });
+            output(data, globals.json);
+        });
+    });
+    const evidence = profile
+        .command("evidence")
+        .description("Manage scenario-answer evidence on a tester profile")
+        .addHelpText("after", `
+Evidence rows persist answers to \`suggest-scenarios\` probes onto a
+specific profile. The \`source\` field on every trace is the same enum
+as the \`type\` field on a suggested scenario — copy verbatim when
+building a traces.json.
+
+Guide: ish docs get-page guides/build-specific-tester`);
+    evidence
+        .command("add")
+        .description("Persist scenario answers as structured evidence on a profile")
+        .argument("<id>", "Profile ID (alias or UUID)")
+        .option("--traces <json-or-@path>", `Array of {text, source, scenario_prompt?, raw_response?} where source ∈ ${EVIDENCE_SOURCES.join("|")}. Inline JSON, @/path/to.json, or - for stdin.`)
+        .option("--traces-file <path>", "Read --traces from a JSON file")
+        .addHelpText("after", `
+Examples:
+  # Inline JSON for a single trace
+  $ ish profile evidence add tp-d4e --traces '[{"text":"I would page my staff engineer first.","source":"situation","scenario_prompt":"PagerDuty fires at 02:00."}]'
+
+  # From a file
+  $ ish profile evidence add tp-d4e --traces-file ./answers.json
+
+  # From stdin (pipe-friendly)
+  $ jq -c '.traces' session.json | ish profile evidence add tp-d4e --traces -
+
+  # Project the response
+  $ ish profile evidence add tp-d4e --traces-file ./answers.json --fields id,source,created_at
+
+Valid source values: ${EVIDENCE_SOURCES.join(", ")}.
+\`source\` on a trace = \`type\` on a suggested scenario — same enum.
+Pair with \`ish profile suggest-scenarios\` to drive the iterative probe → answer loop.
+Verify with \`ish profile evidence list <id>\`.`)
+        .action(async (id, opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            if (opts.traces && opts.tracesFile) {
+                throw new Error("Pass either --traces or --traces-file, not both.");
+            }
+            if (!opts.traces && !opts.tracesFile) {
+                throw new Error("Provide --traces (JSON, @path, or -) or --traces-file <path>.");
+            }
+            const parsed = opts.tracesFile
+                ? await readJsonFileOrStdin(opts.tracesFile)
+                : await parseJsonFlag(opts.traces, "--traces");
+            if (!Array.isArray(parsed) || parsed.length === 0) {
+                throw new Error("traces must be a non-empty JSON array.");
+            }
+            const traces = [];
+            for (let i = 0; i < parsed.length; i++) {
+                const row = parsed[i];
+                if (!row || typeof row !== "object") {
+                    throw new Error(`traces[${i}]: expected object {text, source, ...}.`);
+                }
+                if (typeof row.text !== "string" || row.text.length === 0) {
+                    throw new Error(`traces[${i}].text: required non-empty string.`);
+                }
+                if (typeof row.source !== "string") {
+                    throw new Error(`traces[${i}].source: required string.`);
+                }
+                assertEnumValue(row.source, EVIDENCE_SOURCES, `traces[${i}].source`);
+                if (row.scenario_prompt !== undefined && typeof row.scenario_prompt !== "string") {
+                    throw new Error(`traces[${i}].scenario_prompt: must be a string if provided.`);
+                }
+                traces.push({
+                    text: row.text,
+                    source: row.source,
+                    scenario_prompt: row.scenario_prompt ?? "",
+                    ...(row.raw_response !== undefined ? { raw_response: row.raw_response } : {}),
+                });
+            }
+            const rid = resolveId(id);
+            const body = { traces };
+            if (!globals.quiet) {
+                console.error(`  persisting ${traces.length} evidence trace${traces.length === 1 ? "" : "s"} on ${tagAlias(ALIAS_PREFIX.testerProfile, rid)}...`);
+            }
+            const data = await client.post(`/tester-profiles/${rid}/scenarios`, body);
+            if (globals.json) {
+                output({ items: data, total: data.length }, true);
+            }
+            else {
+                output(data, false);
+            }
+        });
+    });
+    evidence
+        .command("list")
+        .description("List evidence traces persisted on a tester profile (newest first)")
+        .argument("<id>", "Profile ID (alias or UUID)")
+        .addHelpText("after", `
+Examples:
+  # Read back every trace on a profile
+  $ ish profile evidence list tp-d4e
+
+  # Project per-row fields
+  $ ish profile evidence list tp-d4e --fields id,source,scenario_prompt
+
+  # Capture just the sources, one per line (auto-descends into items)
+  $ ish profile evidence list tp-d4e --get source
+
+Returns a {items, total} envelope. Use the same id you passed to \`evidence add\`.`)
+        .action(async (id, _opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const rid = resolveId(id);
+            const data = await client.get(`/tester-profiles/${rid}/scenarios`);
+            if (globals.json) {
+                output({ items: data, total: data.length }, true);
+            }
+            else {
+                output(data, false);
+            }
+        });
+    });
+}
+/**
+ * Parse a flag that accepts inline JSON, an @path reference, or `-` for stdin.
+ * Mirrors the @path convention on --description (resolveTextContent) and the
+ * stdin convention on --file. Used by --traces, --previous-answers, etc.
+ */
+async function parseJsonFlag(value, flagName) {
+    if (value === "-") {
+        return readJsonFileOrStdin();
+    }
+    if (value.startsWith("@")) {
+        const path = value.slice(1);
+        if (!path) {
+            throw new Error(`Missing file path after @ in ${flagName}. Usage: ${flagName} @/path/to/file.json`);
+        }
+        return readJsonFileOrStdin(path);
+    }
+    const trimmed = value.trim();
+    if (trimmed.startsWith("{") || trimmed.startsWith("[")) {
+        try {
+            return JSON.parse(trimmed);
+        }
+        catch (e) {
+            throw new Error(`Invalid JSON in ${flagName}: ${e.message}`);
+        }
+    }
+    throw new Error(`${flagName} expects inline JSON (starting with { or [), an @path reference (@/path/to/file.json), or '-' for stdin.`);
 }
 /**
  * If the value matches the testerProfileSource alias pattern (e.g. "tps-3a4"),

package/dist/commands/study-run.js

@@ -8,9 +8,10 @@
  * 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 { withClient, getWebUrl, terminalLink, resolveWorkspace, resolveStudy, parseWaitTimeout, resolveAudienceProfileIds, addAudienceFilterFlags, hasAudienceFlags, readFileOrStdin, } from "../lib/command-helpers.js";
 import { resolveId, tagAlias, ALIAS_PREFIX } from "../lib/alias-store.js";
 import { output, formatSimulationPoll } from "../lib/output.js";
+import { streamStudyEvents } from "../lib/study-events.js";
 import { isMediaModality, isChatModality, iterationHasContent, describeRequiredContentFlag, readChatMode, readTesterPairConfig, summarizeRoleCriteria, } from "../lib/modality.js";
 import { runLocalSimulations } from "../lib/local-sim/loop.js";
 import { ensureBrowser } from "../lib/local-sim/install.js";
@@ -93,6 +94,11 @@ function dedupeSimulations(simResults) {
     ];
 }
 const POLL_INTERVAL_MS = 5_000;
+// When the backend SSE stream is connected we drop to a slow backstop —
+// events wake us up promptly, so re-fetching every 5s is wasteful. If the
+// stream dies (older backend, broker offline, token mint failure) the loop
+// transparently reverts to POLL_INTERVAL_MS.
+const SSE_BACKSTOP_INTERVAL_MS = 30_000;
 const TERMINAL_STATUSES = new Set(["completed", "errored", "failed", "cancelled", "canceled"]);
 function flattenTesterStatuses(iterations, only) {
     const rows = [];
@@ -118,38 +124,90 @@ function flattenTesterStatuses(iterations, only) {
 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 WaitTimeoutError(`Timed out after ${Math.round(opts.timeoutMs / 1000)}s waiting for simulations. ` +
-                `${done}/${total} done. Run \`ish study poll --study ${opts.studyId}\` to check status.`, {
-                study_id: opts.studyId,
-                ...(opts.iterationId && { iteration_id: opts.iterationId }),
-                timeout_seconds: Math.round(opts.timeoutMs / 1000),
-                done,
-                total,
-                pending: total - done,
-                rows,
-            });
+    // Open the SSE event stream as a wake source. When the backend supports
+    // it (enable_realtime=true + broker live), tester status changes wake
+    // the loop the moment they happen — no need to wait for the next poll
+    // tick. When it doesn't, the iterator exits silently on the first read
+    // and we fall through to pure polling at POLL_INTERVAL_MS.
+    const ac = new AbortController();
+    const eventIter = streamStudyEvents(client, opts.studyId, ac.signal);
+    // Optimistic: we assume the stream will deliver until the first read
+    // confirms otherwise. The first `await pendingEvent` settles within
+    // milliseconds for an unavailable stream (token mint 503 / endpoint 503)
+    // and is essentially a no-op for the latency budget.
+    let sseAlive = true;
+    let pendingEvent = eventIter.next();
+    try {
+        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 WaitTimeoutError(`Timed out after ${Math.round(opts.timeoutMs / 1000)}s waiting for simulations. ` +
+                    `${done}/${total} done. Run \`ish study poll --study ${opts.studyId}\` to check status.`, {
+                    study_id: opts.studyId,
+                    ...(opts.iterationId && { iteration_id: opts.iterationId }),
+                    timeout_seconds: Math.round(opts.timeoutMs / 1000),
+                    done,
+                    total,
+                    pending: total - done,
+                    rows,
+                });
+            }
+            // Wait for either the next backend event or the next tick. Use the
+            // backstop interval while the stream is delivering (events are the
+            // primary wake source); fall back to POLL_INTERVAL_MS once the
+            // stream is dead (older backend or broker dropped mid-run).
+            const interval = sseAlive ? SSE_BACKSTOP_INTERVAL_MS : POLL_INTERVAL_MS;
+            if (sseAlive && pendingEvent !== null) {
+                let timerHandle;
+                const timer = new Promise((resolve) => {
+                    timerHandle = setTimeout(() => resolve({ kind: "timer" }), interval);
+                });
+                const eventOrEnd = pendingEvent.then((r) => ({ kind: "event", result: r }), () => ({ kind: "event", result: { value: undefined, done: true } }));
+                const winner = await Promise.race([eventOrEnd, timer]);
+                if (timerHandle !== undefined)
+                    clearTimeout(timerHandle);
+                if (winner.kind === "event") {
+                    if (winner.result.done) {
+                        // Stream ended; revert to pure polling for the rest of the run.
+                        sseAlive = false;
+                        pendingEvent = null;
+                    }
+                    else {
+                        // Re-arm for the next event. We deliberately don't act on
+                        // the event payload here — the next loop iteration re-fetches
+                        // status and that's the truth source.
+                        pendingEvent = eventIter.next();
+                    }
+                }
+                // Timer winning doesn't replace pendingEvent — it stays parked
+                // and resolves on whichever event arrives next.
+            }
+            else {
+                await new Promise((resolve) => setTimeout(resolve, interval));
+            }
         }
-        await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
+    }
+    finally {
+        // Stop the SSE fetch + reader so we don't leave a dangling HTTP
+        // connection to the backend after returning / throwing.
+        ac.abort();
     }
 }
 function readIterationDetails(details) {
@@ -1065,4 +1123,183 @@ Examples:
             output(data, globals.json);
         });
     });
+    // --- Extend ---
+    //
+    // Resume a terminal tester with `additional_steps` more turns — the
+    // "start" half of the cancel + extend pair. The backend spawns a NEW
+    // tester under the same iteration, branched from the source's last
+    // interaction; the source row is left untouched. When --instruction is
+    // set, the new tester treats it as overriding direction (the backend
+    // surfaces it in a dedicated <user_added_instructions> block on every
+    // prompt — see app-simulation Fix 1).
+    study
+        .command("extend")
+        .description("Extend a terminal tester with more steps (and optionally a mid-run instruction)")
+        .argument("<tester_id>", "Tester to extend (alias or UUID). Must be in a terminal state (completed/failed/cancelled).")
+        .option("--add-steps <n>", "Extra interactions past the source's original cap (1-50; backend caps server-side)", "10")
+        .option("--instruction <text>", "User message to inject as the new tester resumes. Accepts inline text, `@/path/to/file`, or `-` for stdin.")
+        .option("--wait", "Block until the new tester reaches a terminal state")
+        .option("--timeout <s>", "Wait timeout in seconds (default 300; only with --wait)")
+        .option("--dispatch-timeout <s>", "Per-POST timeout in seconds for the dispatch call (default 120)")
+        .option("--workspace <id>", "Workspace ID; accepted for consistency (workspace is inferred from <tester_id>)")
+        .addHelpText("after", `
+The source tester is left untouched; a new tester is spawned under the
+same iteration and branched from the source's last interaction. Get the
+new tester ID from \`.tester_id\` / \`.tester_alias\` on the JSON output.
+
+Examples:
+  # Add 5 more steps to a completed run (no new instruction):
+  $ ish study extend t-072 --add-steps 5
+
+  # Inject a mid-run instruction and wait for completion:
+  $ ish study extend t-072 \\
+      --instruction "Open the language selector and switch to German." \\
+      --wait
+
+  # Long instruction from a file:
+  $ ish study extend t-072 --instruction @/tmp/prompt.txt --wait --timeout 600
+
+  # Instruction from stdin (pipe-friendly):
+  $ echo "Try the search bar instead." | ish study extend t-072 --instruction -
+
+Get tester IDs from \`ish study run --json\` (.tester_aliases[] / .tester_ids[]).
+See \`ish docs get-page concepts/extending-a-simulation\` for the full mental model.`)
+        .action(async (testerId, opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            // --add-steps: client-side parser fails fast before the network
+            // call. Bound mirrors the backend's `le=50` cap; if the backend
+            // moves the bound, this message will lag — the backend remains
+            // authoritative and any 422 is surfaced verbatim.
+            const addStepsRaw = opts.addSteps ?? "10";
+            const addSteps = parseInt(addStepsRaw, 10);
+            if (Number.isNaN(addSteps) || addSteps < 1 || addSteps > 50) {
+                throw new Error(`--add-steps must be an integer between 1 and 50, got "${addStepsRaw}".`);
+            }
+            // --instruction: inline text | `@path` | `-` (stdin).
+            let instruction;
+            if (opts.instruction !== undefined) {
+                let raw;
+                if (opts.instruction === "-") {
+                    raw = await readFileOrStdin("-");
+                }
+                else if (opts.instruction.startsWith("@")) {
+                    raw = await readFileOrStdin(opts.instruction.slice(1));
+                }
+                else {
+                    raw = opts.instruction;
+                }
+                const trimmed = raw.trim();
+                if (trimmed.length === 0) {
+                    throw new Error("--instruction must be non-empty (after trimming).");
+                }
+                instruction = trimmed;
+            }
+            const dispatchTimeoutMs = opts.dispatchTimeout
+                ? Math.max(1, parseInt(opts.dispatchTimeout, 10)) * 1000
+                : 120_000;
+            if (opts.dispatchTimeout &&
+                (Number.isNaN(parseInt(opts.dispatchTimeout, 10)) ||
+                    parseInt(opts.dispatchTimeout, 10) < 1)) {
+                throw new Error(`--dispatch-timeout must be a positive integer (seconds), got "${opts.dispatchTimeout}".`);
+            }
+            const sourceId = resolveId(testerId);
+            const sourceAlias = tagAlias(ALIAS_PREFIX.tester, sourceId);
+            if (!globals.quiet) {
+                const stepNote = `${addSteps} step${addSteps === 1 ? "" : "s"}`;
+                const instrNote = instruction ? " and a new instruction" : "";
+                console.error(`Extending ${sourceAlias} with ${stepNote}${instrNote}...`);
+            }
+            const body = {
+                source_tester_id: sourceId,
+                additional_steps: addSteps,
+            };
+            if (instruction)
+                body.user_message = instruction;
+            const data = await client.post("/simulation/interactive/extend", body, { timeout: dispatchTimeoutMs });
+            const newTesterId = String(data.tester_id);
+            const newAlias = tagAlias(ALIAS_PREFIX.tester, newTesterId);
+            // UUIDs preserved on the output — `study extend` is a write-path
+            // dispatch command and the new `tester_id` is the load-bearing
+            // return value (mirrors how `study run` keeps tester_ids in lean
+            // output via the writePath option).
+            const baseEnvelope = {
+                tester_id: newTesterId,
+                tester_alias: newAlias,
+                source_tester_id: sourceId,
+                source_alias: sourceAlias,
+                study_id: data.study_id,
+                job_id: data.job_id,
+                additional_steps: addSteps,
+                ...(instruction && { instruction }),
+                message: data.message,
+            };
+            if (!opts.wait) {
+                if (globals.json) {
+                    output(baseEnvelope, true, { writePath: true });
+                }
+                else {
+                    console.error(`  New tester: ${newAlias}`);
+                    if (data.message)
+                        console.error(`  ${data.message}`);
+                    console.error(`  Run \`ish study wait ${newAlias} --timeout 600\` to block until it finishes.`);
+                }
+                return;
+            }
+            // --wait: poll the new tester until it reaches a terminal state.
+            // Mirrors the per-tester wait block in `study wait <tester_id>`
+            // above — same WaitTimeoutError shape (exit 5, retryable) so the
+            // failure envelope is consistent across commands.
+            const timeoutMs = parseWaitTimeout(opts.timeout);
+            if (!globals.quiet) {
+                console.error(`Waiting for ${newAlias} to finish...`);
+            }
+            const start = Date.now();
+            let lastStatus = "";
+            while (true) {
+                const status = await client.get(`/simulation/status/${newTesterId}`, undefined, { timeout: 60_000 });
+                const s = String(status.status ?? "unknown");
+                if (!globals.quiet && s !== lastStatus) {
+                    process.stderr.write(`  ${s}\n`);
+                    lastStatus = s;
+                }
+                if (TERMINAL_STATUSES.has(s)) {
+                    const result = {
+                        status: s,
+                        ...(typeof status.interaction_count === "number" && {
+                            interaction_count: status.interaction_count,
+                        }),
+                        ...(status.tester_name && { tester_name: status.tester_name }),
+                        ...(status.error && { error: status.error }),
+                    };
+                    if (globals.json) {
+                        output({ ...baseEnvelope, result }, true, { writePath: true });
+                    }
+                    else {
+                        console.error(`  ${newAlias} finished: ${s}`);
+                        if (status.error)
+                            console.error(`  error: ${status.error}`);
+                    }
+                    return;
+                }
+                if (Date.now() - start > timeoutMs) {
+                    throw new WaitTimeoutError(`Timed out after ${Math.round(timeoutMs / 1000)}s waiting for tester ${newAlias}. Last status: ${s}.`, {
+                        study_id: newTesterId,
+                        timeout_seconds: Math.round(timeoutMs / 1000),
+                        done: 0,
+                        total: 1,
+                        pending: 1,
+                        rows: [
+                            {
+                                id: newTesterId,
+                                status: s,
+                                tester_name: String(status.tester_name ?? "Unknown"),
+                                interaction_count: typeof status.interaction_count === "number" ? status.interaction_count : 0,
+                            },
+                        ],
+                    });
+                }
+                await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
+            }
+        });
+    });
 }

package/dist/commands/workspace.js

@@ -214,11 +214,12 @@ async function collectWorkspaceUsage(client, workspaceId) {
         .get(`/products/${workspaceId}/studies`)
         .catch(() => []);
     // testers_used: paginated list returns { total, items, ... }. Backend
-    // gates `maxCustomTesterProfiles` on visibility=private.
+    // gates `maxCustomTesterProfiles` on visibility=workspace (rows owned by
+    // this workspace; was `private` before the visibility rename).
     const testersPromise = client
         .get("/tester-profiles", {
         product_id: workspaceId,
-        visibility: "private",
+        visibility: "workspace",
         type: "ai",
         limit: "1",
         offset: "0",

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

@@ -20,6 +20,13 @@ export declare class ApiClient {
         token: string;
     });
     get accessToken(): string;
+    /** Resolved base URL including the ``/api/v1`` prefix.
+     *
+     * Exposed so helpers that bypass the JSON-decoding ``fetch`` wrappers
+     * (e.g. the SSE stream in ``lib/study-events.ts``) can build their own
+     * requests against the same backend.
+     */
+    get apiBase(): string;
     private headers;
     get<T = unknown>(path: string, params?: Record<string, string | string[]>, opts?: RequestOpts): Promise<T>;
     post<T = unknown>(path: string, body?: unknown, opts?: RequestOpts): Promise<T>;

package/dist/lib/api-client.js

@@ -83,6 +83,15 @@ export class ApiClient {
     get accessToken() {
         return this.token;
     }
+    /** Resolved base URL including the ``/api/v1`` prefix.
+     *
+     * Exposed so helpers that bypass the JSON-decoding ``fetch`` wrappers
+     * (e.g. the SSE stream in ``lib/study-events.ts``) can build their own
+     * requests against the same backend.
+     */
+    get apiBase() {
+        return this.baseUrl;
+    }
     headers() {
         return {
             Authorization: `Bearer ${this.token}`,

package/dist/lib/command-helpers.js

@@ -245,7 +245,7 @@ export function addAudienceFilterFlags(cmd, opts = {}) {
         .option("--country <code>", "Filter by 2-letter country code (repeatable)", collectRepeatable, [])
         .option("--min-age <n>", "Minimum age (inclusive)")
         .option("--max-age <n>", "Maximum age (inclusive)")
-        .option("--visibility <v>", "Filter by visibility (private|public)");
+        .option("--visibility <v>", "Filter by visibility: workspace (your workspace), shared (community-published), platform (admin-curated). Old values `private` / `public` still accepted as aliases for `workspace` / `platform` until the next release; server logs a deprecation warning.");
 }
 export function getGlobals(cmd) {
     let globals;