@ishlabs/cli 0.11.0 → 0.12.0

package/dist/commands/ask.js

@@ -347,6 +347,7 @@ Examples:
         allFlagName: "--all-simulatable",
         allFlagDescription: "Use every simulatable AI profile matching the filters",
     })
+        .option("--no-dispatch", "Create the ask in DRAFT status without billing or dispatching the round. Hand the draft id back to the user, then start it with `ish ask dispatch <id>`. Audience flags are still required because the testers are materialized at create time. Mutually exclusive with --wait (nothing to wait for).")
         .option("--wait", "Wait until the first round completes (or errors)")
         .option("--timeout <s>", "Wait timeout in seconds (default 300)")
         .addHelpText("after", `
@@ -389,6 +390,9 @@ Picks come back with a \`pick_confidence\` (0..1) score per tester when
 `)
         .action(async (opts, cmd) => {
         await withClient(cmd, async (client, globals) => {
+            if (opts.dispatch === false && opts.wait) {
+                throw new Error("--no-dispatch and --wait are incompatible — a draft ask has nothing to wait for. Drop --wait, or run `ish ask dispatch <id> --wait` after the draft is created.");
+            }
             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);
@@ -398,6 +402,7 @@ Picks come back with a \`pick_confidence\` (0..1) score per tester when
                 language: opts.language,
                 tester_profile_ids: testerIds,
                 first_round: round,
+                ...(opts.dispatch === false && { dispatch: false }),
             };
             let data = await client.post(`/products/${wid}/asks`, body);
             if (data.id) {
@@ -414,11 +419,58 @@ Picks come back with a \`pick_confidence\` (0..1) score per tester when
                 result.alias = tagAlias(ALIAS_PREFIX.ask, String(result.id));
             formatAskDetail(result, globals.json);
             if (!globals.json && data.id) {
+                if (opts.dispatch === false) {
+                    const askAlias = tagAlias(ALIAS_PREFIX.ask, data.id);
+                    process.stderr.write(`\n  Draft created. Start it with: ish ask dispatch ${askAlias}\n`);
+                }
                 const url = getWebUrl(globals, `/${wid}/asks/${data.id}`);
                 process.stderr.write(`\n  ${terminalLink(url, "Open in browser ↗")}\n\n`);
             }
         });
     });
+    // ---- dispatch -----------------------------------------------------------
+    // Pattern B-dispatch: flip a DRAFT ask to RUNNING and enqueue the worker.
+    // Idempotent on the server (409 on non-DRAFT) — surface that as a usage
+    // error rather than a transient failure.
+    ask
+        .command("dispatch")
+        .description("Dispatch a draft ask — bills credits and starts the round")
+        .argument("[id]", "Ask alias or UUID (defaults to active ask)")
+        .option("--ask <id>", "Ask ID; alternative to positional argument")
+        .option("--wait", "Wait until the first round completes (or errors)")
+        .option("--timeout <s>", "Wait timeout in seconds (default 300)")
+        .addHelpText("after", `
+Use after \`ish ask create --no-dispatch\` to start a draft once the user has
+reviewed it. The dispatch is BILLABLE — credits are charged when responses
+land, the same as a normal create.
+
+Examples:
+  # Dispatch the active draft and wait for results:
+  $ ish ask dispatch --wait
+
+  # Dispatch a specific draft, JSON output:
+  $ ish ask dispatch a-6ec --json
+
+A non-DRAFT ask returns a 409 (\`already dispatched\`). The CLI maps that to a
+usage error so re-running this command is safe — no duplicate run.`)
+        .action(async (id, opts, cmd) => {
+        await withClient(cmd, async (client, globals) => {
+            const aid = resolveAsk(pickAskRef(id, opts.ask));
+            let data = await client.post(`/asks/${aid}/dispatch`, {});
+            if (opts.wait) {
+                const timeoutMs = parseWaitTimeout(opts.timeout);
+                data = await pollUntilRoundDone(client, aid, 0, timeoutMs, !!globals.quiet);
+            }
+            const result = data;
+            if (result.id)
+                result.alias = tagAlias(ALIAS_PREFIX.ask, String(result.id));
+            formatAskDetail(result, globals.json);
+            if (!globals.json && data.product_id) {
+                const url = getWebUrl(globals, `/${data.product_id}/asks/${aid}`);
+                process.stderr.write(`\n  ${terminalLink(url, "Open in browser ↗")}\n\n`);
+            }
+        });
+    });
     // ---- get ----------------------------------------------------------------
     ask
         .command("get")

package/dist/lib/docs.js

@@ -574,6 +574,49 @@ ish ask results a-6ec
 ish ask results a-6ec --json | jq '.rounds[0].aggregates'
 \`\`\`
 
+## Status field
+
+Asks carry a top-level \`status\`:
+
+- \`draft\` — created but not dispatched yet. No credits charged. Created
+  by \`ish ask create --no-dispatch\`.
+- \`running\` — dispatched; the round is executing or queued.
+- \`completed\` — round 1 (or the most recent round) finished.
+- \`cancelled\` — terminated explicitly.
+
+Surfaces in \`ish ask list\` (table column) and \`ish ask get\` (header
+metadata line and JSON \`status\` field). Lean JSON keeps the field
+intact — no \`--verbose\` needed to see it.
+
+## Stage-then-dispatch (draft asks)
+
+When you want a human to review the audience and prompt **before** any
+credits are spent, separate creation from dispatch:
+
+\`\`\`
+# 1. Stage — materializes testers, no worker enqueue, no bill yet
+ish ask create --workspace w-6ec --name "tagline AB" \\
+    --prompt "Which sounds better?" \\
+    --variant text:"Short and punchy." \\
+    --variant text:"A longer, descriptive line." \\
+    --sample 30 --wants-pick \\
+    --no-dispatch
+
+# Returns an ask with status="draft". Hand the alias back to the user.
+
+# 2. Dispatch — flips DRAFT → RUNNING and enqueues the round (BILLABLE)
+ish ask dispatch a-6ec --wait
+\`\`\`
+
+\`--no-dispatch\` requires audience flags (testers are still materialized
+at create time — only the worker enqueue and billing are deferred). It
+is incompatible with \`--wait\` since there is nothing to wait for.
+
+\`ish ask dispatch\` is idempotent on the server: a non-DRAFT ask returns
+HTTP 409 (\`already dispatched\`) which the CLI maps to a usage error, so
+re-running the command is safe. The user who calls \`dispatch\` is the
+billing principal — keep that in mind for shared workspaces.
+
 ## Reading the verdict
 
 For \`--wants-pick\` / \`--wants-ratings\` rounds, \`ask results --json\`

package/dist/lib/output.js

@@ -1452,9 +1452,10 @@ export function formatAskList(asks, json) {
         return;
     }
     const aliasMap = getAliasMap(ALIAS_PREFIX.ask);
-    printTable(["#", "NAME", "AUDIENCE", "ROUNDS", "LAST ROUND", "ARCHIVED"], asks.map((a) => [
+    printTable(["#", "NAME", "STATUS", "AUDIENCE", "ROUNDS", "LAST ROUND", "ARCHIVED"], asks.map((a) => [
         aliasMap.get(String(a.id)) || String(a.id || ""),
         String(a.name || ""),
+        String(a.status || "-"),
         String(a.audience_count ?? "0"),
         String(a.round_count ?? "0"),
         formatDate(a.last_round_at),
@@ -1533,6 +1534,8 @@ export function formatAskDetail(ask, json) {
     if (ask.description)
         console.log(String(ask.description));
     const meta = [];
+    if (ask.status)
+        meta.push(String(ask.status));
     if (ask.is_archived)
         meta.push("archived");
     meta.push(formatDate(ask.created_at));

package/dist/lib/skill-content.js

@@ -138,6 +138,11 @@ ish study create --modality chat --endpoint my-bot --assignment "Sign up:Try to
 ish study run --sample 5 --country SE --wait
 ish ask run --new --name "..." --prompt "..." --variant text:"A" --variant text:"B" --sample 30 --wants-pick --wait
 
+# Stage an ask for human review, then dispatch (no credits charged on stage)
+ish ask create --name "..." --prompt "..." --variant text:"A" --variant text:"B" \
+    --sample 30 --wants-pick --no-dispatch
+ish ask dispatch a-6ec --wait
+
 # Results
 ish study results
 ish ask results a-6ec --round 1
@@ -236,6 +241,15 @@ implies \`--quiet\` so the bare value is the only thing on stdout.
   follow-up question to a completed round preserves prior comments,
   picks, and ratings; only the new question is dispatched. Pass
   \`--redispatch-all\` for the legacy reset-and-rerun behavior.
+- **\`ask create --no-dispatch\` stages a draft, no bill yet.** Pair
+  with \`ish ask dispatch <id>\` to flip DRAFT → RUNNING and start
+  the round. Use this when the user wants to review the audience or
+  prompt before any credits are charged. Audience flags are still
+  required (testers materialize at create time); only the worker
+  enqueue and billing are deferred. Asks now carry a top-level
+  \`status\` (\`draft | running | completed | cancelled\`) visible in
+  \`ask list\` and \`ask get\`. \`dispatch\` is idempotent — a
+  non-DRAFT ask returns 409 mapped to a usage error.
 - **\`ask results --json\` adds \`cross_round_summary\` for 2+ rounds.**
   Top-level field with per-round picks/winner snapshots and
   \`picks_delta\` (R1 → last). Don't diff two \`ask results\` calls by
@@ -608,7 +622,41 @@ you can branch on plan caps before \`study create\` returns
 The full reference is at \`ish docs get-page guides/chat\`,
 secrets are at \`ish docs get-page concepts/secret\`.
 
-## 8. Display-vs-capture: a script that does both
+## 8. Stage an ask for human review, then dispatch
+
+Goal: prepare a billable A/B but let the user inspect and approve the
+audience + prompt before any credits are spent. Two-step flow with a
+DRAFT status in between.
+
+\`\`\`bash
+# 1. Stage. No worker enqueued, no bill. Audience flags are still
+#    required — testers materialize at create time.
+ASK=$(ish ask create --name "tagline AB" \\
+        --prompt "Which sounds better?" \\
+        --variant text:"Short and punchy." \\
+        --variant text:"A longer, descriptive line." \\
+        --sample 30 --wants-pick \\
+        --no-dispatch \\
+        --get alias)
+
+# Hand the alias back to the user. They can inspect it:
+#   ish ask get "$ASK"            # status: draft
+#   ish ask get "$ASK" --json | jq '.testers | length'
+
+# 2. Dispatch once approved (BILLABLE). Idempotent: a non-DRAFT ask
+#    returns 409 mapped to exit 2, so re-running is safe.
+ish ask dispatch "$ASK" --wait
+\`\`\`
+
+The \`status\` field on the ask reflects lifecycle (\`draft\` → \`running\`
+→ \`completed\`); \`is_archived\` is orthogonal. \`ish ask list\` shows
+status as a column.
+
+\`--no-dispatch\` is incompatible with \`--wait\` — there is nothing to
+wait for. Pass \`--wait\` to \`ish ask dispatch\` instead if you want to
+block until the round settles.
+
+## 9. Display-vs-capture: a script that does both
 
 Goal: drive an A/B in a script, capture aliases without \`jq\`, and
 still show the human a readable result table at the end.

package/dist/lib/types.d.ts

@@ -245,6 +245,7 @@ export interface SimulationConfig {
 }
 export type AskVariantKind = "image" | "text" | "audio" | "video" | "document";
 export declare const ASK_VARIANT_KINDS: AskVariantKind[];
+export type AskStatus = "draft" | "running" | "completed" | "cancelled";
 export type AskRoundStatus = "running" | "completed" | "errored";
 export type AskResponseStatus = "pending" | "completed" | "errored";
 export interface AskVariant {
@@ -293,6 +294,7 @@ export interface AskCreateInput {
     language?: string;
     tester_profile_ids: string[];
     first_round: AskRoundInput;
+    dispatch?: boolean;
 }
 export interface AskUpdateInput {
     name?: string;
@@ -355,6 +357,7 @@ export interface Ask {
     name: string;
     description?: string | null;
     is_archived: boolean;
+    status?: AskStatus;
     testers: AskAudienceTester[];
     rounds: AskRound[];
     created_at: string;
@@ -367,6 +370,7 @@ export interface AskListItem {
     name: string;
     description?: string | null;
     is_archived: boolean;
+    status?: AskStatus;
     audience_count: number;
     round_count: number;
     last_round_at?: string | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ishlabs/cli",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "The command-line interface for ish",
   "type": "module",
   "bin": {