@ishlabs/cli 0.8.3 → 0.8.5

package/dist/lib/output.js

@@ -11,12 +11,108 @@ import { deterministicAlias, getAliasMap, ALIAS_PREFIX } from "./alias-store.js"
 // --- Lean JSON: strip noise for agent-friendly output ---
 let _verbose = false;
 let _fields;
+let _getField;
 /** Set by withClient() based on global flags. */
 export function setVerbose(v) { _verbose = v; }
 export function setFields(fields) { _fields = fields; }
+/**
+ * Pattern Ω capture mode: when set, jsonOutput() returns the bare value at
+ * the dotted path instead of the full JSON. Cleared between command runs by
+ * each invocation of `applyGlobals()`.
+ */
+export function setGetField(field) { _getField = field; }
+/**
+ * Walk a dotted path through a JSON value. Returns the resolved value or
+ * `MISSING` if any step is undefined. Numeric segments index into arrays;
+ * non-numeric segments key into objects. When a segment is non-numeric and
+ * the current value is an array, the segment is mapped over the array
+ * (e.g. `items.alias` on `{items: [...]}` after `items` is unwrapped to the
+ * array yields the per-element `alias` values).
+ */
+const MISSING = Symbol("missing");
+function walkPath(data, segments) {
+    let cur = data;
+    for (const seg of segments) {
+        if (cur === null || cur === undefined)
+            return MISSING;
+        if (Array.isArray(cur)) {
+            // `seg` could be a numeric index, or a key to apply to each element.
+            const asIndex = /^\d+$/.test(seg) ? parseInt(seg, 10) : null;
+            if (asIndex !== null) {
+                if (asIndex < 0 || asIndex >= cur.length)
+                    return MISSING;
+                cur = cur[asIndex];
+                continue;
+            }
+            // Map across array: pick the key on each element. Skip elements that
+            // lack the key so `--get items.alias` on a list with one bad row
+            // still returns the rest.
+            const mapped = [];
+            for (const el of cur) {
+                if (el !== null && typeof el === "object" && seg in el) {
+                    mapped.push(el[seg]);
+                }
+            }
+            if (mapped.length === 0)
+                return MISSING;
+            cur = mapped;
+            continue;
+        }
+        if (typeof cur !== "object")
+            return MISSING;
+        const obj = cur;
+        if (!(seg in obj))
+            return MISSING;
+        cur = obj[seg];
+    }
+    return cur;
+}
+/**
+ * Resolve `_getField` against `data`. Auto-descends into a top-level
+ * `items: [...]` wrapper when the requested path doesn't start with `items`
+ * and the path resolves on items but not at top level — i.e.
+ * `--get alias` on a list response acts like `--get items.alias`.
+ */
+function extractGetField(data, path) {
+    const segments = path.split(".").map((s) => s.trim()).filter(Boolean);
+    if (segments.length === 0)
+        return MISSING;
+    const direct = walkPath(data, segments);
+    if (direct !== MISSING)
+        return direct;
+    // Auto-descend through {items: [...]} wrapper for paginated list responses.
+    if (segments[0] !== "items"
+        && data !== null
+        && typeof data === "object"
+        && !Array.isArray(data)
+        && Array.isArray(data.items)) {
+        const viaItems = walkPath(data, ["items", ...segments]);
+        if (viaItems !== MISSING)
+            return viaItems;
+    }
+    return MISSING;
+}
+/**
+ * Render an extracted value as a bare string for stdout. Rules:
+ *   - string/number/boolean: printed as-is (no JSON quotes).
+ *   - null: empty string.
+ *   - arrays: one element per line, each element rendered by the same rules
+ *     (objects within the array are compact JSON).
+ *   - objects: compact JSON on a single line.
+ */
+function renderBare(value) {
+    if (value === null || value === undefined)
+        return "";
+    if (Array.isArray(value)) {
+        return value.map((v) => renderBare(v)).join("\n");
+    }
+    if (typeof value === "object")
+        return JSON.stringify(value);
+    return String(value);
+}
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 const TIMESTAMP_KEYS = new Set(["created_at", "updated_at"]);
-const PAGINATION_KEYS = new Set(["items", "total", "limit", "offset"]);
+const PAGINATION_KEYS = new Set(["items", "total", "returned", "limit", "offset", "has_more"]);
 /**
  * Strip UUID-valued fields, null/undefined values, and timestamps.
  * Preserves alias, name, label, status, and other meaningful fields.
@@ -69,7 +165,31 @@ function leanJson(data, keepIds = false) {
     return Object.keys(result).length > 0 ? result : undefined;
 }
 /**
- * Detect a paginated list wrapper: `{items: [...], total?, limit?, offset?}`.
+ * Standard list envelope: `{items, total, returned, limit, offset, has_more}`.
+ * If the backend already returns a wrapper, `total/limit/offset` are passed
+ * through; otherwise they're synthesized from the items array. `returned` and
+ * `has_more` are always CLI-computed so agents can detect truncation without
+ * counting items themselves.
+ *
+ * The envelope itself bypasses leanJson (`preProjected: true` at the call
+ * site) so the wrapper keys are stable even on empty lists — leanJson would
+ * otherwise drop `items: []`. Per-item lean-stripping is applied here so
+ * agents still get the lean shape inside the envelope, unless the caller has
+ * already projected items to a known shape (`preProjectedItems: true`).
+ */
+function wrapList(items, existing, opts = {}) {
+    const returned = items.length;
+    const total = typeof existing?.total === "number" ? existing.total : returned;
+    const limit = typeof existing?.limit === "number" ? existing.limit : returned;
+    const offset = typeof existing?.offset === "number" ? existing.offset : 0;
+    const has_more = total > offset + returned;
+    const leanItems = _verbose || opts.preProjectedItems
+        ? items
+        : leanJson(items) ?? [];
+    return { items: leanItems, total, returned, limit, offset, has_more };
+}
+/**
+ * Detect a paginated list wrapper: `{items, total?, returned?, limit?, offset?, has_more?}`.
  * Used so `--fields` filters per-item shape without dropping pagination metadata.
  */
 function isListWrapper(data) {
@@ -127,6 +247,19 @@ function jsonOutput(data, options = {}) {
     if (_fields && _fields.length > 0) {
         out = pickFields(out, _fields);
     }
+    // Pattern Ω capture mode: --get <field> returns bare values instead of
+    // structured JSON. We extract from the post-lean / post-fields data so the
+    // path the agent reasons about matches what they'd see on a normal --json
+    // call (e.g. UUIDs already replaced by aliases).
+    if (_getField) {
+        const extracted = extractGetField(out, _getField);
+        if (extracted === MISSING) {
+            const err = new Error(`--get: field "${_getField}" not found in response.`);
+            err.name = "ValidationError";
+            throw err;
+        }
+        return renderBare(extracted);
+    }
     return JSON.stringify(out, null, 2);
 }
 /**
@@ -142,9 +275,29 @@ function injectAliases(items, prefix, idField = "id") {
     }
 }
 // --- JSON mode ---
+/**
+ * Catch jsonOutput's --get extraction failure (a ValidationError thrown when
+ * the requested field is missing) and route it through outputError + exit 2,
+ * so commands that don't go through withClient/runInline (e.g. `ish docs *`)
+ * still surface a clean usage error instead of an uncaught stack trace.
+ */
+function safeJsonOutput(data, options = {}) {
+    try {
+        return jsonOutput(data, options);
+    }
+    catch (err) {
+        if (err instanceof Error && err.name === "ValidationError") {
+            outputError(err, true);
+            process.exit(2);
+        }
+        throw err;
+    }
+}
 export function output(data, json, options = {}) {
     if (json) {
-        console.log(jsonOutput(data, options));
+        const text = safeJsonOutput(data, options);
+        if (text !== undefined)
+            console.log(text);
         return;
     }
     if (data === null || data === undefined)
@@ -161,7 +314,9 @@ export function output(data, json, options = {}) {
 }
 export function outputList(rows, json) {
     if (json) {
-        console.log(jsonOutput(rows));
+        const text = safeJsonOutput(rows);
+        if (text !== undefined)
+            console.log(text);
         return;
     }
     if (rows.length === 0) {
@@ -198,6 +353,21 @@ export class ValidationError extends Error {
         this.name = "ValidationError";
     }
 }
+/**
+ * Pull a typed-error detail out of an ApiError body. Backend convention is
+ * HTTPException(detail={error_code, ...fields}), which FastAPI serialises as
+ * {"detail": {error_code, ...fields}}. Returns undefined when the body isn't
+ * shaped that way (e.g. plain string detail, or 422 validation arrays).
+ */
+function structuredDetail(err) {
+    if (!err.body || typeof err.body !== "object")
+        return undefined;
+    const detail = err.body.detail;
+    if (detail && typeof detail === "object" && !Array.isArray(detail) && "error_code" in detail) {
+        return detail;
+    }
+    return undefined;
+}
 /**
  * Map error codes to actionable suggestions so agents can self-recover.
  */
@@ -215,6 +385,14 @@ function suggestionsForError(err) {
                 ];
             case "insufficient_credits":
                 return ["Purchase more credits at https://app.ishlabs.io"];
+            case "usage_limit_reached": {
+                const d = structuredDetail(err);
+                const upgradeUrl = typeof d?.upgrade_url === "string" ? d.upgrade_url : "https://app.ishlabs.io/billing";
+                return [
+                    `Upgrade your plan at ${upgradeUrl}`,
+                    "Run `ish docs get-page reference/billing-limits` for the tier table",
+                ];
+            }
             case "validation_error":
                 return ["Check the command help: add --help to see required options"];
             case "rate_limited":
@@ -262,12 +440,20 @@ export function outputError(err, json) {
         const mergedSuggestions = bodySuggestions
             ? Array.from(new Set([...bodySuggestions.map(String), ...suggestions]))
             : suggestions;
+        const limitDetail = err.error_code === "usage_limit_reached" ? structuredDetail(err) : undefined;
         if (json) {
             console.error(JSON.stringify({
                 error: err.message,
                 error_code: err.error_code,
                 status: err.status,
                 retryable: err.retryable,
+                ...(limitDetail && {
+                    tier: limitDetail.tier,
+                    limit: limitDetail.limit,
+                    current: limitDetail.current,
+                    max: limitDetail.max,
+                    upgrade_url: limitDetail.upgrade_url,
+                }),
                 ...(bodyErrors !== undefined && { errors: bodyErrors }),
                 ...(mergedSuggestions.length > 0 && { suggestions: mergedSuggestions }),
             }));
@@ -380,22 +566,20 @@ function projectWorkspace(workspace, options = {}) {
     return result;
 }
 export function formatWorkspaceList(workspaces, json) {
-    if (workspaces.length === 0) {
-        if (json)
-            console.log("[]");
-        else
-            console.log("No workspaces.");
-        return;
-    }
     injectAliases(workspaces, ALIAS_PREFIX.workspace);
     if (json) {
-        if (_verbose) {
-            console.log(jsonOutput(workspaces));
-        }
-        else {
-            const projected = workspaces.map((w) => projectWorkspace(w));
-            console.log(jsonOutput(projected, { preProjected: true }));
-        }
+        // Synthesize pagination metadata: backend returns a flat array, so
+        // total/limit/offset reflect what we actually shipped.
+        const projected = _verbose
+            ? workspaces
+            : workspaces.map((w) => projectWorkspace(w));
+        // preProjectedItems: workspaces went through projectWorkspace which already
+        // chose the field set; skip the inner leanJson so created_at survives.
+        console.log(jsonOutput(wrapList(projected, undefined, { preProjectedItems: !_verbose }), { preProjected: true }));
+        return;
+    }
+    if (workspaces.length === 0) {
+        console.log("No workspaces.");
         return;
     }
     const aliasMap = getAliasMap(ALIAS_PREFIX.workspace);
@@ -441,16 +625,14 @@ export function formatSiteAccessStatus(summary, json) {
 }
 // --- Study formatting ---
 export function formatStudyList(studies, json) {
-    if (studies.length === 0) {
-        if (json)
-            console.log("[]");
-        else
-            console.log("No studies.");
-        return;
-    }
     injectAliases(studies, ALIAS_PREFIX.study);
     if (json) {
-        console.log(jsonOutput(studies));
+        // Backend returns a flat array; synthesize pagination metadata.
+        console.log(jsonOutput(wrapList(studies), { preProjected: true }));
+        return;
+    }
+    if (studies.length === 0) {
+        console.log("No studies.");
         return;
     }
     const aliasMap = getAliasMap(ALIAS_PREFIX.study);
@@ -463,9 +645,47 @@ export function formatStudyList(studies, json) {
         String(s.tester_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
+ * 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`).
+ *     Original `status` field preserved so existing consumers can still
+ *     branch on it.
+ *   - Human / stderr: a one-line warning describing the mismatch.
+ *
+ * Returns null when status is consistent; no warning emitted.
+ */
+function detectStudyStatusInconsistency(study) {
+    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);
+    if (completedCount === 0 && totalInteractions === 0)
+        return null;
+    return {
+        inferred: "completed_with_errors",
+        reason: `${completedCount}/${allTesters.length} testers completed, ${totalInteractions} total interactions`,
+    };
+}
+function emitStatusInconsistencyWarning(inconsistency) {
+    process.stderr.write(`Warning: study reports status="failed" but ${inconsistency.reason}. ` +
+        `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);
+    if (inconsistency)
+        emitStatusInconsistencyWarning(inconsistency);
     if (json) {
-        console.log(jsonOutput(study, options));
+        const payload = inconsistency
+            ? { ...study, status_inferred: inconsistency.inferred }
+            : study;
+        console.log(jsonOutput(payload, options));
         return;
     }
     // Header
@@ -477,6 +697,12 @@ export function formatStudyDetail(study, json, options = {}) {
         modalityParts.push(String(study.content_type));
     modalityParts.push(String(study.status || "draft"), formatDate(study.created_at));
     console.log(modalityParts.join(" · "));
+    // Pattern C-followup: surface the modality rationale on `study generate`
+    // so agents (and humans) can spot misclassification without re-reading the
+    // brief. The field is only set on the immediate generate response.
+    if (study.modality_rationale) {
+        console.log(`\n  Modality rationale: ${String(study.modality_rationale)}`);
+    }
     // Assignments
     const assignments = Array.isArray(study.assignments) ? study.assignments : [];
     if (assignments.length > 0) {
@@ -560,20 +786,41 @@ function buildStudyResultsEnvelope(study) {
             answers,
         };
     });
+    // 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) => ({
+        alias: t.id ? deterministicAlias(ALIAS_PREFIX.tester, t.id) : null,
+        name: t.name,
+        iteration: t.iterationLabel,
+        status: t.status,
+        interaction_count: t.interactionCount,
+        ...(t.errorMessage && { error_message: t.errorMessage }),
+    }));
     return {
         study: {
             alias: studyAlias,
             name: study.name || null,
             status: study.status || null,
+            ...(inconsistency && { status_inferred: inconsistency.inferred }),
             modality: study.modality || null,
         },
         tester_count: allTesters.length,
         completed_count: completedCount,
+        failed_count: failedCount,
         sentiment,
         interview_answers: interviewAnswers,
+        testers: testerRows,
     };
 }
 export function formatStudyResults(study, json) {
+    const inconsistency = detectStudyStatusInconsistency(study);
+    if (inconsistency)
+        emitStatusInconsistencyWarning(inconsistency);
     if (json) {
         // preProjected: bypass leanJson so the stable envelope keeps documented
         // empty defaults (sentiment: null, interview_answers[].answers: []) rather
@@ -628,6 +875,16 @@ export function formatStudyResults(study, json) {
                 parts.length > 0 ? parts.join(", ") : "-",
             ];
         }));
+        // 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);
+        if (failedRows.length > 0) {
+            console.log("\nFailed testers:");
+            for (const t of failedRows) {
+                const alias = t.id ? deterministicAlias(ALIAS_PREFIX.tester, 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.");
     }
 }
@@ -657,6 +914,7 @@ function collectTesters(study) {
                 name: String(profile?.name || t.instance_name || "Unknown"),
                 iterationLabel: iterLabel,
                 status: String(t.status || "-"),
+                errorMessage: t.error_message ? String(t.error_message) : null,
                 interactionCount: interactions.length,
                 sentimentCounts,
                 interviewAnswers: answers.map((a) => ({
@@ -683,16 +941,14 @@ function truncate(str, maxLen) {
 }
 // --- Iteration formatting ---
 export function formatIterationList(iterations, json) {
-    if (iterations.length === 0) {
-        if (json)
-            console.log("[]");
-        else
-            console.log("No iterations.");
-        return;
-    }
     injectAliases(iterations, ALIAS_PREFIX.iteration);
     if (json) {
-        console.log(jsonOutput(iterations));
+        // Backend returns a flat array; synthesize pagination metadata.
+        console.log(jsonOutput(wrapList(iterations), { preProjected: true }));
+        return;
+    }
+    if (iterations.length === 0) {
+        console.log("No iterations.");
         return;
     }
     const aliasMap = getAliasMap(ALIAS_PREFIX.iteration);
@@ -727,10 +983,15 @@ 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 display = {
         ID: tester.id || "-",
         Profile: profileName,
-        Status: tester.status || "-",
+        Status: status,
+        ...(errorMessage && status.toLowerCase() === "failed" && {
+            Error: errorMessage,
+        }),
         Platform: tester.platform || "-",
         Language: tester.language || "-",
         Interactions: `${interactions.length} interactions`,
@@ -742,24 +1003,27 @@ export function formatTesterDetail(tester, json) {
 }
 // --- Tester Profile formatting ---
 export function formatTesterProfileList(profiles, json, limit) {
-    // The API may return { items: [...], total, limit, offset } or a flat array
+    // The API may return { items: [...], total, limit, offset } or a flat array.
     const wrapper = profiles;
+    const wasWrapper = !Array.isArray(profiles)
+        && profiles !== null
+        && typeof profiles === "object"
+        && (Array.isArray(wrapper?.items) || Array.isArray(wrapper?.profiles));
     const fullList = Array.isArray(profiles) ? profiles
         : Array.isArray(wrapper?.items) ? wrapper.items
             : Array.isArray(wrapper?.profiles) ? wrapper.profiles
-                : null;
-    if (!Array.isArray(fullList) || fullList.length === 0) {
-        if (json)
-            console.log(JSON.stringify(profiles, null, 2));
-        else
-            console.log("No tester profiles.");
-        return;
-    }
+                : [];
     // Client-side limit (server may not enforce it)
     const list = limit ? fullList.slice(0, limit) : fullList;
     injectAliases(list, ALIAS_PREFIX.testerProfile);
     if (json) {
-        console.log(jsonOutput(profiles));
+        // Pass through server-provided pagination when present; otherwise synthesize.
+        const existing = wasWrapper ? wrapper : undefined;
+        console.log(jsonOutput(wrapList(list, existing), { preProjected: true }));
+        return;
+    }
+    if (list.length === 0) {
+        console.log("No tester profiles.");
         return;
     }
     printTable(["#", "NAME", "OCCUPATION", "COUNTRY", "GENDER", "AGE"], list.map((p) => [
@@ -855,16 +1119,14 @@ function variantLetter(index) {
     return `V${index + 1}`;
 }
 export function formatAskList(asks, json) {
-    if (asks.length === 0) {
-        if (json)
-            console.log("[]");
-        else
-            console.log("No asks.");
-        return;
-    }
     injectAliases(asks, ALIAS_PREFIX.ask);
     if (json) {
-        console.log(jsonOutput(asks));
+        // Backend returns a flat array; synthesize pagination metadata.
+        console.log(jsonOutput(wrapList(asks), { preProjected: true }));
+        return;
+    }
+    if (asks.length === 0) {
+        console.log("No asks.");
         return;
     }
     const aliasMap = getAliasMap(ALIAS_PREFIX.ask);
@@ -877,9 +1139,72 @@ export function formatAskList(asks, json) {
         a.is_archived ? "yes" : "no",
     ]));
 }
+/**
+ * Add denormalized counts to a round so agents don't have to count
+ * `responses[]` via jq/python:
+ *   - responses_total:    responses.length
+ *   - responses_complete: count where status === "completed"
+ *   - responses_errored:  count where status === "errored" (only if > 0)
+ */
+function denormalizeRoundCounts(round) {
+    const responses = Array.isArray(round.responses) ? round.responses : null;
+    if (!responses)
+        return round;
+    let complete = 0;
+    let errored = 0;
+    for (const r of responses) {
+        const status = r.status;
+        if (status === "completed")
+            complete++;
+        else if (status === "errored")
+            errored++;
+    }
+    return {
+        ...round,
+        responses_total: responses.length,
+        responses_complete: complete,
+        ...(errored > 0 && { responses_errored: errored }),
+    };
+}
+/**
+ * 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
+ *   - responses_total:    sum across rounds (only when > 0)
+ *   - responses_complete: sum across rounds
+ *   - responses_errored:  sum across rounds (only when > 0)
+ *   - rounds[i].responses_total / _complete / _errored
+ */
+function denormalizeAskCounts(ask) {
+    const enriched = { ...ask };
+    const testers = Array.isArray(ask.testers) ? ask.testers : null;
+    if (testers)
+        enriched.testers_count = testers.length;
+    const rounds = Array.isArray(ask.rounds) ? ask.rounds : null;
+    if (rounds) {
+        let total = 0;
+        let complete = 0;
+        let errored = 0;
+        enriched.rounds = rounds.map((r) => {
+            const decorated = denormalizeRoundCounts(r);
+            total += decorated.responses_total ?? 0;
+            complete += decorated.responses_complete ?? 0;
+            errored += decorated.responses_errored ?? 0;
+            return decorated;
+        });
+        if (total > 0) {
+            enriched.responses_total = total;
+            enriched.responses_complete = complete;
+            if (errored > 0)
+                enriched.responses_errored = errored;
+        }
+    }
+    return enriched;
+}
 export function formatAskDetail(ask, json) {
     if (json) {
-        console.log(jsonOutput(ask));
+        console.log(jsonOutput(denormalizeAskCounts(ask)));
         return;
     }
     console.log(`${ask.name || "Untitled"} (${ask.id || ""})`);
@@ -923,7 +1248,7 @@ export function formatAskDetail(ask, json) {
 }
 export function formatRoundDetail(round, json) {
     if (json) {
-        console.log(jsonOutput(round));
+        console.log(jsonOutput(denormalizeRoundCounts(round)));
         return;
     }
     const variants = Array.isArray(round.variants) ? round.variants : [];
@@ -999,13 +1324,166 @@ function computeVariantStats(round) {
     }
     return stats;
 }
+// When tester_profile and tester_profile_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;
+    if (!tp || !tps)
+        return tester;
+    const shared = Object.keys(tps).filter((k) => k in tp);
+    if (shared.length === 0)
+        return tester;
+    const isEmpty = (v) => {
+        if (v === null || v === undefined)
+            return true;
+        if (Array.isArray(v))
+            return v.length === 0;
+        if (typeof v === "object")
+            return Object.keys(v).length === 0;
+        return false;
+    };
+    const allMatch = shared.every((k) => {
+        const a = tp[k];
+        const b = tps[k];
+        if (isEmpty(a) && isEmpty(b))
+            return true;
+        return JSON.stringify(a) === JSON.stringify(b);
+    });
+    if (!allMatch)
+        return tester;
+    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 },
+    };
+}
+// Shape per-variant stats into a machine-readable aggregates object so agents
+// running A/B tests can read the verdict without parsing prose.
+function buildAggregates(round, stats) {
+    if (stats.length === 0)
+        return undefined;
+    const wantsPick = !!round.wants_pick;
+    const wantsRatings = !!round.wants_ratings;
+    if (!wantsPick && !wantsRatings)
+        return undefined;
+    const out = {};
+    if (wantsPick) {
+        const picks = {};
+        let topCount = -1;
+        let topLetter = "";
+        let tied = false;
+        for (const s of stats) {
+            picks[s.letter] = s.pickCount;
+            if (s.pickCount > topCount) {
+                topCount = s.pickCount;
+                topLetter = s.letter;
+                tied = false;
+            }
+            else if (s.pickCount === topCount && topCount > 0) {
+                tied = true;
+            }
+        }
+        out.picks = picks;
+        if (topCount > 0) {
+            out.winner = { letter: topLetter, count: topCount, tied };
+        }
+    }
+    if (wantsRatings) {
+        const ratings = {};
+        for (const s of stats) {
+            if (s.ratingCount > 0) {
+                ratings[s.letter] = {
+                    mean: Number((s.ratingTotal / s.ratingCount).toFixed(3)),
+                    n: s.ratingCount,
+                };
+            }
+        }
+        if (Object.keys(ratings).length > 0)
+            out.ratings = ratings;
+    }
+    return out;
+}
+function buildCrossRoundSummary(rounds) {
+    if (rounds.length < 2)
+        return undefined;
+    const entries = [];
+    for (const round of rounds) {
+        const idx = typeof round.order_index === "number" ? round.order_index : 0;
+        const stats = computeVariantStats(round);
+        const aggregates = buildAggregates(round, stats);
+        const entry = {
+            round_number: idx + 1,
+            prompt_preview: truncate(String(round.prompt || ""), 80),
+        };
+        if (aggregates?.picks)
+            entry.picks = aggregates.picks;
+        if (aggregates?.winner)
+            entry.winner = aggregates.winner;
+        if (aggregates?.ratings)
+            entry.ratings = aggregates.ratings;
+        entries.push(entry);
+    }
+    // Per-letter delta from first round → last round, when both have picks.
+    const first = entries[0]?.picks;
+    const last = entries[entries.length - 1]?.picks;
+    let picks_delta;
+    if (first && last) {
+        picks_delta = {};
+        const letters = new Set([
+            ...Object.keys(first),
+            ...Object.keys(last),
+        ]);
+        for (const letter of letters) {
+            picks_delta[letter] = (last[letter] ?? 0) - (first[letter] ?? 0);
+        }
+    }
+    return picks_delta ? { rounds: entries, picks_delta } : { rounds: entries };
+}
 export function formatAskResults(ask, json, roundFilter) {
     const rounds = (Array.isArray(ask.rounds) ? ask.rounds : []);
     const filtered = roundFilter !== undefined
         ? rounds.filter((r) => (typeof r.order_index === "number" ? r.order_index : 0) === roundFilter - 1)
         : rounds;
     if (json) {
-        const payload = roundFilter !== undefined ? { ...ask, rounds: filtered } : ask;
+        let total = 0;
+        let complete = 0;
+        let errored = 0;
+        const enrichedRounds = filtered.map((round) => {
+            const stats = computeVariantStats(round);
+            const aggregates = buildAggregates(round, stats);
+            const decorated = denormalizeRoundCounts(round);
+            total += decorated.responses_total ?? 0;
+            complete += decorated.responses_complete ?? 0;
+            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))
+            : undefined;
+        const payload = { ...ask, rounds: enrichedRounds };
+        if (dedupedTesters)
+            payload.testers = dedupedTesters;
+        if (testers)
+            payload.testers_count = testers.length;
+        if (total > 0) {
+            payload.responses_total = total;
+            payload.responses_complete = complete;
+            if (errored > 0)
+                payload.responses_errored = errored;
+        }
+        // Pattern H2: include cross-round summary when 2+ rounds exist so agents
+        // don't have to diff two `ask results` calls themselves.
+        const crossRound = buildCrossRoundSummary(filtered);
+        if (crossRound)
+            payload.cross_round_summary = crossRound;
         console.log(jsonOutput(payload));
         return;
     }
@@ -1065,19 +1543,46 @@ export function formatAskResults(ask, json, roundFilter) {
             console.log(`    ${summary.comment}`);
         }
     }
+    // Pattern H2: cross-round picks comparison when 2+ rounds exist. Saves
+    // agents from re-running results twice and diffing aggregates by hand.
+    const crossRound = buildCrossRoundSummary(filtered);
+    if (crossRound) {
+        console.log("\nCross-round summary:");
+        const letters = new Set();
+        for (const entry of crossRound.rounds) {
+            for (const letter of Object.keys(entry.picks ?? {}))
+                letters.add(letter);
+        }
+        const headers = ["ROUND", "WINNER", ...Array.from(letters).sort()];
+        const rows = crossRound.rounds.map((entry) => {
+            const winnerCell = entry.winner
+                ? entry.winner.tied
+                    ? `${entry.winner.letter} (tied)`
+                    : entry.winner.letter
+                : "-";
+            return [
+                `R${entry.round_number}`,
+                winnerCell,
+                ...Array.from(letters).sort().map((letter) => String(entry.picks?.[letter] ?? 0)),
+            ];
+        });
+        printTable(headers, rows);
+        if (crossRound.picks_delta) {
+            const deltaParts = Object.entries(crossRound.picks_delta).map(([letter, d]) => `${letter}: ${d > 0 ? "+" : ""}${d}`);
+            console.log(`  Δ picks (R1→R${crossRound.rounds.length}): ${deltaParts.join(", ")}`);
+        }
+    }
 }
 // --- Config formatting ---
 export function formatConfigList(configs, json) {
-    if (configs.length === 0) {
-        if (json)
-            console.log("[]");
-        else
-            console.log("No simulation configs.");
-        return;
-    }
     injectAliases(configs, ALIAS_PREFIX.config);
     if (json) {
-        console.log(jsonOutput(configs));
+        // Backend returns a flat array; synthesize pagination metadata.
+        console.log(jsonOutput(wrapList(configs), { preProjected: true }));
+        return;
+    }
+    if (configs.length === 0) {
+        console.log("No simulation configs.");
         return;
     }
     const aliasMap = getAliasMap(ALIAS_PREFIX.config);