@ishlabs/cli 0.21.0 → 0.23.0

package/dist/commands/chat.js

@@ -115,7 +115,7 @@ Examples:
     });
     parent
         .command("create")
-        .description("Create a chatbot endpoint from a config file or stdin")
+        .description("Create a chatbot endpoint from a hand-written ChatbotEndpointConfig JSON (advanced — use `chat endpoint init` to infer the config from a curl sample, JSON, or template).")
         .requiredOption("--endpoint-config <file>", 'Path to JSON file (or "-" for stdin)')
         .option("--name <name>", "Override the name from the config file")
         .option("--workspace <id>", "Workspace ID")
@@ -342,7 +342,7 @@ endpoint, apply the override, and PUT the merged result. Field flags win over
 function attachChatEndpointInit(parent) {
     parent
         .command("init")
-        .description("Author an endpoint from a curl/JSON sample via test-and-map, or from a known-good template")
+        .description("Author an endpoint from a curl/JSON sample via test-and-map, or from a known-good template (recommended for most users — use `chat endpoint create` only when you already have a hand-written ChatbotEndpointConfig).")
         .option("--from-curl <file>", 'Path to a curl example file (or "-" for stdin)')
         .option("--from-json <file>", 'Path to a JSON request/response sample (or "-" for stdin)')
         .option("--template <name>", `Start from a known-good template (one of: ${TEMPLATE_NAMES.join(", ")})`)

package/dist/commands/config.js

@@ -78,11 +78,25 @@ Run \`ish docs overview\` for the full mental model.`);
     });
     config
         .command("schema")
-        .description("Get simulation config schema with defaults")
+        .description("Get simulation config schema with defaults (admin-only — non-admin accounts: ask an admin to share an existing config ID and pass it via `ish study run --config <id>`).")
         .action(async (_opts, cmd) => {
         await withClient(cmd, async (client, globals) => {
-            const data = await client.get("/dev/simulation-configs/schema");
-            output(data, globals.json);
+            try {
+                const data = await client.get("/dev/simulation-configs/schema");
+                output(data, globals.json);
+            }
+            catch (err) {
+                // Pattern Z: re-throw with a hint pointing non-admin agents at the
+                // workaround (use a shared config ID via `study run --config`).
+                if (err instanceof Error && err.status === 403) {
+                    const tagged = err;
+                    const extra = "Non-admin accounts cannot introspect the simulation-config schema. To still use a config, ask an admin to share an existing config ID and pass it via `ish study run --config <id>` (`config --help` for the full workflow).";
+                    tagged.suggestions = Array.isArray(tagged.suggestions)
+                        ? [...tagged.suggestions, extra]
+                        : [extra];
+                }
+                throw err;
+            }
         });
     });
     config

package/dist/commands/source.js

