@ishlabs/cli 0.8.5 → 0.10.0

package/README.md

@@ -88,7 +88,7 @@ Workspace (= product, top-level container)
 ```bash
 ish login                          # browser auth
 ish logout
-ish connect <port>                 # Cloudflare tunnel exposing localhost
+ish connect <port>                 # Cloudflare tunnel exposing localhost (--detach, ish disconnect, ish connect status)
 ish upgrade                        # self-update (single-binary installs only)
 ish upgrade --release 0.8.1        # pin a specific release
 ```
@@ -98,15 +98,21 @@ ish upgrade --release 0.8.1        # pin a specific release
 ### Workspaces, studies, iterations, profiles, configs (CRUD groups)
 
 ```bash
-ish workspace  list | create | get | update | delete | use
+ish workspace  list | create | get | update | delete | use | info
 ish workspace  site-access status | basic-auth | cookie | login | affirm-public | clear
 ish study      list | create | generate | get | results | update | delete | use
 ish iteration  list | create | get | update | delete
 ish profile    list | create | generate | get | update | delete
-ish source     upload | get
+ish source     upload | get | delete
 ish config     list | create | get | schema | update | delete
+ish chat       endpoint list | create | get | update | delete | use | init | test
+ish secret     list | set | delete
 ```
 
+`ish workspace info` reports `studies_used / studies_max / testers_used / testers_max / tier` so an agent can branch on plan caps before a destructive call returns `error_code: usage_limit_reached`.
+
+`ish chat endpoint` configures HTTP-bot endpoints for chat-modality studies (auto-detect from a curl example, smoke-test, edit). `ish secret` is the per-workspace KV store referenced from chatbot endpoint headers via `{{secret:KEY}}` placeholders. Run `ish docs get-page guides/chat` for the end-to-end recipe.
+
 Testers live as a nested group on a study (low-level — usually created via `study run`):
 
 ```bash
@@ -347,16 +353,59 @@ ish profile generate --source tps-3a4 --propose-count
 ish profile generate --source tps-3a4 --count 4
 ```
 
+### Chat-modality studies — `ish chat`
+
+Configure a customer chatbot endpoint and run chat-modality studies against it.
+
+```bash
+# Author from a curl example (or hand-write the config)
+ish chat endpoint init --from-curl ./bot.curl --name my-bot
+ish chat endpoint create --endpoint-config ./bot-config.json --name "my-bot"
+
+# CRUD on saved endpoints (every dialog edit reduces to one of these)
+ish chat endpoint list
+ish chat endpoint get ep-abc --verbose      # round-trippable {id, name, isTunnelBacked, config}
+ish chat endpoint update ep-abc --name "Production support bot"
+ish chat endpoint update ep-abc --url https://api.example.com/v2/chat --mode stateless
+ish chat endpoint get ep-abc --verbose | jq '.config.outgoing.headers["X-API-Key"] = "{{secret:KEY}}"' \
+  | ish chat endpoint update ep-abc --endpoint-config -
+ish chat endpoint delete ep-abc
+ish chat endpoint use ep-abc                 # set as the active chat endpoint
+
+# Smoke test the connection (single turn; tunnel pre-flight when applicable)
+ish chat endpoint test ep-abc -m "Hello"
+ish chat endpoint test ep-abc -m "Tell me more" --conversation-id "$CID"   # stateful threading
+
+# Run a chat-modality study using the saved endpoint (existing study verbs).
+# Audience size lives on study run via --sample / --all / --profile.
+ish study create --modality chat --endpoint ep-abc --name "Sign-up Q1" --assignment "Sign up:Try to sign up"
+ish study run --study stu-xyz --sample 5 --wait
+ish study results stu-xyz --json | jq '.testers'
+```
+
+Local bots (`localhost` / `127.0.0.1` / `0.0.0.0`) auto-flag `is_tunnel_backed=true` on `init`; pair with `ish connect <port>` in another shell. Override with `--tunnel-backed` / `--no-tunnel-backed`.
+
+`init` returns `confidence` (`high` / `medium` / `low`) and a `missingSignals: [...]` array naming any inputs the inference couldn't observe (e.g. `["response_shape", "message_path"]` when no response sample is provided). When confidence is `low`, verify with `chat endpoint test` before running a study.
+
+Failures from `chat endpoint test` carry a structured `error_kind`: `TunnelInactive` (run `ish connect <port>` first), `BotUnreachable` (URL/port wrong or bot down), `BotResponseError` (non-2xx with a status code), `BotEnvelopeError` (200 OK with the bot's own error in the body — see `raw_excerpt`), `BotInvalidResponseError` (response doesn't match the parsing schema), `BotAuthError`, `BotTimeoutError`, `BotRetryExhaustedError`.
+
+Full guide: `ish docs get-page guides/chat`.
+
 ### Expose localhost
 
