@ishlabs/cli 0.17.7 → 0.19.0

package/dist/lib/output.js

@@ -7,6 +7,7 @@
  * for the full API response.
  */
 import { ApiError } from "./api-client.js";
+import { c } from "./colors.js";
 import { deterministicAlias, getAliasMap, ALIAS_PREFIX } from "./alias-store.js";
 // --- Lean JSON: strip noise for agent-friendly output ---
 let _verbose = false;
@@ -117,15 +118,15 @@ const PAGINATION_KEYS = new Set(["items", "total", "returned", "limit", "offset"
 // same shape leanJson strips elsewhere. These are load-bearing for agent
 // follow-up calls and were forcing agents to pass `--verbose` (C5-Bug4).
 const UUID_KEYS_TO_KEEP = new Set([
-    // ask: which variant the tester picked — the load-bearing field for "who picked what".
+    // ask: which variant the participant picked — the load-bearing field for "who picked what".
     "variant_pick_id",
 ]);
 // Keys whose value must pass through leanJson untouched (no UUID stripping,
 // no empty-array drop, no nested recursion). The entire shape is contract:
-// every variant id key and every tester id in its array is load-bearing,
+// every variant id key and every participant id in its array is load-bearing,
 // and unpicked variants must surface as `[]` rather than disappear.
 const LEAN_PASSTHROUGH_KEYS = new Set([
-    // Pattern H: variant_id → [tester_id, ...] for drill-in audience discovery.
+    // Pattern H: variant_id → [participant_id, ...] for drill-in subset discovery.
     "pick_buckets",
     // Pattern A: workspace cold-start fields. Agents need these without --verbose
     // to spot a safe reuse target (has_headroom) and order workspaces by recency.
@@ -133,7 +134,7 @@ const LEAN_PASSTHROUGH_KEYS = new Set([
     // child_counts is a dict — passthrough preserves the inner counts verbatim.
     "study_count",
     "ask_count",
-    "tester_profile_count",
+    "person_count",
     "child_counts",
     "has_headroom",
     "last_activity_at",
@@ -491,7 +492,7 @@ export function outputError(err, json) {
             ...suggestions,
         ]));
         const limitDetail = err.error_code === "usage_limit_reached" ? structuredDetail(err) : undefined;
-        // B7 / Pattern G: dispatch-attempt failures tag the seeded testers
+        // B7 / Pattern G: dispatch-attempt failures tag the seeded participants
         // onto the thrown ApiError so the agent can resume without
         // re-seeding (which would create duplicates). Surface alongside
         // the error envelope so machine-readable consumers see them.
@@ -666,7 +667,7 @@ const WORKSPACE_DEFAULT_FIELDS = [
     "created_at",
     "study_count",
     "ask_count",
-    "tester_profile_count",
+    "person_count",
     "child_counts",
     "has_headroom",
     "last_activity_at",
@@ -701,13 +702,13 @@ export function formatWorkspaceList(workspaces, json) {
         return;
     }
     const aliasMap = getAliasMap(ALIAS_PREFIX.workspace);
-    printTable(["#", "NAME", "ROOM", "STUDIES", "ASKS", "TESTERS", "LAST ACTIVITY"], workspaces.map((w) => [
+    printTable(["#", "NAME", "ROOM", "STUDIES", "ASKS", "PARTICIPANTS", "LAST ACTIVITY"], workspaces.map((w) => [
         aliasMap.get(String(w.id)) || String(w.id || ""),
         String(w.name || ""),
         formatHeadroom(w.has_headroom),
         formatChildCount(w, "studies", "study_count"),
         formatChildCount(w, "asks", "ask_count"),
-        formatChildCount(w, "tester_profiles", "tester_profile_count"),
+        formatChildCount(w, "persons", "person_count"),
         formatDate(w.last_activity_at),
     ]));
 }
@@ -751,7 +752,7 @@ export function formatWorkspaceDetail(workspace, json, options = {}) {
         Headroom: formatHeadroom(workspace.has_headroom),
         Studies: formatChildCount(workspace, "studies", "study_count"),
         Asks: formatChildCount(workspace, "asks", "ask_count"),
-        Testers: formatChildCount(workspace, "tester_profiles", "tester_profile_count"),
+        Participants: formatChildCount(workspace, "persons", "person_count"),
     };
     if (workspace.reused !== undefined)
         display.Reused = workspace.reused ? "yes" : "no";
@@ -783,20 +784,20 @@ export function formatStudyList(studies, json) {
         return;
     }
     const aliasMap = getAliasMap(ALIAS_PREFIX.study);
-    printTable(["#", "NAME", "MODALITY", "TYPE", "STATUS", "TESTERS"], studies.map((s) => [
+    printTable(["#", "NAME", "MODALITY", "TYPE", "STATUS", "PARTICIPANTS"], studies.map((s) => [
         aliasMap.get(String(s.id)) || String(s.id || ""),
         String(s.name || ""),
         String(s.modality || "-"),
         String(s.content_type || "-"),
         String(s.status || "draft"),
-        String(s.tester_count ?? "0"),
+        String(s.participant_count ?? "0"),
     ]));
 }
 /**
  * CLI-side sanity check for ALL-ISSUES Issue #2 / backend Pattern Bk2.
  *
  * Backend sometimes reports `status: "failed"` even when results are
- * populated (testers completed, interactions present). Until the backend
+ * populated (participants completed, interactions present). Until the backend
  * root-cause is fixed, the CLI surfaces the inconsistency rather than
  * letting agents trust a misleading status field:
  *   - JSON: adds a `status_inferred` field (e.g. `completed_with_errors`).
@@ -806,17 +807,17 @@ export function formatStudyList(studies, json) {
  *
  * Returns null when status is consistent; no warning emitted.
  */
-function detectStudyStatusInconsistency(study) {
+function detectStudyStatusInconsistency(study, participants) {
     if (study.status !== "failed")
         return null;
-    const allTesters = collectTesters(study);
-    const completedCount = allTesters.filter((t) => t.status === "completed" || t.status === "complete").length;
-    const totalInteractions = allTesters.reduce((sum, t) => sum + t.interactionCount, 0);
+    const allParticipants = collectParticipants(participants, Array.isArray(study.iterations) ? study.iterations : []);
+    const completedCount = allParticipants.filter((t) => t.status === "completed" || t.status === "complete").length;
+    const totalInteractions = allParticipants.reduce((sum, t) => sum + t.interactionCount, 0);
     if (completedCount === 0 && totalInteractions === 0)
         return null;
     return {
         inferred: "completed_with_errors",
-        reason: `${completedCount}/${allTesters.length} testers completed, ${totalInteractions} total interactions`,
+        reason: `${completedCount}/${allParticipants.length} participants completed, ${totalInteractions} total interactions`,
     };
 }
 function emitStatusInconsistencyWarning(inconsistency) {
@@ -824,14 +825,70 @@ function emitStatusInconsistencyWarning(inconsistency) {
         `CLI inferring status_inferred="${inconsistency.inferred}". ` +
         `Backend root-cause tracked as Issue #2 (Pattern Bk2).\n`);
 }
-export function formatStudyDetail(study, json, options = {}) {
-    const inconsistency = detectStudyStatusInconsistency(study);
+/**
+ * Render an assignment's `steps` checklist and, once a run has graded them, the
+ * per-step `step_completion` rollup (pass rate + a few sample failure reasons).
+ * Both are printed indented under the assignment in `study get` human output;
+ * absent on draft studies and on modalities that don't support steps.
+ */
+function renderAssignmentSteps(a) {
+    const steps = Array.isArray(a.steps) ? a.steps : [];
+    const completion = Array.isArray(a.step_completion)
+        ? a.step_completion
+        : [];
+    if (steps.length === 0 && completion.length === 0)
+        return;
+    // Index completion rows by step name so we can pair them with authored steps.
+    const byName = new Map();
+    for (const sc of completion) {
+        if (typeof sc.name === "string")
+            byName.set(sc.name, sc);
+    }
+    // Prefer the authored step order; fall back to completion rows if a study
+    // somehow returns completion without resolved steps.
+    const rows = steps.length > 0 ? steps : completion;
+    console.log("     Steps:");
+    for (let i = 0; i < rows.length; i++) {
+        const step = rows[i];
+        const name = String(step.name || "Untitled");
+        const sc = byName.get(name) ?? (steps.length === 0 ? step : undefined);
+        let line = `       ${i + 1}. ${name}`;
+        if (sc) {
+            const total = Number(sc.total ?? 0);
+            const passed = Number(sc.passed ?? 0);
+            const rate = sc.rate;
+            if (total === 0 || rate === null || rate === undefined) {
+                line += ` ${c.dim}— not yet graded${c.reset}`;
+            }
+            else {
+                const pct = Math.round(Number(rate) * 100);
+                const mark = passed === total ? `${c.green}✓${c.reset}` : `${c.red}✗${c.reset}`;
+                line += ` ${mark} ${passed}/${total} (${pct}%)`;
+            }
+        }
+        console.log(line);
+        const desc = step.description ?? (sc ? sc.description : undefined);
+        if (typeof desc === "string" && desc.trim()) {
+            console.log(`          ${c.dim}${truncate(desc, 72)}${c.reset}`);
+        }
+        const failures = sc && Array.isArray(sc.sample_failures) ? sc.sample_failures : [];
+        for (const f of failures) {
+            if (typeof f.reason === "string" && f.reason.trim()) {
+                console.log(`          ${c.dim}✗ ${truncate(f.reason, 72)}${c.reset}`);
+            }
+        }
+    }
+}
+export function formatStudyDetail(study, json, options = {}, participants) {
+    const inconsistency = detectStudyStatusInconsistency(study, participants);
     if (inconsistency)
         emitStatusInconsistencyWarning(inconsistency);
     if (json) {
-        const payload = inconsistency
-            ? { ...study, status_inferred: inconsistency.inferred }
-            : study;
+        const payload = { ...study };
+        if (participants !== undefined)
+            payload.participants = participants;
+        if (inconsistency)
+            payload.status_inferred = inconsistency.inferred;
         console.log(jsonOutput(payload, options));
         return;
     }
@@ -860,6 +917,7 @@ export function formatStudyDetail(study, json, options = {}) {
             if (a.instructions) {
                 console.log(`     ${truncate(String(a.instructions), 80)}`);
             }
+            renderAssignmentSteps(a);
         }
     }
     // Interview Questions
@@ -872,12 +930,12 @@ export function formatStudyDetail(study, json, options = {}) {
             console.log(`  ${i + 1}. ${q.question || "Untitled"} ${typeStr}`);
         }
     }
-    // Testers summary
-    const allTesters = collectTesters(study);
-    if (allTesters.length > 0) {
-        console.log(`\nTesters (${allTesters.length}):`);
-        printTable(["#", "NAME", "ITERATION", "STATUS", "INTERACTIONS"], allTesters.map((t) => [
-            t.id ? deterministicAlias(ALIAS_PREFIX.tester, t.id) : t.id,
+    // Participants summary
+    const allParticipants = collectParticipants(participants, Array.isArray(study.iterations) ? study.iterations : []);
+    if (allParticipants.length > 0) {
+        console.log(`\nParticipants (${allParticipants.length}):`);
+        printTable(["#", "NAME", "ITERATION", "STATUS", "INTERACTIONS"], allParticipants.map((t) => [
+            t.id ? deterministicAlias(ALIAS_PREFIX.participant, t.id) : t.id,
             t.name,
             t.iterationLabel,
             t.status,
@@ -890,16 +948,16 @@ export function formatStudyDetail(study, json, options = {}) {
  * study state — fields default to `null`, `0`, or `[]` when nothing has run.
  * Agents can rely on the keys always being present (M4).
  */
-function buildStudyResultsEnvelope(study) {
-    const allTesters = collectTesters(study);
+function buildStudyResultsEnvelope(study, participants) {
+    const allParticipants = collectParticipants(participants, Array.isArray(study.iterations) ? study.iterations : []);
     const studyAlias = study.id
         ? deterministicAlias(ALIAS_PREFIX.study, String(study.id))
         : null;
-    const completedCount = allTesters.filter((t) => t.status === "completed" || t.status === "complete").length;
-    // Aggregate sentiment across all interactions on all testers.
+    const completedCount = allParticipants.filter((t) => t.status === "completed" || t.status === "complete").length;
+    // Aggregate sentiment across all interactions on all participants.
     const sentimentCounts = {};
     let sentimentTotal = 0;
-    for (const t of allTesters) {
+    for (const t of allParticipants) {
         for (const [label, count] of Object.entries(t.sentimentCounts)) {
             sentimentCounts[label] = (sentimentCounts[label] || 0) + count;
             sentimentTotal += count;
@@ -912,18 +970,18 @@ function buildStudyResultsEnvelope(study) {
         }
         : null;
     // Group interview answers by question for easy parsing. Each answer row
-    // includes the tester's session-level `sentiment` (M10) so agents can read
-    // sentiment per answer without round-tripping `study tester <id>` per row.
+    // includes the participant's session-level `sentiment` (M10) so agents can read
+    // sentiment per answer without round-tripping `study participant <id>` per row.
     const questions = Array.isArray(study.interview_questions) ? study.interview_questions : [];
     const interviewAnswers = questions.map((q) => {
         const qObj = q;
         const answers = [];
-        for (const t of allTesters) {
+        for (const t of allParticipants) {
             const a = t.interviewAnswers.find((x) => x.questionId === qObj.id);
             if (a) {
                 answers.push({
-                    tester_alias: t.alias || null,
-                    tester_name: t.name,
+                    participant_alias: t.alias || null,
+                    participant_name: t.name,
                     iteration: t.iterationLabel,
                     answer: a.answer,
                     sentiment: t.summarySentiment,
@@ -939,11 +997,11 @@ function buildStudyResultsEnvelope(study) {
     // CLI-side sanity check (Pattern E / Issue #2). Surface a status_inferred
     // field when the backend reports failed-with-data; agents can branch on
     // either the original status or status_inferred.
-    const inconsistency = detectStudyStatusInconsistency(study);
-    // Pattern B2 (cli half): per-tester rows expose status + error_message so
-    // agents can act on a failed run without re-fetching every tester.
-    const failedCount = allTesters.filter((t) => t.status.toLowerCase() === "failed").length;
-    const testerRows = allTesters.map((t) => ({
+    const inconsistency = detectStudyStatusInconsistency(study, participants);
+    // Pattern B2 (cli half): per-participant rows expose status + error_message so
+    // agents can act on a failed run without re-fetching every participant.
+    const failedCount = allParticipants.filter((t) => t.status.toLowerCase() === "failed").length;
+    const participantRows = allParticipants.map((t) => ({
         alias: t.alias || null,
         name: t.name,
         iteration: t.iterationLabel,
@@ -961,33 +1019,33 @@ function buildStudyResultsEnvelope(study) {
             ...(inconsistency && { status_inferred: inconsistency.inferred }),
             modality: study.modality || null,
         },
-        tester_count: allTesters.length,
+        participant_count: allParticipants.length,
         completed_count: completedCount,
         failed_count: failedCount,
         sentiment,
         interview_answers: interviewAnswers,
-        testers: testerRows,
+        participants: participantRows,
     };
 }
-export function formatStudyResults(study, json) {
-    const inconsistency = detectStudyStatusInconsistency(study);
+export function formatStudyResults(study, participants, json) {
+    const inconsistency = detectStudyStatusInconsistency(study, participants);
     if (inconsistency)
         emitStatusInconsistencyWarning(inconsistency);
     if (json) {
         // preProjected: bypass leanJson so the stable envelope keeps documented
         // empty defaults (sentiment: null, interview_answers[].answers: []) rather
         // than having them stripped by the lean transform.
-        console.log(jsonOutput(buildStudyResultsEnvelope(study), { preProjected: true }));
+        console.log(jsonOutput(buildStudyResultsEnvelope(study, participants), { preProjected: true }));
         return;
     }
-    const allTesters = collectTesters(study);
-    const totalInteractions = allTesters.reduce((sum, t) => sum + t.interactionCount, 0);
+    const allParticipants = collectParticipants(participants, Array.isArray(study.iterations) ? study.iterations : []);
+    const totalInteractions = allParticipants.reduce((sum, t) => sum + t.interactionCount, 0);
     // Header
     console.log(`${study.name || "Untitled"} — Results`);
-    console.log(`${allTesters.length} tester${allTesters.length !== 1 ? "s" : ""} · ${totalInteractions} total interactions`);
+    console.log(`${allParticipants.length} participant${allParticipants.length !== 1 ? "s" : ""} · ${totalInteractions} total interactions`);
     // Sentiment summary
     const totalSentiment = {};
-    for (const t of allTesters) {
+    for (const t of allParticipants) {
         for (const [label, count] of Object.entries(t.sentimentCounts)) {
             totalSentiment[label] = (totalSentiment[label] || 0) + count;
         }
@@ -1002,7 +1060,7 @@ export function formatStudyResults(study, json) {
             const qObj = q;
             const typeStr = formatQuestionType(qObj);
             console.log(`\n  "${qObj.question}" ${typeStr}`);
-            for (const t of allTesters) {
+            for (const t of allParticipants) {
                 const answer = t.interviewAnswers.find((a) => a.questionId === qObj.id);
                 if (answer) {
                     const answerStr = typeof answer.answer === "string"
@@ -1013,13 +1071,13 @@ export function formatStudyResults(study, json) {
             }
         }
     }
-    // Testers table
-    if (allTesters.length > 0) {
-        console.log("\nTesters:");
-        printTable(["#", "NAME", "ITERATION", "STATUS", "INTERACTIONS", "SENTIMENT"], allTesters.map((t) => {
+    // Participants table
+    if (allParticipants.length > 0) {
+        console.log("\nParticipants:");
+        printTable(["#", "NAME", "ITERATION", "STATUS", "INTERACTIONS", "SENTIMENT"], allParticipants.map((t) => {
             const parts = Object.entries(t.sentimentCounts).map(([label, count]) => `${count} ${label.toLowerCase()}`);
             return [
-                t.id ? deterministicAlias(ALIAS_PREFIX.tester, t.id) : t.id,
+                t.id ? deterministicAlias(ALIAS_PREFIX.participant, t.id) : t.id,
                 t.name,
                 t.iterationLabel,
                 t.status,
@@ -1028,41 +1086,41 @@ export function formatStudyResults(study, json) {
             ];
         }));
         // Pattern B2: list any failure reasons under the table so agents see why
-        // a run failed without drilling into `study tester <id>`.
-        const failedRows = allTesters.filter((t) => t.status.toLowerCase() === "failed" && t.errorMessage);
+        // a run failed without drilling into `study participant <id>`.
+        const failedRows = allParticipants.filter((t) => t.status.toLowerCase() === "failed" && t.errorMessage);
         if (failedRows.length > 0) {
-            console.log("\nFailed testers:");
+            console.log("\nFailed participants:");
             for (const t of failedRows) {
-                const alias = t.id ? deterministicAlias(ALIAS_PREFIX.tester, t.id) : t.id;
+                const alias = t.id ? deterministicAlias(ALIAS_PREFIX.participant, t.id) : t.id;
                 console.log(`  ${alias} (${t.name}): ${truncate(t.errorMessage, 200)}`);
             }
         }
-        console.log("\nRun `ish tester get <id> --json` for full interaction details.");
+        console.log("\nRun `ish participant get <id> --json` for full interaction details.");
     }
 }
 /**
- * `study results --summary` projection. Drops interview_answers + per-tester
+ * `study results --summary` projection. Drops interview_answers + per-participant
  * interaction breakdowns; keeps headline counters, sentiment histogram, and a
- * per-tester {alias, status, sentiment, comment} row. Useful for agents that
+ * per-participant {alias, status, sentiment, comment} row. Useful for agents that
  * need to branch on outcome without paying for the full envelope.
  */
-export function buildStudyResultsSummary(study) {
-    const allTesters = collectTesters(study);
+export function buildStudyResultsSummary(study, participants) {
+    const allParticipants = collectParticipants(participants, Array.isArray(study.iterations) ? study.iterations : []);
     const studyAlias = study.id
         ? deterministicAlias(ALIAS_PREFIX.study, String(study.id))
         : null;
-    const completedCount = allTesters.filter((t) => t.status === "completed" || t.status === "complete").length;
-    const failedCount = allTesters.filter((t) => t.status.toLowerCase() === "failed").length;
+    const completedCount = allParticipants.filter((t) => t.status === "completed" || t.status === "complete").length;
+    const failedCount = allParticipants.filter((t) => t.status.toLowerCase() === "failed").length;
     const sentimentCounts = {};
     let sentimentTotal = 0;
-    for (const t of allTesters) {
+    for (const t of allParticipants) {
         for (const [label, count] of Object.entries(t.sentimentCounts)) {
             sentimentCounts[label] = (sentimentCounts[label] || 0) + count;
             sentimentTotal += count;
         }
     }
     const sentiment = sentimentTotal > 0 ? { counts: sentimentCounts, total: sentimentTotal } : null;
-    const testers = allTesters.map((t) => ({
+    const participantRows = allParticipants.map((t) => ({
         alias: t.alias || null,
         name: t.name,
         status: t.status,
@@ -1076,27 +1134,27 @@ export function buildStudyResultsSummary(study) {
             name: study.name || null,
             modality: study.modality || null,
         },
-        tester_count: allTesters.length,
+        participant_count: allParticipants.length,
         completed_count: completedCount,
         failed_count: failedCount,
         sentiment,
-        testers,
+        participants: participantRows,
     };
 }
 /**
- * `study results --transcript <tester_id>` projection. Mirrors the schema
+ * `study results --transcript <participant_id>` projection. Mirrors the schema
  * MCP's `get_chat_transcript` returns (`src/ish_mcp/projections.py:
  * build_chat_transcript`) so callers see the same shape regardless of
- * surface. Tester turns whose action carries no text (e.g. select_option)
+ * surface. Participant turns whose action carries no text (e.g. select_option)
  * surface `text: null`; intent lives on `action_type` + `option_label`.
  * Bot turns with a `bot_reply.failure` block surface `failure` and
  * `text: null` and don't count toward `unique_bot_replies`.
  */
-export function buildChatTranscript(tester) {
-    const id = String(tester.id || "");
-    const alias = id ? deterministicAlias(ALIAS_PREFIX.tester, id) : null;
-    const profile = tester.tester_profile;
-    const interactions = Array.isArray(tester.interactions) ? tester.interactions : [];
+export function buildChatTranscript(participant) {
+    const id = String(participant.id || "");
+    const alias = id ? deterministicAlias(ALIAS_PREFIX.participant, id) : null;
+    const profile = participant.person;
+    const interactions = Array.isArray(participant.interactions) ? participant.interactions : [];
     // Sort by timestamp then created_at so agent doesn't need to re-sort.
     const sorted = [...interactions].sort((a, b) => {
         const aIx = a;
@@ -1115,14 +1173,14 @@ export function buildChatTranscript(tester) {
     const uniqueBotReplies = new Set();
     for (const interaction of sorted) {
         const ix = interaction;
-        // Tester turn — derive role/action from the interaction itself.
+        // Participant turn — derive role/action from the interaction itself.
         // Backend shape (post a880eba rename):
         //   ix.actor in {"ai", "human", "user"} (user is the actual end-user;
         //   we don't surface those in the transcript).
         //   ix.actions: [{action_type, data: {type, turn_index, text?, wire_text?,
         //                                     option_label?, said_instead?, ...}}]
         //   ix.bot_reply: {text?, failure?}
-        // The tester's actual message text is nested under `action.data` —
+        // The participant's actual message text is nested under `action.data` —
         // earlier versions of this builder read off the action top-level
         // (`action.text`, `action.type`), which silently produced
         // `text: null` on every turn (PC-C3 finding #3).
@@ -1157,7 +1215,7 @@ export function buildChatTranscript(tester) {
         }
         const actor = String(ix.actor ?? ix.interaction_type ?? "");
         if (actor === "ai" || actor === "human") {
-            // Resolve the tester's literal text from action.data, preferring
+            // Resolve the participant's literal text from action.data, preferring
             // the canonical wire_text the backend exposes for every action
             // shape (send_text, select_option, ignore_offered, …) so the
             // transcript carries the actual content on every turn — D2.
@@ -1188,7 +1246,7 @@ export function buildChatTranscript(tester) {
                         : null));
             const sentimentObj = ix.sentiment;
             transcript.push({
-                role: "tester",
+                role: "participant",
                 text,
                 turn_index: turnIndex,
                 action_type: actionType,
@@ -1197,15 +1255,15 @@ export function buildChatTranscript(tester) {
             });
         }
     }
-    const summary = tester.tester_summary;
+    const summary = participant.participant_summary;
     return {
-        tester_id: id || null,
-        tester_alias: alias,
-        instance_name: tester.instance_name ?? null,
+        participant_id: id || null,
+        participant_alias: alias,
+        instance_name: participant.instance_name ?? null,
         modality: "chat",
         transcript,
         unique_bot_replies: uniqueBotReplies.size,
-        tester_summary: summary
+        participant_summary: summary
             ? {
                 comment: summary.comment ?? null,
                 sentiment: summary.sentiment ?? null,
@@ -1215,78 +1273,81 @@ export function buildChatTranscript(tester) {
     };
 }
 /**
- * `study tester --summary` projection. Drops the action timeline; keeps the
+ * `study participant --summary` projection. Drops the action timeline; keeps the
  * headline (alias, status, sentiment, comment, error_message). Useful for
- * the common "did this tester finish, what did they say" check that's
+ * the common "did this participant finish, what did they say" check that's
  * currently buried under the full interactions array.
  */
-export function buildTesterSummary(tester) {
-    const id = String(tester.id || "");
-    const alias = id ? deterministicAlias(ALIAS_PREFIX.tester, id) : null;
-    const profile = tester.tester_profile;
-    const summary = tester.tester_summary;
+export function buildParticipantSummary(participant) {
+    const id = String(participant.id || "");
+    const alias = id ? deterministicAlias(ALIAS_PREFIX.participant, id) : null;
+    const profile = participant.person;
+    const summary = participant.participant_summary;
     const summarySentiment = summary?.sentiment;
-    const interactions = Array.isArray(tester.interactions) ? tester.interactions : [];
+    const interactions = Array.isArray(participant.interactions) ? participant.interactions : [];
     const out = {
-        tester: {
+        participant: {
             alias,
-            name: profile?.name ?? tester.instance_name ?? null,
-            iteration_id: tester.iteration_id ?? null,
-            status: tester.status ?? null,
+            name: profile?.name ?? participant.instance_name ?? null,
+            iteration_id: participant.iteration_id ?? null,
+            status: participant.status ?? null,
         },
         interaction_count: interactions.length,
         sentiment: summarySentiment?.label ?? null,
         comment: summary?.comment ?? null,
     };
-    if (tester.error_message)
-        out.error_message = String(tester.error_message);
-    if (tester.error_kind)
-        out.error_kind = String(tester.error_kind);
+    if (participant.error_message)
+        out.error_message = String(participant.error_message);
+    if (participant.error_kind)
+        out.error_kind = String(participant.error_kind);
     return out;
 }
-function collectTesters(study) {
-    const iterations = Array.isArray(study.iterations) ? study.iterations : [];
-    const testers = [];
-    for (const iter of iterations) {
-        const it = iter;
-        const iterLabel = String(it.label || it.name || "-");
-        const iterTesters = Array.isArray(it.testers) ? it.testers : [];
-        for (const tester of iterTesters) {
-            const t = tester;
-            const profile = t.tester_profile;
-            const interactions = Array.isArray(t.interactions) ? t.interactions : [];
-            const sentimentCounts = {};
-            for (const interaction of interactions) {
-                const ix = interaction;
-                const sentiment = ix.sentiment;
-                if (sentiment?.label) {
-                    const label = String(sentiment.label);
-                    sentimentCounts[label] = (sentimentCounts[label] || 0) + 1;
-                }
+function collectParticipants(participants, iterations) {
+    const iterationLabels = new Map();
+    for (const iter of iterations ?? []) {
+        const id = iter.id ? String(iter.id) : "";
+        if (id) {
+            iterationLabels.set(id, String(iter.label || iter.name || "-"));
+        }
+    }
+    const rows = [];
+    for (const participant of participants ?? []) {
+        const t = participant;
+        const profile = t.person;
+        const interactions = Array.isArray(t.interactions) ? t.interactions : [];
+        const sentimentCounts = {};
+        for (const interaction of interactions) {
+            const ix = interaction;
+            const sentiment = ix.sentiment;
+            if (sentiment?.label) {
+                const label = String(sentiment.label);
+                sentimentCounts[label] = (sentimentCounts[label] || 0) + 1;
             }
-            const answers = Array.isArray(t.interview_answers) ? t.interview_answers : [];
-            const summary = t.tester_summary;
-            const summarySentimentObj = summary?.sentiment;
-            const id = String(t.id || "");
-            testers.push({
-                id,
-                name: String(profile?.name || t.instance_name || "Unknown"),
-                alias: id ? deterministicAlias(ALIAS_PREFIX.tester, id) : "",
-                iterationLabel: iterLabel,
-                status: String(t.status || "-"),
-                errorMessage: t.error_message ? String(t.error_message) : null,
-                interactionCount: interactions.length,
-                sentimentCounts,
-                summarySentiment: summarySentimentObj?.label ? String(summarySentimentObj.label) : null,
-                summaryComment: summary?.comment ? String(summary.comment) : null,
-                interviewAnswers: answers.map((a) => ({
-                    questionId: String(a.question_id || ""),
-                    answer: a.answer,
-                })),
-            });
         }
+        const answers = Array.isArray(t.interview_answers) ? t.interview_answers : [];
+        const summary = t.participant_summary;
+        const summarySentimentObj = summary?.sentiment;
+        const id = String(t.id || "");
+        const iterationId = t.iteration_id ? String(t.iteration_id) : "";
+        const iterationLabel = (iterationId && iterationLabels.get(iterationId)) || "-";
+        rows.push({
+            id,
+            name: String(profile?.name || t.instance_name || "Unknown"),
+            alias: id ? deterministicAlias(ALIAS_PREFIX.participant, id) : "",
+            iterationLabel,
+            status: String(t.status || "-"),
+            errorMessage: t.error_message ? String(t.error_message) : null,
+            interactionCount: interactions.length,
+            sentimentCounts,
+            summarySentiment: summarySentimentObj?.label ? String(summarySentimentObj.label) : null,
+            summaryComment: summary?.comment ? String(summary.comment) : null,
+            interviewAnswers: answers.map((a) => ({
+                questionId: String(a.question_id || ""),
+                answer: a.answer,
+            })),
+        });
     }
-    return testers;
+    return rows;
 }
 function formatQuestionType(q) {
     if (!q.type)
@@ -1314,26 +1375,26 @@ export function formatIterationList(iterations, json) {
         return;
     }
     const aliasMap = getAliasMap(ALIAS_PREFIX.iteration);
-    printTable(["#", "LABEL", "NAME", "TESTERS", "CREATED"], iterations.map((it) => {
-        const testers = Array.isArray(it.testers) ? it.testers.length : 0;
+    printTable(["#", "LABEL", "NAME", "PARTICIPANTS", "CREATED"], iterations.map((it) => {
+        const participants = Array.isArray(it.participants) ? it.participants.length : 0;
         return [
             aliasMap.get(String(it.id)) || String(it.id || ""),
             String(it.label || "-"),
             String(it.name || ""),
-            String(testers),
+            String(participants),
             formatDate(it.created_at),
         ];
     }));
 }
-// --- Tester formatting ---
-export function formatTesterDetail(tester, json) {
+// --- Participant formatting ---
+export function formatParticipantDetail(participant, json) {
     if (json) {
-        console.log(jsonOutput(tester));
+        console.log(jsonOutput(participant));
         return;
     }
-    const profile = tester.tester_profile;
+    const profile = participant.person;
     const profileName = profile?.name ? String(profile.name) : "Unknown";
-    const interactions = Array.isArray(tester.interactions) ? tester.interactions : [];
+    const interactions = Array.isArray(participant.interactions) ? participant.interactions : [];
     // Count sentiments
     const sentimentCounts = {};
     for (const interaction of interactions) {
@@ -1345,17 +1406,17 @@ export function formatTesterDetail(tester, json) {
         }
     }
     const sentimentParts = Object.entries(sentimentCounts).map(([label, count]) => `${count} ${label.toLowerCase()}`);
-    const status = String(tester.status || "-");
-    const errorMessage = tester.error_message ? String(tester.error_message) : null;
+    const status = String(participant.status || "-");
+    const errorMessage = participant.error_message ? String(participant.error_message) : null;
     const display = {
-        ID: tester.id || "-",
+        ID: participant.id || "-",
         Profile: profileName,
         Status: status,
         ...(errorMessage && status.toLowerCase() === "failed" && {
             Error: errorMessage,
         }),
-        Platform: tester.platform || "-",
-        Language: tester.language || "-",
+        Platform: participant.platform || "-",
+        Language: participant.language || "-",
         Interactions: `${interactions.length} interactions`,
         ...(sentimentParts.length > 0 && {
             Sentiment: sentimentParts.join(", "),
@@ -1363,8 +1424,8 @@ export function formatTesterDetail(tester, json) {
     };
     printKeyValue(display);
 }
-// --- Tester Profile formatting ---
-export function formatTesterProfileList(profiles, json, limit) {
+// --- Participant Profile formatting ---
+export function formatPersonList(profiles, json, limit) {
     // The API may return { items: [...], total, limit, offset } or a flat array.
     const wrapper = profiles;
     const wasWrapper = !Array.isArray(profiles)
@@ -1377,7 +1438,7 @@ export function formatTesterProfileList(profiles, json, limit) {
                 : [];
     // Client-side limit (server may not enforce it)
     const list = limit ? fullList.slice(0, limit) : fullList;
-    injectAliases(list, ALIAS_PREFIX.testerProfile);
+    injectAliases(list, ALIAS_PREFIX.person);
     if (json) {
         // Pass through server-provided pagination when present; otherwise synthesize.
         const existing = wasWrapper ? wrapper : undefined;
@@ -1385,7 +1446,7 @@ export function formatTesterProfileList(profiles, json, limit) {
         return;
     }
     if (list.length === 0) {
-        console.log("No tester profiles.");
+        console.log("No participant profiles.");
         return;
     }
     printTable(["#", "NAME", "OCCUPATION", "COUNTRY", "GENDER", "AGE"], list.map((p) => [
@@ -1400,31 +1461,35 @@ export function formatTesterProfileList(profiles, json, limit) {
         console.log(`\n  Showing ${list.length} of ${fullList.length} profiles. Use --limit and --offset for more.`);
     }
 }
-// --- Audience source formatting ---
-export function formatAudienceSource(source, json) {
-    if (source.id) {
-        source.alias = deterministicAlias(ALIAS_PREFIX.testerProfileSource, String(source.id));
+// --- Participant attachment formatting ---
+//
+// `formatAttachment` is the canonical printer. `formatPersonSource` is
+// an alias for callers that reference the person-source name.
+export function formatAttachment(attachment, json) {
+    if (attachment.id) {
+        attachment.alias = deterministicAlias(ALIAS_PREFIX.personSource, String(attachment.id));
     }
     if (json) {
-        console.log(jsonOutput(source));
+        console.log(jsonOutput(attachment));
         return;
     }
     const display = {
-        Alias: source.alias || source.id || "-",
-        File: source.original_filename || "-",
-        Kind: source.kind || "-",
-        Status: source.status || "-",
-        "Content-Type": source.content_type || "-",
+        Alias: attachment.alias || attachment.id || "-",
+        File: attachment.file_name || attachment.original_filename || "-",
+        Kind: attachment.kind || "-",
+        Status: attachment.status || "-",
+        "Content-Type": attachment.content_type || "-",
     };
-    if (source.extracted_text_length != null) {
-        display["Text length"] = source.extracted_text_length;
+    if (attachment.extracted_text_length != null) {
+        display["Text length"] = attachment.extracted_text_length;
     }
-    if (source.error) {
-        display.Error = source.error;
+    if (attachment.error) {
+        display.Error = attachment.error;
     }
     printKeyValue(display);
 }
-// --- Generated profile list (returned by /tester-profiles/generate) ---
+export const formatPersonSource = formatAttachment;
+// --- Generated profile list (returned by /people/generate) ---
 export function formatGeneratedProfileList(profiles, json) {
     const list = Array.isArray(profiles) ? profiles : [];
     if (list.length === 0) {
@@ -1434,7 +1499,7 @@ export function formatGeneratedProfileList(profiles, json) {
             console.log("No profiles generated.");
         return;
     }
-    injectAliases(list, ALIAS_PREFIX.testerProfile);
+    injectAliases(list, ALIAS_PREFIX.person);
     if (json) {
         console.log(jsonOutput(list));
         return;
@@ -1457,26 +1522,26 @@ export function formatSimulationPoll(results, json, isMedia = false) {
             console.log("No simulations found.");
         return;
     }
-    injectAliases(results, ALIAS_PREFIX.tester);
+    injectAliases(results, ALIAS_PREFIX.participant);
     if (json) {
         console.log(jsonOutput(results));
         return;
     }
-    const aliasMap = getAliasMap(ALIAS_PREFIX.tester);
+    const aliasMap = getAliasMap(ALIAS_PREFIX.participant);
     const countHeader = isMedia ? "SEGMENTS" : "INTERACTIONS";
-    printTable(["#", "TESTER", "STATUS", countHeader], results.map((r) => {
-        const id = String(r.id || r.tester_id || "");
+    printTable(["#", "PARTICIPANT", "STATUS", countHeader], results.map((r) => {
+        const id = String(r.id || r.participant_id || "");
         return [
             aliasMap.get(id) || id,
-            String(r.tester_name || "Unknown"),
+            String(r.participant_name || "Unknown"),
             String(r.status || "UNKNOWN"),
             String(r.interaction_count ?? "0"),
         ];
     }));
-    // Pattern A (cli half): list per-tester error_message under the table so
-    // agents see why a simulation failed without re-fetching every tester.
+    // Pattern A (cli half): list per-participant error_message under the table so
+    // agents see why a simulation failed without re-fetching every participant.
     // Truncate to 200 chars; full text is available via --json or
-    // `ish study tester get <id>`.
+    // `ish study participant get <id>`.
     const failedRows = results.filter((r) => {
         const status = String(r.status || "").toLowerCase();
         return (status === "failed" || status === "errored") && r.error_message;
@@ -1484,9 +1549,9 @@ export function formatSimulationPoll(results, json, isMedia = false) {
     if (failedRows.length > 0) {
         console.log("\nFailed simulations:");
         for (const r of failedRows) {
-            const id = String(r.id || r.tester_id || "");
+            const id = String(r.id || r.participant_id || "");
             const alias = aliasMap.get(id) || id;
-            const name = String(r.tester_name || "Unknown");
+            const name = String(r.participant_name || "Unknown");
             console.log(`  ${alias} (${name}): ${truncate(String(r.error_message), 200)}`);
         }
     }
@@ -1509,11 +1574,11 @@ export function formatAskList(asks, json) {
         return;
     }
     const aliasMap = getAliasMap(ALIAS_PREFIX.ask);
-    printTable(["#", "NAME", "STATUS", "AUDIENCE", "ROUNDS", "LAST ROUND", "ARCHIVED"], asks.map((a) => [
+    printTable(["#", "NAME", "STATUS", "PARTICIPANTS", "ROUNDS", "LAST ROUND", "ARCHIVED"], asks.map((a) => [
         aliasMap.get(String(a.id)) || String(a.id || ""),
         String(a.name || ""),
         String(a.status || "-"),
-        String(a.audience_count ?? "0"),
+        String(a.participant_count ?? "0"),
         String(a.round_count ?? "0"),
         formatDate(a.last_round_at),
         a.is_archived ? "yes" : "no",
@@ -1550,7 +1615,7 @@ function denormalizeRoundCounts(round) {
  * Layer denormalized counts onto an ask detail so agents reading
  * `ask get`, `ask create --wait`, `ask run --wait`, etc. don't need to
  * count nested arrays:
- *   - testers_count:      ask.testers.length
+ *   - participants_count:      ask.participants.length
  *   - responses_total:    sum across rounds (only when > 0)
  *   - responses_complete: sum across rounds
  *   - responses_errored:  sum across rounds (only when > 0)
@@ -1558,9 +1623,9 @@ function denormalizeRoundCounts(round) {
  */
 function denormalizeAskCounts(ask) {
     const enriched = { ...ask };
-    const testers = Array.isArray(ask.testers) ? ask.testers : null;
-    if (testers)
-        enriched.testers_count = testers.length;
+    const participants = Array.isArray(ask.participants) ? ask.participants : null;
+    if (participants)
+        enriched.participants_count = participants.length;
     const rounds = Array.isArray(ask.rounds) ? ask.rounds : null;
     if (rounds) {
         let total = 0;
@@ -1597,22 +1662,22 @@ export function formatAskDetail(ask, json) {
         meta.push("archived");
     meta.push(formatDate(ask.created_at));
     console.log(meta.join(" · "));
-    const testers = Array.isArray(ask.testers) ? ask.testers : [];
-    console.log(`\nAudience (${testers.length}):`);
-    if (testers.length > 0) {
-        const rows = testers.slice(0, 20).map((t) => {
+    const participants = Array.isArray(ask.participants) ? ask.participants : [];
+    console.log(`\nParticipants (${participants.length}):`);
+    if (participants.length > 0) {
+        const rows = participants.slice(0, 20).map((t) => {
             const obj = t;
-            const profile = obj.tester_profile;
+            const profile = obj.person;
             const name = String(profile?.name || obj.instance_name || "Unknown");
             return [
-                obj.id ? deterministicAlias(ALIAS_PREFIX.tester, String(obj.id)) : "-",
+                obj.id ? deterministicAlias(ALIAS_PREFIX.participant, String(obj.id)) : "-",
                 name,
                 String(obj.status || "-"),
             ];
         });
         printTable(["#", "NAME", "STATUS"], rows);
-        if (testers.length > 20)
-            console.log(`  … and ${testers.length - 20} more`);
+        if (participants.length > 20)
+            console.log(`  … and ${participants.length - 20} more`);
     }
     const rounds = Array.isArray(ask.rounds) ? ask.rounds : [];
     if (rounds.length > 0) {
@@ -1709,18 +1774,18 @@ function computeVariantStats(round) {
 const ERROR_RATE_REFUSE_THRESHOLD = 0.5;
 const N_HIGH_CONFIDENCE_FLOOR = 10;
 const N_MEDIUM_CONFIDENCE_FLOOR = 3;
-// When tester_profile and tester_profile_snapshot share all overlapping fields
+// When person and person_snapshot share all overlapping fields
 // (the common case — snapshot only diverges if the profile was edited after
 // dispatch), drop the redundant content from the snapshot and keep only the
-// snapshot-specific metadata. Saves ~500-1000 bytes per tester in JSON output.
-function dedupeTesterSnapshot(tester) {
-    const tp = tester.tester_profile;
-    const tps = tester.tester_profile_snapshot;
+// snapshot-specific metadata. Saves ~500-1000 bytes per participant in JSON output.
+function dedupeParticipantSnapshot(participant) {
+    const tp = participant.person;
+    const tps = participant.person_snapshot;
     if (!tp || !tps)
-        return tester;
+        return participant;
     const shared = Object.keys(tps).filter((k) => k in tp);
     if (shared.length === 0)
-        return tester;
+        return participant;
     const isEmpty = (v) => {
         if (v === null || v === undefined)
             return true;
@@ -1738,15 +1803,15 @@ function dedupeTesterSnapshot(tester) {
         return JSON.stringify(a) === JSON.stringify(b);
     });
     if (!allMatch)
-        return tester;
+        return participant;
     const snapshotOnly = {};
     for (const k of Object.keys(tps)) {
         if (!(k in tp))
             snapshotOnly[k] = tps[k];
     }
     return {
-        ...tester,
-        tester_profile_snapshot: { ...snapshotOnly, _matches_tester_profile: true },
+        ...participant,
+        person_snapshot: { ...snapshotOnly, _matches_person: true },
     };
 }
 // Shape per-variant stats into a machine-readable aggregates object so agents
@@ -1796,11 +1861,11 @@ function buildAggregates(round, stats) {
         }
         out.picks = picks;
         // Pattern H: pick_buckets keyed by variant id (the value `add_ask_round
-        // --subset-variant` accepts) → tester_ids that picked it. Pre-seed with
+        // --subset-variant` accepts) → participant_ids that picked it. Pre-seed with
         // every declared variant id so unpicked variants surface as empty
         // arrays. Only completed responses with a resolvable variant_pick_id
         // contribute; an errored response carrying a stale variant_pick_id
-        // would otherwise drag a tester into a drill-in audience whose pick
+        // would otherwise drag a participant into a drill-in subset whose pick
         // we can't trust.
         const variants = Array.isArray(round.variants) ? round.variants : [];
         const variantIdSet = new Set();
@@ -1818,7 +1883,7 @@ function buildAggregates(round, stats) {
                 if (resp.status !== "completed")
                     continue;
                 const vpid = resp.variant_pick_id;
-                const tid = resp.tester_id;
+                const tid = resp.participant_id;
                 if (typeof vpid === "string"
                     && variantIdSet.has(vpid)
                     && typeof tid === "string"
@@ -1831,7 +1896,7 @@ function buildAggregates(round, stats) {
         if (topCount > 0) {
             // Refuse the winner when more than half of dispatched responses errored.
             // Calling A or B with a 4/5 failure rate would mislead the agent into
-            // treating one tester's pick as a verdict.
+            // treating one participant's pick as a verdict.
             if (dispatchedTotal > 0
                 && erroredTotal / dispatchedTotal > ERROR_RATE_REFUSE_THRESHOLD) {
                 out.winner = {
@@ -1879,7 +1944,7 @@ function buildAggregates(round, stats) {
  *   - medium: 3 <= n < 10 (small sample but clean)
  *   - high:   n >= 10 AND no errored responses AND not tied
  *
- * Tuned for the typical 5-tester ask: a clean 5/5 lands at "medium" (you
+ * Tuned for the typical 5-participant ask: a clean 5/5 lands at "medium" (you
  * can probably trust the lean), 1/5 with no errors lands at "low" (you
  * need more data), 5/5 with a tie lands at "low" (no winner to call).
  */
@@ -1949,15 +2014,15 @@ export function formatAskResults(ask, json, roundFilter) {
             errored += decorated.responses_errored ?? 0;
             return aggregates ? { ...decorated, aggregates } : decorated;
         });
-        const testers = Array.isArray(ask.testers) ? ask.testers : undefined;
-        const dedupedTesters = testers
-            ? testers.map((t) => dedupeTesterSnapshot(t))
+        const participants = Array.isArray(ask.participants) ? ask.participants : undefined;
+        const dedupedParticipants = participants
+            ? participants.map((t) => dedupeParticipantSnapshot(t))
             : undefined;
         const payload = { ...ask, rounds: enrichedRounds };
-        if (dedupedTesters)
-            payload.testers = dedupedTesters;
-        if (testers)
-            payload.testers_count = testers.length;
+        if (dedupedParticipants)
+            payload.participants = dedupedParticipants;
+        if (participants)
+            payload.participants_count = participants.length;
         if (total > 0) {
             payload.responses_total = total;
             payload.responses_complete = complete;
@@ -2015,8 +2080,8 @@ export function formatAskResults(ask, json, roundFilter) {
             for (const r of completed.slice(0, 10)) {
                 const resp = r;
                 const comment = resp.comment ? truncate(String(resp.comment), 120) : "-";
-                const tester = resp.tester_id ? deterministicAlias(ALIAS_PREFIX.tester, String(resp.tester_id)) : "-";
-                console.log(`    ${tester}: ${comment}`);
+                const participant = resp.participant_id ? deterministicAlias(ALIAS_PREFIX.participant, String(resp.participant_id)) : "-";
+                console.log(`    ${participant}: ${comment}`);
             }
             if (completed.length > 10) {
                 console.log(`    … and ${completed.length - 10} more`);