primitive-admin 1.1.0-alpha.4 → 1.1.0-alpha.41

package/dist/src/commands/workflows.js

@@ -4,8 +4,112 @@ import * as TOML from "@iarna/toml";
 import { lookup as mimeLookup } from "mime-types";
 import { ApiClient } from "../lib/api-client.js";
 import { resolveAppId } from "../lib/config.js";
+import { validateWorkflowToml, formatWorkflowTomlErrors, } from "../lib/workflow-toml-validator.js";
+import { expandWorkflow } from "../lib/workflow-fragments.js";
+import { applyWorkflowBody, workflowKeyMismatchError, } from "../lib/workflow-apply.js";
+import { confirmPrompt } from "../lib/confirm-prompt.js";
 import chalk from "chalk";
-import { success, error, info, warn, keyValue, formatTable, formatId, formatDate, formatStatus, formatDuration, json, divider, } from "../lib/output.js";
+import { success, error, printApiError, info, warn, keyValue, result as printResult, formatTable, formatId, formatDate, formatStatus, formatDuration, json, divider, progress, progressEnd, } from "../lib/output.js";
+/**
+ * Render the `Step Results` section of `workflows runs status`. Pure
+ * formatting helper — returns lines as strings so it's unit-testable
+ * (the caller console.logs them). For each step, emits:
+ *
+ *   `  <id>: <status-label> <duration>`
+ *
+ * and, when applicable, indented follow-up lines:
+ *
+ * - `error_captured` step with `error` → `    error: <truncated message>`
+ * - forEach output with `errors[]` non-empty →
+ *   `    forEach errors: <N/M> - first: <truncated message>`
+ *
+ * The truncation length matches `runs steps` ERROR column (80 chars,
+ * trailing "..." when truncated). See #688.
+ */
+/**
+ * Terminal-status predicate for the `workflows preview --wait` poll loop
+ * (issue #941). A status is terminal when the run has reached an end state and
+ * the wait should stop polling — as opposed to a still-in-flight status
+ * ("running"/"queued"/"waiting") that should keep the loop going until the cap.
+ *
+ * The admin preview-status endpoint emits these terminal values (see
+ * `mapWorkflowStatus` / the server-side `isEnded` set in admin-api.ts):
+ *   - "completed" (Cloudflare "complete" normalized)
+ *   - "failed"    (Cloudflare "errored" normalized)
+ *   - "terminated" (an aborted preview — Codex P2: previously NOT treated as
+ *     terminal, so an aborted preview was misreported as a wait timeout)
+ *
+ * We accept the un-normalized Cloudflare spellings too ("complete"/"errored")
+ * defensively, in case a status slips through un-normalized.
+ */
+export function isPreviewWaitTerminalStatus(s) {
+    return (s === "completed" ||
+        s === "complete" ||
+        s === "failed" ||
+        s === "errored" ||
+        s === "terminated");
+}
+export function renderRunStatusStepResults(stepResults) {
+    const lines = [];
+    for (const step of stepResults || []) {
+        const statusLabel = step.skipped
+            ? chalk.gray("skipped")
+            : step.status === "error_captured"
+                ? chalk.yellow("error_captured")
+                : step.status === "failed"
+                    ? chalk.red("failed")
+                    : step.status === "completed"
+                        ? chalk.green("completed")
+                        : step.status || "?";
+        const durationLabel = formatDuration(step.durationMs);
+        lines.push(`  ${step.id}: ${statusLabel} ${durationLabel}`);
+        // Single-step error_captured: show the captured error message.
+        if (step.status === "error_captured" && step.error) {
+            const errMsg = typeof step.error === "string" ? step.error : String(step.error);
+            const truncated = errMsg.length > 80 ? errMsg.slice(0, 77) + "..." : errMsg;
+            lines.push(`    ${chalk.dim("error:")} ${chalk.yellow(truncated)}`);
+        }
+        else if (step.status === "error_captured" && step.errorDetails) {
+            // No top-level error but errorDetails present — hint to drill in.
+            lines.push(`    ${chalk.dim("error: <see runs step-detail for full errorDetails>")}`);
+        }
+        // forEach aggregated errors: a one-line summary surfaces the count
+        // of `error_captured` iterations and a sample message (#688).
+        const fo = step.output;
+        if (fo && typeof fo === "object" && Array.isArray(fo.errors) && fo.errors.length > 0) {
+            const total = (Array.isArray(fo.items) ? fo.items.length : 0)
+                || (fo.totalSucceeded ?? 0) + (fo.totalFailed ?? 0);
+            const firstErr = (Array.isArray(fo.errorMessages) && fo.errorMessages.length > 0
+                ? fo.errorMessages[0]
+                : (fo.errors[0]?.error ?? "?"));
+            const firstStr = typeof firstErr === "string" ? firstErr : String(firstErr);
+            const truncated = firstStr.length > 80 ? firstStr.slice(0, 77) + "..." : firstStr;
+            lines.push(`    ${chalk.dim("forEach errors:")} ${chalk.yellow(`${fo.totalFailed ?? fo.errors.length}/${total}`)} ${chalk.dim("- first:")} ${chalk.yellow(truncated)}`);
+        }
+    }
+    return lines;
+}
+/**
+ * Issue #687 (review feedback): render an unambiguous label for a workflow
+ * config slot ("active config", "draft config", etc.) when the slot may be
+ * unnamed. Falls back to a short ID prefix so users staging multiple unnamed
+ * configs can still tell them apart.
+ *
+ *   formatConfigSlotLabel("active config", "v2", "01KRT...")        → 'active config "v2"'
+ *   formatConfigSlotLabel("active config", null, "01KRTABCDXYZ...") → 'active config (01KRTABCDXYZ…)'
+ *   formatConfigSlotLabel("active config", null, null)              → 'active config'
+ *
+ * Exported for testability.
+ */
+export function formatConfigSlotLabel(slot, configName, configId, prefixLength = 12) {
+    if (configName) {
+        return `${slot} "${configName}"`;
+    }
+    if (configId) {
+        return `${slot} (${String(configId).slice(0, prefixLength)}…)`;
+    }
+    return slot;
+}
 export function registerWorkflowsCommands(program) {
     const workflows = program
         .command("workflows")
@@ -63,35 +167,68 @@ Examples:
         .option("--name <name>", "Display name")
         .option("--description <desc>", "Description")
         .option("--from-file <path>", "Load workflow from TOML file")
+        .option("--requires-client-apply <bool>", "Require client-side apply: true or false")
+        .option("--sync-callable <bool>", "Allow client.workflows.runSync(): true or false")
         .option("--json", "Output as JSON")
         .action(async (appId, options) => {
         const resolvedAppId = resolveAppId(appId, options);
         const client = new ApiClient();
         let payload;
         if (options.fromFile) {
+            let tomlData;
             try {
                 const content = readFileSync(options.fromFile, "utf-8");
-                const tomlData = TOML.parse(content);
-                const workflow = tomlData.workflow || tomlData;
-                payload = {
-                    workflowKey: workflow.key || workflow.workflowKey,
-                    name: workflow.name,
-                    description: workflow.description,
-                    steps: tomlData.steps || [],
-                    inputSchema: workflow.inputSchema ? JSON.parse(workflow.inputSchema) : undefined,
-                    outputSchema: workflow.outputSchema ? JSON.parse(workflow.outputSchema) : undefined,
-                    perUserMaxRunning: workflow.perUserMaxRunning,
-                    perUserMaxQueued: workflow.perUserMaxQueued,
-                    perAppMaxRunning: workflow.perAppMaxRunning,
-                    perAppMaxQueued: workflow.perAppMaxQueued,
-                    queueTtlSeconds: workflow.queueTtlSeconds,
-                    dequeueOrder: workflow.dequeueOrder,
-                };
+                tomlData = TOML.parse(content);
             }
             catch (err) {
                 error(`Failed to read TOML file: ${err.message}`);
                 process.exit(1);
             }
+            // Issue #685: reject misnested headers (e.g. [steps.<id>.request])
+            // before we send anything to the server. These parse to TOML
+            // sub-tables that the runtime silently ignores. We validate
+            // outside the parse try-block so the diagnostic isn't masked by
+            // the generic "Failed to read TOML" handler.
+            const tomlErrors = validateWorkflowToml(tomlData);
+            if (tomlErrors.length > 0) {
+                error(formatWorkflowTomlErrors(options.fromFile, tomlErrors));
+                process.exit(1);
+            }
+            const workflow = tomlData.workflow || tomlData;
+            payload = {
+                workflowKey: workflow.key || workflow.workflowKey,
+                name: workflow.name,
+                description: workflow.description,
+                steps: tomlData.steps || [],
+                inputSchema: workflow.inputSchema ? JSON.parse(workflow.inputSchema) : undefined,
+                outputSchema: workflow.outputSchema ? JSON.parse(workflow.outputSchema) : undefined,
+                perUserMaxRunning: workflow.perUserMaxRunning,
+                perUserMaxQueued: workflow.perUserMaxQueued,
+                perAppMaxRunning: workflow.perAppMaxRunning,
+                perAppMaxQueued: workflow.perAppMaxQueued,
+                queueTtlSeconds: workflow.queueTtlSeconds,
+                dequeueOrder: workflow.dequeueOrder,
+                requiresClientApply: workflow.requiresClientApply,
+                // #807: align create --from-file with sync/update — read syncCallable
+                // from the TOML so all three entry points behave identically.
+                syncCallable: workflow.syncCallable,
+                // #571: carry accessRule through so a TOML's access-control rule
+                // lands on create instead of being silently dropped. On create the
+                // server default is already null, so coalesce a falsy/absent rule to
+                // undefined (omit) rather than sending "" — both clear, but undefined
+                // is the precise "no rule declared" signal.
+                accessRule: workflow.accessRule || undefined,
+                // #1173: forward the workflow principal mode (`runAs`) from the TOML,
+                // matching `sync push` create (sync.ts ~3345). Without this, a
+                // `runAs="system"` TOML reached the server as non-system, so the
+                // identity validator correctly rejected system-only steps (e.g.
+                // `iterate-users`). Create semantics — `workflow.runAs || undefined`
+                // (absent/empty → server default), NOT the presence-aware clearing
+                // form that `sync push` update uses. `capabilities` is intentionally
+                // NOT forwarded: `sync push` doesn't serialize/persist it today, so
+                // forwarding it only here would create a new asymmetry (see #1173).
+                runAs: workflow.runAs || undefined,
+            };
         }
         else {
             if (!options.key || !options.name) {
@@ -105,6 +242,12 @@ Examples:
                 steps: [],
             };
         }
+        if (options.requiresClientApply !== undefined) {
+            payload.requiresClientApply = options.requiresClientApply === "true";
+        }
+        if (options.syncCallable !== undefined) {
+            payload.syncCallable = options.syncCallable === "true";
+        }
         try {
             const result = await client.createWorkflow(resolvedAppId, payload);
             if (options.json) {
@@ -116,7 +259,9 @@ Examples:
             keyValue("Key", result.workflow?.workflowKey);
         }
         catch (err) {
-            error(err.message);
+            // #1173: render the server's structured `details[]` (e.g. the specific
+            // identity-validation reason) instead of only the generic message.
+            printApiError(err);
             process.exit(1);
         }
     });
@@ -137,19 +282,30 @@ Examples:
                 return;
             }
             const wf = result.workflow;
-            keyValue("Workflow ID", wf.workflowId);
-            keyValue("Key", wf.workflowKey);
-            keyValue("Name", wf.name);
-            keyValue("Description", wf.description);
-            keyValue("Status", formatStatus(wf.status));
-            keyValue("Active Config", wf.activeConfigId || "-");
-            keyValue("Latest Revision", wf.latestRevision || "-");
+            printResult("Workflow ID", wf.workflowId);
+            printResult("Key", wf.workflowKey);
+            printResult("Name", wf.name);
+            printResult("Description", wf.description);
+            printResult("Status", formatStatus(wf.status));
+            printResult("Active Config", wf.activeConfigId || "-");
+            printResult("Latest Revision", wf.latestRevision || "-");
+            printResult("Client Apply", wf.requiresClientApply !== false ? "yes" : "no");
+            printResult("Sync Callable", wf.syncCallable === true ? "yes" : "no");
+            // #1233 — runAs unset means the engine defaults to "caller"; show that
+            // default rather than a blank so the deployed principal mode is visible.
+            printResult("Run As", wf.runAs || "caller");
+            printResult("Capabilities", Array.isArray(wf.capabilities) && wf.capabilities.length > 0
+                ? wf.capabilities.join(", ")
+                : "-");
+            if (wf.accessRule) {
+                printResult("Access Rule", wf.accessRule);
+            }
             divider();
             info("Queue Settings:");
-            keyValue("  Per User Max Running", wf.perUserMaxRunning);
-            keyValue("  Per User Max Queued", wf.perUserMaxQueued);
-            keyValue("  Per App Max Running", wf.perAppMaxRunning);
-            keyValue("  Dequeue Order", wf.dequeueOrder);
+            printResult("  Per User Max Running", wf.perUserMaxRunning);
+            printResult("  Per User Max Queued", wf.perUserMaxQueued);
+            printResult("  Per App Max Running", wf.perAppMaxRunning);
+            printResult("  Dequeue Order", wf.dequeueOrder);
             if (wf.inputSchema) {
                 divider();
                 info("Input Schema:");
@@ -193,7 +349,7 @@ Examples:
     // Update workflow
     workflows
         .command("update")
-        .description("Update workflow metadata")
+        .description("Update workflow metadata, or push a new body with --from-file")
         .argument("<workflow-id>", "Workflow ID")
         .option("--app <app-id>", "App ID (uses current app if not specified)")
         .option("--name <name>", "Display name")
@@ -202,9 +358,114 @@ Examples:
         .option("--per-user-max-running <n>", "Max running per user")
         .option("--per-user-max-queued <n>", "Max queued per user")
         .option("--dequeue-order <order>", "Dequeue order: fifo, lifo")
+        .option("--requires-client-apply <bool>", "Require client-side apply: true or false")
+        .option("--sync-callable <bool>", "Allow client.workflows.runSync(): true or false")
+        .option("--access-rule <expr>", "CEL expression for workflow access (empty string to clear)")
+        .option("--from-file <path>", "Push a revised body (metadata + steps) from a TOML file, keeping the same key/id. " +
+        "Overwrites the active config in place — live immediately (no separate publish). " +
+        "Explicit metadata flags above override values in the TOML.")
         .option("--json", "Output as JSON")
         .action(async (workflowId, options) => {
         const resolvedAppId = resolveAppId(undefined, options);
+        // --from-file: push a full body (metadata + steps) to the existing
+        // workflow, keeping its key/id. Symmetric with `create --from-file` and
+        // mirrors the `sync push` update-existing path via the shared
+        // `applyWorkflowBody` helper (#1249).
+        if (options.fromFile) {
+            let tomlData;
+            try {
+                // Expand top-level `include = [...]` workflow fragments before
+                // deriving steps, matching what `sync push` does (`parseTomlFile`
+                // runs `expandWorkflowTomlData`). `update --from-file` overwrites an
+                // existing workflow's live active config, so parsing the raw TOML
+                // and reading only `tomlData.steps` would drop fragment-supplied
+                // steps — an include-only workflow would overwrite the live body
+                // with an empty step list (silent data loss, #1286). `expandWorkflow`
+                // reads + parses + splices fragments; a TOML with no `include` key is
+                // returned unchanged, so the non-fragment case is unaffected.
+                tomlData = expandWorkflow(options.fromFile);
+            }
+            catch (err) {
+                error(`Failed to read TOML file: ${err.message}`);
+                process.exit(1);
+            }
+            // Issue #685: reject misnested headers before sending anything to the
+            // server — identical validation to `create --from-file`. Runs on the
+            // expanded data (post fragment splice), matching `sync push`.
+            const tomlErrors = validateWorkflowToml(tomlData);
+            if (tomlErrors.length > 0) {
+                error(formatWorkflowTomlErrors(options.fromFile, tomlErrors));
+                process.exit(1);
+            }
+            const tomlWorkflow = tomlData.workflow || tomlData;
+            const steps = tomlData.steps || [];
+            const client = new ApiClient();
+            // Fetch the existing workflow: we need its real workflowKey (Fork 2
+            // key-mismatch guard) and its activeConfigId (live body overwrite).
+            let existing;
+            try {
+                const got = await client.getWorkflow(resolvedAppId, workflowId);
+                existing = got?.workflow;
+            }
+            catch (err) {
+                printApiError(err);
+                process.exit(1);
+            }
+            if (!existing) {
+                error(`Workflow not found: ${workflowId}`);
+                process.exit(1);
+            }
+            // Fork 2: a TOML key that contradicts the target's key is almost
+            // certainly the wrong file — error rather than silently ignore it.
+            const mismatch = workflowKeyMismatchError(tomlWorkflow, existing.workflowKey);
+            if (mismatch) {
+                error(mismatch);
+                process.exit(1);
+            }
+            // Fork 1 (B): explicit `update` flags override TOML-derived metadata.
+            const mergedWorkflow = { ...tomlWorkflow };
+            if (options.name)
+                mergedWorkflow.name = options.name;
+            if (options.description)
+                mergedWorkflow.description = options.description;
+            if (options.status)
+                mergedWorkflow.status = options.status;
+            if (options.perUserMaxRunning) {
+                mergedWorkflow.perUserMaxRunning = parseInt(options.perUserMaxRunning);
+            }
+            if (options.perUserMaxQueued) {
+                mergedWorkflow.perUserMaxQueued = parseInt(options.perUserMaxQueued);
+            }
+            if (options.dequeueOrder)
+                mergedWorkflow.dequeueOrder = options.dequeueOrder;
+            if (options.requiresClientApply !== undefined) {
+                mergedWorkflow.requiresClientApply = options.requiresClientApply === "true";
+            }
+            if (options.syncCallable !== undefined) {
+                mergedWorkflow.syncCallable = options.syncCallable === "true";
+            }
+            if (options.accessRule !== undefined) {
+                mergedWorkflow.accessRule = options.accessRule;
+            }
+            try {
+                const { updateSlotLabel, fullWorkflow } = await applyWorkflowBody(client, resolvedAppId, workflowId, mergedWorkflow, steps, { activeConfigId: existing.activeConfigId });
+                if (options.json) {
+                    json(fullWorkflow);
+                    return;
+                }
+                success(`Workflow updated from ${options.fromFile} (${updateSlotLabel}).`);
+                keyValue("Workflow ID", workflowId);
+                keyValue("Key", existing.workflowKey);
+                keyValue("Steps", steps.length);
+            }
+            catch (err) {
+                // Surface the server's structured `details[]` (e.g. syncCallable /
+                // identity validation reasons) like create/sync push do.
+                printApiError(err);
+                process.exit(1);
+            }
+            return;
+        }
         const payload = {};
         if (options.name)
             payload.name = options.name;
@@ -218,6 +479,19 @@ Examples:
             payload.perUserMaxQueued = parseInt(options.perUserMaxQueued);
         if (options.dequeueOrder)
             payload.dequeueOrder = options.dequeueOrder;
+        if (options.requiresClientApply !== undefined) {
+            payload.requiresClientApply = options.requiresClientApply === "true";
+        }
+        if (options.syncCallable !== undefined) {
+            payload.syncCallable = options.syncCallable === "true";
+        }
+        // #571: presence guard, NOT truthiness — `--access-rule ""` must reach
+        // the server (it clears the rule) while an omitted flag leaves
+        // options.accessRule undefined so the server's hasOwnProperty guard
+        // leaves the existing rule untouched.
+        if (options.accessRule !== undefined) {
+            payload.accessRule = options.accessRule;
+        }
         if (Object.keys(payload).length === 0) {
             error("No update options specified.");
             process.exit(1);
@@ -232,7 +506,8 @@ Examples:
             success("Workflow updated.");
         }
         catch (err) {
-            error(err.message);
+            // #1173: surface structured `details[]` on update too.
+            printApiError(err);
             process.exit(1);
         }
     });
@@ -246,24 +521,16 @@ Examples:
         .option("-y, --yes", "Skip confirmation prompt")
         .action(async (workflowId, options) => {
         const resolvedAppId = resolveAppId(undefined, options);
-        if (!options.yes) {
-            const action = options.hard ? "permanently delete" : "archive";
-            const inquirer = await import("inquirer");
-            const { confirm } = await inquirer.default.prompt([
-                {
-                    type: "confirm",
-                    name: "confirm",
-                    message: `Are you sure you want to ${action} workflow ${workflowId}?`,
-                    default: false,
-                },
-            ]);
-            if (!confirm) {
-                info("Cancelled.");
-                return;
-            }
-        }
         const client = new ApiClient();
         try {
+            if (!options.yes) {
+                const action = options.hard ? "permanently delete" : "archive";
+                const confirmed = await confirmPrompt(`Are you sure you want to ${action} workflow ${workflowId}?`);
+                if (!confirmed) {
+                    info("Cancelled.");
+                    return;
+                }
+            }
             if (options.hard) {
                 await client.deleteWorkflow(resolvedAppId, workflowId);
                 success("Workflow deleted.");
@@ -271,6 +538,10 @@ Examples:
             else {
                 await client.updateWorkflow(resolvedAppId, workflowId, { status: "archived" });
                 success("Workflow archived.");
+                // #1238 — archiving keeps the workflowKey reserved, so recreating
+                // under the same key fails with "workflowKey already exists". Point
+                // at the remedy so the reserved-key behavior is discoverable.
+                info(`The workflowKey stays reserved while archived. To free it for reuse, run: primitive workflows delete ${workflowId} --hard`);
             }
         }
         catch (err) {
@@ -278,12 +549,39 @@ Examples:
             process.exit(1);
         }
     });
+    // Expand a workflow TOML and print the result (no server contact).
+    //
+    // Authors use this to inspect what `include = [...]` fragments produce
+    // before pushing. Surfaces include-collision and unique-id failures with
+    // helpful messages without going through `sync push`.
+    workflows
+        .command("expand")
+        .description("Expand a workflow TOML's include fragments and print the result")
+        .argument("<file>", "Path to the workflow TOML file")
+        .option("--format <format>", "Output format: json (default) or toml", "json")
+        .action((file, options) => {
+        try {
+            const expanded = expandWorkflow(file);
+            if (options.format === "toml") {
+                // Strip the `include` key (already removed by expander) and emit
+                // valid TOML so the result is round-trippable.
+                console.log(TOML.stringify(expanded));
+            }
+            else {
+                console.log(JSON.stringify(expanded, null, 2));
+            }
+        }
+        catch (err) {
+            error(err?.message ?? String(err));
+            process.exit(1);
+        }
+    });
     // Draft subcommand
     const draft = workflows.command("draft").description("Manage workflow draft");
     // Update draft
     draft
         .command("update")
-        .description("Update workflow draft steps")
+        .description("Update workflow draft steps (deprecated; use 'workflows configs' for staged rollouts)")
         .argument("<workflow-id>", "Workflow ID")
         .option("--app <app-id>", "App ID (uses current app if not specified)")
         .option("--from-file <path>", "Load steps from TOML file")
@@ -294,21 +592,27 @@ Examples:
             error("--from-file is required");
             process.exit(1);
         }
-        let payload;
+        let tomlData;
         try {
             const content = readFileSync(options.fromFile, "utf-8");
-            const tomlData = TOML.parse(content);
-            const workflow = tomlData.workflow || tomlData;
-            payload = {
-                steps: tomlData.steps || [],
-                inputSchema: workflow.inputSchema ? JSON.parse(workflow.inputSchema) : undefined,
-                outputSchema: workflow.outputSchema ? JSON.parse(workflow.outputSchema) : undefined,
-            };
+            tomlData = TOML.parse(content);
         }
         catch (err) {
             error(`Failed to read TOML file: ${err.message}`);
             process.exit(1);
         }
+        // Issue #685: reject misnested headers before pushing.
+        const tomlErrors = validateWorkflowToml(tomlData);
+        if (tomlErrors.length > 0) {
+            error(formatWorkflowTomlErrors(options.fromFile, tomlErrors));
+            process.exit(1);
+        }
+        const workflow = tomlData.workflow || tomlData;
+        const payload = {
+            steps: tomlData.steps || [],
+            inputSchema: workflow.inputSchema ? JSON.parse(workflow.inputSchema) : undefined,
+            outputSchema: workflow.outputSchema ? JSON.parse(workflow.outputSchema) : undefined,
+        };
         const client = new ApiClient();
         try {
             const result = await client.updateWorkflowDraft(resolvedAppId, workflowId, payload);
@@ -318,8 +622,27 @@ Examples:
             }
             success("Draft updated.");
             keyValue("Steps", result.draft?.steps?.length || 0);
+            // Issue #687: surface server-side deprecation hint when applicable.
+            if (result.deprecation) {
+                warn(`[deprecated] ${result.deprecation}`);
+            }
         }
         catch (err) {
+            // Issue #987: config-model workflows reject the legacy draft slot with
+            // a 409 (the draft never executes). Surface the actionable config path
+            // cleanly instead of dumping a raw API error.
+            if (err?.statusCode === 409 && err?.code === "WORKFLOW_CONFIG_MODEL") {
+                error("This workflow has an active configuration, so the legacy draft slot is inert " +
+                    "(it won't change what runs). For dev-loop edits, use 'sync push' — it writes the\n" +
+                    "active config directly and activates the workflow end-to-end:\n" +
+                    "  primitive sync push\n" +
+                    "For staged rollouts, create + activate a config, then flip the status to active\n" +
+                    "(configs activate only sets the active config; it does not change the workflow status):\n" +
+                    "  primitive workflows configs create <workflow-id> --name <name> --from-file <path>\n" +
+                    "  primitive workflows configs activate <workflow-id> <config-id>\n" +
+                    "  primitive workflows update <workflow-id> --status active");
+                process.exit(1);
+            }
             error(err.message);
             process.exit(1);
         }
@@ -327,7 +650,7 @@ Examples:
     // Publish workflow
     workflows
         .command("publish")
-        .description("Publish the current draft as a new revision")
+        .description("Publish the current draft as a new revision (deprecated for new-model workflows; use 'workflows configs activate')")
         .argument("<workflow-id>", "Workflow ID")
         .option("--app <app-id>", "App ID (uses current app if not specified)")
         .option("--json", "Output as JSON")
@@ -343,8 +666,27 @@ Examples:
             success("Workflow published.");
             keyValue("Revision ID", result.revision?.revisionId);
             keyValue("Published At", formatDate(result.revision?.publishedAt));
+            // Issue #687: surface server-side deprecation hint when applicable.
+            if (result.deprecation) {
+                warn(`[deprecated] ${result.deprecation}`);
+            }
         }
         catch (err) {
+            // Issue #987: 'publish' is inert on config-model workflows (production
+            // runs read the active config), so the server rejects with a 409.
+            // Point the user at the config primitives instead of a raw API error.
+            if (err?.statusCode === 409 && err?.code === "WORKFLOW_CONFIG_MODEL") {
+                error("This workflow has an active configuration, so 'publish' is inert " +
+                    "(it bumps a legacy pointer that doesn't change what runs). For dev-loop edits, use\n" +
+                    "'sync push' — it writes the active config directly and activates the workflow end-to-end:\n" +
+                    "  primitive sync push\n" +
+                    "For staged rollouts, create + activate a config, then flip the status to active\n" +
+                    "(configs activate only sets the active config; it does not change the workflow status):\n" +
+                    "  primitive workflows configs create <workflow-id> --name <name> --from-file <path>\n" +
+                    "  primitive workflows configs activate <workflow-id> <config-id>\n" +
+                    "  primitive workflows update <workflow-id> --status active");
+                process.exit(1);
+            }
             error(err.message);
             process.exit(1);
         }
