@ishlabs/cli 0.17.7 → 0.18.0

package/dist/commands/study-run.js

@@ -1,18 +1,19 @@
 /**
  * ish study run — Run, monitor, and cancel simulations of a study.
  *
- * `ish study run` creates testers for the latest (or specified) iteration
+ * `ish study run` creates participants 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 { Option } from "commander";
 import * as readline from "node:readline/promises";
-import { withClient, getWebUrl, terminalLink, resolveWorkspace, resolveStudy, parseWaitTimeout, resolveAudienceProfileIds, addAudienceFilterFlags, hasAudienceFlags, readFileOrStdin, } from "../lib/command-helpers.js";
+import { withClient, getWebUrl, terminalLink, resolveWorkspace, resolveStudy, parseWaitTimeout, resolvePersonIds, addPersonFilterFlags, hasPersonFlags, 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 { isMediaModality, isChatModality, iterationHasContent, describeRequiredContentFlag, readChatMode, readParticipantPairConfig, summarizeRoleCriteria, } from "../lib/modality.js";
 // NOTE: local-sim modules are loaded via dynamic import at the `--local`
 // branch below, NOT statically here. `local-sim/install.ts` deep-imports
 // `playwright-core/lib/server/registry/index`, which is not exposed by
@@ -33,7 +34,7 @@ function parseMaxInteractions(value) {
  * iteration carries its own value. Picked to match the frontend's
  * conservative interactive launchers and to prevent runaway spend when an
  * iteration runs against a broken or non-responsive surface — without a
- * cap, a stuck tester can rack up hundreds of steps before the SDK gives
+ * cap, a stuck participant can rack up hundreds of steps before the SDK gives
  * up.
  */
 const DEFAULT_MAX_INTERACTIONS = 20;