-For interactive studies that need to reach a service running on your machine:
+For interactive studies (and chat endpoints with `is_tunnel_backed=true`) that need to reach a service running on your machine:
 
 ```bash
-ish connect 3000                       # Cloudflare tunnel to localhost:3000
+ish connect 3000                          # foreground Cloudflare tunnel to :3000
+ish connect 3000 --detach --json          # fork after first heartbeat; prints {pid, tunnel_url, registered}
+ish connect status --json                 # {active, pid, tunnel_url, registered_at} or {active:false}
+ish disconnect --json                     # graceful shutdown of an active tunnel
 ISH_TOKEN=YOUR_TOKEN ish connect 8080
 ```
 
-`connect` is a long-running command — keep it open while testers run. The Cloudflare tunnel URL prints prominently after "Connected"; pass `--json` for one-line machine-readable output (`{"status":"connected","tunnel_url":"...","local_port":3000,"registered":true}`) suitable for scripts.
+Foreground `connect` is long-running — keep it open while testers run. The tunnel URL prints prominently after "Connected"; pass `--json` for one-line machine-readable output (`{"status":"connected","tunnel_url":"...","local_port":3000,"registered":true}`). The `--detach` form forks after the first successful heartbeat and returns immediately, tracking PID + URL in `~/.ish/connect.lock` so `connect status` and `disconnect` find it later.
+
+Destructive verbs in `--json` mode (e.g. `chat endpoint delete`, `study delete`) require an explicit `--yes`; the rejection envelope carries `error_kind: "ConfirmationRequired"` and an `example` field with the same command + `--yes` appended, so an agent can recover without re-reading the help text.
 
 ## Global flags
 

package/dist/auth.d.ts

@@ -1,6 +1,21 @@
 /**
- * Browser-based authentication via the Ish frontend plugin auth flow.
- * Uses the existing /auth/plugin + /api/plugin/auth/poll infrastructure.
+ * Browser-based authentication via Supabase OAuth Server (RFC 6749 / OAuth 2.1).
+ *
+ * Flow:
+ *   1. DCR (RFC 7591) — register a one-shot public OAuth client at the Supabase
+ *      OAuth Server with the loopback redirect URI we just opened a port for.
+ *   2. PKCE (RFC 7636 S256) — generate verifier + challenge.
+ *   3. Loopback redirect (RFC 8252) — listen on 127.0.0.1:<random> and open the
+ *      browser at the Supabase /oauth/authorize URL.
+ *   4. After the user signs in + consents at <ish-frontend>/oauth/consent,
+ *      Supabase redirects back to our loopback with ?code=&state=.
+ *   5. Exchange code → tokens at /oauth/token, return access + refresh.
+ *
+ * Refresh tokens minted here flow back through /oauth/token (not the legacy
+ * /auth/v1/token endpoint), so refreshTokens() targets the same URL.
+ *
+ * Tokens land in ~/.ish/config.json with the same shape as before; the MCP
+ * server's `local` mode keeps reading them without changes.
  */
 export declare function getAppUrl(): string;
 export declare function getSupabaseUrl(): string;