@@ -355,12 +697,18 @@ Examples:
         .description("Run a preview execution of the workflow")
         .argument("<workflow-id>", "Workflow ID")
         .option("--app <app-id>", "App ID (uses current app if not specified)")
-        .option("--config <config-id>", "Use specific configuration (uses draft if not specified)")
+        .option("--config <config-id>", "Use specific configuration")
+        .option("--draft", "Force preview of the draft version, even if active is newer")
+        .option("--active", "Force preview of the active config, even if a newer draft exists (issue #687)")
         .option("--input <json>", "Root input as JSON")
         .option("--wait", "Wait for completion and show result")
         .option("--json", "Output as JSON")
         .action(async (workflowId, options) => {
         const resolvedAppId = resolveAppId(undefined, options);
+        if (options.draft && options.active) {
+            error("--draft and --active are mutually exclusive");
+            process.exit(1);
+        }
         let rootInput;
         if (options.input) {
             try {
@@ -376,7 +724,15 @@ Examples:
             const result = await client.previewWorkflow(resolvedAppId, workflowId, {
                 rootInput,
                 configId: options.config,
+                useDraft: options.draft || false,
+                // Issue #687: --active forces the active config even when a newer
+                // draft exists (the inverse of --draft).
+                preferActive: options.active || false,
             });
+            // Display warning from the server (e.g. "previewing draft because newer than active")
+            if (result.warning) {
+                warn(result.warning);
+            }
             if (!options.wait) {
                 if (options.json) {
                     json(result);
@@ -384,26 +740,72 @@ Examples:
                 }
                 success("Preview started.");
                 keyValue("Instance ID", result.instanceId);
+                // Issue #687: name the side we ran so the user always knows which
+                // version produced the output (the "print the source" pattern).
+                const source = result.source;
+                if (source === "draft") {
+                    info("Previewing draft version.");
+                }
+                else if (source === "active") {
+                    // Issue #687 (review feedback): when configName is missing,
+                    // fall back to a short ID prefix so users staging multiple
+                    // unnamed configs can disambiguate.
+                    const label = formatConfigSlotLabel("active config", result.configName, result.configId);
+                    info(`Previewing ${label}.`);
+                }
+                else if (source === "config") {
+                    const label = formatConfigSlotLabel("the requested config", result.configName, result.configId);
+                    info(`Previewing ${label}.`);
+                }
                 info("Use 'workflows runs status' to check progress.");
                 return;
             }
-            // Poll for completion
+            // Poll for completion. Issue #941: track whether the loop broke on a
+            // terminal state vs. ran to exhaustion, so a timed-out wait is
+            // distinguishable from a workflow that legitimately reported "running".
             info("Waiting for completion...");
             let status;
-            const maxAttempts = 60;
+            // Fixed ~60s cap (60 × 1s sleep + RTT). PRIMITIVE_PREVIEW_WAIT_ATTEMPTS
+            // overrides the iteration count for tests that exercise the
+            // poll-loop-exhaustion path without a full 60s wait; unset in normal use.
+            const maxAttempts = (() => {
+                const raw = process.env.PRIMITIVE_PREVIEW_WAIT_ATTEMPTS;
+                const parsed = raw ? parseInt(raw, 10) : NaN;
+                return Number.isInteger(parsed) && parsed > 0 ? parsed : 60;
+            })();
+            let reachedTerminal = false;
             for (let i = 0; i < maxAttempts; i++) {
                 await new Promise((r) => setTimeout(r, 1000));
                 const statusResult = await client.getPreviewStatus(resolvedAppId, workflowId, result.instanceId);
                 status = statusResult.status;
-                if (status?.status === "completed" || status?.status === "failed") {
+                const s = status?.status;
+                // Issue #941 (Codex P2): an aborted preview reports
+                // status:"terminated" from the admin preview-status endpoint, which
+                // is a real terminal state — the wait did NOT time out. The shared
+                // predicate includes it so the loop breaks and `waitTimedOut` stays
+                // false (vs. the prior check that omitted "terminated" and let the
+                // loop run to the cap, misreporting an abort as a timeout).
+                if (isPreviewWaitTerminalStatus(s)) {
+                    reachedTerminal = true;
                     break;
                 }
             }
+            // Issue #941: on poll-loop exhaustion with a still-non-terminal run,
+            // emit an explicit timeout signal and exit non-zero (124, the GNU
+            // `timeout` convention) instead of silently returning the bare
+            // non-terminal status as if the wait succeeded.
+            const waitTimedOut = !reachedTerminal;
             if (options.json) {
-                json({ instanceId: result.instanceId, status });
+                // Additive field only — `status` is preserved so existing parsers
+                // don't break; `waitTimedOut` lets automation tell "still running,
+                // wait gave up" from "finished".
+                json({ instanceId: result.instanceId, status, waitTimedOut });
+                if (waitTimedOut) {
+                    process.exit(124);
+                }
                 return;
             }
-            if (status?.status === "completed") {
+            if (status?.status === "completed" || status?.status === "complete") {
                 success("Preview completed.");
                 if (status.output) {
                     console.log("\nOutput:");
@@ -417,15 +819,24 @@ Examples:
                     });
                 }
             }
-            else if (status?.status === "failed") {
+            else if (status?.status === "failed" || status?.status === "errored") {
                 error("Preview failed.");
                 if (status.error) {
                     console.log("\nError:");
                     console.log(JSON.stringify(status.error, null, 2));
                 }
             }
+            else if (status?.status === "terminated") {
+                // Issue #941 (Codex P2): the preview was aborted (e.g. via
+                // `workflows preview ... abort`, or an external terminate). This is a
+                // real terminal state — NOT a timeout — so render it distinctly and
+                // exit 0 (the wait succeeded in observing a terminal result).
+                warn("Preview was terminated (aborted before completion).");
+            }
             else {
-                info("Preview still running. Check status with 'workflows runs status'.");
+                // Timed out without ever reaching a terminal state (issue #941).
+                error(`Wait timed out after ${maxAttempts}s; preview still running. Check status with 'workflows runs status'.`);
+                process.exit(124);
             }
         }
         catch (err) {
@@ -506,9 +917,9 @@ Examples:
                 if (status.stepResults && status.stepResults.length > 0) {
                     divider();
                     info("Step Results:");
-                    status.stepResults.forEach((step) => {
-                        console.log(`  ${step.id}: ${formatDuration(step.durationMs)} ${step.skipped ? "(skipped)" : ""}`);
-                    });
+                    for (const line of renderRunStatusStepResults(status.stepResults)) {
+                        console.log(line);
+                    }
                 }
                 if (status.error) {
                     divider();
@@ -522,6 +933,462 @@ Examples:
             process.exit(1);
         }
     });
+    // Steps for a run
+    runs
+        .command("steps")
+        .description("Show step-level details for a workflow run")
+        .argument("<workflow-id>", "Workflow ID")
+        .argument("<run-id>", "Run ID")
+        .option("--app <app-id>", "App ID")
+        .option("--json", "Output as JSON")
+        .action(async (workflowId, runId, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        const client = new ApiClient();
+        try {
+            const { items } = await client.getWorkflowStepRuns(resolvedAppId, workflowId, runId);
+            if (options.json) {
+                json(items);
+                return;
+            }
+            if (!items || items.length === 0) {
+                info("No step runs found.");
+                return;
+            }
+            console.log(formatTable(items, [
+                { header: "STEP", key: "stepId" },
+                { header: "KIND", key: "stepKind" },
+                {
+                    header: "STATUS",
+                    key: "status",
+                    format: (v) => v === "completed" ? chalk.green(v) :
+                        v === "failed" ? chalk.red(v) :
+                            v === "skipped" ? chalk.gray(v) :
+                                v === "error_captured" ? chalk.yellow(v) : v,
+                },
+                { header: "DURATION", key: "durationMs", format: formatDuration },
+                {
+                    header: "TOKENS",
+                    key: "totalTokens",
+                    format: (v) => v ? String(v).replace(/\B(?=(\d{3})+(?!\d))/g, ",") : "-",
+                },
+                {
+                    header: "ERROR",
+                    key: "error",
+                    format: (v) => v ? (v.length > 60 ? v.slice(0, 57) + "..." : v) : "",
+                },
+            ]));
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // Step detail
+    runs
+        .command("step-detail")
+        .description("Show full details for a single step")
+        .argument("<workflow-id>", "Workflow ID")
+        .argument("<run-id>", "Run ID")
+        .argument("<step-id>", "Step ID")
+        .option("--app <app-id>", "App ID")
+        .option("--json", "Output as JSON")
+        .action(async (workflowId, runId, stepId, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        const client = new ApiClient();
+        try {
+            const { items } = await client.getWorkflowStepRuns(resolvedAppId, workflowId, runId);
+            const step = items.find((s) => s.stepId === stepId);
+            if (!step) {
+                error(`Step "${stepId}" not found in run ${runId}`);
+                process.exit(1);
+            }
+            if (options.json) {
+                json(step);
+                return;
+            }
+            keyValue("Step", step.stepId);
+            keyValue("Kind", step.stepKind);
+            keyValue("Status", formatStatus(step.status));
+            keyValue("Duration", formatDuration(step.durationMs));
+            keyValue("Started", formatDate(step.startedAt));
+            keyValue("Ended", formatDate(step.endedAt));
+            if (step.totalTokens) {
+                keyValue("Tokens", `${step.inputTokens || 0} in / ${step.outputTokens || 0} out / ${step.totalTokens} total`);
+            }
+            if (step.retryCount) {
+                keyValue("Retries", String(step.retryCount));
+            }
+            if (step.config) {
+                divider();
+                info("Config (rendered):");
+                console.log(JSON.stringify(step.config, null, 2));
+            }
+            if (step.rawConfig) {
+                divider();
+                info("Config (raw):");
+                console.log(JSON.stringify(step.rawConfig, null, 2));
+            }
+            if (step.input) {
+                divider();
+                info("Input:");
+                console.log(JSON.stringify(step.input, null, 2));
+            }
+            if (step.output) {
+                divider();
+                info("Output:");
+                console.log(JSON.stringify(step.output, null, 2));
+            }
+            if (step.error) {
+                divider();
+                error("Error: " + step.error);
+                if (step.errorDetails) {
+                    console.log(step.errorDetails);
+                }
+            }
+            if (step.templateWarnings && step.templateWarnings.length > 0) {
+                divider();
+                warn("Template Warnings:");
+                step.templateWarnings.forEach((w) => {
+                    console.log(`  ${w.expression}: ${w.message}`);
+                });
+            }
+            if (step.context) {
+                divider();
+                info("Context Snapshot:");
+                console.log(JSON.stringify(step.context, null, 2));
+            }
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // Integration call logs for a run (cross-pivot from workflow-run to
+    // integrations.logs — see issue #699).
+    runs
+        .command("logs")
+        .description("List integration calls made by a specific workflow run (cross-pivot of `integrations logs`)")
+        .argument("<run-id>", "Workflow run ID")
+        .option("--app <app-id>", "App ID (uses current app if not specified)")
+        .option("--limit <n>", "Number of logs to show", "100")
+        .option("--json", "Output as JSON")
+        .action(async (runId, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        const client = new ApiClient();
+        try {
+            const logs = await client.listWorkflowRunIntegrationLogs(resolvedAppId, runId, { limit: parseInt(options.limit) });
+            if (options.json) {
+                json(logs);
+                return;
+            }
+            if (!logs || logs.length === 0) {
+                info("No integration calls found for this run.");
+                return;
+            }
+            console.log(formatTable(logs, [
+                { header: "TIME", key: "timestamp", format: formatDate },
+                { header: "STEP", key: "stepId", format: (v) => v || "" },
+                {
+                    header: "INTEGRATION",
+                    key: "integrationKey",
+                    format: (v) => v || "",
+                },
+                { header: "METHOD", key: "method" },
+                { header: "PATH", key: "path" },
+                { header: "STATUS", key: "status" },
+                { header: "DURATION", key: "durationMs", format: formatDuration },
+                { header: "TRACE", key: "traceId", format: formatId },
+            ]));
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // Error summary
+    runs
+        .command("error")
+        .description("Show error details for a failed workflow run")
+        .argument("<workflow-id>", "Workflow ID")
+        .argument("<run-id>", "Run ID")
+        .option("--app <app-id>", "App ID")
+        .option("--json", "Output as JSON")
+        .action(async (workflowId, runId, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        const client = new ApiClient();
+        try {
+            const [runResult, stepsResult] = await Promise.all([
+                client.getWorkflowRunStatus(resolvedAppId, workflowId, runId),
+                client.getWorkflowStepRuns(resolvedAppId, workflowId, runId),
+            ]);
+            const failedStep = stepsResult.items.find((s) => s.status === "failed");
+            const errorInfo = {
+                runId,
+                status: runResult.run?.status,
+                errorMessage: runResult.run?.errorMessage || runResult.instanceStatus?.error?.message,
+                failedStep: failedStep ? {
+                    stepId: failedStep.stepId,
+                    stepKind: failedStep.stepKind,
+                    error: failedStep.error,
+                    errorDetails: failedStep.errorDetails,
+                    input: failedStep.input,
+                    config: failedStep.config,
+                } : null,
+            };
+            if (options.json) {
+                json(errorInfo);
+                return;
+            }
+            keyValue("Run ID", runId);
+            keyValue("Status", formatStatus(errorInfo.status));
+            if (errorInfo.errorMessage) {
+                divider();
+                error("Error: " + errorInfo.errorMessage);
+            }
+            if (failedStep) {
+                divider();
+                info(`Failed Step: ${failedStep.stepId} (${failedStep.stepKind})`);
+                if (failedStep.error) {
+                    error("  " + failedStep.error);
+                }
+                if (failedStep.errorDetails) {
+                    console.log(failedStep.errorDetails);
+                }
+                if (failedStep.input) {
+                    divider();
+                    info("Step Input:");
+                    console.log(JSON.stringify(failedStep.input, null, 2));
+                }
+                if (failedStep.config) {
+                    divider();
+                    info("Step Config:");
+                    console.log(JSON.stringify(failedStep.config, null, 2));
+                }
+            }
+            else {
+                info("No failed step found in step runs.");
+            }
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // Failures list
+    runs
+        .command("failures")
+        .description("List recent workflow run failures")
+        .argument("<workflow-id>", "Workflow ID")
+        .option("--app <app-id>", "App ID")
+        .option("--limit <n>", "Number of failures to show", "10")
+        .option("--json", "Output as JSON")
+        .action(async (workflowId, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        const client = new ApiClient();
+        try {
+            const { items } = await client.listWorkflowRuns(resolvedAppId, workflowId, {
+                status: "failed",
+                limit: parseInt(options.limit),
+            });
+            if (options.json) {
+                json(items);
+                return;
+            }
+            if (!items || items.length === 0) {
+                info("No failures found.");
+                return;
+            }
+            console.log(formatTable(items, [
+                { header: "RUN ID", key: "runId", format: formatId },
+                { header: "ERROR", key: "errorMessage", format: (v) => v ? (v.length > 50 ? v.slice(0, 47) + "..." : v) : "-" },
+                { header: "STARTED", key: "startedAt", format: formatDate },
+                { header: "ENDED", key: "endedAt", format: formatDate },
+            ]));
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // ── Iterations: inspect / reset iterate-users singleton iterations (#1209) ──
+    const iterations = workflows
+        .command("iterations")
+        .description("Inspect and reset iterate-users iterations");
+    iterations
+        .command("list")
+        .description("List iterate-users iterations for the app")
+        .option("--app <app-id>", "App ID (uses current app if not specified)")
+        .option("--json", "Output as JSON")
+        .action(async (options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        const client = new ApiClient();
+        try {
+            const { items } = await client.listIterations(resolvedAppId);
+            if (options.json) {
+                json(items);
+                return;
+            }
+            if (!items || items.length === 0) {
+                info("No iterations found.");
+                return;
+            }
+            console.log(formatTable(items, [
+                { header: "ITERATION", key: "iterationName" },
+                { header: "STATUS", key: "status", format: formatStatus },
+                { header: "ACQUIRED", key: "lastAcquireMode", format: (v) => v || "" },
+                { header: "PROCESSED", key: "totalProcessed" },
+                { header: "FAILED", key: "failedCount" },
+                { header: "LAST RUN", key: "lastRunAt", format: formatDate },
+            ]));
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    iterations
+        .command("get")
+        .description("Show details for a single iterate-users iteration")
+        .argument("<name>", "Iteration name")
+        .option("--app <app-id>", "App ID (uses current app if not specified)")
+        .option("--json", "Output as JSON")
+        .action(async (name, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        const client = new ApiClient();
+        try {
+            const it = await client.getIteration(resolvedAppId, name);
+            if (options.json) {
+                json(it);
+                return;
+            }
+            keyValue("Iteration", it.iterationName);
+            keyValue("Status", formatStatus(it.status));
+            keyValue("Acquired as", it.lastAcquireMode || "(unknown)");
+            keyValue("Run ID", it.runId);
+            keyValue("Instance ID", it.instanceId);
+            keyValue("Started", formatDate(it.startedAt));
+            keyValue("Last run", formatDate(it.lastRunAt));
+            keyValue("Lock expires", formatDate(it.lockExpiresAt));
+            keyValue("Processed", String(it.totalProcessed ?? 0));
+            keyValue("Succeeded", String(it.succeededCount ?? 0));
+            keyValue("Failed (total)", String(it.failedCount ?? 0));
+            keyValue("Skipped", String(it.skippedCount ?? 0));
+            if (it.lastError) {
+                keyValue("Last error", it.lastError);
+            }
+            const sample = Array.isArray(it.failedUserIdsSample)
+                ? it.failedUserIdsSample
+                : [];
+            if (sample.length > 0) {
+                const label = it.failedUserIdsTruncated
+                    ? `Failed user IDs (sample, truncated; ${it.failedCount} total)`
+                    : `Failed user IDs (sample)`;
+                keyValue(label, sample.join(", "));
+            }
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    iterations
+        .command("reset")
+        .description("Reset a terminal (completed/failed) iteration so the next trigger runs fresh")
+        .argument("<name>", "Iteration name")
+        .option("--app <app-id>", "App ID (uses current app if not specified)")
+        .option("--json", "Output as JSON")
+        .action(async (name, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        const client = new ApiClient();
+        try {
+            const res = await client.resetIteration(resolvedAppId, name);
+            if (options.json) {
+                json(res);
+                return;
+            }
+            success(`Reset iteration "${name}" (was ${res.previousStatus}). The next trigger will run fresh.`);
+        }
+        catch (err) {
+            // A running iteration is refused with 409 + lock metadata — surface a
+            // clear message rather than a raw error.
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // Analytics overview
+    const analyticsCmd = workflows.command("analytics").description("View workflow performance analytics");
+    analyticsCmd
+        .command("overview")
+        .description("View workflow performance metrics")
+        .option("--app <app-id>", "App ID")
+        .option("--days <n>", "Time window in days", "7")
+        .option("--json", "Output as JSON")
+        .action(async (options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        const client = new ApiClient();
+        try {
+            const result = await client.getWorkflowAnalytics(resolvedAppId, {
+                windowDays: parseInt(options.days),
+            });
+            if (options.json) {
+                json(result);
+                return;
+            }
+            info(`Workflow Analytics (${result.windowDays || options.days} days)`);
+            console.log();
+            keyValue("Total Runs", String(result.totals?.totalRuns ?? 0));
+            keyValue("Success Rate", `${((result.totals?.successRate ?? 0) * 100).toFixed(1)}%`);
+            keyValue("Avg Duration", formatDuration(result.totals?.avgDurationMs));
+            if (result.tokenUsage) {
+                console.log();
+                info("Token Usage:");
+                keyValue("  Input Tokens", String(result.tokenUsage.totalInputTokens ?? 0));
+                keyValue("  Output Tokens", String(result.tokenUsage.totalOutputTokens ?? 0));
+                keyValue("  Total Tokens", String(result.tokenUsage.totalTokens ?? 0));
+            }
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    analyticsCmd
+        .command("top")
+        .description("View top workflows by usage")
+        .option("--app <app-id>", "App ID")
+        .option("--days <n>", "Time window in days", "7")
+        .option("--limit <n>", "Number of workflows to show", "10")
+        .option("--json", "Output as JSON")
+        .action(async (options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        const client = new ApiClient();
+        try {
+            const result = await client.getTopWorkflows(resolvedAppId, {
+                windowDays: parseInt(options.days),
+                limit: parseInt(options.limit),
+            });
+            if (options.json) {
+                json(result);
+                return;
+            }
+            if (!result.items || result.items.length === 0) {
+                info("No workflow activity in this period.");
+                return;
+            }
+            console.log(formatTable(result.items, [
+                { header: "WORKFLOW", key: "workflow" },
+                { header: "RUNS", key: "executions" },
+                { header: "SUCCESS", key: "success_pct", format: (v) => `${v}%` },
+                { header: "P50", key: "p50", format: (v) => formatDuration(v) },
+                { header: "P95", key: "p95", format: (v) => formatDuration(v) },
+                { header: "TOKENS", key: "total_tokens", format: (v) => v ? String(Math.round(v)).replace(/\B(?=(\d{3})+(?!\d))/g, ",") : "-" },
+            ]));
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
     // ============================================
     // CONFIGS SUBCOMMAND
     // ============================================
@@ -593,12 +1460,12 @@ Examples:
                 json(config);
                 return;
             }
-            keyValue("Config ID", config.configId);
-            keyValue("Name", config.configName);
-            keyValue("Description", config.description || "-");
-            keyValue("Status", formatStatus(config.status));
-            keyValue("Created", formatDate(config.createdAt));
-            keyValue("Modified", formatDate(config.modifiedAt));
+            printResult("Config ID", config.configId);
+            printResult("Name", config.configName);
+            printResult("Description", config.description || "-");
+            printResult("Status", formatStatus(config.status));
+            printResult("Created", formatDate(config.createdAt));
+            printResult("Modified", formatDate(config.modifiedAt));
             if (config.steps && config.steps.length > 0) {
                 divider();
                 info(`Steps (${config.steps.length}):`);
@@ -630,15 +1497,22 @@ Examples:
         }
         let steps = [];
         if (options.fromFile) {
+            let tomlData;
             try {
                 const content = readFileSync(options.fromFile, "utf-8");
-                const tomlData = TOML.parse(content);
-                steps = tomlData.steps || [];
+                tomlData = TOML.parse(content);
             }
             catch (err) {
                 error(`Failed to read TOML file: ${err.message}`);
                 process.exit(1);
             }
+            // Issue #685: reject misnested headers before pushing.
+            const tomlErrors = validateWorkflowToml(tomlData);
+            if (tomlErrors.length > 0) {
+                error(formatWorkflowTomlErrors(options.fromFile, tomlErrors));
+                process.exit(1);
+            }
+            steps = tomlData.steps || [];
         }
         const client = new ApiClient();
         try {
@@ -678,15 +1552,22 @@ Examples:
         if (options.description !== undefined)
             payload.description = options.description;
         if (options.fromFile) {
+            let tomlData;
             try {
                 const content = readFileSync(options.fromFile, "utf-8");
-                const tomlData = TOML.parse(content);
-                payload.steps = tomlData.steps || [];
+                tomlData = TOML.parse(content);
             }
             catch (err) {
                 error(`Failed to read TOML file: ${err.message}`);
                 process.exit(1);
             }
+            // Issue #685: reject misnested headers before pushing.
+            const tomlErrors = validateWorkflowToml(tomlData);
+            if (tomlErrors.length > 0) {
+                error(formatWorkflowTomlErrors(options.fromFile, tomlErrors));
+                process.exit(1);
+            }
+            payload.steps = tomlData.steps || [];
         }
         if (Object.keys(payload).length === 0) {
             error("No update options specified. Use --name, --description, or --from-file.");
@@ -772,15 +1653,14 @@ Examples:
         .action(async (workflowId, configId, options) => {
         const resolvedAppId = resolveAppId(undefined, options);
         if (!options.yes) {
-            const inquirer = await import("inquirer");
-            const { confirm } = await inquirer.default.prompt([
-                {
-                    type: "confirm",
-                    name: "confirm",
-                    message: `Are you sure you want to archive configuration ${configId}?`,
-                    default: false,
-                },
-            ]);
+            let confirm;
+            try {
+                confirm = await confirmPrompt(`Are you sure you want to archive configuration ${configId}?`);
+            }
+            catch (err) {
+                error(err.message);
+                process.exit(1);
+            }
             if (!confirm) {
                 info("Cancelled.");
                 return;
@@ -925,13 +1805,15 @@ Examples:
                 json(result);
                 return;
             }
-            keyValue("Test Case ID", result.testCaseId);
-            keyValue("Name", result.name);
-            keyValue("Created", formatDate(result.createdAt));
+            printResult("Test Case ID", result.testCaseId);
+            printResult("Name", result.name);
+            printResult("Created", formatDate(result.createdAt));
             divider();
             info("Input Variables:");
             try {
-                const vars = JSON.parse(result.inputVariables || "{}");
+                const vars = typeof result.inputVariables === 'string'
+                    ? JSON.parse(result.inputVariables || "{}")
+                    : (result.inputVariables || {});
                 console.log(JSON.stringify(vars, null, 2));
             }
             catch {
@@ -939,13 +1821,16 @@ Examples:
             }
             if (result.expectedOutputPattern) {
                 divider();
-                keyValue("Expected Pattern", result.expectedOutputPattern);
+                printResult("Expected Pattern", result.expectedOutputPattern);
             }
             if (result.expectedOutputContains) {
                 divider();
                 info("Expected Contains:");
                 try {
-                    console.log(JSON.stringify(JSON.parse(result.expectedOutputContains), null, 2));
+                    const contains = typeof result.expectedOutputContains === 'string'
+                        ? JSON.parse(result.expectedOutputContains)
+                        : result.expectedOutputContains;
+                    console.log(JSON.stringify(contains, null, 2));
                 }
                 catch {
                     console.log(result.expectedOutputContains);
@@ -955,7 +1840,10 @@ Examples:
                 divider();
                 info("Expected JSON Subset:");
                 try {
-                    console.log(JSON.stringify(JSON.parse(result.expectedJsonSubset), null, 2));
+                    const subset = typeof result.expectedJsonSubset === 'string'
+                        ? JSON.parse(result.expectedJsonSubset)
+                        : result.expectedJsonSubset;
+                    console.log(JSON.stringify(subset, null, 2));
                 }
                 catch {
                     console.log(result.expectedJsonSubset);
@@ -1056,15 +1944,14 @@ Examples:
         .action(async (workflowId, testCaseId, options) => {
         const resolvedAppId = resolveAppId(undefined, options);
         if (!options.yes) {
-            const inquirer = await import("inquirer");
-            const { confirm } = await inquirer.default.prompt([
-                {
-                    type: "confirm",
-                    name: "confirm",
-                    message: `Are you sure you want to delete test case ${testCaseId}?`,
-                    default: false,
-                },
-            ]);
+            let confirm;
+            try {
+                confirm = await confirmPrompt(`Are you sure you want to delete test case ${testCaseId}?`);
+            }
+            catch (err) {
+                error(err.message);
+                process.exit(1);
+            }
             if (!confirm) {
                 info("Cancelled.");
                 return;
@@ -1337,9 +2224,10 @@ Examples:
                 while (result.status === "running") {
                     await new Promise((r) => setTimeout(r, 2000));
                     result = await fetchStatus();
-                    process.stdout.write(`\r  Completed: ${result.completed}/${result.results?.length || 0}  `);
+                    // Progress goes to stderr so it can't corrupt JSON on stdout under --json.
+                    progress(`  Completed: ${result.completed}/${result.results?.length || 0}  `);
                 }
-                console.log();
+                progressEnd();
             }
             if (options.json) {
                 json(result);
@@ -1383,15 +2271,14 @@ Examples:
         .action(async (workflowId, batchId, options) => {
         const resolvedAppId = resolveAppId(undefined, options);
         if (!options.yes) {
-            const inquirer = await import("inquirer");
-            const { confirm } = await inquirer.default.prompt([
-                {
-                    type: "confirm",
-                    name: "confirm",
-                    message: `Are you sure you want to cancel batch ${batchId}?`,
-                    default: false,
-                },
-            ]);
+            let confirm;
+            try {
+                confirm = await confirmPrompt(`Are you sure you want to cancel batch ${batchId}?`);
+            }
+            catch (err) {
+                error(err.message);
+                process.exit(1);
+            }
             if (!confirm) {
                 info("Cancelled.");
                 return;
@@ -1555,15 +2442,14 @@ Examples:
         .action(async (workflowId, testCaseId, filename, options) => {
         const resolvedAppId = resolveAppId(undefined, options);
         if (!options.yes) {
-            const inquirer = await import("inquirer");
-            const { confirm } = await inquirer.default.prompt([
-                {
-                    type: "confirm",
-                    name: "confirm",
-                    message: `Are you sure you want to delete attachment "${filename}"?`,
-                    default: false,
-                },
-            ]);
+            let confirm;
+            try {
+                confirm = await confirmPrompt(`Are you sure you want to delete attachment "${filename}"?`);
+            }
+            catch (err) {
+                error(err.message);
+                process.exit(1);
+            }
             if (!confirm) {
                 info("Cancelled.");
                 return;