@@ -56,7 +57,7 @@ function parseSlowMo(value) {
  * produce a structured envelope (`error_code: "wait_timeout"`, exit 5
  * transient) distinct from the generic timeout/network/server errors
  * that the api-client wrapper produces. Carries the in-flight progress
- * (testers done / total) so `study wait` always emits final state JSON
+ * (participants done / total) so `study wait` always emits final state JSON
  * even when it bails on the timer.
  */
 export class WaitTimeoutError extends Error {
@@ -71,9 +72,9 @@ export class WaitTimeoutError extends Error {
 }
 /**
  * M13 / Pattern J: collapse the N near-duplicate `simulations[]` rows the
- * batch start endpoint returns (one per tester, all sharing study_id) into a
- * single batch entry with `tester_ids[]` + `tester_aliases[]` + `job_ids[]`.
- * Agents always need the per-tester ids, but the surrounding scaffolding
+ * batch start endpoint returns (one per participant, all sharing study_id) into a
+ * single batch entry with `participant_ids[]` + `participant_aliases[]` + `job_ids[]`.
+ * Agents always need the per-participant ids, but the surrounding scaffolding
  * (study_id, message) is shared so repeating it N times costs context for no
  * extra signal. Falls back to the raw rows if the response shape is unfamiliar.
  */
@@ -91,8 +92,8 @@ function dedupeSimulations(simResults) {
     return [
         {
             study_id: studyId,
-            tester_ids: simResults.map((r) => r.tester_id),
-            tester_aliases: simResults.map((r) => tagAlias(ALIAS_PREFIX.tester, String(r.tester_id))),
+            participant_ids: simResults.map((r) => r.participant_id),
+            participant_aliases: simResults.map((r) => tagAlias(ALIAS_PREFIX.participant, String(r.participant_id))),
             job_ids: simResults.map((r) => r.job_id ?? null),
             count: simResults.length,
             message: simResults[0].message,
@@ -106,20 +107,20 @@ const POLL_INTERVAL_MS = 5_000;
 // 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) {
+function flattenParticipantStatuses(iterations, only) {
     const rows = [];
     for (const iteration of iterations ?? []) {
-        for (const t of iteration.testers ?? []) {
+        for (const t of iteration.participants ?? []) {
             if (only && !only.has(t.id))
                 continue;
-            // Pattern A (cli half): backend now reports per-tester crash detail at
+            // Pattern A (cli half): backend now reports per-participant crash detail at
             // `error_message`. Keep `error` / `failure_reason` as legacy fallbacks
             // until every backend deploy is on the new contract.
             const errorMessage = t.error_message || t.error || t.failure_reason || null;
             rows.push({
                 id: t.id,
                 status: t.status,
-                tester_name: t.tester_profile?.name || "Unknown",
+                participant_name: t.person?.name || "Unknown",
                 interaction_count: Array.isArray(t.interactions) ? t.interactions.length : 0,
                 ...(errorMessage && { error_message: errorMessage }),
             });
@@ -131,7 +132,7 @@ async function pollStudyUntilDone(client, opts) {
     const start = Date.now();
     let lastReported = "";
     // Open the SSE event stream as a wake source. When the backend supports
-    // it (enable_realtime=true + broker live), tester status changes wake
+    // it (enable_realtime=true + broker live), participant 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.
@@ -151,7 +152,7 @@ async function pollStudyUntilDone(client, opts) {
             if (opts.iterationId) {
                 iterations = (iterations ?? []).filter((it) => it.id === opts.iterationId);
             }
-            const rows = flattenTesterStatuses(iterations, opts.testerIds);
+            const rows = flattenParticipantStatuses(iterations, opts.participantIds);
             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;
@@ -234,22 +235,24 @@ 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)")
+        .description("Run a study (creates participants 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, {
+    addPersonFilterFlags(studyRun, {
         allFlagName: "--all",
-        allFlagDescription: "Use every AI profile matching the filters (workspace-wide if no filters set)",
+        allFlagDescription: "Use every AI person 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 (interactive / media only). Precedence: flag > iteration's stored value > CLI default (${DEFAULT_MAX_INTERACTIONS}).`)
-        .option("--max-turns <n>", "Max conversation turns per tester (chat studies only)")
+        .option("--config <id>", "Simulation config ID (required for media unless every person has one)")
+        .addOption(new Option("--sim-config <json|@file>", "Dev: per-run config overrides (ConfigOverrides JSON, or @path to a file). Layers on top of --config. "
+        + "e.g. --sim-config '{\"model_settings\":{\"agent\":{\"model\":\"gemini-3.5-flash\"}}}'").hideHelp())
+        .option("--max-interactions <n>", `Max interactions per participant (interactive / media only). Precedence: flag > iteration's stored value > CLI default (${DEFAULT_MAX_INTERACTIONS}).`)
+        .option("--max-turns <n>", "Max conversation turns per participant (chat studies only)")
         .option("--early-termination", "Allow chat agent to end the conversation early when goals are met (chat studies only)")
         .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("--dispatch-timeout <s>", "Per-POST timeout in seconds for the create-testers + dispatch calls (default 120). Bump if `study run` times out client-side after seeding testers but before dispatch — those testers exist server-side and are surfaced under `seeded_but_not_dispatched_*` in the error envelope so the agent can resume.")
+        .option("--dispatch-timeout <s>", "Per-POST timeout in seconds for the create-participants + dispatch calls (default 120). Bump if `study run` times out client-side after seeding participants but before dispatch — those participants exist server-side and are surfaced under `seeded_but_not_dispatched_*` in the error envelope so the agent can resume.")
         .option("-y, --yes", "Skip confirmation prompt")
         // Local simulation options
         .option("--local", "Run simulation with local browser (Playwright) instead of remote")
@@ -257,7 +260,7 @@ export function attachStudyRunCommands(study) {
         .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)")
+        .option("--parallel <n>", "Run N participants 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>\`.
@@ -265,23 +268,22 @@ Note: --workspace and --study are optional if you have set active context
   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 (--bio, --country,
+  People: pass nothing to reuse the iteration's existing participants. Pass
+  --person to use specific people, or filter flags (--bio, --country,
   --gender, --min-age, --max-age, --occupation, --search, --visibility)
-  with --sample <N> or --all to seed a fresh audience from the workspace
-  pool.
+  with --sample <N> or --all to seed from the workspace pool.
 
 Examples:
-  # Run the latest iteration, reusing its testers:
+  # Run the latest iteration, reusing its participants:
   $ ish study run -y
 
-  # Run with an explicit audience:
-  $ ish study run --profile tp-795,tp-af2
+  # Run with explicit people:
+  $ ish study run --person p-795,p-af2
 
-  # Run with a demographic-filtered sample (3 Swedish profiles aged 35–50):
+  # Run with a demographic-filtered sample (3 Swedish people aged 35–50):
   $ ish study run --country SE --min-age 35 --max-age 50 --sample 3
 
-  # Run with every female profile in the workspace:
+  # Run with every female person in the workspace:
   $ ish study run --gender female --all
 
   # Run a specific iteration:
@@ -290,7 +292,7 @@ Examples:
   # Override the simulation config (e.g. for a media study):
   $ ish study run --config c-c3c
 
-  # Cap interactions per tester (default 20 — pass higher to allow deeper
+  # Cap interactions per participant (default 20 — pass higher to allow deeper
   # exploration, lower to cap spend on a known-broken surface):
   $ ish study run --max-interactions 30
 
@@ -305,6 +307,26 @@ Examples:
         await withClient(cmd, async (client, globals) => {
             const log = (msg) => { if (!globals.quiet)
                 console.error(msg); };
+            // Internal-only: per-run ConfigOverrides (model/prompt/sim-settings) layered
+            // on top of the base sim config by the backend's merge_config_overrides.
+            // Gated behind ISH_INTERNAL (defense-in-depth only — the real authorization
+            // belongs on the backend; the API currently accepts config_overrides from any
+            // authed caller). Parsed up front so a bad payload fails before seeding participants.
+            let configOverrides;
+            if (opts.simConfig) {
+                if (!process.env.ISH_INTERNAL) {
+                    throw new Error("--sim-config is an internal-only flag. Set ISH_INTERNAL=1 to use it.");
+                }
+                const raw = opts.simConfig.startsWith("@")
+                    ? await readFileOrStdin(opts.simConfig.slice(1))
+                    : opts.simConfig;
+                try {
+                    configOverrides = JSON.parse(raw);
+                }
+                catch (e) {
+                    throw new Error(`--sim-config is not valid JSON: ${e.message}`);
+                }
+            }
             const resolvedWorkspace = resolveWorkspace(opts.workspace);
             // Pattern A (Sprint 2): when `--iteration` is passed without
             // `--study`, derive the parent study from the iteration itself
@@ -335,7 +357,7 @@ Examples:
             }
             // B7: per-POST dispatch timeout (default 120s — long enough to survive
             // a slow-cold backend, short enough that an agent doesn't sit blind
-            // for many minutes). Applied to both the testers/batch POST AND the
+            // for many minutes). Applied to both the participants/batch POST AND the
             // simulation start POST so the seed + dispatch budget is the same.
             const dispatchTimeoutMs = opts.dispatchTimeout
                 ? Math.max(1, parseInt(opts.dispatchTimeout, 10)) * 1000
@@ -344,12 +366,12 @@ Examples:
                 || parseInt(opts.dispatchTimeout, 10) < 1)) {
                 throw new Error(`--dispatch-timeout must be a positive integer (seconds), got "${opts.dispatchTimeout}".`);
             }
-            // Step 0: Fetch study (with its iterations + their existing testers)
+            // Step 0: Fetch study (with its iterations + their existing participants)
             const study = await client.get(`/studies/${resolvedStudy}`);
             const modality = study.modality || "interactive";
             const isMedia = isMediaModality(modality);
             const isChat = isChatModality(modality);
-            // Pair-mode (tester_pair) is read off the iteration once we've
+            // Pair-mode (participant_pair) is read off the iteration once we've
             // resolved it below; set defaults here so the value is in scope.
             let chatMode = "external_chatbot";
             let isPair = false;
@@ -381,108 +403,108 @@ Examples:
             // a clear suggestion rather than masking the problem.
             if (isChat) {
                 chatMode = readChatMode(iteration.details);
-                isPair = chatMode === "tester_pair";
+                isPair = chatMode === "participant_pair";
             }
             if (!iterationHasContent(iteration.details, modality)) {
-                const flagHint = describeRequiredContentFlag(modality, isPair ? "tester_pair" : undefined);
+                const flagHint = describeRequiredContentFlag(modality, isPair ? "participant_pair" : undefined);
                 const iterAlias = tagAlias(ALIAS_PREFIX.iteration, iterationId);
-                throw new Error(`Iteration "${iterationLabel}" (${iterAlias}) has no ${isMedia ? "content" : isPair ? "audiences/scenarios" : isChat ? "endpoint" : "URL"} configured yet. ` +
+                throw new Error(`Iteration "${iterationLabel}" (${iterAlias}) has no ${isMedia ? "content" : isPair ? "people/scenarios" : isChat ? "endpoint" : "URL"} configured yet. ` +
                     `Add ${isMedia ? "content" : isPair ? "the pair-mode payload" : isChat ? "an endpoint" : "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);
-            const pairConfig = isPair ? readTesterPairConfig(iteration.details) : undefined;
-            // Step 2: Resolve audience.
-            // - If any audience flag is set (--profile / --sample / --all / filter flags),
+            const pairConfig = isPair ? readParticipantPairConfig(iteration.details) : undefined;
+            // Step 2: Resolve people.
+            // - If any person flag is set (--person / --sample / --all / filter flags),
             //   resolve a fresh ID list from the workspace pool via the shared helper.
-            // - Otherwise reuse the iteration's existing testers.
-            // - For chat tester_pair iterations, audiences live inside the
+            // - Otherwise reuse the iteration's existing participants.
+            // - For chat participant_pair iterations, people live inside the
             //   iteration's mode_details and are authoritative; run-time
             //   overrides are refused.
-            const profileNames = new Map();
-            const profileIds = [];
-            const existingTesters = [];
-            const audienceSet = hasAudienceFlags(opts);
+            const personNames = new Map();
+            const personIds = [];
+            const existingParticipants = [];
+            const personSet = hasPersonFlags(opts);
             if (isPair) {
-                if (audienceSet) {
-                    throw new Error("tester_pair chat iterations carry their own audiences inside mode_details; run-time audience overrides (--profile / --sample / --all / --country / --gender / --min-age / --max-age / --search / --visibility) are not supported. " +
-                        "To change the audiences, update the iteration via `ish iteration update <id> --details-json '{...}'`.");
+                if (personSet) {
+                    throw new Error("participant_pair chat iterations carry their own people inside mode_details; run-time overrides (--person / --sample / --all / --country / --gender / --min-age / --max-age / --search / --visibility) are not supported. " +
+                        "To change the people, update the iteration via `ish iteration update <id> --details-json '{...}'`.");
                 }
                 if (!pairConfig) {
                     throw new Error("Pair-mode iteration is missing mode_details; cannot dispatch.");
                 }
-                // Surface a flat profileIds[] (a then b) so downstream
+                // Surface a flat personIds[] (a then b) so downstream
                 // bookkeeping (config resolution, output) still has something to
-                // chew on. The pair-batch tester-provisioning POST below uses
+                // chew on. The pair-batch participant-provisioning POST below uses
                 // the split lists, not this flat one.
-                for (const pid of pairConfig.audience_a) {
-                    if (!profileNames.has(pid)) {
-                        profileNames.set(pid, "");
-                        profileIds.push(pid);
+                for (const pid of pairConfig.group_a) {
+                    if (!personNames.has(pid)) {
+                        personNames.set(pid, "");
+                        personIds.push(pid);
                     }
                 }
-                for (const pid of pairConfig.audience_b) {
-                    if (!profileNames.has(pid)) {
-                        profileNames.set(pid, "");
-                        profileIds.push(pid);
+                for (const pid of pairConfig.group_b) {
+                    if (!personNames.has(pid)) {
+                        personNames.set(pid, "");
+                        personIds.push(pid);
                     }
                 }
             }
-            else if (audienceSet) {
-                const resolved = await resolveAudienceProfileIds(client, resolvedWorkspace, opts, { requireSimulatable: false, allFlagName: "--all" });
-                profileIds.push(...resolved);
+            else if (personSet) {
+                const resolved = await resolvePersonIds(client, resolvedWorkspace, opts, { requireSimulatable: false, allFlagName: "--all" });
+                personIds.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);
+            else if (iteration.participants && iteration.participants.length > 0) {
+                for (const t of iteration.participants) {
+                    const pid = t.person_id || t.person?.id;
+                    const name = t.person?.name;
+                    if (pid && !personNames.has(pid)) {
+                        personNames.set(pid, name || "");
+                        personIds.push(pid);
                     }
                     if (t.id) {
-                        existingTesters.push({ id: t.id, tester_profile: { name: name || "Unknown" } });
+                        existingParticipants.push({ id: t.id, person: { name: name || "Unknown" } });
                     }
                 }
             }
-            // Pair iterations always seed fresh testers via the pair-batch
-            // endpoint; never reuse a stale tester roster from a prior run.
-            const reuseExistingTesters = !isPair && !audienceSet && existingTesters.length > 0;
-            // Pair iterations with criteria-only audiences will have empty
-            // profileIds at this stage if the backend deferred resolution past
+            // Pair iterations always seed fresh participants via the pair-batch
+            // endpoint; never reuse a stale participant roster from a prior run.
+            const reuseExistingParticipants = !isPair && !personSet && existingParticipants.length > 0;
+            // Pair iterations with criteria-only groups will have empty
+            // personIds at this stage if the backend deferred resolution past
             // iteration create. That's a valid state — skip the
-            // "no audience flags" guard for them and let dispatch surface any
+            // "no people flags" guard for them and let dispatch surface any
             // backend-side resolution errors (e.g. pool too small).
-            const pairCriteriaOnly = isPair && !!pairConfig && profileIds.length === 0
+            const pairCriteriaOnly = isPair && !!pairConfig && personIds.length === 0
                 && (!!pairConfig.role_criteria_a || !!pairConfig.role_criteria_b);
-            if (profileIds.length === 0 && !pairCriteriaOnly) {
-                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.");
+            if (personIds.length === 0 && !pairCriteriaOnly) {
+                throw new Error(`Iteration "${iterationLabel}" has no participants and no person flags were given. ` +
+                    "Pass --person <ids>, or filter flags (--country, --gender, --min-age, --max-age, --search, --visibility) with --sample <N> or --all.");
             }
-            // Step 3: Resolve simulation config. Always pre-flight every profile
+            // Step 3: Resolve simulation config. Always pre-flight every person
             // when no --config override is given: missing simulation_config_id
             // is fatal across all modalities (media + chat batch dispatch use it
             // per-item; interactive + pair dispatch fail server-side on the
-            // first sim start) and creating tester rows before discovering it
+            // first sim start) and creating participant rows before discovering it
             // leaves phantom DRAFT rows in the iteration. Pair mode reads
-            // pairConfig.audience_a; non-pair uses profileIds. profileConfigMap
+            // pairConfig.group_a; non-pair uses personIds. personConfigMap
             // is consumed by the media branch; other branches just need the
             // validation side effect.
             const resolvedConfigOverride = opts.config ? resolveId(opts.config) : undefined;
-            const profileConfigMap = new Map();
+            const personConfigMap = new Map();
             if (!resolvedConfigOverride) {
                 const idsToCheck = isPair && pairConfig
-                    ? [...new Set([...pairConfig.audience_a, ...pairConfig.audience_b])]
-                    : profileIds;
+                    ? [...new Set([...pairConfig.group_a, ...pairConfig.group_b])]
+                    : personIds;
                 for (const pid of idsToCheck) {
-                    const profile = await client.get(`/tester-profiles/${pid}`);
+                    const profile = await client.get(`/people/${pid}`);
                     if (profile.simulation_config_id) {
-                        profileConfigMap.set(pid, profile.simulation_config_id);
+                        personConfigMap.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" +
+                        throw new Error(`Profile ${personNames.get(pid) || pid} has no simulation config assigned.\n` +
+                            "Use --config <id> to specify one, or assign a config to the person.\n" +
                             "List configs with: ish config list");
                     }
                 }
@@ -496,19 +518,19 @@ Examples:
                 if (study.content_type)
                     log(`    Content type:   ${study.content_type}`);
                 if (isPair && pairConfig) {
-                    log(`    Chat mode:      tester_pair`);
-                    // Audience description per side: prefer explicit count when
+                    log(`    Chat mode:      participant_pair`);
+                    // Group description per side: prefer explicit count when
                     // present; otherwise show the criteria filter that the backend
                     // will resolve into a pool.
-                    const describeSide = (audLen, crit) => {
-                        if (audLen > 0)
-                            return `${audLen} profile(s)${crit ? ` (criteria validates list)` : ""}`;
+                    const describeSide = (groupLen, crit) => {
+                        if (groupLen > 0)
+                            return `${groupLen} person(s)${crit ? ` (criteria validates list)` : ""}`;
                         const summary = summarizeRoleCriteria(crit);
                         return summary ? `criteria (${summary}) — pool resolved server-side` : "—";
                     };
-                    log(`    Audience A:     ${describeSide(pairConfig.audience_a.length, pairConfig.role_criteria_a)}`);
-                    log(`    Audience B:     ${describeSide(pairConfig.audience_b.length, pairConfig.role_criteria_b)}`);
-                    const explicitConvs = Math.min(pairConfig.audience_a.length, pairConfig.audience_b.length);
+                    log(`    Group A:        ${describeSide(pairConfig.group_a.length, pairConfig.role_criteria_a)}`);
+                    log(`    Group B:        ${describeSide(pairConfig.group_b.length, pairConfig.role_criteria_b)}`);
+                    const explicitConvs = Math.min(pairConfig.group_a.length, pairConfig.group_b.length);
                     const criteriaResolved = !!pairConfig.role_criteria_a || !!pairConfig.role_criteria_b;
                     if (explicitConvs > 0 && !criteriaResolved) {
                         log(`    Conversations:  ${explicitConvs} (1:1 by index)`);
@@ -573,13 +595,13 @@ Examples:
                 if (opts.language)
                     log(`    Language:       ${opts.language}`);
                 if (!isPair) {
-                    log(`    Profiles (${profileIds.length}):`);
-                    for (const pid of profileIds) {
-                        const name = profileNames.get(pid);
+                    log(`    Profiles (${personIds.length}):`);
+                    for (const pid of personIds) {
+                        const name = personNames.get(pid);
                         log(`      - ${name ? `${name} (${pid})` : pid}`);
                     }
-                    const testerCount = profileIds.length;
-                    if (testerCount > 0) {
+                    const participantCount = personIds.length;
+                    if (participantCount > 0) {
                         if (isChat) {
                             const turnsForChat = opts.maxTurns
                                 ? parseInt(opts.maxTurns, 10)
@@ -587,7 +609,7 @@ Examples:
                                     ? iteration.details.max_turns
                                     : 14);
                             if (Number.isFinite(turnsForChat)) {
-                                const est = estimateChatSolo({ testerCount, maxTurns: turnsForChat });
+                                const est = estimateChatSolo({ participantCount, maxTurns: turnsForChat });
                                 log(`    Credits (est):  ≈ ${est.upper_bound} credit(s) upper bound — ${est.breakdown}`);
                             }
                         }
@@ -600,7 +622,7 @@ Examples:
                                     : `CLI default — pass --max-interactions to override`;
                             log(`    Max steps:      ${stepsForMedia} (${source})`);
                             if (Number.isFinite(stepsForMedia)) {
-                                const est = estimateMediaRun({ testerCount, maxInteractions: stepsForMedia });
+                                const est = estimateMediaRun({ participantCount, maxInteractions: stepsForMedia });
                                 log(`    Credits (est):  ≈ ${est.upper_bound} credit(s) upper bound — ${est.breakdown}`);
                             }
                         }
@@ -621,10 +643,10 @@ Examples:
                 const { ensureBrowser } = await import("../lib/local-sim/install.js");
                 await ensureBrowser({ quiet: globals.quiet, skipPrompt: globals.json });
             }
-            // Step 5: Either reuse the iteration's testers or batch-create new ones
-            let createdTesters;
+            // Step 5: Either reuse the iteration's participants or batch-create new ones
+            let createdParticipants;
             // Pair-mode bookkeeping: the dispatch endpoint takes
-            // `conversation_ids`, not tester ids. We populate this list either
+            // `conversation_ids`, not participant ids. We populate this list either
             // by reusing the iteration's existing Conversation rows or by
             // calling pair-batch.
             let pairConversationIds = [];
@@ -633,24 +655,24 @@ Examples:
                 //   1. If the iteration already carries `conversations[]` from a
                 //      prior dispatch, reuse them — skip pair-batch entirely.
                 //   2. Otherwise call pair-batch with the resolved
-                //      audience UUID lists. Criteria-only iterations should
-                //      already have audiences materialised at iteration-create
+                //      group UUID lists. Criteria-only iterations should
+                //      already have groups materialised at iteration-create
                 //      time; if they're still empty here, the backend's
-                //      `PairAudienceResolutionError` is the authoritative
+                //      `PairGroupResolutionError` is the authoritative
                 //      failure mode — refuse before hitting pair-batch.
                 //
                 // Wire shapes per backend `app/api/iterations/routers`:
-                //   POST /iterations/{id}/testers/pair-batch
+                //   POST /iterations/{id}/participants/pair-batch
                 //     body  : { side_a: UUID[1..20], side_b: UUID[1..20] (equal len),
                 //               language?: str }
                 //     reply : { conversations: [{ conversation_id, pair_index,
-                //                              tester_a_id, tester_b_id }] }
+                //                              participant_a_id, participant_b_id }] }
                 const existingConvs = iteration.conversations ?? [];
                 const reusable = [];
                 for (const c of existingConvs) {
                     const cid = c.conversation_id || c.id;
-                    if (cid && c.tester_a_id && c.tester_b_id) {
-                        reusable.push({ conversation_id: cid, tester_a_id: c.tester_a_id, tester_b_id: c.tester_b_id });
+                    if (cid && c.participant_a_id && c.participant_b_id) {
+                        reusable.push({ conversation_id: cid, participant_a_id: c.participant_a_id, participant_b_id: c.participant_b_id });
                     }
                 }
                 let pairRows;
@@ -659,79 +681,79 @@ Examples:
                     log(`Reusing ${reusable.length} existing conversation${reusable.length > 1 ? "s" : ""} on iteration "${iterationLabel}"`);
                 }
                 else {
-                    if (pairConfig.audience_a.length === 0 || pairConfig.audience_b.length === 0) {
-                        throw new Error("Pair-mode iteration has empty audience_a / audience_b and no conversations yet. " +
+                    if (pairConfig.group_a.length === 0 || pairConfig.group_b.length === 0) {
+                        throw new Error("Pair-mode iteration has empty group_a / group_b and no conversations yet. " +
                             "If this iteration was created with --role-criteria-a/-b, the backend should have " +
-                            "resolved a profile pool at create time — try `ish iteration get <id>` to fetch a " +
-                            "fresh shape, or recreate with explicit --profile-a/-b.");
+                            "resolved a person pool at create time — try `ish iteration get <id>` to fetch a " +
+                            "fresh shape, or recreate with explicit --person-a/-b.");
                     }
-                    log(`Provisioning ${pairConfig.audience_a.length} pair conversation${pairConfig.audience_a.length > 1 ? "s" : ""}...`);
-                    const pairBatchResult = await client.post(`/iterations/${iterationId}/testers/pair-batch`, {
-                        side_a: pairConfig.audience_a,
-                        side_b: pairConfig.audience_b,
+                    log(`Provisioning ${pairConfig.group_a.length} pair conversation${pairConfig.group_a.length > 1 ? "s" : ""}...`);
+                    const pairBatchResult = await client.post(`/iterations/${iterationId}/participants/pair-batch`, {
+                        side_a: pairConfig.group_a,
+                        side_b: pairConfig.group_b,
                         ...(opts.language && { language: opts.language }),
                     }, { timeout: dispatchTimeoutMs });
                     pairRows = (pairBatchResult.conversations ?? []).map((c) => ({
                         conversation_id: c.conversation_id,
-                        tester_a_id: c.tester_a_id,
-                        tester_b_id: c.tester_b_id,
+                        participant_a_id: c.participant_a_id,
+                        participant_b_id: c.participant_b_id,
                     }));
                     if (pairRows.length === 0) {
                         throw new Error("Pair-batch returned no conversations. The backend response did not include any conversation IDs.");
                     }
-                    log(`Created ${pairRows.length * 2} testers (${pairRows.length} conversation${pairRows.length > 1 ? "s" : ""})`);
+                    log(`Created ${pairRows.length * 2} participants (${pairRows.length} conversation${pairRows.length > 1 ? "s" : ""})`);
                 }
                 pairConversationIds = pairRows.map((r) => r.conversation_id);
-                // Flatten both sides' tester IDs for downstream bookkeeping:
+                // Flatten both sides' participant IDs for downstream bookkeeping:
                 // error-tagging (`seeded_but_not_dispatched_ids`), poll filtering,
                 // and JSON output. Names aren't returned by pair-batch; agents
                 // who care can correlate via `ish iteration get <id>`.
-                createdTesters = [];
+                createdParticipants = [];
                 for (let i = 0; i < pairRows.length; i++) {
                     const row = pairRows[i];
-                    createdTesters.push({
-                        id: row.tester_a_id,
-                        tester_profile: { name: `pair ${i} side A` },
+                    createdParticipants.push({
+                        id: row.participant_a_id,
+                        person: { name: `pair ${i} side A` },
                     });
-                    createdTesters.push({
-                        id: row.tester_b_id,
-                        tester_profile: { name: `pair ${i} side B` },
+                    createdParticipants.push({
+                        id: row.participant_b_id,
+                        person: { name: `pair ${i} side B` },
                     });
                 }
             }
-            else if (reuseExistingTesters && existingTesters.length > 0) {
-                createdTesters = existingTesters;
-                log(`Reusing ${createdTesters.length} existing tester${createdTesters.length > 1 ? "s" : ""} from iteration "${iterationLabel}"`);
+            else if (reuseExistingParticipants && existingParticipants.length > 0) {
+                createdParticipants = existingParticipants;
+                log(`Reusing ${createdParticipants.length} existing participant${createdParticipants.length > 1 ? "s" : ""} from iteration "${iterationLabel}"`);
             }
             else {
-                const testerInputs = profileIds.map((profileId) => ({
-                    tester_profile_id: profileId,
-                    tester_type: "ai",
+                const participantInputs = personIds.map((profileId) => ({
+                    person_id: profileId,
+                    participant_type: "ai",
                     status: "draft",
                     ...(opts.language && { language: opts.language }),
                     ...(!isMedia && !isChat && { platform: detailsView.platform || "browser" }),
                 }));
-                log(`Creating ${testerInputs.length} tester${testerInputs.length > 1 ? "s" : ""}...`);
-                const batchResult = await client.post(`/iterations/${iterationId}/testers/batch`, { testers: testerInputs }, { timeout: dispatchTimeoutMs });
-                createdTesters = batchResult.testers;
-                log(`Created ${createdTesters.length} tester${createdTesters.length > 1 ? "s" : ""}`);
+                log(`Creating ${participantInputs.length} participant${participantInputs.length > 1 ? "s" : ""}...`);
+                const batchResult = await client.post(`/iterations/${iterationId}/participants/batch`, { participants: participantInputs }, { timeout: dispatchTimeoutMs });
+                createdParticipants = batchResult.participants;
+                log(`Created ${createdParticipants.length} participant${createdParticipants.length > 1 ? "s" : ""}`);
             }
             // Step 6: Dispatch
             if (opts.local) {
                 if (isMedia || isChat) {
                     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");
+                const participantNameMap = new Map();
+                for (const t of createdParticipants) {
+                    participantNameMap.set(t.id, t.person?.name ?? "Unknown");
                 }
                 const { runLocalSimulations } = await import("../lib/local-sim/loop.js");
                 await runLocalSimulations(client, {
                     workspaceId: resolvedWorkspace,
                     studyId: resolvedStudy,
                     iterationId,
-                    testerIds: createdTesters.map((t) => t.id),
-                    testerNames: testerNameMap,
+                    participantIds: createdParticipants.map((t) => t.id),
+                    participantNames: participantNameMap,
                     url: detailsView.url,
                     screenFormat: detailsView.screenFormat,
                     locale: detailsView.locale,
@@ -745,31 +767,31 @@ Examples:
                     json: globals.json,
                 });
                 if (globals.json) {
-                    const testersOut = createdTesters.map((t) => ({
+                    const participantsOut = createdParticipants.map((t) => ({
                         id: t.id,
-                        alias: tagAlias(ALIAS_PREFIX.tester, String(t.id)),
-                        profile_name: t.tester_profile?.name,
+                        alias: tagAlias(ALIAS_PREFIX.participant, String(t.id)),
+                        person_name: t.person?.name,
                     }));
                     output({
                         iteration_id: iterationId,
-                        testers: testersOut,
-                        tester_ids: testersOut.map((t) => t.id),
-                        tester_aliases: testersOut.map((t) => t.alias),
+                        participants: participantsOut,
+                        participant_ids: participantsOut.map((t) => t.id),
+                        participant_aliases: participantsOut.map((t) => t.alias),
                         mode: "local",
                     }, true);
                 }
                 return;
             }
-            log(`Starting ${createdTesters.length} simulation${createdTesters.length > 1 ? "s" : ""}...`);
+            log(`Starting ${createdParticipants.length} simulation${createdParticipants.length > 1 ? "s" : ""}...`);
             let simResults;
             // B7 / Pattern G: tag any failure during the dispatch POST with the
-            // testers that already exist server-side. The client doesn't know
+            // participants that already exist server-side. The client doesn't know
             // whether the backend processed our POST or never received it, so
             // re-running `study run` would double-seed (we'd create another
-            // batch of testers on top of these). Instead, surface the seeded
+            // batch of participants on top of these). Instead, surface the seeded
             // ids in the error envelope under `seeded_but_not_dispatched_ids`
             // / `_aliases` so the agent can resume by polling them or calling
-            // `study tester delete <id>` then retrying.
+            // `study participant delete <id>` then retrying.
             const dispatchAttempt = async (fn) => {
                 try {
                     return await fn();
@@ -777,8 +799,8 @@ Examples:
                 catch (err) {
                     if (err instanceof Error) {
                         const tagged = err;
-                        tagged.seeded_but_not_dispatched_ids = createdTesters.map((t) => t.id);
-                        tagged.seeded_but_not_dispatched_aliases = createdTesters.map((t) => tagAlias(ALIAS_PREFIX.tester, String(t.id)));
+                        tagged.seeded_but_not_dispatched_ids = createdParticipants.map((t) => t.id);
+                        tagged.seeded_but_not_dispatched_aliases = createdParticipants.map((t) => tagAlias(ALIAS_PREFIX.participant, String(t.id)));
                     }
                     throw err;
                 }
@@ -803,22 +825,22 @@ Examples:
                     // chat_credit_cost(max_turns) * 2 * len(conversation_ids).
                     let pairConfigId = resolvedConfigOverride;
                     if (!pairConfigId) {
-                        // Fall back to the first audience_a profile's
+                        // Fall back to the first group_a person's
                         // simulation_config_id. Pair dispatch takes a single config
-                        // for the whole batch, so we don't need the per-profile map
+                        // for the whole batch, so we don't need the per-person map
                         // the external_chatbot path builds. Step 3 already populated
-                        // profileConfigMap with every audience profile's config when
+                        // personConfigMap with every group person's config when
                         // --config was not passed, so reuse that.
-                        const fallbackProfileId = pairConfig.audience_a[0];
+                        const fallbackProfileId = pairConfig.group_a[0];
                         if (!fallbackProfileId) {
-                            throw new Error("Pair-mode dispatch requires --config <id>: the iteration has no audience profile to draw a default config_id from.");
+                            throw new Error("Pair-mode dispatch requires --config <id>: the iteration has no person to draw a default config_id from.");
                         }
-                        pairConfigId = profileConfigMap.get(fallbackProfileId);
+                        pairConfigId = personConfigMap.get(fallbackProfileId);
                         if (!pairConfigId) {
                             // Defensive: Step 3 should have either populated the map or
                             // thrown. If we land here something upstream changed.
                             throw new Error(`Pair-mode dispatch requires a config_id. Profile ${fallbackProfileId} has no simulation config assigned and --config was not passed.\n` +
-                                "Use --config <id> to specify one, or assign a config to the profile.\n" +
+                                "Use --config <id> to specify one, or assign a config to the person.\n" +
                                 "List configs with: ish config list");
                         }
                     }
@@ -833,10 +855,10 @@ Examples:
                     simResults = simResult.results;
                 }
                 else {
-                    const chatBatchItems = createdTesters.map((t, i) => ({
+                    const chatBatchItems = createdParticipants.map((t, i) => ({
                         study_id: resolvedStudy,
-                        tester_id: t.id,
-                        config_id: resolvedConfigOverride || profileConfigMap.get(profileIds[i]),
+                        participant_id: t.id,
+                        config_id: resolvedConfigOverride || personConfigMap.get(personIds[i]),
                         ...(opts.language && { language: opts.language }),
                     }));
                     const simResult = await dispatchAttempt(() => client.post("/simulation/chat/start/batch", {
@@ -849,11 +871,12 @@ Examples:
                 }
             }
             else if (isMedia) {
-                const mediaBatchItems = createdTesters.map((t, i) => ({
+                const mediaBatchItems = createdParticipants.map((t, i) => ({
                     study_id: resolvedStudy,
-                    tester_id: t.id,
-                    config_id: resolvedConfigOverride || profileConfigMap.get(profileIds[i]),
+                    participant_id: t.id,
+                    config_id: resolvedConfigOverride || personConfigMap.get(personIds[i]),
                     ...(opts.language && { language: opts.language }),
+                    ...(configOverrides !== undefined && { config_overrides: configOverrides }),
                 }));
                 const simResult = await dispatchAttempt(() => client.post("/simulation/media/start/batch", {
                     product_id: resolvedWorkspace,
@@ -863,12 +886,13 @@ Examples:
                 simResults = simResult.results;
             }
             else {
-                const simItems = createdTesters.map((t) => ({
+                const simItems = createdParticipants.map((t) => ({
                     study_id: resolvedStudy,
-                    tester_id: t.id,
+                    participant_id: t.id,
                     ...(resolvedConfigOverride && { config_id: resolvedConfigOverride }),
                     ...(opts.language && { language: opts.language }),
                     ...(detailsView.locale && { locale: detailsView.locale }),
+                    ...(configOverrides !== undefined && { config_overrides: configOverrides }),
                 }));
                 const simResult = await dispatchAttempt(() => client.post("/simulation/interactive/start/batch", {
                     product_id: resolvedWorkspace,
@@ -880,7 +904,7 @@ Examples:
                 }, { timeout: dispatchTimeoutMs }));
                 simResults = simResult.results;
             }
-            // Pair-mode preview block: surface the audience sizes + scenario
+            // Pair-mode preview block: surface the group sizes + scenario
             // previews + initiator in the JSON envelope so agents can verify
             // what they just dispatched without needing a follow-up
             // `iteration get`. Mirrors the human confirmation block (which is
@@ -891,12 +915,12 @@ Examples:
                     ? iteration.details.max_turns
                     : 14);
             const pairPreview = isPair && pairConfig ? {
-                mode: "tester_pair",
-                audience_a_size: pairConfig.audience_a.length,
-                audience_b_size: pairConfig.audience_b.length,
+                mode: "participant_pair",
+                group_a_size: pairConfig.group_a.length,
+                group_b_size: pairConfig.group_b.length,
                 // Post-dispatch we know the actual conversation count from the
                 // pair-batch (or reuse) result. This is the authoritative number
-                // — better than guessing from audience length, which may diverge
+                // — better than guessing from group length, which may diverge
                 // when the backend trims to the smaller side.
                 conversation_count: pairConversationIds.length,
                 conversation_ids: pairConversationIds,
@@ -926,12 +950,12 @@ Examples:
             // Non-pair credit estimate — surfaced as a top-level field in the
             // JSON envelope alongside `pair_preview.credit_estimate`. Mirrors
             // backend formulas (`media_credit_cost` / `chat_credit_cost`).
-            // null when we can't estimate (criteria-only audience, etc.).
+            // null when we can't estimate (criteria-only group, etc.).
             const nonPairCreditEstimate = (() => {
                 if (isPair)
                     return null;
-                const testerCount = createdTesters.length || profileIds.length;
-                if (testerCount <= 0)
+                const participantCount = createdParticipants.length || personIds.length;
+                if (participantCount <= 0)
                     return null;
                 if (isChat) {
                     const turns = opts.maxTurns
@@ -941,25 +965,25 @@ Examples:
                             : 14);
                     if (!Number.isFinite(turns))
                         return null;
-                    return estimateChatSolo({ testerCount, maxTurns: turns });
+                    return estimateChatSolo({ participantCount, maxTurns: turns });
                 }
                 const steps = resolveMaxInteractions(opts.maxInteractions, iteration.details);
                 if (!Number.isFinite(steps))
                     return null;
-                return estimateMediaRun({ testerCount, maxInteractions: steps });
+                return estimateMediaRun({ participantCount, maxInteractions: steps });
             })();
             if (!opts.wait) {
                 if (globals.json) {
-                    const testersOut = createdTesters.map((t) => ({
+                    const participantsOut = createdParticipants.map((t) => ({
                         id: t.id,
-                        alias: tagAlias(ALIAS_PREFIX.tester, String(t.id)),
-                        profile_name: t.tester_profile?.name,
+                        alias: tagAlias(ALIAS_PREFIX.participant, String(t.id)),
+                        person_name: t.person?.name,
                     }));
                     output({
                         iteration_id: iterationId,
-                        testers: testersOut,
-                        tester_ids: testersOut.map((t) => t.id),
-                        tester_aliases: testersOut.map((t) => t.alias),
+                        participants: participantsOut,
+                        participant_ids: participantsOut.map((t) => t.id),
+                        participant_aliases: participantsOut.map((t) => t.alias),
                         url: getWebUrl(globals, `/${resolvedWorkspace}/${resolvedStudy}/timeline`),
                         ...(pairPreview && { pair_preview: pairPreview }),
                         ...(nonPairCreditEstimate && { credit_estimate: nonPairCreditEstimate }),
@@ -968,9 +992,9 @@ Examples:
                 }
                 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 participant = createdParticipants[i];
+                        const personName = participant?.person?.name || "Unknown";
+                        log(`  ${personName.padEnd(24)} QUEUED`);
                     }
                     const url = getWebUrl(globals, `/${resolvedWorkspace}/${resolvedStudy}/timeline`);
                     log(`\n  ${terminalLink(url, "Open in browser ↗")}\n`);
@@ -978,27 +1002,27 @@ Examples:
                 }
                 return;
             }
-            // --wait: block until all dispatched testers reach a terminal state
+            // --wait: block until all dispatched participants reach a terminal state
             const timeoutMs = parseWaitTimeout(opts.timeout);
-            const dispatchedIds = new Set(createdTesters.map((t) => t.id));
+            const dispatchedIds = new Set(createdParticipants.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,
+                participantIds: dispatchedIds,
                 timeoutMs,
                 quiet: globals.quiet,
             });
             if (globals.json) {
-                const testersOut = createdTesters.map((t) => ({
+                const participantsOut = createdParticipants.map((t) => ({
                     id: t.id,
-                    alias: tagAlias(ALIAS_PREFIX.tester, String(t.id)),
-                    profile_name: t.tester_profile?.name,
+                    alias: tagAlias(ALIAS_PREFIX.participant, String(t.id)),
+                    person_name: t.person?.name,
                 }));
                 output({
                     iteration_id: iterationId,
-                    testers: testersOut,
-                    tester_ids: testersOut.map((t) => t.id),
-                    tester_aliases: testersOut.map((t) => t.alias),
+                    participants: participantsOut,
+                    participant_ids: participantsOut.map((t) => t.id),
+                    participant_aliases: participantsOut.map((t) => t.alias),
                     url: getWebUrl(globals, `/${resolvedWorkspace}/${resolvedStudy}/timeline`),
                     ...(pairPreview && { pair_preview: pairPreview }),
                     ...(nonPairCreditEstimate && { credit_estimate: nonPairCreditEstimate }),
@@ -1017,28 +1041,28 @@ Examples:
     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[])")
+        .argument("[participant_id]", "Participant ID (alias or UUID; from `ish study run --json`.participant_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) => {
+        .option("--workspace <id>", "Workspace ID; accepted for consistency (workspace is inferred from --study/--iteration/<participant_id>)")
+        .addHelpText("after", "\nExamples:\n  $ ish study poll --study <study_id>\n  $ ish study poll <participant_id> --json\n\nGet participant IDs from `ish study run --json` (.participant_aliases[] / .participant_ids[]).")
+        .action(async (participantId, opts, cmd) => {
         await withClient(cmd, async (client, globals) => {
-            if (testerId) {
-                const data = await client.get(`/simulation/status/${resolveId(testerId)}`);
+            if (participantId) {
+                const data = await client.get(`/simulation/status/${resolveId(participantId)}`);
                 output(data, globals.json);
                 return;
             }
             // M7: fall back to the active study (set by `ish study use`) when
-            // neither a tester_id nor an explicit --study is passed. This brings
+            // neither a participant_id nor an explicit --study is passed. This brings
             // poll into parity with `study results` / `study wait` / `study run`,
             // all of which already honor the active study. Without the fallback
             // an agent that ran `study use s-...` then `study poll` would get a
-            // confusing "Provide a tester_id argument or --study flag" error.
+            // confusing "Provide a participant_id argument or --study flag" error.
             const rid = resolveStudy(opts.study);
             const study = await client.get(`/studies/${rid}`);
             const isMedia = isMediaModality(study.modality);
-            const allTesters = flattenTesterStatuses(study.iterations);
-            formatSimulationPoll(allTesters, globals.json, isMedia);
+            const allParticipants = flattenParticipantStatuses(study.iterations);
+            formatSimulationPoll(allParticipants, 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`);
@@ -1049,21 +1073,21 @@ Examples:
     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)")
+        .argument("[participant_id]", "Participant ID (alias or UUID; from `ish study run --json`.participant_aliases[])")
+        .option("--study <id>", "Study ID (wait for all participants in the study)")
+        .option("--iteration <id>", "Iteration ID (wait for participants 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) => {
+        .option("--workspace <id>", "Workspace ID; accepted for consistency (workspace is inferred from --study/--iteration/<participant_id>)")
+        .addHelpText("after", "\nExamples:\n  $ ish study wait                         # wait on the active study\n  $ ish study wait --iteration i-d4e\n  $ ish study wait <participant_id> --timeout 600\n\nGet participant IDs from `ish study run --json` (.participant_aliases[] / .participant_ids[]).")
+        .action(async (participantId, opts, cmd) => {
         await withClient(cmd, async (client, globals) => {
             const timeoutMs = parseWaitTimeout(opts.timeout);
-            if (testerId) {
+            if (participantId) {
                 const start = Date.now();
                 let lastStatus = "";
-                const resolvedTester = resolveId(testerId);
+                const resolvedParticipant = resolveId(participantId);
                 while (true) {
-                    const data = await client.get(`/simulation/status/${resolvedTester}`, undefined, { timeout: 60_000 });
+                    const data = await client.get(`/simulation/status/${resolvedParticipant}`, undefined, { timeout: 60_000 });
                     const status = String(data.status ?? "unknown");
                     if (!globals.quiet && status !== lastStatus) {
                         process.stderr.write(`  ${status}\n`);
@@ -1074,20 +1098,20 @@ Examples:
                         return;
                     }
                     if (Date.now() - start > timeoutMs) {
-                        // M8 + M9 (per-tester wait): structured wait_timeout with the
+                        // M8 + M9 (per-participant wait): structured wait_timeout with the
                         // current status as `progress.rows[0]` so `study wait <id>`
                         // always emits machine-readable final state.
-                        throw new WaitTimeoutError(`Timed out after ${Math.round(timeoutMs / 1000)}s waiting for tester ${testerId}. Last status: ${status}.`, {
-                            study_id: resolvedTester,
+                        throw new WaitTimeoutError(`Timed out after ${Math.round(timeoutMs / 1000)}s waiting for participant ${participantId}. Last status: ${status}.`, {
+                            study_id: resolvedParticipant,
                             timeout_seconds: Math.round(timeoutMs / 1000),
                             done: 0,
                             total: 1,
                             pending: 1,
                             rows: [
                                 {
-                                    id: resolvedTester,
+                                    id: resolvedParticipant,
                                     status,
-                                    tester_name: String(data.tester_name ?? "Unknown"),
+                                    participant_name: String(data.participant_name ?? "Unknown"),
                                     interaction_count: 0,
                                 },
                             ],
@@ -1133,57 +1157,57 @@ Examples:
     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) => {
+        .argument("<participant_id>", "Participant ID (alias or UUID; from `ish study run --json`.participant_aliases[])")
+        .option("--workspace <id>", "Workspace ID; accepted for consistency (workspace is inferred from <participant_id>)")
+        .addHelpText("after", "\nExamples:\n  $ ish study cancel pt-072\n  $ ish study cancel <uuid>\n\nGet participant IDs from `ish study run --json` (.participant_aliases[] / .participant_ids[]).")
+        .action(async (participantId, _opts, cmd) => {
         await withClient(cmd, async (client, globals) => {
-            const data = await client.post(`/simulation/cancel/${resolveId(testerId)}`);
+            const data = await client.post(`/simulation/cancel/${resolveId(participantId)}`);
             output(data, globals.json);
         });
     });
     // --- Extend ---
     //
-    // Resume a terminal tester with `additional_steps` more turns — the
+    // Resume a terminal participant 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
+    // participant 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
+    // set, the new participant 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).")
+        .description("Extend a terminal participant with more steps (and optionally a mid-run instruction)")
+        .argument("<participant_id>", "Participant 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("--instruction <text>", "User message to inject as the new participant resumes. Accepts inline text, `@/path/to/file`, or `-` for stdin.")
+        .option("--wait", "Block until the new participant 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>)")
+        .option("--workspace <id>", "Workspace ID; accepted for consistency (workspace is inferred from <participant_id>)")
         .addHelpText("after", `
-The source tester is left untouched; a new tester is spawned under the
+The source participant is left untouched; a new participant 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.
+new participant ID from \`.participant_id\` / \`.participant_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
+  $ ish study extend pt-072 --add-steps 5
 
   # Inject a mid-run instruction and wait for completion:
-  $ ish study extend t-072 \\
+  $ ish study extend pt-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
+  $ ish study extend pt-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 -
+  $ echo "Try the search bar instead." | ish study extend pt-072 --instruction -
 
-Get tester IDs from \`ish study run --json\` (.tester_aliases[] / .tester_ids[]).
+Get participant IDs from \`ish study run --json\` (.participant_aliases[] / .participant_ids[]).
 See \`ish docs get-page concepts/extending-a-simulation\` for the full mental model.`)
-        .action(async (testerId, opts, cmd) => {
+        .action(async (participantId, 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
@@ -1221,30 +1245,30 @@ See \`ish docs get-page concepts/extending-a-simulation\` for the full mental mo
                     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);
+            const sourceId = resolveId(participantId);
+            const sourceAlias = tagAlias(ALIAS_PREFIX.participant, 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,
+                source_participant_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);
+            const newParticipantId = String(data.participant_id);
+            const newAlias = tagAlias(ALIAS_PREFIX.participant, newParticipantId);
             // 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
+            // dispatch command and the new `participant_id` is the load-bearing
+            // return value (mirrors how `study run` keeps participant_ids in lean
             // output via the writePath option).
             const baseEnvelope = {
-                tester_id: newTesterId,
-                tester_alias: newAlias,
-                source_tester_id: sourceId,
+                participant_id: newParticipantId,
+                participant_alias: newAlias,
+                source_participant_id: sourceId,
                 source_alias: sourceAlias,
                 study_id: data.study_id,
                 job_id: data.job_id,
@@ -1257,15 +1281,15 @@ See \`ish docs get-page concepts/extending-a-simulation\` for the full mental mo
                     output(baseEnvelope, true, { writePath: true });
                 }
                 else {
-                    console.error(`  New tester: ${newAlias}`);
+                    console.error(`  New participant: ${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>`
+            // --wait: poll the new participant until it reaches a terminal state.
+            // Mirrors the per-participant wait block in `study wait <participant_id>`
             // above — same WaitTimeoutError shape (exit 5, retryable) so the
             // failure envelope is consistent across commands.
             const timeoutMs = parseWaitTimeout(opts.timeout);
@@ -1275,7 +1299,7 @@ See \`ish docs get-page concepts/extending-a-simulation\` for the full mental mo
             const start = Date.now();
             let lastStatus = "";
             while (true) {
-                const status = await client.get(`/simulation/status/${newTesterId}`, undefined, { timeout: 60_000 });
+                const status = await client.get(`/simulation/status/${newParticipantId}`, undefined, { timeout: 60_000 });
                 const s = String(status.status ?? "unknown");
                 if (!globals.quiet && s !== lastStatus) {
                     process.stderr.write(`  ${s}\n`);
@@ -1287,7 +1311,7 @@ See \`ish docs get-page concepts/extending-a-simulation\` for the full mental mo
                         ...(typeof status.interaction_count === "number" && {
                             interaction_count: status.interaction_count,
                         }),
-                        ...(status.tester_name && { tester_name: status.tester_name }),
+                        ...(status.participant_name && { participant_name: status.participant_name }),
                         ...(status.error && { error: status.error }),
                     };
                     if (globals.json) {
@@ -1301,17 +1325,17 @@ See \`ish docs get-page concepts/extending-a-simulation\` for the full mental mo
                     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,
+                    throw new WaitTimeoutError(`Timed out after ${Math.round(timeoutMs / 1000)}s waiting for participant ${newAlias}. Last status: ${s}.`, {
+                        study_id: newParticipantId,
                         timeout_seconds: Math.round(timeoutMs / 1000),
                         done: 0,
                         total: 1,
                         pending: 1,
                         rows: [
                             {
-                                id: newTesterId,
+                                id: newParticipantId,
                                 status: s,
-                                tester_name: String(status.tester_name ?? "Unknown"),
+                                participant_name: String(status.participant_name ?? "Unknown"),
                                 interaction_count: typeof status.interaction_count === "number" ? status.interaction_count : 0,
                             },
                         ],