primitive-admin 1.0.52 → 1.0.54

package/dist/src/commands/workflows.js

@@ -1,14 +1,19 @@
-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 { parseConfigToml, stringifyConfigToml } from "../lib/config-toml.js";
 import { lookup as mimeLookup } from "mime-types";
+import { generateWorkflowTypes, } from "../lib/workflow-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 { validateWorkflowToml, formatWorkflowTomlErrors, } from "../lib/workflow-toml-validator.js";
 import { expandWorkflow } from "../lib/workflow-fragments.js";
+import { buildWorkflowPayloadFromToml } from "../lib/workflow-payload.js";
+import { applyWorkflowBody, workflowKeyMismatchError, parseCapabilitiesFlag, } from "../lib/workflow-apply.js";
 import { confirmPrompt } from "../lib/confirm-prompt.js";
 import chalk from "chalk";
-import { success, error, info, warn, keyValue, result as printResult, formatTable, formatId, formatDate, formatStatus, formatDuration, json, divider, progress, progressEnd, } from "../lib/output.js";
+import { success, error, printApiError, info, warn, keyValue, result as printResult, formatTable, formatId, formatDate, formatStatus, formatDuration, json, divider, progress, progressEnd, } from "../lib/output.js";
 /**
  * Render the `Step Results` section of `workflows runs status`. Pure
  * formatting helper — returns lines as strings so it's unit-testable
@@ -88,6 +93,75 @@ export function renderRunStatusStepResults(stepResults) {
     }
     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
@@ -177,7 +251,7 @@ Examples:
             let tomlData;
             try {
                 const content = readFileSync(options.fromFile, "utf-8");
-                tomlData = TOML.parse(content);
+                tomlData = parseConfigToml(content);
             }
             catch (err) {
                 error(`Failed to read TOML file: ${err.message}`);
@@ -194,29 +268,15 @@ Examples:
                 process.exit(1);
             }
             const workflow = tomlData.workflow || tomlData;
+            // #1177: build the `[workflow]`-derived fields through the shared
+            // builder so this create path can't drift from `sync push` again
+            // (`status`, `capabilities`, `perAppMax*`, `queueTtlSeconds`, `runAs`,
+            // `accessRule`, `syncCallable` all flow from one field list). Structural
+            // fields (`workflowKey`, `steps`) are attached here.
             payload = {
                 workflowKey: workflow.key || workflow.workflowKey,
-                name: workflow.name,
-                description: workflow.description,
                 steps: tomlData.steps || [],
-                inputSchema: workflow.inputSchema ? JSON.parse(workflow.inputSchema) : undefined,
-                outputSchema: workflow.outputSchema ? JSON.parse(workflow.outputSchema) : undefined,
-                perUserMaxRunning: workflow.perUserMaxRunning,
-                perUserMaxQueued: workflow.perUserMaxQueued,
-                perAppMaxRunning: workflow.perAppMaxRunning,
-                perAppMaxQueued: workflow.perAppMaxQueued,
-                queueTtlSeconds: workflow.queueTtlSeconds,
-                dequeueOrder: workflow.dequeueOrder,
-                requiresClientApply: workflow.requiresClientApply,
-                // #807: align create --from-file with sync/update — read syncCallable
-                // from the TOML so all three entry points behave identically.
-                syncCallable: workflow.syncCallable,
-                // #571: carry accessRule through so a TOML's access-control rule
-                // lands on create instead of being silently dropped. On create the
-                // server default is already null, so coalesce a falsy/absent rule to
-                // undefined (omit) rather than sending "" — both clear, but undefined
-                // is the precise "no rule declared" signal.
-                accessRule: workflow.accessRule || undefined,
+                ...buildWorkflowPayloadFromToml(workflow, { mode: "create" }),
             };
         }
         else {
@@ -248,7 +308,9 @@ Examples:
             keyValue("Key", result.workflow?.workflowKey);
         }
         catch (err) {
-            error(err.message);
+            // #1173: render the server's structured `details[]` (e.g. the specific
+            // identity-validation reason) instead of only the generic message.
+            printApiError(err);
             process.exit(1);
         }
     });
@@ -256,7 +318,7 @@ Examples:
     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) => {
@@ -278,6 +340,12 @@ Examples:
             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);
             }
@@ -330,8 +398,8 @@ Examples:
     // Update workflow
     workflows
         .command("update")
-        .description("Update workflow metadata")
-        .argument("<workflow-id>", "Workflow ID")
+        .description("Update workflow metadata, or push a new body with --from-file")
+        .argument("<workflow-id>", "Workflow ID or key")
         .option("--app <app-id>", "App ID (uses current app if not specified)")
         .option("--name <name>", "Display name")
         .option("--description <desc>", "Description")
@@ -342,9 +410,117 @@ Examples:
         .option("--requires-client-apply <bool>", "Require client-side apply: true or false")
         .option("--sync-callable <bool>", "Allow client.workflows.runSync(): true or false")
         .option("--access-rule <expr>", "CEL expression for workflow access (empty string to clear)")
+        .option("--capabilities <list>", "Comma-separated capability grants (e.g. membership,secrets); empty string revokes all")
+        .option("--from-file <path>", "Push a revised body (metadata + steps) from a TOML file, keeping the same key/id. " +
+        "Overwrites the active config in place — live immediately (no separate publish). " +
+        "Explicit metadata flags above override values in the TOML.")
         .option("--json", "Output as JSON")
         .action(async (workflowId, options) => {
         const resolvedAppId = resolveAppId(undefined, options);
+        // --from-file: push a full body (metadata + steps) to the existing
+        // workflow, keeping its key/id. Symmetric with `create --from-file` and
+        // mirrors the `sync push` update-existing path via the shared
+        // `applyWorkflowBody` helper (#1249).
+        if (options.fromFile) {
+            let tomlData;
+            try {
+                // Expand top-level `include = [...]` workflow fragments before
+                // deriving steps, matching what `sync push` does (`parseTomlFile`
+                // runs `expandWorkflowTomlData`). `update --from-file` overwrites an
+                // existing workflow's live active config, so parsing the raw TOML
+                // and reading only `tomlData.steps` would drop fragment-supplied
+                // steps — an include-only workflow would overwrite the live body
+                // with an empty step list (silent data loss, #1286). `expandWorkflow`
+                // reads + parses + splices fragments; a TOML with no `include` key is
+                // returned unchanged, so the non-fragment case is unaffected.
+                tomlData = expandWorkflow(options.fromFile);
+            }
+            catch (err) {
+                error(`Failed to read TOML file: ${err.message}`);
+                process.exit(1);
+            }
+            // Issue #685: reject misnested headers before sending anything to the
+            // server — identical validation to `create --from-file`. Runs on the
+            // expanded data (post fragment splice), matching `sync push`.
+            const tomlErrors = validateWorkflowToml(tomlData);
+            if (tomlErrors.length > 0) {
+                error(formatWorkflowTomlErrors(options.fromFile, tomlErrors));
+                process.exit(1);
+            }
+            const tomlWorkflow = tomlData.workflow || tomlData;
+            const steps = tomlData.steps || [];
+            const client = new ApiClient();
+            // Fetch the existing workflow: we need its real workflowKey (Fork 2
+            // key-mismatch guard) and its activeConfigId (live body overwrite).
+            let existing;
+            try {
+                const got = await client.getWorkflow(resolvedAppId, workflowId);
+                existing = got?.workflow;
+            }
+            catch (err) {
+                printApiError(err);
+                process.exit(1);
+            }
+            if (!existing) {
+                error(`Workflow not found: ${workflowId}`);
+                process.exit(1);
+            }
+            // Fork 2: a TOML key that contradicts the target's key is almost
+            // certainly the wrong file — error rather than silently ignore it.
+            const mismatch = workflowKeyMismatchError(tomlWorkflow, existing.workflowKey);
+            if (mismatch) {
+                error(mismatch);
+                process.exit(1);
+            }
+            // Fork 1 (B): explicit `update` flags override TOML-derived metadata.
+            const mergedWorkflow = { ...tomlWorkflow };
+            if (options.name)
+                mergedWorkflow.name = options.name;
+            if (options.description)
+                mergedWorkflow.description = options.description;
+            if (options.status)
+                mergedWorkflow.status = options.status;
+            if (options.perUserMaxRunning) {
+                mergedWorkflow.perUserMaxRunning = parseInt(options.perUserMaxRunning);
+            }
+            if (options.perUserMaxQueued) {
+                mergedWorkflow.perUserMaxQueued = parseInt(options.perUserMaxQueued);
+            }
+            if (options.dequeueOrder)
+                mergedWorkflow.dequeueOrder = options.dequeueOrder;
+            if (options.requiresClientApply !== undefined) {
+                mergedWorkflow.requiresClientApply = options.requiresClientApply === "true";
+            }
+            if (options.syncCallable !== undefined) {
+                mergedWorkflow.syncCallable = options.syncCallable === "true";
+            }
+            if (options.accessRule !== undefined) {
+                mergedWorkflow.accessRule = options.accessRule;
+            }
+            // #1232: an explicit --capabilities flag overrides whatever the TOML
+            // declares (grant/revoke on top of a --from-file body push).
+            if (options.capabilities !== undefined) {
+                mergedWorkflow.capabilities = parseCapabilitiesFlag(options.capabilities);
+            }
+            try {
+                const { updateSlotLabel, fullWorkflow } = await applyWorkflowBody(client, resolvedAppId, workflowId, mergedWorkflow, steps, { activeConfigId: existing.activeConfigId });
+                if (options.json) {
+                    json(fullWorkflow);
+                    return;
+                }
+                success(`Workflow updated from ${options.fromFile} (${updateSlotLabel}).`);
+                keyValue("Workflow ID", workflowId);
+                keyValue("Key", existing.workflowKey);
+                keyValue("Steps", steps.length);
+            }
+            catch (err) {
+                // Surface the server's structured `details[]` (e.g. syncCallable /
+                // identity validation reasons) like create/sync push do.
+                printApiError(err);
+                process.exit(1);
+            }
+            return;
+        }
         const payload = {};
         if (options.name)
             payload.name = options.name;
@@ -371,6 +547,14 @@ Examples:
         if (options.accessRule !== undefined) {
             payload.accessRule = options.accessRule;
         }
+        // #1232: the CLI fallback the issue asked for — grant/revoke a workflow's
+        // sensitive `capabilities` (e.g. `membership`) on an existing workflow.
+        // Presence-guarded like --access-rule: an omitted flag stays undefined so
+        // the server's hasOwnProperty guard leaves the existing grant untouched;
+        // `--capabilities ""` sends [] to revoke. The server validates the names.
+        if (options.capabilities !== undefined) {
+            payload.capabilities = parseCapabilitiesFlag(options.capabilities);
+        }
         if (Object.keys(payload).length === 0) {
             error("No update options specified.");
             process.exit(1);
@@ -385,7 +569,8 @@ Examples:
             success("Workflow updated.");
         }
         catch (err) {
-            error(err.message);
+            // #1173: surface structured `details[]` on update too.
+            printApiError(err);
             process.exit(1);
         }
     });
@@ -393,7 +578,7 @@ Examples:
     workflows
         .command("delete")
         .description("Delete or archive a 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("--hard", "Permanently delete instead of archive")
         .option("-y, --yes", "Skip confirmation prompt")
@@ -416,6 +601,10 @@ Examples:
             else {
                 await client.updateWorkflow(resolvedAppId, workflowId, { status: "archived" });
                 success("Workflow archived.");
+                // #1238 — archiving keeps the workflowKey reserved, so recreating
+                // under the same key fails with "workflowKey already exists". Point
+                // at the remedy so the reserved-key behavior is discoverable.
+                info(`The workflowKey stays reserved while archived. To free it for reuse, run: primitive workflows delete ${workflowId} --hard`);
             }
         }
         catch (err) {
@@ -439,7 +628,7 @@ Examples:
             if (options.format === "toml") {
                 // Strip the `include` key (already removed by expander) and emit
                 // valid TOML so the result is round-trippable.
-                console.log(TOML.stringify(expanded));
+                console.log(stringifyConfigToml(expanded));
             }
             else {
                 console.log(JSON.stringify(expanded, null, 2));
@@ -456,7 +645,7 @@ Examples:
     draft
         .command("update")
         .description("Update workflow draft steps (deprecated; use 'workflows configs' for staged rollouts)")
-        .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("--from-file <path>", "Load steps from TOML file")
         .option("--json", "Output as JSON")
@@ -469,7 +658,7 @@ Examples:
         let tomlData;
         try {
             const content = readFileSync(options.fromFile, "utf-8");
-            tomlData = TOML.parse(content);
+            tomlData = parseConfigToml(content);
         }
         catch (err) {
             error(`Failed to read TOML file: ${err.message}`);
@@ -525,7 +714,7 @@ Examples:
     workflows
         .command("publish")
         .description("Publish the current draft as a new revision (deprecated for new-model workflows; use 'workflows configs activate')")
-        .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) => {
@@ -569,7 +758,7 @@ 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")
         .option("--draft", "Force preview of the draft version, even if active is newer")
@@ -718,13 +907,195 @@ 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
     runs
         .command("list")
         .description("List workflow runs")
-        .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("--status <status>", "Filter by status: pending, running, completed, failed")
         .option("--limit <n>", "Number of runs to show", "20")
@@ -749,6 +1120,8 @@ Examples:
                 { 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" : "" },
             ]));
@@ -762,7 +1135,7 @@ Examples:
     runs
         .command("status")
         .description("Get status of a workflow run")
-        .argument("<workflow-id>", "Workflow ID")
+        .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")
@@ -778,7 +1151,13 @@ Examples:
             const run = result.run;
             keyValue("Run ID", run.runId);
             keyValue("Status", formatStatus(run.status));
-            keyValue("Started", formatDate(run.startedAt));
+            // #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) {
@@ -811,7 +1190,7 @@ Examples:
     runs
         .command("steps")
         .description("Show step-level details for a workflow run")
-        .argument("<workflow-id>", "Workflow ID")
+        .argument("<workflow-id>", "Workflow ID or key")
         .argument("<run-id>", "Run ID")
         .option("--app <app-id>", "App ID")
         .option("--json", "Output as JSON")
@@ -828,7 +1207,12 @@ Examples:
                 info("No step runs found.");
                 return;
             }
-            console.log(formatTable(items, [
+            // #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" },
                 {
@@ -839,6 +1223,13 @@ Examples:
                             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",
@@ -861,7 +1252,7 @@ Examples:
     runs
         .command("step-detail")
         .description("Show full details for a single step")
-        .argument("<workflow-id>", "Workflow ID")
+        .argument("<workflow-id>", "Workflow ID or key")
         .argument("<run-id>", "Run ID")
         .argument("<step-id>", "Step ID")
         .option("--app <app-id>", "App ID")
@@ -983,7 +1374,7 @@ Examples:
     runs
         .command("error")
         .description("Show error details for a failed workflow run")
-        .argument("<workflow-id>", "Workflow ID")
+        .argument("<workflow-id>", "Workflow ID or key")
         .argument("<run-id>", "Run ID")
         .option("--app <app-id>", "App ID")
         .option("--json", "Output as JSON")
@@ -1052,7 +1443,7 @@ Examples:
     runs
         .command("failures")
         .description("List recent workflow run failures")
-        .argument("<workflow-id>", "Workflow ID")
+        .argument("<workflow-id>", "Workflow ID or key")
         .option("--app <app-id>", "App ID")
         .option("--limit <n>", "Number of failures to show", "10")
         .option("--json", "Output as JSON")
@@ -1084,6 +1475,111 @@ Examples:
             process.exit(1);
         }
     });
+    // ── Iterations: inspect / reset iterate-users singleton iterations (#1209) ──
+    const iterations = workflows
+        .command("iterations")
+        .description("Inspect and reset iterate-users iterations");
+    iterations
+        .command("list")
+        .description("List iterate-users iterations for the app")
+        .option("--app <app-id>", "App ID (uses current app if not specified)")
+        .option("--json", "Output as JSON")
+        .action(async (options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        const client = new ApiClient();
+        try {
+            const { items } = await client.listIterations(resolvedAppId);
+            if (options.json) {
+                json(items);
+                return;
+            }
+            if (!items || items.length === 0) {
+                info("No iterations found.");
+                return;
+            }
+            console.log(formatTable(items, [
+                { header: "ITERATION", key: "iterationName" },
+                { header: "STATUS", key: "status", format: formatStatus },
+                { header: "ACQUIRED", key: "lastAcquireMode", format: (v) => v || "" },
+                { header: "PROCESSED", key: "totalProcessed" },
+                { header: "FAILED", key: "failedCount" },
+                { header: "LAST RUN", key: "lastRunAt", format: formatDate },
+            ]));
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    iterations
+        .command("get")
+        .description("Show details for a single iterate-users iteration")
+        .argument("<name>", "Iteration name")
+        .option("--app <app-id>", "App ID (uses current app if not specified)")
+        .option("--json", "Output as JSON")
+        .action(async (name, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        const client = new ApiClient();
+        try {
+            const it = await client.getIteration(resolvedAppId, name);
+            if (options.json) {
+                json(it);
+                return;
+            }
+            keyValue("Iteration", it.iterationName);
+            keyValue("Status", formatStatus(it.status));
+            keyValue("Acquired as", it.lastAcquireMode || "(unknown)");
+            keyValue("Run ID", it.runId);
+            keyValue("Instance ID", it.instanceId);
+            keyValue("Started", formatDate(it.startedAt));
+            keyValue("Last run", formatDate(it.lastRunAt));
+            keyValue("Lock expires", formatDate(it.lockExpiresAt));
+            keyValue("Processed", String(it.totalProcessed ?? 0));
+            keyValue("Succeeded", String(it.succeededCount ?? 0));
+            keyValue("Failed (total)", String(it.failedCount ?? 0));
+            keyValue("Skipped", String(it.skippedCount ?? 0));
+            if (it.lastError) {
+                keyValue("Last error", it.lastError);
+            }
+            const sample = Array.isArray(it.failedUserIdsSample)
+                ? it.failedUserIdsSample
+                : [];
+            if (sample.length > 0) {
+                const label = it.failedUserIdsTruncated
+                    ? `Failed user IDs (sample, truncated; ${it.failedCount} total)`
+                    : `Failed user IDs (sample)`;
+                keyValue(label, sample.join(", "));
+            }
+        }
+        catch (err) {
+            error(err.message);
+            process.exit(1);
+        }
+    });
+    iterations
+        .command("reset")
+        .description("Reset a terminal (completed/failed) iteration so the next trigger runs fresh")
+        .argument("<name>", "Iteration name")
+        .option("--app <app-id>", "App ID (uses current app if not specified)")
+        .option("--json", "Output as JSON")
+        .action(async (name, options) => {
+        const resolvedAppId = resolveAppId(undefined, options);
+        const client = new ApiClient();
+        try {
+            const res = await client.resetIteration(resolvedAppId, name);
+            if (options.json) {
+                json(res);
+                return;
+            }
+            success(`Reset iteration "${name}" (was ${res.previousStatus}). The next trigger will run fresh.`);
+        }
+        catch (err) {
+            // A running iteration is refused with 409 + lock metadata — surface a
+            // clear message rather than a raw error.
+            error(err.message);
+            process.exit(1);
+        }
+    });
     // Analytics overview
     const analyticsCmd = workflows.command("analytics").description("View workflow performance analytics");
     analyticsCmd
@@ -1176,7 +1672,7 @@ Examples:
     configs
         .command("list")
         .description("List configurations for a 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("--json", "Output as JSON")
         .action(async (workflowId, options) => {
@@ -1216,7 +1712,7 @@ Examples:
     configs
         .command("get")
         .description("Get configuration details")
-        .argument("<workflow-id>", "Workflow ID")
+        .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("--json", "Output as JSON")
@@ -1252,7 +1748,7 @@ Examples:
     configs
         .command("create")
         .description("Create a new configuration")
-        .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("--name <name>", "Configuration name (required)")
         .option("--description <desc>", "Description")
@@ -1269,7 +1765,7 @@ Examples:
             let tomlData;
             try {
                 const content = readFileSync(options.fromFile, "utf-8");
-                tomlData = TOML.parse(content);
+                tomlData = parseConfigToml(content);
             }
             catch (err) {
                 error(`Failed to read TOML file: ${err.message}`);
@@ -1306,7 +1802,7 @@ Examples:
     configs
         .command("update")
         .description("Update a configuration")
-        .argument("<workflow-id>", "Workflow ID")
+        .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("--name <name>", "Configuration name")
@@ -1324,7 +1820,7 @@ Examples:
             let tomlData;
             try {
                 const content = readFileSync(options.fromFile, "utf-8");
-                tomlData = TOML.parse(content);
+                tomlData = parseConfigToml(content);
             }
             catch (err) {
                 error(`Failed to read TOML file: ${err.message}`);
@@ -1362,7 +1858,7 @@ Examples:
     configs
         .command("activate")
         .description("Set a configuration as the active (default) configuration")
-        .argument("<workflow-id>", "Workflow ID")
+        .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("--json", "Output as JSON")
@@ -1387,7 +1883,7 @@ Examples:
     configs
         .command("duplicate")
         .description("Duplicate a configuration")
-        .argument("<workflow-id>", "Workflow ID")
+        .argument("<workflow-id>", "Workflow ID or key")
         .argument("<config-id>", "Configuration ID to duplicate")
         .option("--app <app-id>", "App ID (uses current app if not specified)")
         .option("--name <name>", "Name for the new configuration")
@@ -1415,7 +1911,7 @@ Examples:
     configs
         .command("archive")
         .description("Archive a configuration")
-        .argument("<workflow-id>", "Workflow ID")
+        .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")
@@ -2234,6 +2730,109 @@ Examples:
             process.exit(1);
         }
     });
+    // ============================================
+    // Codegen command (issue #1442)
+    // ============================================
+    workflows
+        .command("codegen")
+        .description("Generate typed TypeScript signatures from the local workflows/*.toml schemas. Emits one <key>.generated.ts per workflow (<Key>Input/<Key>Output types + a <key>(client) typed invoker factory returning { runSync?, start }).")
+        .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 <key>.generated.ts files (defaults to <sync-dir>/workflows/generated/)")
+        .option("--check", "Exit non-zero if generated output is out of date (CI guard); does not write.")
+        .option("--json", "Output the result summary as JSON")
+        .action(async (workflowKey, options) => {
+        try {
+            // 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).
+            const codegenResult = 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("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)