@@ -17,9 +32,10 @@ export declare function resolveSupabaseProjectFromToken(accessToken: string | un
 export declare function decodeJwtExp(token: string): number;
 export declare function decodeJwtClaims(token: string): Record<string, unknown> | undefined;
 export declare function isTokenExpired(token: string, bufferSeconds?: number): boolean;
-export declare function login(appUrl?: string): Promise<{
+export declare function login(): Promise<{
     accessToken: string;
     refreshToken: string;
+    clientId: string;
 }>;
 /**
  * Thrown by `refreshTokens` when the refresh attempt failed permanently and
@@ -36,9 +52,12 @@ export declare class AuthRefreshPermanentError extends Error {
     readonly body: string;
     constructor(httpStatus: number, body: string, errorCode: string | undefined);
 }
-export declare function refreshTokens(refreshToken: string, options?: {
+export declare function refreshTokens(refreshToken: string, options: {
     /** The (possibly expired) access token. Used to pick the correct Supabase project. */
     accessToken?: string;
+    /** OAuth client_id from DCR at login time. Supabase requires it on
+     *  refresh because the issued client is public (no client secret). */
+    clientId: string;
     /** Force a specific Supabase project URL (e.g. for tests). */
     supabaseUrl?: string;
     /** Force a specific anon/publishable key. */

package/dist/auth.js

@@ -1,11 +1,27 @@
 /**
- * Browser-based authentication via the Ish frontend plugin auth flow.
- * Uses the existing /auth/plugin + /api/plugin/auth/poll infrastructure.
+ * Browser-based authentication via Supabase OAuth Server (RFC 6749 / OAuth 2.1).
+ *
+ * Flow:
+ *   1. DCR (RFC 7591) — register a one-shot public OAuth client at the Supabase
+ *      OAuth Server with the loopback redirect URI we just opened a port for.
+ *   2. PKCE (RFC 7636 S256) — generate verifier + challenge.
+ *   3. Loopback redirect (RFC 8252) — listen on 127.0.0.1:<random> and open the
+ *      browser at the Supabase /oauth/authorize URL.
+ *   4. After the user signs in + consents at <ish-frontend>/oauth/consent,
+ *      Supabase redirects back to our loopback with ?code=&state=.
+ *   5. Exchange code → tokens at /oauth/token, return access + refresh.
+ *
+ * Refresh tokens minted here flow back through /oauth/token (not the legacy
+ * /auth/v1/token endpoint), so refreshTokens() targets the same URL.
+ *
+ * Tokens land in ~/.ish/config.json with the same shape as before; the MCP
+ * server's `local` mode keeps reading them without changes.
  */
+import * as http from "node:http";
 import * as crypto from "node:crypto";
 import { execFile } from "node:child_process";
-const POLL_INTERVAL = 2_000;
-const LOGIN_TIMEOUT = 5 * 60 * 1000; // 5 minutes (matches server-side token TTL)
+const LOGIN_TIMEOUT = 5 * 60 * 1000; // 5 minutes
+const CLIENT_NAME = "ish CLI";
 const DEFAULT_APP_URL = "https://app.ishlabs.io";
 // Known Supabase projects, keyed by hostname. The CLI may be talking to either
 // production or development depending on how the user logged in — the access
@@ -13,12 +29,12 @@ const DEFAULT_APP_URL = "https://app.ishlabs.io";
 // must send refresh requests back to that same project (with its matching
 // publishable/anon key) or Supabase will reject them.
 const SUPABASE_PROJECTS = {
-    // Production
+    // Development (default — local dev work hits this project)
     "muqvgnqyubmqnfnqwxuk.supabase.co": {
         url: "https://muqvgnqyubmqnfnqwxuk.supabase.co",
         anonKey: "sb_publishable_pxXwY9EaWFwkR7h728NWvQ_NFqGfh8K",
     },
-    // Development
+    // Production
     "hngymyxdyamokpbeakps.supabase.co": {
         url: "https://hngymyxdyamokpbeakps.supabase.co",
         anonKey: "sb_publishable_JlS-HfwNyDqLNbrfbrkUlw_PSdZJdo2",
@@ -108,35 +124,141 @@ export function isTokenExpired(token, bufferSeconds = 300) {
         return true;
     return Date.now() / 1000 >= exp - bufferSeconds;
 }
-// --- Login via browser polling ---
-export async function login(appUrl) {
-    const url = appUrl ?? getAppUrl();
-    const state = crypto.randomBytes(32).toString("hex");
-    const loginUrl = `${url}/auth/plugin?state=${state}`;
-    console.error("Opening browser to sign in...");
-    console.error(`If the browser doesn't open, visit:\n  ${loginUrl}\n`);
-    openBrowser(loginUrl);
-    console.error("Waiting for authentication...");
-    const deadline = Date.now() + LOGIN_TIMEOUT;
-    while (Date.now() < deadline) {
-        await new Promise((r) => setTimeout(r, POLL_INTERVAL));
-        try {
-            const resp = await fetch(`${url}/api/plugin/auth/poll?state=${state}`, {
-                signal: AbortSignal.timeout(10_000),
-            });
-            if (resp.status === 200) {
-                const data = await resp.json();
-                if (data.status === "complete" && data.access_token && data.refresh_token) {
-                    return { accessToken: data.access_token, refreshToken: data.refresh_token };
-                }
+function startCallbackServer() {
+    return new Promise((resolve, reject) => {
+        let resolveCallback = null;
+        const callbackPromise = new Promise((res) => {
+            resolveCallback = res;
+        });
+        const server = http.createServer((req, res) => {
+            const reqUrl = new URL(req.url ?? "/", "http://127.0.0.1");
+            if (reqUrl.pathname !== "/callback") {
+                res.writeHead(404);
+                res.end();
+                return;
             }
-            // 202 = pending, keep polling
+            const cb = {
+                code: reqUrl.searchParams.get("code") ?? undefined,
+                state: reqUrl.searchParams.get("state") ?? undefined,
+                error: reqUrl.searchParams.get("error") ?? undefined,
+                errorDescription: reqUrl.searchParams.get("error_description") ?? undefined,
+            };
+            const headline = cb.error ? "Sign-in failed" : "Signed in to Ish";
+            const subline = cb.error
+                ? `${cb.error}${cb.errorDescription ? `: ${cb.errorDescription}` : ""}`
+                : "You can close this window and return to your terminal.";
+            const html = `<!doctype html><html><head><meta charset="utf-8"><title>${headline}</title></head><body style="font-family:system-ui,-apple-system,sans-serif;padding:3em;text-align:center;color:#1f2937"><h1 style="font-weight:600;margin-bottom:1em">${headline}</h1><p style="color:#6b7280">${subline}</p></body></html>`;
+            res.writeHead(cb.error ? 400 : 200, { "Content-Type": "text/html; charset=utf-8" });
+            res.end(html);
+            if (resolveCallback)
+                resolveCallback(cb);
+        });
+        server.on("error", reject);
+        server.listen(0, "127.0.0.1", () => {
+            const addr = server.address();
+            if (!addr || typeof addr === "string") {
+                reject(new Error("Failed to start callback server"));
+                return;
+            }
+            resolve({
+                port: addr.port,
+                waitForCallback: () => callbackPromise,
+                close: () => {
+                    server.close();
+                },
+            });
+        });
+    });
+}
+async function registerOAuthClient(supabaseUrl, redirectUri) {
+    const resp = await fetch(`${supabaseUrl}/auth/v1/oauth/clients/register`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+            client_name: CLIENT_NAME,
+            redirect_uris: [redirectUri],
+            application_type: "native",
+            grant_types: ["authorization_code", "refresh_token"],
+            response_types: ["code"],
+            token_endpoint_auth_method: "none",
+        }),
+        signal: AbortSignal.timeout(15_000),
+    });
+    if (!resp.ok) {
+        throw new Error(`Dynamic client registration failed (HTTP ${resp.status}): ${await resp.text().catch(() => "")}`);
+    }
+    const data = await resp.json();
+    if (typeof data.client_id !== "string") {
+        throw new Error("Dynamic client registration response missing client_id");
+    }
+    return data.client_id;
+}
+function generatePkcePair() {
+    const verifier = crypto.randomBytes(64).toString("base64url");
+    const challenge = crypto.createHash("sha256").update(verifier).digest("base64url");
+    return { verifier, challenge };
+}
+export async function login() {
+    const supabaseUrl = getSupabaseUrl();
+    const server = await startCallbackServer();
+    const redirectUri = `http://127.0.0.1:${server.port}/callback`;
+    try {
+        const clientId = await registerOAuthClient(supabaseUrl, redirectUri);
+        const { verifier, challenge } = generatePkcePair();
+        const state = crypto.randomBytes(24).toString("base64url");
+        const authorizeUrl = new URL(`${supabaseUrl}/auth/v1/oauth/authorize`);
+        authorizeUrl.searchParams.set("response_type", "code");
+        authorizeUrl.searchParams.set("client_id", clientId);
+        authorizeUrl.searchParams.set("redirect_uri", redirectUri);
+        authorizeUrl.searchParams.set("state", state);
+        authorizeUrl.searchParams.set("scope", "openid email profile");
+        authorizeUrl.searchParams.set("code_challenge", challenge);
+        authorizeUrl.searchParams.set("code_challenge_method", "S256");
+        console.error("Opening browser to sign in...");
+        console.error(`If the browser doesn't open, visit:\n  ${authorizeUrl.toString()}\n`);
+        openBrowser(authorizeUrl.toString());
+        console.error("Waiting for authentication...");
+        const timeoutPromise = new Promise((_, reject) => {
+            setTimeout(() => reject(new Error("Login timed out. Please try again.")), LOGIN_TIMEOUT);
+        });
+        const cb = await Promise.race([server.waitForCallback(), timeoutPromise]);
+        if (cb.error) {
+            throw new Error(`OAuth error: ${cb.error}${cb.errorDescription ? ` — ${cb.errorDescription}` : ""}`);
         }
-        catch {
-            // Network error, keep polling
+        if (cb.state !== state) {
+            throw new Error("OAuth state mismatch — possible CSRF attempt. Please try again.");
+        }
+        if (!cb.code) {
+            throw new Error("No authorization code received from Supabase.");
         }
+        const tokenResp = await fetch(`${supabaseUrl}/auth/v1/oauth/token`, {
+            method: "POST",
+            headers: { "Content-Type": "application/x-www-form-urlencoded" },
+            body: new URLSearchParams({
+                grant_type: "authorization_code",
+                code: cb.code,
+                redirect_uri: redirectUri,
+                client_id: clientId,
+                code_verifier: verifier,
+            }).toString(),
+            signal: AbortSignal.timeout(15_000),
+        });
+        if (!tokenResp.ok) {
+            throw new Error(`Token exchange failed (HTTP ${tokenResp.status}): ${await tokenResp.text().catch(() => "")}`);
+        }
+        const tokenData = await tokenResp.json();
+        if (typeof tokenData.access_token !== "string" || typeof tokenData.refresh_token !== "string") {
+            throw new Error("Token exchange response missing access_token or refresh_token");
+        }
+        return {
+            accessToken: tokenData.access_token,
+            refreshToken: tokenData.refresh_token,
+            clientId,
+        };
+    }
+    finally {
+        server.close();
     }
-    throw new Error("Login timed out. Please try again.");
 }
 // --- Token refresh ---
 /**
@@ -177,16 +299,20 @@ function parseRefreshErrorCode(body) {
     return undefined;
 }
 export async function refreshTokens(refreshToken, options) {
-    const project = options?.supabaseUrl && options?.anonKey
+    const project = options.supabaseUrl && options.anonKey
         ? { url: options.supabaseUrl, anonKey: options.anonKey }
-        : resolveSupabaseProjectFromToken(options?.accessToken);
-    const resp = await fetch(`${project.url}/auth/v1/token?grant_type=refresh_token`, {
+        : resolveSupabaseProjectFromToken(options.accessToken);
+    // OAuth-server-minted tokens refresh through /oauth/token. The legacy
+    // /auth/v1/token endpoint is for password/magic-link flows and won't
+    // accept refresh tokens issued under the OAuth grant.
+    const resp = await fetch(`${project.url}/auth/v1/oauth/token`, {
         method: "POST",
-        headers: {
-            apikey: project.anonKey,
-            "Content-Type": "application/json",
-        },
-        body: JSON.stringify({ refresh_token: refreshToken }),
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: new URLSearchParams({
+            grant_type: "refresh_token",
+            refresh_token: refreshToken,
+            client_id: options.clientId,
+        }).toString(),
         signal: AbortSignal.timeout(10_000),
     });
     if (!resp.ok) {

package/dist/commands/ask.d.ts

@@ -2,4 +2,16 @@
  * ish ask — Create and run asks (multi-round surveys with variants).
  */
 import type { Command } from "commander";
+import type { AudienceSubset } from "../lib/types.js";
+/**
+ * Parse the `--subset-round <n> --subset-variant <variant_id>` pair into
+ * an `AudienceSubset` payload (Pattern B). Both flags must be passed
+ * together or neither — half a subset is a misconfiguration the agent
+ * should fix before dispatch, not a silent fallthrough to the full
+ * audience.
+ *
+ * Returns `undefined` when neither flag is set; throws when only one is
+ * set or when `--subset-round` isn't a positive integer.
+ */
+export declare function parseAudienceSubset(subsetRound: string | undefined, subsetVariant: string | undefined): AudienceSubset | undefined;
 export declare function registerAskCommands(program: Command): void;

package/dist/commands/ask.js

@@ -7,6 +7,7 @@ import { loadConfig, saveConfig } from "../config.js";
 import { formatAskList, formatAskDetail, formatRoundDetail, formatAskResults, output, } from "../lib/output.js";
 import { parseVariantInputs, uploadAndBuildVariants, } from "../lib/ask-variants.js";
 import { loadQuestionsManifest } from "../lib/ask-questions.js";
+import { ApiError } from "../lib/api-client.js";
 const POLL_INTERVAL_MS = 5_000;
 // ---------------------------------------------------------------------------
 // Helpers
@@ -108,6 +109,32 @@ async function buildRoundInput(client, productId, opts, quiet) {
         round.questions = questions;
     return round;
 }
+/**
+ * Parse the `--subset-round <n> --subset-variant <variant_id>` pair into
+ * an `AudienceSubset` payload (Pattern B). Both flags must be passed
+ * together or neither — half a subset is a misconfiguration the agent
+ * should fix before dispatch, not a silent fallthrough to the full
+ * audience.
+ *
+ * Returns `undefined` when neither flag is set; throws when only one is
+ * set or when `--subset-round` isn't a positive integer.
+ */
+export function parseAudienceSubset(subsetRound, subsetVariant) {
+    if (subsetRound === undefined && subsetVariant === undefined)
+        return undefined;
+    if (subsetRound === undefined || subsetVariant === undefined) {
+        throw new Error("--subset-round and --subset-variant must be passed together (or both omitted).");
+    }
+    const round = Number.parseInt(subsetRound, 10);
+    if (!Number.isFinite(round) || round < 1 || !/^\d+$/.test(subsetRound)) {
+        throw new Error(`--subset-round must be a positive integer (got "${subsetRound}").`);
+    }
+    const trimmedVariant = subsetVariant.trim();
+    if (trimmedVariant.length === 0) {
+        throw new Error("--subset-variant must be a variant UUID (got empty string).");
+    }
+    return { round, picked_variant_id: trimmedVariant };
+}
 // ---------------------------------------------------------------------------
 // Command registration
 // ---------------------------------------------------------------------------
@@ -145,6 +172,8 @@ Concept pages: ish docs get-page concepts/ask
         allFlagName: "--all-simulatable",
         allFlagDescription: "Use every simulatable AI profile matching the filters (with --new only)",
     })
+        .option("--subset-round <n>", "Drill-in subset (Pattern B) — append-round only. 1-indexed prior round to filter against. Pair with --subset-variant.")
+        .option("--subset-variant <variant_id>", "Drill-in subset (Pattern B) — append-round only. Variant id (UUID) on the prior round whose pickers should inherit. Read from `aggregates.pick_buckets` or `variants[*].id` on the prior round's `ask results --json`.")
         .option("--wait", "Wait until the round completes (or errors)")
         .option("--timeout <s>", "Wait timeout in seconds (default 300)")
         .addHelpText("after", `
@@ -169,6 +198,9 @@ Examples:
                 if (pickedId) {
                     throw new Error("Cannot pass an ask id together with --new. Drop the id, or drop --new to append a round.");
                 }
+                if (opts.subsetRound !== undefined || opts.subsetVariant !== undefined) {
+                    throw new Error("--subset-round / --subset-variant are only valid when appending to an existing ask. Drop --new or drop the subset flags.");
+                }
                 const wid = resolveWorkspace(opts.workspace);
                 const testerIds = await resolveAudienceProfileIds(client, wid, audienceFlags(opts), { requireSimulatable: true, allFlagName: "--all-simulatable" });
                 const round = await buildRoundInput(client, wid, opts, !!globals.quiet);
@@ -180,7 +212,28 @@ Examples:
                     tester_profile_ids: testerIds,
                     first_round: round,
                 };
-                let data = await client.post(`/products/${wid}/asks`, body, { timeout: 120_000 });
+                // M5 / Pattern G: `ask run --new` POSTs to a non-idempotent
+                // create endpoint. If the backend errors after the row is
+                // committed (a 500 mid-pipeline, a network timeout after the
+                // POST landed), an automatic retry would create a duplicate
+                // ask. Override `retryable` to false on any failure here so
+                // agents don't auto-retry. The error envelope also reminds
+                // the agent to inspect `ish ask list --workspace <id>` before
+                // re-running, since the resource may already exist.
+                let data;
+                try {
+                    data = await client.post(`/products/${wid}/asks`, body, { timeout: 120_000 });
+                }
+                catch (err) {
+                    if (err instanceof ApiError) {
+                        err.retryable = false;
+                        const tagged = err;
+                        tagged.suggestions = [
+                            `\`ish ask list --workspace ${wid}\` to check whether the ask was created server-side before retrying — \`ask run --new\` is non-idempotent and will duplicate on retry.`,
+                        ];
+                    }
+                    throw err;
+                }
                 if (data.id) {
                     const config = loadConfig();
                     config.ask = data.id;
@@ -223,6 +276,9 @@ Examples:
             }
             const ask = await client.get(`/asks/${aid}`);
             const round = await buildRoundInput(client, ask.product_id, opts, !!globals.quiet);
+            const subset = parseAudienceSubset(opts.subsetRound, opts.subsetVariant);
+            if (subset)
+                round.audience_subset = subset;
             const created = await client.post(`/asks/${aid}/rounds`, round);
             if (opts.wait) {
                 const timeoutMs = parseWaitTimeout(opts.timeout);
@@ -519,14 +575,32 @@ the model's self-reported confidence in its variant choice. See
         .option("--wants-pick", "Each tester picks a favourite variant (compatible with --wants-ratings; can be set together).")
         .option("--wants-ratings", "Each tester rates every variant 1–5 (compatible with --wants-pick; can be set together). If neither is set, testers leave a free-form comment only.")
         .option("--questions <file.json>", `Questions JSON file: [{"question":"...","type":"text"|"slider"|"likert"|"single-choice"|"multiple-choice"|"number"}]`)
+        .option("--subset-round <n>", "Drill-in subset (Pattern B) — 1-indexed prior round to filter against. Pair with --subset-variant. The new round dispatches only to testers who picked --subset-variant on round N.")
+        .option("--subset-variant <variant_id>", "Drill-in subset (Pattern B) — variant id (UUID) on the prior round whose pickers should inherit. Pair with --subset-round. Read from `aggregates.pick_buckets` or `variants[*].id` on the prior round.")
         .option("--wait", "Wait until the new round completes")
         .option("--timeout <s>", "Wait timeout in seconds (default 300)")
-        .addHelpText("after", "\nExamples:\n  $ ish ask add-round a-6ec --prompt \"And now?\" --variant text:\"Hello\" --variant text:\"Hi\" --wait")
+        .addHelpText("after", `
+Examples:
+  # Append round 2 to the same audience.
+  $ ish ask add-round a-6ec --prompt "And now?" --variant text:"Hello" --variant text:"Hi" --wait
+
+  # Drill round 2 into the round-1-A-pickers (Pattern B).
+  $ ish ask add-round a-6ec \\
+      --prompt "What would make you actually click?" \\
+      --subset-round 1 --subset-variant 5f3a... \\
+      --wait
+
+If --subset-round / --subset-variant fails to resolve (round missing, variant
+not on that round, or zero pickers), the backend returns a 422 with
+error_kind: "audience_subset_invalid".`)
         .action(async (id, opts, cmd) => {
         await withClient(cmd, async (client, globals) => {
             const aid = resolveAsk(pickAskRef(id, opts.ask));
             const ask = await client.get(`/asks/${aid}`);
             const round = await buildRoundInput(client, ask.product_id, opts, !!globals.quiet);
+            const subset = parseAudienceSubset(opts.subsetRound, opts.subsetVariant);
+            if (subset)
+                round.audience_subset = subset;
             const created = await client.post(`/asks/${aid}/rounds`, round);
             if (opts.wait) {
                 const timeoutMs = parseWaitTimeout(opts.timeout);
@@ -607,6 +681,57 @@ text, slider, likert, single-choice, multiple-choice, number.`)
             }, globals.json);
         });
     });
+    // ---- retry --------------------------------------------------------------
+    ask
+        .command("retry")
+        .description("Re-dispatch only the errored responses on a round (idempotent: zero-errored is a no-op).")
+        .argument("[id]", "Ask alias or UUID (defaults to active ask)")
+        .option("--ask <id>", "Ask ID; alternative to positional argument")
+        .requiredOption("--round <n|round-id>", "Round number (1-indexed) or round id/alias")
+        .option("--wait", "Wait until the retried round completes (or errors)")
+        .option("--timeout <s>", "Wait timeout in seconds (default 300)")
+        .addHelpText("after", `
+Examples:
+  # Retry the errored 4 of 5 testers on round 1.
+  $ ish ask retry a-d3e --round 1
+
+  # Retry and wait for the round to settle.
+  $ ish ask retry a-d3e --round 1 --wait
+
+Notes:
+  - COMPLETED responses are left untouched. Only ERRORED rows are reset to PENDING and re-run from scratch.
+  - The round flips back to RUNNING for the duration of the retry; the prior round summary is dropped and rebuilt once the retry settles.
+  - On a round with no errored responses, the verb is a no-op and returns the round unchanged.`)
+        .action(async (id, opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const aid = resolveAsk(pickAskRef(id, opts.ask));
+            const ask = await client.get(`/asks/${aid}`);
+            const round = getRoundByIndexOrId(ask, opts.round);
+            const updated = await client.post(`/asks/${aid}/rounds/${round.id}/retry`, {});
+            if (opts.wait) {
+                const timeoutMs = parseWaitTimeout(opts.timeout);
+                await pollUntilRoundDone(client, aid, updated.order_index, timeoutMs, !!globals.quiet);
+                const refreshed = await client.get(`/asks/${aid}`);
+                const target = refreshed.rounds.find((r) => r.id === updated.id);
+                if (target) {
+                    formatRoundDetail(target, globals.json);
+                    return;
+                }
+            }
+            if (!globals.json || globals.verbose) {
+                formatRoundDetail(updated, globals.json);
+                return;
+            }
+            output({
+                id: aid,
+                alias: tagAlias(ALIAS_PREFIX.ask, aid),
+                round: {
+                    round_number: updated.order_index + 1,
+                    status: updated.status,
+                },
+            }, globals.json);
+        });
+    });
     // ---- add-testers --------------------------------------------------------
     const askAddTesters = ask
         .command("add-testers")

package/dist/commands/chat.d.ts

@@ -0,0 +1,17 @@
+/**
+ * ish chat — Configure chatbot endpoints and run chat-modality studies.
+ *
+ * The CLI's primary user is autonomous AI agents. Every verb here is
+ * scriptable: deterministic JSON outputs, no interactive prompts, no
+ * REPLs. Endpoint editing matches the editor dialog's semantics
+ * (full-replace via PUT) plus client-side field-shorthand flags for
+ * common one-line edits.
+ *
+ * Chat-modality studies are reached via the existing `ish study create
+ * --modality chat --endpoint <id>` extension; this file does NOT
+ * fork a parallel `chat run` verb tree.
+ */
+import type { Command } from "commander";
+import { envelopeFromRow } from "../lib/chat-endpoint-formatters.js";
+export declare function registerChatCommand(program: Command): void;
+export { envelopeFromRow };