@@ -27,7 +27,7 @@ same attachment across multiple generation runs; otherwise pass a local path dir
 to \`person generate --source\` and it auto-uploads.
 
 Concept pages: ish docs get-page concepts/source
-                ish docs get-page concepts/profile`);
+                ish docs get-page concepts/person`);
     source
         .command("upload")
         .description("Upload a file as a participant attachment and wait for processing")

package/dist/commands/study-analyze.js

@@ -14,7 +14,7 @@
  * about latency than load).
  */
 import { withClient, resolveStudy, parseWaitTimeout } from "../lib/command-helpers.js";
-import { resolveId } from "../lib/alias-store.js";
+import { resolveId, tagAlias, ALIAS_PREFIX } from "../lib/alias-store.js";
 import { output, printTable } from "../lib/output.js";
 import { WaitTimeoutError } from "./study-run.js";
 const POLL_INTERVAL_MS = 5_000;
@@ -160,11 +160,24 @@ Trigger a new run with \`ish study analyze --wait\`.`)
             const history = await client.get(`/studies/${studyId}/results`);
             const latest = history[0] ?? null;
             if (globals.json) {
+                // Pattern K: never emit empty stdout. When no analyses have run,
+                // ship a stable envelope with a hint pointing at the verb that
+                // populates it. Mirrors the `study results` empty-envelope contract.
+                if (!latest) {
+                    const studyAlias = tagAlias(ALIAS_PREFIX.study, studyId);
+                    output({
+                        latest: null,
+                        history: [],
+                        hint: `No analyses run yet. Trigger one with \`ish study analyze ${studyAlias}\`.`,
+                    }, true, { preProjected: true });
+                    return;
+                }
                 output({ latest, history }, true);
                 return;
             }
             if (!latest) {
-                console.log("No analysis runs yet. Trigger one with `ish study analyze`.");
+                const studyAlias = tagAlias(ALIAS_PREFIX.study, studyId);
+                console.log(`No analysis runs yet. Trigger one with \`ish study analyze ${studyAlias}\`.`);
                 return;
             }
             if (opts.all) {

package/dist/commands/study-participant.js

@@ -76,6 +76,25 @@ Tips:
             const result = data;
             if (result.id)
                 result.alias = tagAlias(ALIAS_PREFIX.participant, String(result.id));
+            // Pattern L: enrich with parent-graph aliases so agents can traverse
+            // from a participant straight to its study without hopping through
+            // `iteration get`. The participant response carries `iteration_id` but
+            // not `study_id`; one iteration fetch supplies both.
+            const iterationId = typeof result.iteration_id === "string" ? result.iteration_id : null;
+            if (iterationId) {
+                result.iteration_alias = tagAlias(ALIAS_PREFIX.iteration, iterationId);
+                try {
+                    const iter = await client.get(`/iterations/${iterationId}`);
+                    if (typeof iter.study_id === "string") {
+                        result.study_id = iter.study_id;
+                        result.study_alias = tagAlias(ALIAS_PREFIX.study, iter.study_id);
+                    }
+                }
+                catch {
+                    // Best-effort enrichment; if the iteration fetch fails (deleted,
+                    // permission), keep going with the alias we already injected.
+                }
+            }
             if (opts.summary) {
                 output(buildParticipantSummary(result), globals.json, { preProjected: true });
                 return;

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

@@ -44,6 +44,8 @@ interface ParticipantStatusRow {
     participant_name: string;
     interaction_count: number;
     error_message?: string;
+    error_kind?: string;
+    age_seconds?: number;
 }
 export declare function attachStudyRunCommands(study: Command): void;
 export {};

package/dist/commands/study-run.js

@@ -108,6 +108,26 @@ 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"]);
+// If any running participant has been alive longer than this on the
+// server, the wait-timeout message picks up an explicit "likely stuck"
+// hint. Sized just above the worker's in-process stale-heartbeat
+// threshold (600s) so the suggestion matches the backend reaper's
+// verdict (see app/services/jobs/cleanup_stale_participants.py).
+const LIKELY_STUCK_AGE_SECONDS = 900;
+function buildWaitTimeoutMessage(opts) {
+    const base = `Timed out after ${opts.timeoutSeconds}s waiting for simulations. ` +
+        `${opts.done}/${opts.total} done. ${opts.resumeHint}`;
+    const likelyStuck = opts.rows.some((r) => typeof r.age_seconds === "number" &&
+        r.age_seconds >= LIKELY_STUCK_AGE_SECONDS &&
+        !TERMINAL_STATUSES.has(r.status));
+    if (!likelyStuck)
+        return base;
+    return (base +
+        " At least one participant has been running >15 min (see " +
+        "`progress.rows[].age_seconds`); the worker likely died. The " +
+        "backend reaper will mark it FAILED(stale_worker) within ~15 min — " +
+        "don't keep polling.");
+}
 function flattenParticipantStatuses(participants, opts = {}) {
     const rows = [];
     for (const t of participants ?? []) {
@@ -128,6 +148,8 @@ function flattenParticipantStatuses(participants, opts = {}) {
             participant_name: t.person?.name || "Unknown",
             interaction_count: Array.isArray(t.interactions) ? t.interactions.length : 0,
             ...(errorMessage && { error_message: String(errorMessage) }),
+            ...(t.error_kind && { error_kind: t.error_kind }),
+            ...(typeof t.age_seconds === "number" && { age_seconds: t.age_seconds }),
         });
     }
     return rows;
@@ -171,8 +193,13 @@ async function pollStudyUntilDone(client, opts) {
                 return { rows, isMedia };
             }
             if (Date.now() - start > opts.timeoutMs) {
-                throw new WaitTimeoutError(`Timed out after ${Math.round(opts.timeoutMs / 1000)}s waiting for simulations. ` +
-                    `${done}/${total} done. Run \`ish study poll --study ${opts.studyId}\` to check status.`, {
+                throw new WaitTimeoutError(buildWaitTimeoutMessage({
+                    timeoutSeconds: Math.round(opts.timeoutMs / 1000),
+                    done,
+                    total,
+                    rows,
+                    resumeHint: `Run \`ish study poll --study ${opts.studyId}\` to check status.`,
+                }), {
                     study_id: opts.studyId,
                     ...(opts.iterationId && { iteration_id: opts.iterationId }),
                     timeout_seconds: Math.round(opts.timeoutMs / 1000),
@@ -1128,20 +1155,32 @@ Examples:
                         // 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 participant ${participantId}. Last status: ${status}.`, {
+                        const ageSeconds = typeof data.age_seconds === "number"
+                            ? data.age_seconds
+                            : undefined;
+                        const rows = [
+                            {
+                                id: resolvedParticipant,
+                                status,
+                                participant_name: String(data.participant_name ?? "Unknown"),
+                                interaction_count: 0,
+                                ...(data.error_kind && { error_kind: String(data.error_kind) }),
+                                ...(typeof ageSeconds === "number" && { age_seconds: ageSeconds }),
+                            },
+                        ];
+                        throw new WaitTimeoutError(buildWaitTimeoutMessage({
+                            timeoutSeconds: Math.round(timeoutMs / 1000),
+                            done: 0,
+                            total: 1,
+                            rows,
+                            resumeHint: `Last status: ${status}.`,
+                        }), {
                             study_id: resolvedParticipant,
                             timeout_seconds: Math.round(timeoutMs / 1000),
                             done: 0,
                             total: 1,
                             pending: 1,
-                            rows: [
-                                {
-                                    id: resolvedParticipant,
-                                    status,
-                                    participant_name: String(data.participant_name ?? "Unknown"),
-                                    interaction_count: 0,
-                                },
-                            ],
+                            rows,
                         });
                     }
                     await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
@@ -1352,20 +1391,32 @@ 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 participant ${newAlias}. Last status: ${s}.`, {
+                    const ageSeconds = typeof status.age_seconds === "number"
+                        ? status.age_seconds
+                        : undefined;
+                    const rows = [
+                        {
+                            id: newParticipantId,
+                            status: s,
+                            participant_name: String(status.participant_name ?? "Unknown"),
+                            interaction_count: typeof status.interaction_count === "number" ? status.interaction_count : 0,
+                            ...(status.error_kind && { error_kind: String(status.error_kind) }),
+                            ...(typeof ageSeconds === "number" && { age_seconds: ageSeconds }),
+                        },
+                    ];
+                    throw new WaitTimeoutError(buildWaitTimeoutMessage({
+                        timeoutSeconds: Math.round(timeoutMs / 1000),
+                        done: 0,
+                        total: 1,
+                        rows,
+                        resumeHint: `Last status: ${s}.`,
+                    }), {
                         study_id: newParticipantId,
                         timeout_seconds: Math.round(timeoutMs / 1000),
                         done: 0,
                         total: 1,
                         pending: 1,
-                        rows: [
-                            {
-                                id: newParticipantId,
-                                status: s,
-                                participant_name: String(status.participant_name ?? "Unknown"),
-                                interaction_count: typeof status.interaction_count === "number" ? status.interaction_count : 0,
-                            },
-                        ],
+                        rows,
                     });
                 }
                 await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));

package/dist/commands/study.js

@@ -8,7 +8,7 @@ import { resolveId, tagAlias, ALIAS_PREFIX } from "../lib/alias-store.js";
 import { loadConfig, saveConfig } from "../config.js";
 import { formatStudyList, formatStudyDetail, formatStudyResults, buildStudyResultsEnvelope, buildStudyResultsSummary, buildChatTranscript, formatStudyResultsGroupBy, output, ValidationError, } from "../lib/output.js";
 import { applyResultsFilters } from "../lib/study-results-filters.js";
-import { buildStudyResultsPerIteration, buildStudyResultsPerFrame, buildStudyResultsPerSegment, buildStudyResultsPerTurn, buildStudyResultsPerAssignment, buildStudyResultsPerStep, } from "../lib/study-results-projections.js";
+import { buildStudyResultsPerIteration, buildStudyResultsPerFrame, buildStudyResultsPerSegment, buildStudyResultsPerTurn, buildStudyResultsPerAssignment, buildStudyResultsPerStep, wrapSliceProjection, } from "../lib/study-results-projections.js";
 import { VALID_CONTENT_TYPES } from "../lib/types.js";
 import { fetchStudyParticipants } from "../lib/study-participants.js";
 import { parseAssignment, loadAssignmentsFile, validateAssignmentsArray, parseQuestion } from "../lib/study-inputs.js";
@@ -611,7 +611,7 @@ Next: configure a run with \`ish iteration create --study <id>\`,
     });
     study
         .command("get")
-        .description("Get study overview (accepts multiple IDs for batched lookup)")
+        .description("Get the full study payload — iterations (with run details), assignments, interview questions, sentiment + status counts. Accepts multiple IDs for batched lookup. NOTE: this is the full payload, not a roll-up — for a compact cross-study comparison view use `study results <id> --summary`.")
         .argument("<ids...>", "Study ID(s) — one or more aliases/UUIDs (space- or comma-separated)")
         .addHelpText("after", `
 Examples:
@@ -636,6 +636,18 @@ list table layout in human mode.`)
                 const result = data;
                 if (result.id)
                     result.alias = tagAlias(ALIAS_PREFIX.study, String(result.id));
+                // Pattern I-r3-1: inline iterations carry only label/name/details
+                // from the wire; tag each with its `alias` (computed from id via
+                // the local alias-store) so agents can drill from `study get` into
+                // `iteration get <alias>` / `study results --iteration <alias>`
+                // without a separate `iteration list` round-trip.
+                if (Array.isArray(result.iterations)) {
+                    for (const iter of result.iterations) {
+                        if (typeof iter.id === "string") {
+                            iter.alias = tagAlias(ALIAS_PREFIX.iteration, iter.id);
+                        }
+                    }
+                }
                 if (data.product_id) {
                     result.url = getWebUrl(globals, `/${data.product_id}/${rid}/overview`);
                 }
@@ -655,6 +667,13 @@ list table layout in human mode.`)
                 const r = data;
                 if (r.id)
                     r.alias = tagAlias(ALIAS_PREFIX.study, String(r.id));
+                if (Array.isArray(r.iterations)) {
+                    for (const iter of r.iterations) {
+                        if (typeof iter.id === "string") {
+                            iter.alias = tagAlias(ALIAS_PREFIX.iteration, iter.id);
+                        }
+                    }
+                }
                 if (data.product_id) {
                     r.url = getWebUrl(globals, `/${data.product_id}/${rid}/overview`);
                 }
@@ -671,7 +690,7 @@ list table layout in human mode.`)
     });
     study
         .command("results")
-        .description("View aggregated results: participant counts, sentiment, interview answers. Returns a stable envelope with empty fields when no runs have completed. Slice with filter flags (--frame, --segment, --turn, --side, --assignment, --step, --sentiment, --actor, --iteration, --participant) or project with --group-by (iteration|frame|segment|turn|assignment|step).")
+        .description("View aggregated results: participant counts, sentiment, interview answers. Returns a stable envelope with empty fields when no runs have completed. Slice with filter flags (--frame [interactive], --segment [video/audio/text/document], --turn [chat], --side [chat participant_pair], --assignment, --step, --sentiment, --actor, --iteration, --participant) or project with --group-by <axis> (iteration | frame [interactive] | segment [media] | turn [chat] | assignment | step).")
         .argument("<id>", "Study ID")
         .option("--workspace <id>", "Workspace ID; accepted for consistency (workspace is inferred from the study)")
         .option("--summary", "Lean summary projection: counts + sentiment + per-participant {alias, status, sentiment, comment}. Drops interview_answers + per-interaction breakdowns. Composes with filters: `--summary --frame login` narrows the summary to the login-screen interactions.")
@@ -688,7 +707,7 @@ list table layout in human mode.`)
         .option("--side <a|b>", "Filter participant_pair chat interactions by assignment side. Other modalities: warned and ignored.")
         .option("--assignment <ref>", "Filter to a single assignment by UUID or name (substring, case-insensitive).")
         .option("--step <ref>", "Filter `participant_assignments[].step_results[]` to a single step by step-id or name (substring). Pair with --include-evidence to also drop non-evidence interactions.")
-        .option("--sentiment <labels>", "Filter to interactions whose sentiment.label is in the comma-separated list (case-insensitive; repeatable). Drops null-sentiment rows.", collectIds, [])
+        .option("--sentiment <labels>", "Filter to interactions whose sentiment.label is in the comma-separated list (case-insensitive; repeatable). Drops interactions whose sentiment is null. A participant is kept when at least one of their interactions matches, even if their aggregate session sentiment is null (e.g. failed runs with a pre-error matching interaction).", collectIds, [])
         .option("--actor <actor>", "Filter to interactions whose actor is `ai`, `human`, or `user` (case-insensitive).")
         .option("--iteration <ref>", "Restrict to a single iteration by UUID or label.")
         .option("--participant <ref>", "Restrict to a single participant by UUID or `pt-…` alias.")
@@ -713,6 +732,7 @@ Default --json envelope (M10: per-answer sentiment now included):
     "participant_count": 12,
     "completed_count": 8,
     "failed_count": 0,
+    "participant_status_counts": { "completed": 8, "running": 3, "draft": 1 },
     "sentiment": { "counts": { "Satisfied": 5, "Frustrated": 2 }, "total": 7 },
     "interview_answers": [
       { "question": "...", "type": "text",
@@ -733,6 +753,12 @@ When any filter flag is passed, the envelope gains a \`totals_unfiltered\` field
 ("matched 12 / 80 participants"). A zero-match filter returns the stable
 envelope with participant_count=0 and exit code 0 (not 4).
 
+Filtered count semantics: \`participant_count\` is the matched-set total (every
+participant whose interactions matched the filter — including running and
+failed). The unfiltered denominator is \`totals_unfiltered.participant_count\`,
+and the same envelope still carries \`completed_count\` / \`failed_count\` so
+agents can compute "completed AND matched" without a second call.
+
 --summary projection (M2-friction-7: drops the interview_answers payload):
   { study, participant_count, completed_count, failed_count, sentiment, participants: [...] }
 
@@ -749,23 +775,34 @@ envelope with participant_count=0 and exit code 0 (not 4).
     "participant_summary": { "comment": "...", "sentiment": {...} }
   }
 
---group-by iteration projection:
-  { study, slices: [{ iteration_id, iteration_label, participant_count, interaction_count, sentiment, sample_comments, top_actions }, ...], totals_unfiltered, warnings }
+--group-by projections share one envelope (uniform across all six axes):
+  { axis, rows, totals_unfiltered, modality_warnings, study_id, modality }
 
---group-by frame projection (interactive only):
-  [{ frame_id, frame_label, interaction_count, sentiment_histogram, sample_comments, participant_aliases }, ...]
+  axis              echoes the requested axis (iteration|frame|segment|turn|assignment|step)
+  study_id          the \`s-…\` alias
+  modality          the study's modality
+  totals_unfiltered { participant_count, interaction_count } — pre-filter counts
+  modality_warnings any filter-flag mismatches (e.g. --turn on a non-chat study)
 
---group-by segment projection (video/audio/text/document):
-  [{ segment_index, segment_label, interaction_count, sentiment_histogram, engagement_histogram, sample_comments }, ...]
+Per-axis row shape (one element of \`rows[]\`):
 
---group-by turn projection (chat only):
-  [{ turn_index, interaction_count, sentiment_histogram, sample_replies, failures }, ...]
+--group-by iteration:
+  { iteration_id, iteration_label, participant_count, interaction_count, sentiment, sample_comments, top_actions }
 
---group-by assignment projection:
-  [{ assignment_id, assignment_name, interaction_count, sentiment_histogram, step_completion }, ...]
+--group-by frame (interactive only):
+  { frame_id, frame_label, interaction_count, sentiment_histogram, sample_comments, participant_aliases }
 
---group-by step projection:
-  [{ assignment_id, assignment_name, step_id, step_name, total, passed, inconclusive, failed, rate, participant_verdicts: [{ participant_alias, verdict, reason, evidence_interaction_ids }, ...] }, ...]
+--group-by segment (video/audio/text/document):
+  { segment_index, segment_label, interaction_count, sentiment_histogram, engagement_histogram, sample_comments }
+
+--group-by turn (chat only):
+  { turn_index, interaction_count, sentiment_histogram, sample_replies, failures }
+
+--group-by assignment:
+  { assignment_id, assignment_name, interaction_count, sentiment_histogram, step_completion }
+
+--group-by step:
+  { assignment_id, assignment_name, step_id, step_name, total, passed, inconclusive, failed, rate, participant_verdicts: [{ participant_alias, verdict, reason, evidence_interaction_ids }] }
 
 Tips:
   Use \`--get <path>\` for a single value (e.g. \`--get participant_count\`),
@@ -794,17 +831,24 @@ Common --get paths (--transcript <participant_id> envelope):
   --get participant_summary.sentiment                # aggregate sentiment map
   --get unique_bot_replies                      # bot-side message count
 
-Common --get paths (--group-by projections):
-  --get slices.iteration_label                       # per-iteration: one label per line
-  --get slices.0.participant_count                   # per-iteration: first slice's count
-  --get 0.frame_label                                # per-frame: first frame's label
-  --get 0.sentiment_histogram                        # per-frame/segment/turn: first slice's sentiment map
-  --get 0.segment_index                              # per-segment: first segment's index
-  --get 0.turn_index                                 # per-turn: first turn's index
-  --get 0.assignment_name                            # per-assignment/step: first slice's assignment
-  --get 0.step_name                                  # per-step: first slice's step
-  --get 0.rate                                       # per-step: first step's pass-rate
-  --get 0.participant_verdicts.verdict               # per-step: verdict per participant
+Common --get paths (--group-by envelope — uniform across axes):
+  --get axis                                         # echoes the requested axis
+  --get study_id                                     # s-… alias
+  --get modality                                     # study's modality
+  --get modality_warnings                            # filter-flag mismatches (one warning per line)
+  --get totals_unfiltered.participant_count          # pre-filter participant count
+  --get totals_unfiltered.interaction_count          # pre-filter interaction count
+
+  --get rows.iteration_label                         # per-iteration: one label per line
+  --get rows.0.participant_count                     # per-iteration: first row's count
+  --get rows.0.frame_label                           # per-frame: first row's label
+  --get rows.0.sentiment_histogram                   # per-frame/segment/turn: first row's sentiment map
+  --get rows.0.segment_index                         # per-segment: first row's index
+  --get rows.0.turn_index                            # per-turn: first row's index
+  --get rows.0.assignment_name                       # per-assignment/step: first row's assignment
+  --get rows.0.step_name                             # per-step: first row's step
+  --get rows.0.rate                                  # per-step: first row's pass-rate
+  --get rows.0.participant_verdicts.verdict          # per-step: verdict per participant
 
 When no runs have completed, the default envelope is returned with zero counts and empty arrays.`)
         .action(async (id, opts, cmd) => {
@@ -930,15 +974,27 @@ When no runs have completed, the default envelope is returned with zero counts a
             // (devon's T7 note: projection builders are intentionally
             // modality-agnostic and bucket non-matching rows into `_unmatched`;
             // the surface is responsible for refusing nonsensical axes up front).
+            // Pattern B: modality-mismatched --group-by names the offending axis's
+            // domain AND suggests the axis that DOES apply to the study's current
+            // modality, so a cold-start agent can retry productively in one hop.
+            const axisHint = (mod) => {
+                if (mod === "interactive")
+                    return "use --group-by frame";
+                if (["video", "audio", "text", "document"].includes(mod))
+                    return "use --group-by segment";
+                if (mod === "chat")
+                    return "use --group-by turn";
+                return undefined;
+            };
             if (groupByKind === "frame" && modality !== "interactive") {
-                throw new ValidationError(`--group-by frame requires modality=interactive; this study is "${modality}".`, ["interactive"]);
+                throw new ValidationError(`--group-by frame requires modality=interactive; this study is "${modality}".`, ["interactive"], axisHint(modality));
             }
             const SEGMENT_MODALITIES = ["video", "audio", "text", "document"];
             if (groupByKind === "segment" && !SEGMENT_MODALITIES.includes(modality)) {
-                throw new ValidationError(`--group-by segment requires modality ∈ {${SEGMENT_MODALITIES.join(", ")}}; this study is "${modality}".`, SEGMENT_MODALITIES);
+                throw new ValidationError(`--group-by segment requires modality ∈ {${SEGMENT_MODALITIES.join(", ")}}; this study is "${modality}".`, SEGMENT_MODALITIES, axisHint(modality));
             }
             if (groupByKind === "turn" && modality !== "chat") {
-                throw new ValidationError(`--group-by turn requires modality=chat; this study is "${modality}".`, ["chat"]);
+                throw new ValidationError(`--group-by turn requires modality=chat; this study is "${modality}".`, ["chat"], axisHint(modality));
             }
             // Coerce the frames payload to a plain array of records (the API
             // returns a bare array). Tolerate `{items: [...]}` shape in case the
@@ -995,7 +1051,8 @@ When no runs have completed, the default envelope is returned with zero counts a
                         projection = buildStudyResultsPerStep(filtered);
                         break;
                 }
-                formatStudyResultsGroupBy(projection, groupByKind, globals.json);
+                const envelope = wrapSliceProjection(filtered, groupByKind, projection, rid, modality);
+                formatStudyResultsGroupBy(envelope, groupByKind, globals.json);
                 return;
             }
             if (wantsSummary) {
@@ -1011,13 +1068,18 @@ When no runs have completed, the default envelope is returned with zero counts a
                 return;
             }
             // Default (no --group-by, no --summary) but filters set: stable
-            // envelope on the filtered participants + totals_unfiltered. Empty
-            // slice contract: zero matches yields participant_count=0 and exit
-            // 0, never a 4/not-found.
+            // envelope on the filtered participants + totals_unfiltered + the
+            // modality_warnings array (Pattern U). Without `modality_warnings`
+            // on this envelope, agents who pipe stderr to /dev/null lose the
+            // filter-mismatch signal entirely; the `--group-by` envelope
+            // already carries it (see wrapSliceProjection), so this is just
+            // closing the asymmetry. Empty slice contract: zero matches still
+            // yields participant_count=0 and exit 0, never a 4/not-found.
             const envelope = buildStudyResultsEnvelope(filtered.study, filtered.participants);
             const envelopeOut = {
                 ...envelope,
                 totals_unfiltered: filtered.totals_unfiltered,
+                modality_warnings: filtered.warnings,
             };
             output(envelopeOut, globals.json, { preProjected: true });
         });

package/dist/lib/command-helpers.js

@@ -294,15 +294,16 @@ function enforceParticipantCap(ids, flags, opts) {
  */
 export function addPersonFilterFlags(cmd, opts = {}) {
     const allFlag = opts.allFlagName ?? "--all";
-    const allDesc = opts.allFlagDescription ?? "Use every person matching the filters";
+    const allDesc = (opts.allFlagDescription ?? "Use every person matching the filters")
+        + " (capped at 20 per dispatch — split into multiple slices for larger cohorts)";
     return cmd
         .option("--person <ids>", "Person IDs/aliases (comma-separated or repeatable)", collectIds, [])
-        .option("--sample <N>", "Randomly sample N people from the matching pool")
+        .option("--sample <N>", "Randomly sample N people from the matching pool (max 20 per dispatch — split into multiple slices for larger cohorts)")
         .option(allFlag, allDesc)
         .option("--search <text>", "Substring match against person name")
         .option("--bio <text>", "Substring match against person bio")
         .option("--occupation <text>", "Substring match against person occupation (repeatable)", collectRepeatable, [])
-        .option("--gender <gender>", "Filter by gender (repeatable)", collectRepeatable, [])
+        .option("--gender <gender>", "Filter by gender (female, male, nonbinary; repeatable, OR semantics)", collectRepeatable, [])
         .option("--country <code>", "Filter by 2-letter country code (repeatable)", collectRepeatable, [])
         .option("--min-age <n>", "Minimum age (inclusive)")
         .option("--max-age <n>", "Maximum age (inclusive)")