primitive-admin 1.1.0-alpha.6 → 1.1.0-alpha.60

package/dist/src/commands/workflows.js

@@ -1,21 +1,240 @@
-import { readFileSync, writeFileSync, statSync } from "fs";
+import { readFileSync, writeFileSync, statSync, readdirSync, } from "fs";
 import { basename } from "path";
-import * as TOML from "@iarna/toml";
+import * as path from "path";
+import { stringifyConfigToml } from "../lib/config-toml.js";
 import { lookup as mimeLookup } from "mime-types";
+import { generateWorkflowTypes, } from "../lib/workflow-codegen/generator.js";
+import { generateWorkflowSwiftTypes } from "../lib/swift-codegen/generator.js";
 import { ApiClient } from "../lib/api-client.js";
 import { resolveAppId } from "../lib/config.js";
+import { resolveCodegenSourceDir } from "../lib/codegen-shared/resolveCodegenSourceDir.js";
+import { expandWorkflow } from "../lib/workflow-fragments.js";
+import { confirmPrompt } from "../lib/confirm-prompt.js";
+import { buildWorkflowRunEnvelope, buildWorkflowStepEnvelope, collectWorkflowFailures, describeEmptyRunPage, describeFailureSweep, formatFailureCodeCell, formatFailureErrorCell, formatFailureStepCell, selectFailedStepRow, toWorkflowRunInspectionRow, DEFAULT_FAILURE_SWEEP_MAX_SCAN, FAILURE_SWEEP_MAX_REQUESTS, SERVER_SCAN_ROWS_PER_REQUEST, } from "../lib/log-inspection.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, info, warn, keyValue, result as printResult, formatTable, formatId, formatDate, formatStatus, formatDuration, json, jsonLine, divider, dim, progress, progressEnd, } from "../lib/output.js";
+import { pollUntil, followLoop, watchLoop, parseIntervalSeconds, } from "../lib/watch.js";
+import { APPLY_RUN_STATUSES, RUN_STATUS_LIST, SETTLED_RUN_STATUSES, } from "../lib/run-status.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.
+ */
+/**
+ * Stop-polling predicate for the `workflows preview --wait` loop (issues #941,
+ * #2348). True when the run has settled and the wait should stop — as opposed
+ * to a still-in-flight status ("queued"/"running") that keeps the loop going
+ * until the cap.
+ *
+ * Since #2348 the server reconciles every status surface onto the canonical
+ * vocabulary before it goes on the wire, so this reads the one shared set in
+ * `lib/run-status.ts` instead of re-deriving terminality here:
+ *   - "completed" / "failed" / "terminated" — true terminals. "terminated" is
+ *     an aborted preview, a real end state (Codex P2 on #941: it used to be
+ *     omitted, so an abort was misreported as a wait timeout).
+ *   - "apply_pending" / "apply_claimed" — the run finished and is parked
+ *     waiting for a client to apply its result. It never advances on its own,
+ *     so the previous ladder spun here until the 60s cap.
+ *   - "missing" — no live instance to observe; more polling cannot help.
+ *
+ * The raw Cloudflare spellings ("complete"/"errored"/"waiting") are gone: the
+ * server no longer puts them on the wire, and matching them here would have
+ * kept two vocabularies alive.
+ */
+export function isPreviewWaitTerminalStatus(s) {
+    return typeof s === "string" && SETTLED_RUN_STATUSES.has(s);
+}
+/**
+ * Which arm the `workflows preview --wait` render ladder takes (#2636).
+ *
+ * Extracted from the ladder so the branch decision is testable: the point of
+ * the `skipped` arm is that an elided preview — one whose declarative lock was
+ * held under `onContention: "ignore"` — reports that it did not run, instead
+ * of falling through to the timeout branch and exiting 124 as though it were
+ * still going.
+ */
+export function previewWaitOutcome(status) {
+    if (status === "completed")
+        return "completed";
+    if (status === "failed")
+        return "failed";
+    if (status === "terminated")
+        return "terminated";
+    if (status === "skipped")
+        return "skipped";
+    if (typeof status === "string" && APPLY_RUN_STATUSES.has(status))
+        return "apply";
+    if (status === "missing")
+        return "missing";
+    return "timeout";
+}
+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;
+}
+/**
+ * #1367 — annotate step-run rows with the inter-step gap: the wall-clock time
+ * between the previous step's `endedAt` and this step's `startedAt`. Sorts by
+ * `startedAt` when every row has a parseable one (tie-break `stepIndex`),
+ * otherwise by `stepIndex` for the whole list — the ordering mode must be
+ * chosen once for all rows, not per pair: a per-pair timestamp-vs-index
+ * fallback is not transitive when some rows lack a timestamp (A<B by index,
+ * B<C by index, C<A by time), and a non-transitive comparator leaves
+ * Array.prototype.sort free to return an arbitrary order, computing gaps
+ * against the wrong predecessor. The first step has no predecessor, so its
+ * `gapMs` is `null`. A gap is only meaningful when both adjacent timestamps
+ * parse and the gap is positive. When the immediate predecessor lacks a valid
+ * `endedAt`, the gap is left `null` rather than measured from an older,
+ * non-adjacent step — otherwise a later step could raise a false stall
+ * warning against a step it does not actually follow. Exported for
+ * testability.
+ */
+export function annotateStepGaps(steps) {
+    const rows = [...(steps || [])];
+    const allTimed = rows.every((r) => r?.startedAt && !Number.isNaN(new Date(r.startedAt).getTime()));
+    rows.sort((a, b) => {
+        if (allTimed) {
+            const sa = new Date(a.startedAt).getTime();
+            const sb = new Date(b.startedAt).getTime();
+            if (sa !== sb)
+                return sa - sb;
+        }
+        return (a?.stepIndex ?? 0) - (b?.stepIndex ?? 0);
+    });
+    let prevEnded = null;
+    for (const row of rows) {
+        const started = row?.startedAt ? new Date(row.startedAt).getTime() : NaN;
+        if (prevEnded != null && !Number.isNaN(started)) {
+            const gap = started - prevEnded;
+            row.gapMs = gap > 0 ? gap : 0;
+        }
+        else {
+            row.gapMs = null;
+        }
+        // Only genuinely adjacent steps yield a gap: if this step lacks a valid
+        // `endedAt`, clear the predecessor so the NEXT step's gap is left null
+        // instead of being measured from a non-adjacent earlier step.
+        const ended = row?.endedAt ? new Date(row.endedAt).getTime() : NaN;
+        prevEnded = Number.isNaN(ended) ? null : ended;
+    }
+    return rows;
+}
+/**
+ * #1367 — compute min / p50 / p95 / max over a set of latency samples (ms).
+ * Ignores non-finite values. Returns `null` when there are no valid samples.
+ * Percentiles use nearest-rank on the sorted samples. Exported for testability.
+ */
+export function summarizeLatencyDistribution(values) {
+    const nums = (values || []).filter((v) => typeof v === "number" && Number.isFinite(v));
+    if (nums.length === 0)
+        return null;
+    nums.sort((a, b) => a - b);
+    const pct = (p) => {
+        const rank = Math.ceil((p / 100) * nums.length);
+        return nums[Math.min(nums.length - 1, Math.max(0, rank - 1))];
+    };
+    return {
+        count: nums.length,
+        min: nums[0],
+        p50: pct(50),
+        p95: pct(95),
+        max: nums[nums.length - 1],
+    };
+}
+/**
+ * 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")
-        .description("Build multi-step workflows, publish revisions, and monitor runs")
+        .description("Inspect workflows, run and monitor them, and take one out of service")
         .addHelpText("after", `
 Examples:
   $ primitive workflows list
-  $ primitive workflows create --from-file process-doc.toml
-  $ primitive workflows publish 01HXY...
+  $ primitive config new workflow process-doc          # scaffold workflows/process-doc.toml
+  $ primitive sync push --only workflow/process-doc  # apply it
   $ primitive workflows runs list 01HXY...
+  $ primitive workflows disable 01HXY...               # take it out of service now
+`);
+    // Server-side configuration is authored in TOML and applied with `sync push`
+    // (issue #2645) — this group no longer carries config-setting flags.
+    workflows.addHelpText("after", `
+Configuration lives in workflows/<key>.toml:
+  $ primitive config fields workflow          # the file's keys, types and defaults
+  $ primitive config new workflow <key>       # scaffold one locally
+  $ primitive config set workflow/<key> <path>=<value>
+  $ primitive sync push --only workflow/<key>
+
+Which body runs is configuration too: name it with activeConfigName in
+workflows/<key>.toml (bodies live in workflows/<key>.configs/<name>.toml) and
+apply it with 'sync push'. The one exception is 'workflows publish', which
+promotes the legacy draft slot on a workflow with NO active config — see its
+--help.
 `);
     // List workflows
     workflows
@@ -53,78 +272,10 @@ Examples:
             process.exit(1);
         }
     });
-    // Create workflow
-    workflows
-        .command("create")
-        .description("Create a new workflow")
-        .argument("[app-id]", "App ID (uses current app if not specified)")
-        .option("--app <app-id>", "App ID")
-        .option("--key <key>", "Workflow key (unique identifier)")
-        .option("--name <name>", "Display name")
-        .option("--description <desc>", "Description")
-        .option("--from-file <path>", "Load workflow from TOML file")
-        .option("--json", "Output as JSON")
-        .action(async (appId, options) => {
-        const resolvedAppId = resolveAppId(appId, options);
-        const client = new ApiClient();
-        let payload;
-        if (options.fromFile) {
-            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,
-                };
-            }
-            catch (err) {
-                error(`Failed to read TOML file: ${err.message}`);
-                process.exit(1);
-            }
-        }
-        else {
-            if (!options.key || !options.name) {
-                error("Required: --key, --name (or use --from-file)");
-                process.exit(1);
-            }
-            payload = {
-                workflowKey: options.key,
-                name: options.name,
-                description: options.description,
-                steps: [],
-            };
-        }
-        try {
-            const result = await client.createWorkflow(resolvedAppId, payload);
-            if (options.json) {
-                json(result);
-                return;
-            }
-            success(`Workflow created: ${result.workflow?.name || options.name}`);
-            keyValue("Workflow ID", result.workflow?.workflowId);
-            keyValue("Key", result.workflow?.workflowKey);
-        }
-        catch (err) {
-            error(err.message);
-            process.exit(1);
-        }
-    });
-    // Get workflow
     workflows
         .command("get")
         .description("Get workflow details")
-        .argument("<workflow-id>", "Workflow ID")
+        .argument("<workflow-id>", "Workflow ID or key")
         .option("--app <app-id>", "App ID (uses current app if not specified)")
         .option("--json", "Output as JSON")
         .action(async (workflowId, options) => {
@@ -137,19 +288,36 @@ 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));
+            // #2645 criterion 9 — `status` is what the repo configured; this is
+            // whether an operator has pulled it out of service right now. Two
+            // different questions, so `get` answers both.
+            printResult("In Service", wf.operationallyDisabled === true
+                ? "no (operationally disabled — `workflows enable` to restore)"
+                : "yes");
+            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:");
@@ -190,147 +358,112 @@ Examples:
             process.exit(1);
         }
     });
-    // Update workflow
     workflows
-        .command("update")
-        .description("Update workflow metadata")
-        .argument("<workflow-id>", "Workflow ID")
-        .option("--app <app-id>", "App ID (uses current app if not specified)")
-        .option("--name <name>", "Display name")
-        .option("--description <desc>", "Description")
-        .option("--status <status>", "Status: draft, active, archived")
-        .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("--json", "Output as JSON")
-        .action(async (workflowId, options) => {
-        const resolvedAppId = resolveAppId(undefined, options);
-        const payload = {};
-        if (options.name)
-            payload.name = options.name;
-        if (options.description)
-            payload.description = options.description;
-        if (options.status)
-            payload.status = options.status;
-        if (options.perUserMaxRunning)
-            payload.perUserMaxRunning = parseInt(options.perUserMaxRunning);
-        if (options.perUserMaxQueued)
-            payload.perUserMaxQueued = parseInt(options.perUserMaxQueued);
-        if (options.dequeueOrder)
-            payload.dequeueOrder = options.dequeueOrder;
-        if (Object.keys(payload).length === 0) {
-            error("No update options specified.");
-            process.exit(1);
-        }
-        const client = new ApiClient();
+        .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 result = await client.updateWorkflow(resolvedAppId, workflowId, payload);
-            if (options.json) {
-                json(result);
-                return;
+            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(stringifyConfigToml(expanded));
+            }
+            else {
+                console.log(JSON.stringify(expanded, null, 2));
             }
-            success("Workflow updated.");
         }
         catch (err) {
-            error(err.message);
+            error(err?.message ?? String(err));
             process.exit(1);
         }
     });
-    // Delete workflow
+    // #2645 criterion 9 — the operational toggle.
+    //
+    // Configuration is authored in TOML and applied with `sync push`, which would
+    // otherwise mean an operator needs a repo checkout to stop a misbehaving
+    // workflow. It does not: taking something out of service is an OPERATION, and
+    // these two verbs are its only writers. They change no configuration field —
+    // `status` still says whatever the committed TOML says — so the repo keeps
+    // describing the server and `sync diff` reports the object as "operationally
+    // disabled; configuration unchanged" rather than as drift.
     workflows
-        .command("delete")
-        .description("Delete or archive a workflow")
-        .argument("<workflow-id>", "Workflow ID")
+        .command("disable")
+        .description("Take a workflow out of service now. Operational, not configuration: no TOML field changes, and 'sync push' cannot set or clear it.")
+        .argument("<workflow-id>", "Workflow ID or key")
         .option("--app <app-id>", "App ID (uses current app if not specified)")
-        .option("--hard", "Permanently delete instead of archive")
-        .option("-y, --yes", "Skip confirmation prompt")
+        .option("--json", "Output as JSON")
         .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.hard) {
-                await client.deleteWorkflow(resolvedAppId, workflowId);
-                success("Workflow deleted.");
-            }
-            else {
-                await client.updateWorkflow(resolvedAppId, workflowId, { status: "archived" });
-                success("Workflow archived.");
+            const result = await client.disableWorkflow(resolvedAppId, workflowId);
+            if (options.json) {
+                json(result);
+                return;
             }
+            success(`Workflow disabled: ${result.workflowKey || workflowId}`);
+            info("New runs are refused. Configuration is unchanged — `primitive workflows enable` puts it back.");
         }
         catch (err) {
             error(err.message);
             process.exit(1);
         }
     });
-    // Draft subcommand
-    const draft = workflows.command("draft").description("Manage workflow draft");
-    // Update draft
-    draft
-        .command("update")
-        .description("Update workflow draft steps")
-        .argument("<workflow-id>", "Workflow ID")
+    workflows
+        .command("enable")
+        .description("Put an operationally disabled workflow back in service.")
+        .argument("<workflow-id>", "Workflow ID or key")
         .option("--app <app-id>", "App ID (uses current app if not specified)")
-        .option("--from-file <path>", "Load steps from TOML file")
         .option("--json", "Output as JSON")
         .action(async (workflowId, options) => {
         const resolvedAppId = resolveAppId(undefined, options);
-        if (!options.fromFile) {
-            error("--from-file is required");
-            process.exit(1);
-        }
-        let payload;
-        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,
-            };
-        }
-        catch (err) {
-            error(`Failed to read TOML file: ${err.message}`);
-            process.exit(1);
-        }
         const client = new ApiClient();
         try {
-            const result = await client.updateWorkflowDraft(resolvedAppId, workflowId, payload);
+            const result = await client.enableWorkflow(resolvedAppId, workflowId);
             if (options.json) {
                 json(result);
                 return;
             }
-            success("Draft updated.");
-            keyValue("Steps", result.draft?.steps?.length || 0);
+            success(`Workflow enabled: ${result.workflowKey || workflowId}`);
+            // `status` is configuration, so enabling does not publish a draft.
+            if (result.status && result.status !== "active") {
+                warn(`Status is "${result.status}", so it still will not run. Status is configuration — set it in workflows/<key>.toml and 'sync push'.`);
+            }
         }
         catch (err) {
             error(err.message);
             process.exit(1);
         }
     });
-    // Publish workflow
+    // The one write verb that survives the TOML-only rule (#2645), and only for
+    // the workflows the rule cannot reach: a definition with NO active config —
+    // i.e. one created before the config model, since creation has minted a
+    // config ever since. On those, `sync push` writes the legacy DRAFT slot
+    // (`workflow-apply.ts`) while execution reads the active revision, so
+    // promoting the pushed body is a step nothing else performs. For every other
+    // workflow the server refuses this call and `activeConfigName` is the answer.
     workflows
         .command("publish")
-        .description("Publish the current draft as a new revision")
-        .argument("<workflow-id>", "Workflow ID")
+        .description("Promote the legacy draft slot to a new revision. Legacy only: works on a workflow with no active config, and the server refuses it otherwise.")
+        .argument("<workflow-id>", "Workflow ID or key")
         .option("--app <app-id>", "App ID (uses current app if not specified)")
         .option("--json", "Output as JSON")
+        .addHelpText("after", `
+The exception to TOML-only authoring, and a narrow one.
+
+This publishes the LEGACY draft slot, which only a workflow with no active
+config still has — workflows created before the configuration model. On those,
+'sync push' writes the draft and the running revision is unchanged until this
+promotes it, so removing this command would strand them.
+
+Every other workflow is authored in its file: the body lives in
+workflows/<key>.configs/<name>.toml, activeConfigName in workflows/<key>.toml
+names the one that runs, and 'sync push' applies both. The server rejects this
+command for such a workflow rather than bumping a pointer that changes nothing.
+`)
         .action(async (workflowId, options) => {
         const resolvedAppId = resolveAppId(undefined, options);
         const client = new ApiClient();
@@ -343,8 +476,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, author the config as a sidecar and name it in the workflow file:\n" +
+                    "  workflows/<key>.configs/<name>.toml   # the config body\n" +
+                    "  activeConfigName = \"<name>\"           # in workflows/<key>.toml\n" +
+                    "  primitive config set workflow/<key> workflow.status=active\n" +
+                    "  primitive sync push --only workflow/<key>");
+                process.exit(1);
+            }
             error(err.message);
             process.exit(1);
         }
@@ -353,14 +505,20 @@ Examples:
     workflows
         .command("preview")
         .description("Run a preview execution of the workflow")
-        .argument("<workflow-id>", "Workflow ID")
+        .argument("<workflow-id>", "Workflow ID or key")
         .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 +534,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 +550,77 @@ 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") {
+            // #2348: this render ladder used to re-derive terminality (and matched
+            // the raw "complete"/"errored" spellings the server no longer emits).
+            // It now branches on the same canonical values the poll loop stops on,
+            // via the shared sets in lib/run-status.ts.
+            const waitOutcome = previewWaitOutcome(status?.status);
+            if (waitOutcome === "completed") {
                 success("Preview completed.");
                 if (status.output) {
                     console.log("\nOutput:");
@@ -417,15 +634,45 @@ Examples:
                     });
                 }
             }
-            else if (status?.status === "failed") {
+            else if (waitOutcome === "failed") {
                 error("Preview failed.");
                 if (status.error) {
                     console.log("\nError:");
                     console.log(JSON.stringify(status.error, null, 2));
                 }
             }
+            else if (waitOutcome === "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 if (waitOutcome === "skipped") {
+                // #2636 — the preview's declarative lock was held and the definition
+                // declared `onContention: "ignore"`, so it never ran. That is an
+                // outcome, not a timeout: report it and exit 0.
+                warn(`Preview did not run — lock held${status?.skipReason ? ` (${status.skipReason})` : ""}.`);
+            }
+            else if (waitOutcome === "apply") {
+                // #2348: the run finished and is parked waiting for a client to claim
+                // and apply its result. It will not advance on its own, so the wait
+                // stopping here is a success, not a timeout.
+                warn(`Preview finished and is waiting to be applied (status: ${status.status}).`);
+                if (status.output) {
+                    console.log("\nOutput:");
+                    console.log(JSON.stringify(status.output, null, 2));
+                }
+            }
+            else if (waitOutcome === "missing") {
+                // #2348: no live instance to observe — reporting a timeout here would
+                // suggest the preview is still running, which it is not.
+                error("Preview instance not found (status: missing).");
+            }
             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) {
@@ -433,39 +680,513 @@ Examples:
             process.exit(1);
         }
     });
+    // #1367 — hidden queue-latency measurement tool. Fires a batch of runs of a
+    // (trivial, no-op) workflow, polls until each has an executionStartedAt, and
+    // reports the observed queueDelayMs / createCallDurationMs distribution. This
+    // is the post-deploy verification vehicle: local miniflare does not exhibit
+    // real Cloudflare scheduling delay, so run it against an agents/alpha scratch
+    // app. Creates are paced (default 10/s) to stay clear of CF's ~100/s shared
+    // instance-creation limit; a create failure (e.g. 429) is recorded, not fatal.
+    workflows
+        .command("queue-latency-test", { hidden: true })
+        .description("(hidden) Fire N no-op runs and report the queue-delay distribution (post-deploy tool)")
+        .argument("<workflow-id>", "Workflow ID or key of a trivial no-op workflow")
+        .option("--app <app-id>", "App ID (uses current app if not specified)")
+        .option("--count <n>", "Number of runs to fire", "50")
+        .option("--rate <r>", "Max creates per second (<=10 recommended)", "10")
+        .option("--input <json>", "Root input as JSON")
+        .option("--timeout <sec>", "Seconds to wait for all runs to start", "120")
+        .option("--verbose", "Print a per-run row")
+        .option("--json", "Output as JSON")
+        .action(async (workflowId, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        const client = new ApiClient();
+        const count = Math.max(1, parseInt(options.count, 10) || 50);
+        const rate = Math.max(1, parseInt(options.rate, 10) || 10);
+        const timeoutSec = Math.max(1, parseInt(options.timeout, 10) || 120);
+        const intervalMs = Math.ceil(1000 / rate);
+        const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+        let rootInput;
+        if (options.input) {
+            try {
+                rootInput = JSON.parse(options.input);
+            }
+            catch {
+                error("Invalid JSON in --input");
+                process.exit(1);
+            }
+        }
+        const fired = [];
+        if (!options.json) {
+            info(`Firing ${count} run(s) of ${workflowId} at up to ${rate}/s (interval ${intervalMs}ms)...`);
+        }
+        for (let i = 0; i < count; i++) {
+            try {
+                const res = await client.previewWorkflow(resolvedAppId, workflowId, {
+                    rootInput,
+                });
+                fired.push({
+                    index: i,
+                    instanceId: res?.instanceId,
+                    createFailed: false,
+                    started: false,
+                });
+            }
+            catch (err) {
+                // A create failure (e.g. HTTP 500 from CF's shared-class rate limit) is
+                // a recorded datapoint, not a reason to abort the whole batch.
+                fired.push({
+                    index: i,
+                    createFailed: true,
+                    createError: err?.message ? String(err.message) : String(err),
+                    started: false,
+                });
+            }
+            if (i < count - 1)
+                await sleep(intervalMs);
+        }
+        // Poll the run list until every non-failed run has executionStartedAt set
+        // (queueDelayMs present) or we hit the timeout.
+        const byInstance = new Map();
+        for (const f of fired) {
+            if (f.instanceId)
+                byInstance.set(f.instanceId, f);
+        }
+        const deadline = Date.now() + timeoutSec * 1000;
+        const pending = () => fired.filter((f) => !f.createFailed && !f.started).length;
+        // The admin run-list endpoint caps each page at 200, so a single large
+        // request cannot cover a batch of more than 200 runs — the earliest ones
+        // would never be matched and would be falsely reported as not started.
+        // Page through with the cursor (runs come back newest-first, so our batch
+        // is at the front) until every pending run is matched or we run out of
+        // pages. Bound the scan so we never walk the whole run history.
+        const PAGE_LIMIT = 200;
+        const scanBudget = count + PAGE_LIMIT;
+        while (pending() > 0 && Date.now() < deadline) {
+            await sleep(1000);
+            try {
+                let cursor;
+                let scanned = 0;
+                do {
+                    const { items, cursor: nextCursor } = await client.listWorkflowRuns(resolvedAppId, workflowId, { limit: PAGE_LIMIT, cursor: cursor ?? undefined });
+                    for (const run of items || []) {
+                        const f = run?.instanceId ? byInstance.get(run.instanceId) : undefined;
+                        if (f && !f.started && run.executionStartedAt) {
+                            f.started = true;
+                            f.queueDelayMs =
+                                typeof run.queueDelayMs === "number" ? run.queueDelayMs : null;
+                            f.createCallDurationMs =
+                                typeof run.createCallDurationMs === "number"
+                                    ? run.createCallDurationMs
+                                    : null;
+                        }
+                    }
+                    scanned += items?.length || 0;
+                    cursor = nextCursor;
+                } while (pending() > 0 && cursor && scanned < scanBudget);
+            }
+            catch {
+                // Transient list error — keep polling until the deadline.
+            }
+        }
+        const createFailures = fired.filter((f) => f.createFailed).length;
+        const startedRuns = fired.filter((f) => f.started);
+        const queueDelays = startedRuns.map((f) => f.queueDelayMs);
+        const createDurations = startedRuns.map((f) => f.createCallDurationMs);
+        const queueDist = summarizeLatencyDistribution(queueDelays);
+        const createDist = summarizeLatencyDistribution(createDurations);
+        const notStarted = fired.filter((f) => !f.createFailed && !f.started).length;
+        if (options.json) {
+            json({
+                workflowId,
+                requested: count,
+                created: count - createFailures,
+                createFailures,
+                started: startedRuns.length,
+                notStartedWithinTimeout: notStarted,
+                queueDelayMs: queueDist,
+                createCallDurationMs: createDist,
+                runs: options.verbose
+                    ? fired.map((f) => ({
+                        index: f.index,
+                        instanceId: f.instanceId ?? null,
+                        createFailed: f.createFailed,
+                        createError: f.createError ?? null,
+                        started: f.started,
+                        queueDelayMs: f.queueDelayMs ?? null,
+                        createCallDurationMs: f.createCallDurationMs ?? null,
+                    }))
+                    : undefined,
+            });
+            return;
+        }
+        divider();
+        keyValue("Requested", count);
+        keyValue("Created", count - createFailures);
+        keyValue("Create failures", createFailures);
+        keyValue("Started", startedRuns.length);
+        keyValue("Not started (timeout)", notStarted);
+        divider();
+        if (queueDist) {
+            info("Queue delay (executionStartedAt - requested):");
+            keyValue("  min", formatDuration(queueDist.min));
+            keyValue("  p50", formatDuration(queueDist.p50));
+            keyValue("  p95", formatDuration(queueDist.p95));
+            keyValue("  max", formatDuration(queueDist.max));
+        }
+        else {
+            warn("No runs started — no queue-delay samples collected.");
+        }
+        if (createDist) {
+            divider();
+            info("Create-call duration:");
+            keyValue("  min", formatDuration(createDist.min));
+            keyValue("  p50", formatDuration(createDist.p50));
+            keyValue("  p95", formatDuration(createDist.p95));
+            keyValue("  max", formatDuration(createDist.max));
+        }
+        if (options.verbose) {
+            divider();
+            console.log(formatTable(fired.map((f) => ({
+                run: f.index,
+                instanceId: f.instanceId ?? "-",
+                status: f.createFailed ? "create-failed" : f.started ? "started" : "pending",
+                queueDelayMs: f.queueDelayMs,
+                createCallDurationMs: f.createCallDurationMs,
+            })), [
+                { header: "RUN", key: "run" },
+                { header: "INSTANCE", key: "instanceId", format: formatId },
+                { header: "STATE", key: "status" },
+                { header: "DELAY", key: "queueDelayMs", format: formatDuration },
+                { header: "CREATE", key: "createCallDurationMs", format: formatDuration },
+            ]));
+        }
+    });
     // Runs subcommand
     const runs = workflows.command("runs").description("Manage workflow runs");
     // List runs
+    const runsTableColumns = [
+        { header: "RUN ID", key: "runId", format: formatId },
+        { header: "STATUS", key: "status", format: formatStatus },
+        { header: "STARTED", key: "startedAt", format: formatDate },
+        // #1367 — queue delay (requested → execution start).
+        { header: "DELAY", key: "queueDelayMs", format: formatDuration },
+        { header: "ENDED", key: "endedAt", format: formatDate },
+        { header: "PREVIEW", key: "isPreview", format: (v) => (v ? "yes" : "") },
+    ];
     runs
         .command("list")
         .description("List workflow runs")
-        .argument("<workflow-id>", "Workflow ID")
+        // #1967 — the workflow id is optional when `--user-id` is given: that
+        // form lists one user's runs across every workflow.
+        .argument("[workflow-id]", "Workflow ID or key (optional with --user-id)")
         .option("--app <app-id>", "App ID (uses current app if not specified)")
-        .option("--status <status>", "Filter by status: pending, running, completed, failed")
+        // #2348: the canonical run-status vocabulary. The old text advertised
+        // "pending", which no server path ever writes, and omitted "terminated".
+        // An unrecognised value is now a 400 from the server, not an empty page.
+        .option("--status <status>", `Filter by status: ${RUN_STATUS_LIST}`)
+        .option("--user-id <user-id>", "List runs started by this user, across every workflow")
         .option("--limit <n>", "Number of runs to show", "20")
+        .option("--cursor <cursor>", "Pagination cursor from a previous page")
+        // #1969 — shared tailing flags. `--watch` re-renders the current list each
+        // interval (snapshot); `--follow` appends new/changed runs (tail). Mutually
+        // exclusive; `--interval` floor is 1s (default 2s).
+        .option("--watch", "Re-render the current run list every interval (snapshot)")
+        .option("--follow", "Append runs as they start or change (tail)")
+        .option("--interval <seconds>", "Poll interval in seconds (min 1, default 2)")
         .option("--json", "Output as JSON")
         .action(async (workflowId, options) => {
         const resolvedAppId = resolveAppId(undefined, options);
         const client = new ApiClient();
+        const limit = parseInt(options.limit);
+        if (options.watch && options.follow) {
+            error("--watch and --follow are mutually exclusive; pass only one.");
+            process.exit(1);
+        }
+        // #1967 — one of the two selectors is required; `list` never enumerates
+        // every run in the app.
+        if (!workflowId && !options.userId) {
+            error("Provide a workflow ID, or --user-id to list one user's runs across every workflow.");
+            process.exit(1);
+        }
+        // The user view reads the runs-by-user index, which has no resume
+        // contract — `--follow`'s checkpoint is keyed on the by-workflow index.
+        if (options.userId && options.follow) {
+            error("--follow is not supported with --user-id (it reads a different index). Use --watch instead.");
+            process.exit(1);
+        }
+        // Both selectors resolve through the same page shape, so the rest of the
+        // command is identical either way.
+        const fetchPage = (params) => options.userId
+            ? client.listUserWorkflowRuns(resolvedAppId, options.userId, {
+                ...params,
+                // With both a workflow id and --user-id, narrow to that workflow.
+                workflowId: workflowId || undefined,
+            })
+            : client.listWorkflowRuns(resolvedAppId, workflowId, params);
+        // One-shot list (no tailing).
+        if (!options.watch && !options.follow) {
+            try {
+                const page = await fetchPage({
+                    status: options.status,
+                    limit,
+                    cursor: options.cursor,
+                });
+                const { items } = page;
+                if (options.json) {
+                    // #1316 envelope with the shared inspection item shape — never a
+                    // bare array — preserving nextCursor/hasMore + the deprecated
+                    // `cursor` dual-emit alias (behaviors 6, 7).
+                    json(buildWorkflowRunEnvelope(items, page));
+                    return;
+                }
+                // The cursor hint prints whether or not this page had rows: a
+                // filtered read can come back empty with more of the index still to
+                // walk, and a bare "No runs found." would read as "this user has no
+                // matching runs" (#1967 review).
+                const printCursorHint = () => {
+                    if (!page.nextCursor)
+                        return;
+                    console.log();
+                    dim(`More runs. Use --cursor ${page.nextCursor} for the next page.`);
+                };
+                if (!items || items.length === 0) {
+                    // #2237 — the honest empty state: a bounded filtered read can stop
+                    // before it reaches a match, so the message says how far it got and
+                    // how to continue instead of asserting there are none. `runs list`
+                    // deliberately does NOT auto-resume like `runs failures` — it is a
+                    // pager, and its `--limit` is a page size.
+                    info(describeEmptyRunPage(page, !!options.cursor));
+                    return;
+                }
+                console.log(formatTable(items, runsTableColumns));
+                printCursorHint();
+            }
+            catch (err) {
+                error(err.message);
+                process.exit(1);
+            }
+            return;
+        }
+        // Tailing (`--watch` / `--follow`). SIGINT → AbortController installed
+        // here at the command level; the handler is removed in `finally` so it
+        // never leaks past this command (unlike the persistent process.on).
+        let intervalSeconds;
         try {
-            const { items } = await client.listWorkflowRuns(resolvedAppId, workflowId, {
-                status: options.status,
-                limit: parseInt(options.limit),
-            });
+            intervalSeconds = parseIntervalSeconds(options.interval);
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+        const intervalMs = intervalSeconds * 1000;
+        const controller = new AbortController();
+        const onSigint = () => controller.abort();
+        process.on("SIGINT", onSigint);
+        try {
+            if (options.follow) {
+                const source = {
+                    fetchAfter: async (resumeAfter) => {
+                        if (resumeAfter === undefined) {
+                            // Bootstrap: newest position, descending, one row. followLoop
+                            // discards the items and keeps only the baseline checkpoint.
+                            const page = await client.listWorkflowRuns(resolvedAppId, workflowId, {
+                                follow: true,
+                                forward: false,
+                                limit: 1,
+                                status: options.status,
+                            });
+                            return { items: page.items, hasMore: false, resumeAfter: page.resumeAfter };
+                        }
+                        const page = await client.listWorkflowRuns(resolvedAppId, workflowId, {
+                            follow: true,
+                            forward: true,
+                            after: resumeAfter,
+                            limit,
+                            status: options.status,
+                        });
+                        return {
+                            items: page.items,
+                            hasMore: !!page.hasMore,
+                            resumeAfter: page.resumeAfter,
+                        };
+                    },
+                };
+                if (!options.json) {
+                    info("Following runs (Ctrl-C to stop)…");
+                }
+                await followLoop(source, {
+                    intervalMs,
+                    signal: controller.signal,
+                    render: (items) => {
+                        if (options.json) {
+                            // One JSON object per line (a tail has no closing bracket to
+                            // wait for), each in the shared inspection item shape — the
+                            // same items the one-shot envelope carries (behavior 7).
+                            for (const run of items)
+                                jsonLine(toWorkflowRunInspectionRow(run));
+                            return;
+                        }
+                        for (const run of items) {
+                            console.log(`${formatDate(run.startedAt)}  ${formatStatus(run.status)}  ${formatId(run.runId)}`);
+                        }
+                    },
+                });
+            }
+            else {
+                // --watch: periodic snapshot redraw. The most recent page's
+                // pagination fields are kept so the `--json` redraw emits the same
+                // envelope the one-shot path does, not a bare array (behavior 7).
+                let lastPage = {};
+                await watchLoop(async () => {
+                    const page = await fetchPage({
+                        status: options.status,
+                        limit,
+                        cursor: options.cursor,
+                    });
+                    lastPage = page;
+                    return page.items;
+                }, {
+                    intervalMs,
+                    signal: controller.signal,
+                    render: (items) => {
+                        if (options.json) {
+                            json(buildWorkflowRunEnvelope(items, lastPage));
+                            return;
+                        }
+                        // Renderer owns the redraw: clear the screen, then print.
+                        process.stdout.write("\x1b[2J\x1b[H");
+                        if (!items || items.length === 0) {
+                            console.log("No runs found.");
+                            return;
+                        }
+                        console.log(formatTable(items, runsTableColumns));
+                    },
+                });
+            }
+        }
+        finally {
+            process.removeListener("SIGINT", onSigint);
+        }
+    });
+    // Run status
+    runs
+        .command("status")
+        .description("Get status of a workflow run")
+        .argument("<workflow-id>", "Workflow ID or key")
+        .argument("<run-id>", "Run ID")
+        .option("--app <app-id>", "App ID (uses current app if not specified)")
+        .option("--json", "Output as JSON")
+        .action(async (workflowId, runId, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        const client = new ApiClient();
+        try {
+            const result = await client.getWorkflowRunStatus(resolvedAppId, workflowId, runId);
             if (options.json) {
-                json(items);
+                json(result);
+                return;
+            }
+            const run = result.run;
+            keyValue("Run ID", run.runId);
+            keyValue("Status", formatStatus(run.status));
+            // #2636 — the machine-readable outcome next to the status: why a
+            // failed run failed, or why an elided run never ran.
+            if (run.errorCode)
+                keyValue("Error code", run.errorCode);
+            if (run.skipReason)
+                keyValue("Skip reason", run.skipReason);
+            // #1367 — `startedAt` is the request time; `executionStartedAt` is when
+            // Cloudflare actually started running the instance. Queue delay is the
+            // gap. A still-queued run shows "-" for execution start / queue delay.
+            keyValue("Requested", formatDate(run.startedAt));
+            keyValue("Execution started", formatDate(run.executionStartedAt));
+            keyValue("Queue delay", formatDuration(run.queueDelayMs));
+            keyValue("Create call", formatDuration(run.createCallDurationMs));
+            keyValue("Ended", formatDate(run.endedAt));
+            keyValue("Preview", run.isPreview ? "yes" : "no");
+            if (result.instanceStatus) {
+                const status = result.instanceStatus;
+                if (status.output) {
+                    divider();
+                    info("Output:");
+                    console.log(JSON.stringify(status.output, null, 2));
+                }
+                if (status.stepResults && status.stepResults.length > 0) {
+                    divider();
+                    info("Step Results:");
+                    for (const line of renderRunStatusStepResults(status.stepResults)) {
+                        console.log(line);
+                    }
+                }
+                if (status.error) {
+                    divider();
+                    error("Error:");
+                    console.log(JSON.stringify(status.error, null, 2));
+                }
+            }
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    // Steps for a run
+    runs
+        .command("steps")
+        .description("Show step-level details for a workflow run")
+        .argument("<workflow-id>", "Workflow ID or key")
+        .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) {
+                // Steps are unpaginated (one run's full trace) — the shared
+                // inspection item shape wrapped in `{items}`, no cursor (behavior 6).
+                json(buildWorkflowStepEnvelope(items));
                 return;
             }
             if (!items || items.length === 0) {
-                info("No runs found.");
+                info("No step runs found.");
                 return;
             }
-            console.log(formatTable(items, [
-                { header: "RUN ID", key: "runId", format: formatId },
-                { header: "STATUS", key: "status", format: formatStatus },
-                { header: "STARTED", key: "startedAt", format: formatDate },
-                { header: "ENDED", key: "endedAt", format: formatDate },
-                { header: "PREVIEW", key: "isPreview", format: (v) => v ? "yes" : "" },
+            // #1367 — inter-step gap: idle time between one step ending and the
+            // next starting. Only surfaced above a 1s threshold so normal
+            // back-to-back steps stay quiet; a large gap flags a mid-run stall.
+            const STEP_GAP_THRESHOLD_MS = 1000;
+            const rows = annotateStepGaps(items);
+            console.log(formatTable(rows, [
+                { 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: "GAP",
+                    key: "gapMs",
+                    format: (v) => typeof v === "number" && v >= STEP_GAP_THRESHOLD_MS
+                        ? chalk.yellow(formatDuration(v))
+                        : chalk.dim("-"),
+                },
+                { 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) {
@@ -473,102 +1194,363 @@ Examples:
             process.exit(1);
         }
     });
-    // Run status
+    // Step detail
     runs
-        .command("status")
-        .description("Get status of a workflow run")
-        .argument("<workflow-id>", "Workflow ID")
+        .command("step-detail")
+        .description("Show full details for a single step")
+        .argument("<workflow-id>", "Workflow ID or key")
         .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 or key")
+        .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 result = await client.getWorkflowRunStatus(resolvedAppId, workflowId, runId);
+            const [runResult, stepsResult] = await Promise.all([
+                client.getWorkflowRunStatus(resolvedAppId, workflowId, runId),
+                client.getWorkflowStepRuns(resolvedAppId, workflowId, runId),
+            ]);
+            // #2074 — one selection rule shared with the STEP column of
+            // `runs failures`: prefer the run's own denormalized attribution, and
+            // fall back to the lowest-`stepIndex` failed row (never "whatever the
+            // query returned first") so the two views can't disagree.
+            const failedStep = selectFailedStepRow(stepsResult.items, runResult.run?.failedStepId);
+            const errorInfo = {
+                runId,
+                status: runResult.run?.status,
+                // #2636 — the platform's classification of the failure, when it owns
+                // one (a lost declarative-lock race, an exhausted lock wait).
+                errorCode: runResult.run?.errorCode ?? null,
+                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.errorCode) {
+                keyValue("Code", errorInfo.errorCode);
+            }
+            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 or key")
+        .option("--app <app-id>", "App ID")
+        // #2237 — `--limit` is the number of FAILURES to collect, as the help text
+        // always claimed. It used to be passed straight through as the server's
+        // bounded page limit, so a workflow with a long success streak answered
+        // "No failures found." while failures sat just past the scan budget.
+        .option("--limit <n>", "Number of failures to collect", "10")
+        .option("--max-scan <n>", `Stop after examining this many runs, to the nearest request (each examines up to ${SERVER_SCAN_ROWS_PER_REQUEST}; 0 = no cap; a sweep issues at most ${FAILURE_SWEEP_MAX_REQUESTS} requests either way)`, String(DEFAULT_FAILURE_SWEEP_MAX_SCAN))
+        // `--cursor` seeds the sweep's starting position; the sweep then resumes
+        // itself, so it is only needed to continue an earlier capped search.
+        .option("--cursor <cursor>", "Resume the search from a previous cursor")
+        .option("--json", "Output as JSON")
+        .action(async (workflowId, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        const client = new ApiClient();
+        const limit = parseInt(options.limit, 10);
+        const maxScan = parseInt(options.maxScan, 10);
+        if (!Number.isFinite(limit) || limit < 1) {
+            error("--limit must be a positive integer.");
+            process.exit(1);
+        }
+        if (!Number.isFinite(maxScan) || maxScan < 0) {
+            error("--max-scan must be a non-negative integer (0 = no cap).");
+            process.exit(1);
+        }
+        // Ctrl-C during a multi-second sweep prints what was collected plus the
+        // resume cursor rather than dropping the work on the floor. The handler
+        // is removed in `finally` so it never leaks past this command.
+        //
+        // Registering a listener replaces Node's terminate-on-SIGINT default, and
+        // `shouldStop` is only read between requests — so a first Ctrl-C during a
+        // slow in-flight request would otherwise appear to do nothing and leave
+        // the command unkillable. A second one exits immediately (#2237 review).
+        let interrupted = false;
+        let sigints = 0;
+        const onSigint = () => {
+            interrupted = true;
+            if (++sigints > 1)
+                process.exit(130);
+        };
+        process.on("SIGINT", onSigint);
+        // Progress on stderr, TTY only, never in `--json` mode: a silent
+        // multi-second command invites the Ctrl-C it is trying to survive.
+        const showProgress = !options.json && !!process.stderr.isTTY;
+        try {
+            const sweep = await collectWorkflowFailures(({ cursor, limit: pageLimit }) => client.listWorkflowRuns(resolvedAppId, workflowId, {
+                status: "failed",
+                limit: pageLimit,
+                cursor,
+            }), {
+                limit,
+                maxScan,
+                startCursor: options.cursor,
+                shouldStop: () => interrupted,
+                onProgress: showProgress
+                    ? (scanned, collected) => progress(`Searching… ${scanned} runs examined, ${collected} failure${collected === 1 ? "" : "s"} found`)
+                    : undefined,
+            });
+            if (showProgress && sweep.requests >= 1) {
+                // Clear the progress line so it does not sit above the table. One
+                // request is the common case — `onProgress` fires after EVERY request
+                // including the first, so guarding on `> 1` left the line on screen
+                // with the cursor parked at its end (#2237 review).
+                process.stderr.write("\r\x1b[K");
+            }
+            // A SIGINT that arrived after the sweep returned (while the table is
+            // rendering) did not truncate anything, so only a sweep that actually
+            // stopped on the interrupt reports 130. `exitCode` rather than
+            // `process.exit()` so a piped stdout is not truncated mid-write.
+            const exitInterrupted = sweep.stoppedBecause === "interrupted";
+            const items = sweep.items;
             if (options.json) {
-                json(result);
+                // #2074 — the shared inspection item shape inside the endpoint's own
+                // #1316 envelope, never a bare array. #2237 — `items` is the
+                // concatenation across every resumed page, `scanned` their sum, and
+                // `nextCursor` the last one observed.
+                json(buildWorkflowRunEnvelope(items, {
+                    nextCursor: sweep.nextCursor,
+                    hasMore: !!sweep.nextCursor,
+                    ...(sweep.scannedKnown ? { scanned: sweep.scanned } : {}),
+                }));
+                if (exitInterrupted)
+                    process.exitCode = 130;
                 return;
             }
-            const run = result.run;
-            keyValue("Run ID", run.runId);
-            keyValue("Status", formatStatus(run.status));
-            keyValue("Started", formatDate(run.startedAt));
-            keyValue("Ended", formatDate(run.endedAt));
-            keyValue("Preview", run.isPreview ? "yes" : "no");
-            if (result.instanceStatus) {
-                const status = result.instanceStatus;
-                if (status.output) {
-                    divider();
-                    info("Output:");
-                    console.log(JSON.stringify(status.output, null, 2));
-                }
-                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)" : ""}`);
-                    });
-                }
-                if (status.error) {
-                    divider();
-                    error("Error:");
-                    console.log(JSON.stringify(status.error, null, 2));
-                }
+            if (items.length > 0) {
+                console.log(formatTable(items, [
+                    { header: "RUN ID", key: "runId", format: formatId },
+                    // STEP sits before ERROR so the truncated message stays the last
+                    // wide column and the step id is never the thing that gets cut.
+                    // `-` is a routine outcome, not a bug: launch-time failures
+                    // (create/schema/R2 aborts, reclaimed runs) legitimately have no
+                    // failed step, and runs that predate #2074 carry no attribution.
+                    { header: "STEP", key: "failedStepId", format: formatFailureStepCell },
+                    // #2636 — the platform's classification, next to the message an
+                    // operator would otherwise have had to pattern-match.
+                    { header: "CODE", key: "errorCode", format: formatFailureCodeCell },
+                    { header: "ERROR", key: "errorMessage", format: formatFailureErrorCell },
+                    { header: "STARTED", key: "startedAt", format: formatDate },
+                    { header: "ENDED", key: "endedAt", format: formatDate },
+                ]));
             }
+            // #2237 — replaces the unconditional "No failures found.": every form
+            // either states the search was complete or says how far it got and how
+            // to continue. A triage command must never assert an absence it did
+            // not establish.
+            const summary = describeFailureSweep(sweep, limit);
+            if (summary) {
+                if (items.length > 0)
+                    console.log();
+                info(summary);
+            }
+            if (exitInterrupted)
+                process.exitCode = 130;
         }
         catch (err) {
             error(err.message);
             process.exit(1);
         }
+        finally {
+            process.removeListener("SIGINT", onSigint);
+        }
     });
-    // ============================================
-    // CONFIGS SUBCOMMAND
-    // ============================================
-    const configs = workflows
-        .command("configs")
-        .description("Manage workflow configurations")
-        .addHelpText("after", `
-Examples:
-  $ primitive workflows configs list <workflow-id>
-  $ primitive workflows configs get <workflow-id> <config-id>
-  $ primitive workflows configs create <workflow-id> --name "v2" --from-file workflow.toml
-  $ primitive workflows configs activate <workflow-id> <config-id>
-  $ primitive workflows configs duplicate <workflow-id> <config-id> --name "v2-copy"
-`);
-    // List configs
-    configs
+    // ── 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 configurations for a workflow")
-        .argument("<workflow-id>", "Workflow ID")
+        .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 (workflowId, options) => {
+        .action(async (options) => {
         const resolvedAppId = resolveAppId(undefined, options);
         const client = new ApiClient();
         try {
-            const { items } = await client.listWorkflowConfigs(resolvedAppId, workflowId);
+            const { items } = await client.listIterations(resolvedAppId);
             if (options.json) {
                 json(items);
                 return;
             }
             if (!items || items.length === 0) {
-                info("No configurations found.");
+                info("No iterations found.");
                 return;
             }
-            // Get workflow to find active config
-            const { workflow } = await client.getWorkflow(resolvedAppId, workflowId);
-            const activeConfigId = workflow?.activeConfigId;
             console.log(formatTable(items, [
-                { header: "ID", key: "configId", format: formatId },
-                { header: "NAME", key: "configName" },
+                { header: "ITERATION", key: "iterationName" },
                 { header: "STATUS", key: "status", format: formatStatus },
-                {
-                    header: "ACTIVE",
-                    key: "configId",
-                    format: (v) => v === activeConfigId ? "★" : "",
-                },
-                { header: "MODIFIED", key: "modifiedAt", format: formatDate },
+                { header: "ACQUIRED", key: "lastAcquireMode", format: (v) => v || "" },
+                { header: "PROCESSED", key: "totalProcessed" },
+                { header: "FAILED", key: "failedCount" },
+                { header: "LAST RUN", key: "lastRunAt", format: formatDate },
             ]));
         }
         catch (err) {
@@ -576,35 +1558,44 @@ Examples:
             process.exit(1);
         }
     });
-    // Get config
-    configs
+    iterations
         .command("get")
-        .description("Get configuration details")
-        .argument("<workflow-id>", "Workflow ID")
-        .argument("<config-id>", "Configuration ID")
+        .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 (workflowId, configId, options) => {
+        .action(async (name, options) => {
         const resolvedAppId = resolveAppId(undefined, options);
         const client = new ApiClient();
         try {
-            const config = await client.getWorkflowConfig(resolvedAppId, workflowId, configId);
+            const it = await client.getIteration(resolvedAppId, name);
             if (options.json) {
-                json(config);
+                json(it);
                 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));
-            if (config.steps && config.steps.length > 0) {
-                divider();
-                info(`Steps (${config.steps.length}):`);
-                config.steps.forEach((step, idx) => {
-                    console.log(`  ${idx + 1}. ${step.id} (${step.kind})`);
-                });
+            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) {
@@ -612,184 +1603,189 @@ Examples:
             process.exit(1);
         }
     });
-    // Create config
-    configs
-        .command("create")
-        .description("Create a new configuration")
-        .argument("<workflow-id>", "Workflow ID")
+    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("--name <name>", "Configuration name (required)")
-        .option("--description <desc>", "Description")
-        .option("--from-file <path>", "Load steps from TOML file")
         .option("--json", "Output as JSON")
-        .action(async (workflowId, options) => {
+        .action(async (name, options) => {
         const resolvedAppId = resolveAppId(undefined, options);
-        if (!options.name) {
-            error("--name is required");
-            process.exit(1);
-        }
-        let steps = [];
-        if (options.fromFile) {
-            try {
-                const content = readFileSync(options.fromFile, "utf-8");
-                const tomlData = TOML.parse(content);
-                steps = tomlData.steps || [];
-            }
-            catch (err) {
-                error(`Failed to read TOML file: ${err.message}`);
-                process.exit(1);
-            }
-        }
         const client = new ApiClient();
         try {
-            const config = await client.createWorkflowConfig(resolvedAppId, workflowId, {
-                configName: options.name,
-                description: options.description,
-                steps,
-            });
+            const res = await client.resetIteration(resolvedAppId, name);
             if (options.json) {
-                json(config);
+                json(res);
                 return;
             }
-            success(`Configuration created: ${config.configName}`);
-            keyValue("Config ID", config.configId);
+            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);
         }
     });
-    // Update config
-    configs
-        .command("update")
-        .description("Update a configuration")
-        .argument("<workflow-id>", "Workflow ID")
-        .argument("<config-id>", "Configuration ID")
-        .option("--app <app-id>", "App ID (uses current app if not specified)")
-        .option("--name <name>", "Configuration name")
-        .option("--description <desc>", "Description")
-        .option("--from-file <path>", "Update steps from TOML file")
+    // 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 (workflowId, configId, options) => {
+        .action(async (options) => {
         const resolvedAppId = resolveAppId(undefined, options);
-        const payload = {};
-        if (options.name)
-            payload.configName = options.name;
-        if (options.description !== undefined)
-            payload.description = options.description;
-        if (options.fromFile) {
-            try {
-                const content = readFileSync(options.fromFile, "utf-8");
-                const tomlData = TOML.parse(content);
-                payload.steps = tomlData.steps || [];
-            }
-            catch (err) {
-                error(`Failed to read TOML file: ${err.message}`);
-                process.exit(1);
-            }
-        }
-        if (Object.keys(payload).length === 0) {
-            error("No update options specified. Use --name, --description, or --from-file.");
-            process.exit(1);
-        }
         const client = new ApiClient();
         try {
-            const config = await client.updateWorkflowConfig(resolvedAppId, workflowId, configId, payload);
+            const result = await client.getWorkflowAnalytics(resolvedAppId, {
+                windowDays: parseInt(options.days),
+            });
             if (options.json) {
-                json(config);
+                json(result);
                 return;
             }
-            success("Configuration updated.");
-            keyValue("Config ID", config.configId);
-            keyValue("Name", config.configName);
+            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);
         }
     });
-    // Activate config
-    configs
-        .command("activate")
-        .description("Set a configuration as the active (default) configuration")
-        .argument("<workflow-id>", "Workflow ID")
-        .argument("<config-id>", "Configuration ID")
-        .option("--app <app-id>", "App ID (uses current app if not specified)")
+    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 (workflowId, configId, options) => {
+        .action(async (options) => {
         const resolvedAppId = resolveAppId(undefined, options);
         const client = new ApiClient();
         try {
-            const result = await client.activateWorkflowConfig(resolvedAppId, workflowId, configId);
+            const result = await client.getTopWorkflows(resolvedAppId, {
+                windowDays: parseInt(options.days),
+                limit: parseInt(options.limit),
+            });
             if (options.json) {
                 json(result);
                 return;
             }
-            success("Configuration activated.");
-            keyValue("Active Config ID", result.activeConfigId || configId);
+            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);
         }
     });
-    // Duplicate config
+    // ============================================
+    // CONFIGS SUBCOMMAND
+    // ============================================
+    const configs = workflows
+        .command("configs")
+        .description("Manage workflow configurations")
+        .addHelpText("after", `
+Examples:
+  $ primitive workflows configs list <workflow-id>
+  $ primitive workflows configs get <workflow-id> <config-id>
+
+Config bodies are authored as files, not verbs: write
+workflows/<key>.configs/<name>.toml and name the live one with
+activeConfigName in workflows/<key>.toml, then run 'primitive sync push'.
+`);
+    // List configs
     configs
-        .command("duplicate")
-        .description("Duplicate a configuration")
-        .argument("<workflow-id>", "Workflow ID")
-        .argument("<config-id>", "Configuration ID to duplicate")
+        .command("list")
+        .description("List configurations for a workflow")
+        .argument("<workflow-id>", "Workflow ID or key")
         .option("--app <app-id>", "App ID (uses current app if not specified)")
-        .option("--name <name>", "Name for the new configuration")
         .option("--json", "Output as JSON")
-        .action(async (workflowId, configId, options) => {
+        .action(async (workflowId, options) => {
         const resolvedAppId = resolveAppId(undefined, options);
         const client = new ApiClient();
         try {
-            const config = await client.duplicateWorkflowConfig(resolvedAppId, workflowId, configId, {
-                configName: options.name,
-            });
+            const { items } = await client.listWorkflowConfigs(resolvedAppId, workflowId);
             if (options.json) {
-                json(config);
+                json(items);
+                return;
+            }
+            if (!items || items.length === 0) {
+                info("No configurations found.");
                 return;
             }
-            success(`Configuration duplicated: ${config.configName}`);
-            keyValue("New Config ID", config.configId);
+            // Get workflow to find active config
+            const { workflow } = await client.getWorkflow(resolvedAppId, workflowId);
+            const activeConfigId = workflow?.activeConfigId;
+            console.log(formatTable(items, [
+                { header: "ID", key: "configId", format: formatId },
+                { header: "NAME", key: "configName" },
+                { header: "STATUS", key: "status", format: formatStatus },
+                {
+                    header: "ACTIVE",
+                    key: "configId",
+                    format: (v) => v === activeConfigId ? "★" : "",
+                },
+                { header: "MODIFIED", key: "modifiedAt", format: formatDate },
+            ]));
         }
         catch (err) {
             error(err.message);
             process.exit(1);
         }
     });
-    // Archive config
+    // Get config
     configs
-        .command("archive")
-        .description("Archive a configuration")
-        .argument("<workflow-id>", "Workflow ID")
+        .command("get")
+        .description("Get configuration details")
+        .argument("<workflow-id>", "Workflow ID or key")
         .argument("<config-id>", "Configuration ID")
         .option("--app <app-id>", "App ID (uses current app if not specified)")
-        .option("-y, --yes", "Skip confirmation prompt")
+        .option("--json", "Output as JSON")
         .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,
-                },
-            ]);
-            if (!confirm) {
-                info("Cancelled.");
-                return;
-            }
-        }
         const client = new ApiClient();
         try {
-            await client.archiveWorkflowConfig(resolvedAppId, workflowId, configId);
-            success("Configuration archived.");
+            const config = await client.getWorkflowConfig(resolvedAppId, workflowId, configId);
+            if (options.json) {
+                json(config);
+                return;
+            }
+            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}):`);
+                config.steps.forEach((step, idx) => {
+                    console.log(`  ${idx + 1}. ${step.id} (${step.kind})`);
+                });
+            }
         }
         catch (err) {
             error(err.message);
@@ -810,7 +1806,6 @@ Examples:
   $ primitive workflows tests run-all <workflow-id>
   $ primitive workflows tests run-all <workflow-id> --test-cases 01ABC,01DEF,01GHI
 `);
-    // List test cases
     tests
         .command("list")
         .description("List test cases for a workflow")
@@ -925,13 +1920,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 +1936,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 +1955,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 +2059,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;
@@ -1334,12 +2336,21 @@ Examples:
             let result = await fetchStatus();
             if (options.wait && result.status === "running") {
                 info("Waiting for batch completion...");
-                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}  `);
-                }
-                console.log();
+                // #1969 — shared poll primitive (delay-then-probe every 2s, honoring
+                // an AbortSignal). `onError: "throw"` preserves the prior loop's
+                // fail-fast behavior: a throwing fetchStatus (expired token, deleted
+                // batch → 401/404) propagates to the command-level catch below and
+                // exits non-zero, rather than spinning forever with a frozen progress
+                // line. (The follow/watch tail loops legitimately keep "continue".)
+                const controller = new AbortController();
+                result = await pollUntil(fetchStatus, (r) => r.status !== "running", {
+                    intervalMs: 2000,
+                    signal: controller.signal,
+                    onError: "throw",
+                    // Progress goes to stderr so it can't corrupt JSON on stdout under --json.
+                    onValue: (r) => progress(`  Completed: ${r.completed}/${r.results?.length || 0}  `),
+                });
+                progressEnd();
             }
             if (options.json) {
                 json(result);
@@ -1383,15 +2394,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 +2565,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;
@@ -1579,6 +2588,130 @@ Examples:
             process.exit(1);
         }
     });
+    // ============================================
+    // Codegen command (issue #1442)
+    // ============================================
+    workflows
+        .command("codegen")
+        .description("Generate typed client signatures from the local workflows/*.toml schemas. TypeScript (default): one <key>.generated.ts per workflow (<Key>Input/<Key>Output types + a <key>(client) invoker factory). Swift (--lang swift): one <key>.generated.swift per workflow (<Key>Input/<Key>Output Codable types).\n\nFormatting: the emitted TypeScript is already formatted the way Prettier's DEFAULT config formats it, so a `codegen` -> `prettier --write` -> `codegen --check` pipeline stays green. If your project uses a NON-default Prettier config (a different printWidth, trailingComma, or quote style), Prettier will reformat the generated files and `--check` will then fail: add the generated directory to `.prettierignore` and commit the raw emission instead.")
+        .argument("[workflow-key]", "Generate for a single workflow (defaults to every workflows/*.toml found)")
+        .option("--app <app-id>", "App ID")
+        .option("--sync-dir <path>", "Override path to the sync directory (defaults to ./.primitive/sync/<env>/<appId>/)")
+        .option("-o, --output <dir>", "Output directory for the generated files (defaults to <sync-dir>/workflows/generated/)")
+        .option("--lang <lang>", "Target language for the generated types: 'ts' (default) or 'swift'.", "ts")
+        .option("--check", "Exit non-zero if generated output is out of date (CI guard); does not write. Compares byte-for-byte, so the file on disk must match the emission exactly.")
+        .option("--json", "Output the result summary as JSON")
+        .action(async (workflowKey, options) => {
+        try {
+            // 0. Validate --lang up front so an unknown value fails clearly rather
+            //    than silently defaulting to the TS emitter.
+            const lang = String(options.lang ?? "ts").toLowerCase();
+            if (lang !== "ts" && lang !== "swift") {
+                error(`Unknown --lang "${options.lang}". Use "ts" or "swift".`);
+                process.exit(1);
+            }
+            // 1. Resolve the single source workflows/ directory via the shared
+            //    active-environment resolver (issue #1510). Honors --sync-dir /
+            //    --app overrides, resolves the active env
+            //    (--env → PRIMITIVE_ENV → defaultEnvironment → single-env), and
+            //    preserves the legacy per-app scan fallback in bare-dir mode.
+            const workflowsSourceDir = resolveCodegenSourceDir({
+                subdir: "workflows",
+                options: { app: options.app, syncDir: options.syncDir },
+            });
+            // 2. Collect the source .toml files (one per workflow), filtered to a
+            //    single workflow when an argument is given. Match on the file stem;
+            //    the generator resolves the real key from `[workflow].key`.
+            const inputs = [];
+            for (const fileName of readdirSync(workflowsSourceDir)) {
+                if (!fileName.endsWith(".toml"))
+                    continue;
+                const stem = fileName.slice(0, -".toml".length);
+                if (workflowKey && stem !== workflowKey)
+                    continue;
+                const tomlPath = path.join(workflowsSourceDir, fileName);
+                inputs.push({
+                    fileStem: stem,
+                    tomlPath,
+                    tomlContent: readFileSync(tomlPath, "utf-8"),
+                });
+            }
+            if (inputs.length === 0) {
+                error(workflowKey
+                    ? `No workflows/${workflowKey}.toml found under .primitive/sync/.`
+                    : "No workflows/*.toml files found to generate from.");
+                process.exit(1);
+            }
+            // 3. Resolve the output directory. Default: a `generated/` subdir of
+            //    the first source dir (keeps generated output beside the schema).
+            const outputDir = options.output
+                ? path.resolve(options.output)
+                : path.join(path.dirname(inputs[0].tomlPath), "generated");
+            // 4. Run codegen (or --check) with the selected emitter. Both the TS
+            //    and Swift generators return the same WriteOrCheckResult shape, so
+            //    the reporting below is emitter-agnostic. Fork 1 = A: only the
+            //    emitter differs; both read the same synced TOMLs and the same
+            //    drift-guarded schema descriptor.
+            const codegenResult = lang === "swift"
+                ? await generateWorkflowSwiftTypes({
+                    inputs,
+                    outputDir,
+                    check: !!options.check,
+                    singleWorkflow: !!workflowKey,
+                })
+                : await generateWorkflowTypes({
+                    inputs,
+                    outputDir,
+                    check: !!options.check,
+                    singleWorkflow: !!workflowKey,
+                });
+            if (options.check) {
+                if (codegenResult.mismatches.length > 0) {
+                    if (options.json) {
+                        json({ ok: false, mismatches: codegenResult.mismatches });
+                    }
+                    else {
+                        error(`Check failed: ${codegenResult.mismatches.length} file(s) out of date.`);
+                        for (const m of codegenResult.mismatches) {
+                            error(`  ${m.reason}: ${path.relative(process.cwd(), m.filePath)}`);
+                        }
+                        info(lang === "swift"
+                            ? "Run `primitive workflows codegen --lang swift` to regenerate."
+                            : "Run `primitive workflows codegen` to regenerate.");
+                    }
+                    process.exit(1);
+                }
+                if (options.json) {
+                    json({ ok: true, checked: codegenResult.writtenFiles.length });
+                }
+                else {
+                    success(`Check passed: ${codegenResult.writtenFiles.length} file(s) up to date.`);
+                }
+                return;
+            }
+            if (options.json) {
+                json({
+                    written: codegenResult.writtenFiles,
+                    deleted: codegenResult.deletedFiles,
+                });
+                return;
+            }
+            success(`Generated ${codegenResult.writtenFiles.length} file(s)` +
+                (codegenResult.deletedFiles.length > 0
+                    ? `, deleted ${codegenResult.deletedFiles.length} stale file(s).`
+                    : "."));
+            for (const f of codegenResult.writtenFiles) {
+                keyValue("  wrote", path.relative(process.cwd(), f));
+            }
+            for (const f of codegenResult.deletedFiles) {
+                keyValue("  deleted", path.relative(process.cwd(), f));
+            }
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
 }
 function formatFileSize(bytes) {
     if (bytes < 1024)