primitive-admin 1.0.61 → 1.0.62

package/dist/src/commands/workflows.js

@@ -1,20 +1,22 @@
-import { readFileSync, writeFileSync, statSync, readdirSync, } from "fs";
-import { basename } from "path";
+import { Option } from "commander";
+import { readFileSync, writeFileSync, readdirSync, } from "fs";
 import * as path from "path";
-import { parseConfigToml, stringifyConfigToml } from "../lib/config-toml.js";
-import { lookup as mimeLookup } from "mime-types";
+import { stringifyConfigToml } from "../lib/config-toml.js";
 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 { formatAccessRuleForDisplay } from "../lib/access-rule-display.js";
 import { resolveCodegenSourceDir } from "../lib/codegen-shared/resolveCodegenSourceDir.js";
-import { validateWorkflowToml, validateWorkflowIdentity, effectiveWorkflowIdentity, formatWorkflowTomlErrors, validateWorkflowExpressionsToml, validateWorkflowExpressionsRawToml, } from "../lib/workflow-toml-validator.js";
+import { resolveSyncDirOverride } from "../lib/sync-dir-selector.js";
 import { expandWorkflow } from "../lib/workflow-fragments.js";
-import { buildWorkflowPayloadFromToml, parseWorkflowExpressionsToml, } from "../lib/workflow-payload.js";
-import { applyWorkflowBody, workflowKeyMismatchError, parseCapabilitiesFlag, } from "../lib/workflow-apply.js";
 import { confirmPrompt } from "../lib/confirm-prompt.js";
+import { parseStatusFilter } from "../lib/object-status-filter.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, printApiError, info, warn, keyValue, result as printResult, formatTable, formatId, formatDate, formatStatus, formatDuration, json, divider, progress, progressEnd, } 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
@@ -32,27 +34,52 @@ import { success, error, printApiError, info, warn, keyValue, result as printRes
  * trailing "..." when truncated). See #688.
  */
 /**
- * Terminal-status predicate for the `workflows preview --wait` poll loop
- * (issue #941). A status is terminal when the run has reached an end state and
- * the wait should stop polling — as opposed to a still-in-flight status
- * ("running"/"queued"/"waiting") that should keep the loop going until the cap.
+ * 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.
  *
- * The admin preview-status endpoint emits these terminal values (see
- * `mapWorkflowStatus` / the server-side `isEnded` set in admin-api.ts):
- *   - "completed" (Cloudflare "complete" normalized)
- *   - "failed"    (Cloudflare "errored" normalized)
- *   - "terminated" (an aborted preview — Codex P2: previously NOT treated as
- *     terminal, so an aborted preview was misreported as a wait timeout)
+ * 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.
  *
- * We accept the un-normalized Cloudflare spellings too ("complete"/"errored")
- * defensively, in case a status slips through un-normalized.
+ * 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 (s === "completed" ||
-        s === "complete" ||
-        s === "failed" ||
-        s === "errored" ||
-        s === "terminated");
+    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 = [];
@@ -94,6 +121,48 @@ export function renderRunStatusStepResults(stepResults) {
     }
     return lines;
 }
+/**
+ * #2771 — how long a step row has been going.
+ *
+ * A step that is still executing is persisted with status `running` and a
+ * `durationMs` of 0 (the column is required; the real value is written when the
+ * step ends). Printing that 0 hides the one number that matters while a run is
+ * in flight — how long the current step has been stuck — so a running row is
+ * measured from its `startedAt` instead. Finished rows keep their stored
+ * duration. Exported for testability.
+ */
+export function stepRunDisplayDurationMs(step, now = Date.now()) {
+    const stored = typeof step?.durationMs === "number" ? step.durationMs : null;
+    if (step?.status !== "running")
+        return stored;
+    const started = step?.startedAt ? new Date(step.startedAt).getTime() : NaN;
+    if (Number.isNaN(started))
+        return stored;
+    return Math.max(0, now - started);
+}
+/**
+ * #2771 — the step lines `workflows runs status` should render.
+ *
+ * Cloudflare's instance status carries `stepResults` only once the run reaches
+ * a terminal state, so a live run used to print `Status: running` and nothing
+ * else. The persisted step rows now exist DURING the run, so they are the
+ * fallback: mapped onto the shape `renderRunStatusStepResults` reads, with a
+ * running step's elapsed time in place of its 0 placeholder. The instance's own
+ * results always win when it has them. Exported for testability.
+ */
+export function stepResultsForRunStatus(instanceStepResults, persistedStepRuns, now = Date.now()) {
+    if (instanceStepResults && instanceStepResults.length > 0)
+        return instanceStepResults;
+    return (persistedStepRuns || []).map((row) => ({
+        id: row?.stepId,
+        kind: row?.stepKind,
+        status: row?.status,
+        durationMs: stepRunDisplayDurationMs(row, now),
+        error: row?.error,
+        errorDetails: row?.errorDetails,
+        output: row?.output,
+    }));
+}
 /**
  * #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
@@ -187,13 +256,38 @@ export function formatConfigSlotLabel(slot, configName, configId, prefixLength =
 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 create workflow process-doc       # scaffold workflows/process-doc.toml
+  $ primitive config 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 `config 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 create workflow <key>  # scaffold one locally
+  $ primitive config set workflow/<key> <path>=<value>
+  $ primitive config 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 'config push'. There is no other write path: revisions are
+read-only history from the retired legacy path (issue #2768).
+`);
+    // Per-subject analytics have one home, the `analytics` noun (issue #2766) —
+    // this group's own analytics commands were removed, so say where they went.
+    workflows.addHelpText("after", `
+Analytics live under the analytics noun:
+  $ primitive analytics workflows --window-days 7 --limit 10
+
+That is the single home for per-subject analytics (workflows, prompts,
+integrations). It ranks workflows by runs; there is no app-wide workflow
+overview — the endpoint behind the retired overview command never existed.
 `);
     // List workflows
     workflows
@@ -201,14 +295,22 @@ Examples:
         .description("List workflows")
         .argument("[app-id]", "App ID (uses current app if not specified)")
         .option("--app <app-id>", "App ID")
-        .option("--status <status>", "Filter by status: draft, active, archived")
+        .option("--status <status>", "Filter by status: active, inactive, archived")
         .option("--json", "Output as JSON")
         .action(async (appId, options) => {
         const resolvedAppId = resolveAppId(appId, options);
         const client = new ApiClient();
         try {
+            // #2803 — `draft` is gone; refuse it by name rather than returning the
+            // empty list a canonical filter would produce. #2887 added `archived`:
+            // the delete flow writes one now, so asking for the retired rows is a
+            // question with an answer rather than a 400.
             const { items } = await client.listWorkflows(resolvedAppId, {
-                status: options.status,
+                status: parseStatusFilter("workflows", options.status, [
+                    "active",
+                    "inactive",
+                    "archived",
+                ]),
             });
             if (options.json) {
                 json(items);
@@ -231,109 +333,6 @@ 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("--requires-client-apply <bool>", "Require client-side apply: true or false")
-        .option("--sync-callable <bool>", "Allow client.workflows.runSync(): true or false")
-        .option("--json", "Output as JSON")
-        .action(async (appId, options) => {
-        const resolvedAppId = resolveAppId(appId, options);
-        const client = new ApiClient();
-        let payload;
-        if (options.fromFile) {
-            let tomlData;
-            try {
-                const content = readFileSync(options.fromFile, "utf-8");
-                tomlData = parseConfigToml(content);
-            }
-            catch (err) {
-                error(`Failed to read TOML file: ${err.message}`);
-                process.exit(1);
-            }
-            // Reject misnested headers (#685, e.g. [steps.<id>.request]) and the
-            // #1447 runAs="system" + accessRule dead-config combo before we send
-            // anything to the server. These parse to TOML
-            // sub-tables that the runtime silently ignores. We validate
-            // outside the parse try-block so the diagnostic isn't masked by
-            // the generic "Failed to read TOML" handler.
-            const tomlErrors = validateWorkflowToml(tomlData);
-            if (tomlErrors.length > 0) {
-                error(formatWorkflowTomlErrors(options.fromFile, tomlErrors));
-                process.exit(1);
-            }
-            const workflow = tomlData.workflow || tomlData;
-            // #1614 — parse the top-level `[expr.cel]` named-guard definitions
-            // (structural, like steps) and validate them client-side before push.
-            const fromFileSteps = tomlData.steps || [];
-            const fromFileExpressions = parseWorkflowExpressionsToml(tomlData);
-            // #1614 — validate the RAW `[expr.cel]` table shape first, so a
-            // non-string body (e.g. `ready = true`) fails fast instead of being
-            // silently dropped by parseWorkflowExpressionsToml.
-            const fromFileExprErrors = [
-                ...validateWorkflowExpressionsRawToml(tomlData),
-                ...validateWorkflowExpressionsToml(fromFileSteps, fromFileExpressions),
-            ];
-            if (fromFileExprErrors.length > 0) {
-                error(`${options.fromFile}: workflow expressions are invalid:\n  - ${fromFileExprErrors.join("\n  - ")}`);
-                process.exit(1);
-            }
-            // #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`, `expressions`) are attached here.
-            payload = {
-                workflowKey: workflow.key || workflow.workflowKey,
-                steps: fromFileSteps,
-                ...buildWorkflowPayloadFromToml(workflow, { mode: "create" }),
-                // #1614 — named `expr.*` definitions (absent → undefined).
-                expressions: fromFileExpressions ?? undefined,
-            };
-        }
-        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: [],
-            };
-        }
-        if (options.requiresClientApply !== undefined) {
-            payload.requiresClientApply = options.requiresClientApply === "true";
-        }
-        if (options.syncCallable !== undefined) {
-            payload.syncCallable = options.syncCallable === "true";
-        }
-        try {
-            const result = await client.createWorkflow(resolvedAppId, payload);
-            if (options.json) {
-                json(result);
-                return;
-            }
-            success(`Workflow created: ${result.workflow?.name || options.name}`);
-            keyValue("Workflow ID", result.workflow?.workflowId);
-            keyValue("Key", result.workflow?.workflowKey);
-        }
-        catch (err) {
-            // #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);
-        }
-    });
-    // Get workflow
     workflows
         .command("get")
         .description("Get workflow details")
@@ -354,6 +353,9 @@ Examples:
             printResult("Key", wf.workflowKey);
             printResult("Name", wf.name);
             printResult("Description", wf.description);
+            // #2803 — ONE availability row. The server returns the canonical
+            // value, so a workflow an operator disabled reads `inactive` here and
+            // there is no second row left to disagree with it.
             printResult("Status", formatStatus(wf.status));
             printResult("Active Config", wf.activeConfigId || "-");
             printResult("Latest Revision", wf.latestRevision || "-");
@@ -365,9 +367,12 @@ Examples:
             printResult("Capabilities", Array.isArray(wf.capabilities) && wf.capabilities.length > 0
                 ? wf.capabilities.join(", ")
                 : "-");
-            if (wf.accessRule) {
-                printResult("Access Rule", wf.accessRule);
-            }
+            // #2652: a caller workflow with no rule denies every non-admin start,
+            // so the row is always printed — the sentinel names the consequence,
+            // and a `runAs: "system"` workflow gets its own exempt wording.
+            printResult("Access Rule", formatAccessRuleForDisplay(wf.accessRule, "workflow", {
+                runAs: wf.runAs,
+            }));
             divider();
             info("Queue Settings:");
             printResult("  Per User Max Running", wf.perUserMaxRunning);
@@ -414,255 +419,6 @@ Examples:
             process.exit(1);
         }
     });
-    // Update workflow
-    workflows
-        .command("update")
-        .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")
-        .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("--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);
-            }
-            // Reject misnested headers (#685) before sending anything to the
-            // server. Runs on the expanded data (post fragment splice), matching
-            // `sync push`.
-            //
-            // The #1447 system + accessRule identity check is SKIPPED here and
-            // re-run below against the merged metadata (codex review, 2026-07-15):
-            // `update --from-file` applies command-line overrides (`--access-rule`)
-            // after parsing, so `--access-rule ""` must be able to repair an
-            // offending file, and an override-introduced accessRule on a system
-            // workflow must still be caught. Checking the raw file here would do
-            // neither.
-            const tomlErrors = validateWorkflowToml(tomlData, {
-                skipWorkflowIdentity: true,
-            });
-            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);
-            }
-            // #1447 (maintainer decision, 2026-07-21): run the identity lint
-            // against the EFFECTIVE identity that will be PERSISTED — the merge of
-            // the stored record (`existing.runAs` / `existing.accessRule`) with the
-            // incoming file/flags — not the file alone. `applyWorkflowBody` omits
-            // undefined fields, so the server retains the other side of the pair:
-            // an existing `runAs="system"` workflow plus a file adding only an
-            // `accessRule` (or a file flipping a workflow with a stored rule to
-            // `runAs="system"`) passes a file-only lint and is then rejected by the
-            // server's PATCH. `existing` is already fetched above, so merging costs
-            // zero extra round-trips. A field present in `mergedWorkflow` (including
-            // an empty-string clear, e.g. `--access-rule ""`) overrides the stored
-            // value; an absent field falls back to what the server keeps.
-            const mergedIdentityError = validateWorkflowIdentity(effectiveWorkflowIdentity(existing, mergedWorkflow));
-            if (mergedIdentityError) {
-                error(formatWorkflowTomlErrors(options.fromFile, [mergedIdentityError]));
-                process.exit(1);
-            }
-            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;
-        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 (options.requiresClientApply !== undefined) {
-            payload.requiresClientApply = options.requiresClientApply === "true";
-        }
-        if (options.syncCallable !== undefined) {
-            payload.syncCallable = options.syncCallable === "true";
-        }
-        // #571: presence guard, NOT truthiness — `--access-rule ""` must reach
-        // the server (it clears the rule) while an omitted flag leaves
-        // options.accessRule undefined so the server's hasOwnProperty guard
-        // leaves the existing rule untouched.
-        if (options.accessRule !== undefined) {
-            payload.accessRule = options.accessRule;
-        }
-        // #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);
-        }
-        const client = new ApiClient();
-        try {
-            const result = await client.updateWorkflow(resolvedAppId, workflowId, payload);
-            if (options.json) {
-                json(result);
-                return;
-            }
-            success("Workflow updated.");
-        }
-        catch (err) {
-            // #1173: surface structured `details[]` on update too.
-            printApiError(err);
-            process.exit(1);
-        }
-    });
-    // Delete workflow
-    workflows
-        .command("delete")
-        .description("Delete or archive a workflow")
-        .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")
-        .action(async (workflowId, options) => {
-        const resolvedAppId = resolveAppId(undefined, options);
-        const client = new ApiClient();
-        try {
-            if (!options.yes) {
-                const action = options.hard ? "permanently delete" : "archive";
-                const confirmed = await confirmPrompt(`Are you sure you want to ${action} workflow ${workflowId}?`);
-                if (!confirmed) {
-                    info("Cancelled.");
-                    return;
-                }
-            }
-            if (options.hard) {
-                await client.deleteWorkflow(resolvedAppId, workflowId);
-                success("Workflow deleted.");
-            }
-            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) {
-            error(err.message);
-            process.exit(1);
-        }
-    });
-    // Expand a workflow TOML and print the result (no server contact).
-    //
-    // Authors use this to inspect what `include = [...]` fragments produce
-    // before pushing. Surfaces include-collision and unique-id failures with
-    // helpful messages without going through `sync push`.
     workflows
         .command("expand")
         .description("Expand a workflow TOML's include fragments and print the result")
@@ -685,122 +441,116 @@ Examples:
             process.exit(1);
         }
     });
-    // Draft subcommand
-    const draft = workflows.command("draft").description("Manage workflow draft");
-    // Update draft
-    draft
-        .command("update")
-        .description("Update workflow draft steps (deprecated; use 'workflows configs' for staged rollouts)")
+    // #2645 criterion 9 / #2803 — the operational verbs.
+    //
+    // Configuration is authored in TOML and applied with `config 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 the ONLY writers of `status`, which is server-owned and
+    // no longer a TOML key. The committed configuration says nothing about
+    // availability, so `config diff` reports the server's status as operator
+    // state rather than as drift.
+    workflows
+        .command("disable")
+        .description("Take a workflow out of service now. Operational, not configuration: `status` is server-owned and 'config push' can neither set nor clear it.")
         .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 tomlData;
+        const client = new ApiClient();
         try {
-            const content = readFileSync(options.fromFile, "utf-8");
-            tomlData = parseConfigToml(content);
+            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(`Failed to read TOML file: ${err.message}`);
-            process.exit(1);
-        }
-        // `draft update` is step-only — it sends `steps` (and draft schemas),
-        // never the `[workflow]` identity fields — so skip the #1447 identity
-        // lint (a false positive here; codex round-2 finding 2) but keep the
-        // structural #685 checks.
-        const tomlErrors = validateWorkflowToml(tomlData, {
-            skipWorkflowIdentity: true,
-        });
-        if (tomlErrors.length > 0) {
-            error(formatWorkflowTomlErrors(options.fromFile, tomlErrors));
+            error(err.message);
             process.exit(1);
         }
-        const workflow = tomlData.workflow || tomlData;
-        const payload = {
-            steps: tomlData.steps || [],
-            inputSchema: workflow.inputSchema ? JSON.parse(workflow.inputSchema) : undefined,
-            outputSchema: workflow.outputSchema ? JSON.parse(workflow.outputSchema) : undefined,
-        };
+    });
+    workflows
+        .command("enable")
+        .description("Put a workflow back in service.")
+        .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) => {
+        const resolvedAppId = resolveAppId(undefined, options);
         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);
-            // Issue #687: surface server-side deprecation hint when applicable.
-            if (result.deprecation) {
-                warn(`[deprecated] ${result.deprecation}`);
-            }
+            success(`Workflow enabled: ${result.workflowKey || workflowId}`);
         }
         catch (err) {
-            // Issue #987: config-model workflows reject the legacy draft slot with
-            // a 409 (the draft never executes). Surface the actionable config path
-            // cleanly instead of dumping a raw API error.
-            if (err?.statusCode === 409 && err?.code === "WORKFLOW_CONFIG_MODEL") {
-                error("This workflow has an active configuration, so the legacy draft slot is inert " +
-                    "(it won't change what runs). For dev-loop edits, use 'sync push' — it writes the\n" +
-                    "active config directly and activates the workflow end-to-end:\n" +
-                    "  primitive sync push\n" +
-                    "For staged rollouts, create + activate a config, then flip the status to active\n" +
-                    "(configs activate only sets the active config; it does not change the workflow status):\n" +
-                    "  primitive workflows configs create <workflow-id> --name <name> --from-file <path>\n" +
-                    "  primitive workflows configs activate <workflow-id> <config-id>\n" +
-                    "  primitive workflows update <workflow-id> --status active");
-                process.exit(1);
-            }
             error(err.message);
             process.exit(1);
         }
     });
-    // Publish workflow
+    // #2907 — the delete flow's CLI spelling. Not a second writer of `status`:
+    // this is the plain `DELETE` #2887 made retire-with-history, which until now
+    // only the admin API and the console could reach. Named `archive`, not
+    // `delete`, because a configuration noun gets no `delete` verb
+    // (docs/cli-design.md) and prune-by-push stays the only CLI hard-delete path.
     workflows
-        .command("publish")
-        .description("Publish the current draft as a new revision (deprecated for new-model workflows; use 'workflows configs activate')")
+        .command("archive")
+        .description("Retire a workflow (soft delete). Delete-lifecycle, not `disable`: the definition is kept so its history still resolves, it goes on holding its key, and there is no un-archive.")
         .argument("<workflow-id>", "Workflow ID or key")
         .option("--app <app-id>", "App ID (uses current app if not specified)")
+        .option("-y, --yes", "Skip confirmation prompt")
         .option("--json", "Output as JSON")
+        .addHelpText("after", `
+What archiving a workflow costs (retire-with-history):
+  New runs are refused, and so is every \`workflow.call\` into it.
+  Its runs, revisions, configurations and test cases keep resolving what they
+  point at — that is what the tombstone exists for.
+  The archived row still holds its workflowKey.
+  \`primitive workflows enable\` refuses an archived workflow; there is no
+  un-archive.
+
+Reclaiming the key means hard-deleting the row and its cascade:
+  $ rm workflows/<key>.toml
+  $ primitive config push --prune     # confirmed; hard-deletes the row
+  # or hard-delete it in the console, then re-add the file and push.
+`)
         .action(async (workflowId, options) => {
         const resolvedAppId = resolveAppId(undefined, options);
+        if (!options.yes) {
+            let confirmed;
+            try {
+                confirmed = await confirmPrompt(`Archive workflow ${workflowId}? New runs are refused, its history is ` +
+                    `kept, it goes on holding its key, and there is no un-archive.`);
+            }
+            catch (err) {
+                error(err.message);
+                process.exit(1);
+            }
+            if (!confirmed) {
+                info("Cancelled.");
+                return;
+            }
+        }
         const client = new ApiClient();
         try {
-            const result = await client.publishWorkflow(resolvedAppId, workflowId);
+            // The soft delete: no `hard`, so the #1238 cascade does not run and the
+            // definition row stays queryable.
+            const result = await client.deleteWorkflow(resolvedAppId, workflowId);
             if (options.json) {
                 json(result);
                 return;
             }
-            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}`);
-            }
+            success(`Workflow archived: ${workflowId}`);
+            info("Runs, revisions and test cases keep resolving. The row still holds its key — reclaim it by removing its file and running a confirmed `primitive config push --prune`.");
         }
         catch (err) {
-            // Issue #987: 'publish' is inert on config-model workflows (production
-            // runs read the active config), so the server rejects with a 409.
-            // Point the user at the config primitives instead of a raw API error.
-            if (err?.statusCode === 409 && err?.code === "WORKFLOW_CONFIG_MODEL") {
-                error("This workflow has an active configuration, so 'publish' is inert " +
-                    "(it bumps a legacy pointer that doesn't change what runs). For dev-loop edits, use\n" +
-                    "'sync push' — it writes the active config directly and activates the workflow end-to-end:\n" +
-                    "  primitive sync push\n" +
-                    "For staged rollouts, create + activate a config, then flip the status to active\n" +
-                    "(configs activate only sets the active config; it does not change the workflow status):\n" +
-                    "  primitive workflows configs create <workflow-id> --name <name> --from-file <path>\n" +
-                    "  primitive workflows configs activate <workflow-id> <config-id>\n" +
-                    "  primitive workflows update <workflow-id> --status active");
-                process.exit(1);
-            }
             error(err.message);
             process.exit(1);
         }
@@ -919,7 +669,12 @@ Examples:
                 }
                 return;
             }
-            if (status?.status === "completed" || status?.status === "complete") {
+            // #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:");
@@ -933,20 +688,41 @@ Examples:
                     });
                 }
             }
-            else if (status?.status === "failed" || status?.status === "errored") {
+            else if (waitOutcome === "failed") {
                 error("Preview failed.");
                 if (status.error) {
                     console.log("\nError:");
                     console.log(JSON.stringify(status.error, null, 2));
                 }
             }
-            else if (status?.status === "terminated") {
+            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 {
                 // 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'.`);
@@ -1143,44 +919,209 @@ Examples:
     // 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 or key")
+        // #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();
-        try {
-            const { items } = await client.listWorkflowRuns(resolvedAppId, workflowId, {
-                status: options.status,
-                limit: parseInt(options.limit),
-            });
-            if (options.json) {
-                json(items);
-                return;
+        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();
             }
-            if (!items || items.length === 0) {
-                info("No runs found.");
-                return;
+            catch (err) {
+                error(err.message);
+                process.exit(1);
             }
-            console.log(formatTable(items, [
-                { 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" : "" },
-            ]));
+            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 {
+            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
@@ -1195,13 +1136,39 @@ Examples:
         const client = new ApiClient();
         try {
             const result = await client.getWorkflowRunStatus(resolvedAppId, workflowId, runId);
+            // #2771 — a Cloudflare instance reports `stepResults` only once the run
+            // is terminal, so a live run used to answer with `status: running` and
+            // nothing else for its whole duration. Step rows are now written as the
+            // run goes, so fall back to them: the steps finished so far plus the one
+            // currently executing. Resolved BEFORE the output branches — a script
+            // polling `--json` needs the in-flight trace as much as a human does.
+            // Best-effort: a lookup failure still leaves the run details intact.
+            const instanceStepResults = result.instanceStatus?.stepResults;
+            let persistedStepRuns = [];
+            if (!instanceStepResults || instanceStepResults.length === 0) {
+                try {
+                    const stepRuns = await client.getWorkflowStepRuns(resolvedAppId, workflowId, runId);
+                    persistedStepRuns = stepRuns?.items || [];
+                }
+                catch {
+                    persistedStepRuns = [];
+                }
+            }
             if (options.json) {
-                json(result);
+                // Purely additive: `stepRuns` appears only when the persisted rows are
+                // what carries the trace, so a terminal run's JSON is unchanged.
+                json(persistedStepRuns.length > 0 ? { ...result, stepRuns: persistedStepRuns } : 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.
@@ -1211,26 +1178,24 @@ Examples:
             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));
+            const stepResultLines = renderRunStatusStepResults(stepResultsForRunStatus(instanceStepResults, persistedStepRuns));
+            if (result.instanceStatus?.output) {
+                divider();
+                info("Output:");
+                console.log(JSON.stringify(result.instanceStatus.output, null, 2));
+            }
+            if (stepResultLines.length > 0) {
+                divider();
+                info("Step Results:");
+                for (const line of stepResultLines) {
+                    console.log(line);
                 }
             }
+            if (result.instanceStatus?.error) {
+                divider();
+                error("Error:");
+                console.log(JSON.stringify(result.instanceStatus.error, null, 2));
+            }
         }
         catch (err) {
             error(err.message);
@@ -1251,7 +1216,9 @@ Examples:
         try {
             const { items } = await client.getWorkflowStepRuns(resolvedAppId, workflowId, runId);
             if (options.json) {
-                json(items);
+                // 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) {
@@ -1262,7 +1229,13 @@ Examples:
             // 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);
+            // #2771 — an in-flight run also returns the step executing right now
+            // (status `running`, duration not written yet). Show its elapsed time
+            // so a step stuck retrying is visible as such.
+            const rows = annotateStepGaps(items).map((row) => ({
+                ...row,
+                displayDurationMs: stepRunDisplayDurationMs(row),
+            }));
             console.log(formatTable(rows, [
                 { header: "STEP", key: "stepId" },
                 { header: "KIND", key: "stepKind" },
@@ -1272,7 +1245,9 @@ Examples:
                     format: (v) => v === "completed" ? chalk.green(v) :
                         v === "failed" ? chalk.red(v) :
                             v === "skipped" ? chalk.gray(v) :
-                                v === "error_captured" ? chalk.yellow(v) : v,
+                                v === "error_captured" ? chalk.yellow(v) :
+                                    // #2771 — the step executing right now.
+                                    v === "running" ? chalk.cyan(v) : v,
                 },
                 {
                     header: "GAP",
@@ -1281,7 +1256,7 @@ Examples:
                         ? chalk.yellow(formatDuration(v))
                         : chalk.dim("-"),
                 },
-                { header: "DURATION", key: "durationMs", format: formatDuration },
+                { header: "DURATION", key: "displayDurationMs", format: formatDuration },
                 {
                     header: "TOKENS",
                     key: "totalTokens",
@@ -1437,10 +1412,17 @@ Examples:
                 client.getWorkflowRunStatus(resolvedAppId, workflowId, runId),
                 client.getWorkflowStepRuns(resolvedAppId, workflowId, runId),
             ]);
-            const failedStep = stepsResult.items.find((s) => s.status === "failed");
+            // #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,
@@ -1457,6 +1439,9 @@ Examples:
             }
             keyValue("Run ID", runId);
             keyValue("Status", formatStatus(errorInfo.status));
+            if (errorInfo.errorCode) {
+                keyValue("Code", errorInfo.errorCode);
+            }
             if (errorInfo.errorMessage) {
                 divider();
                 error("Error: " + errorInfo.errorMessage);
@@ -1496,35 +1481,126 @@ Examples:
         .description("List recent workflow run failures")
         .argument("<workflow-id>", "Workflow ID or key")
         .option("--app <app-id>", "App ID")
-        .option("--limit <n>", "Number of failures to show", "10")
+        // #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 { items } = await client.listWorkflowRuns(resolvedAppId, workflowId, {
+            const sweep = await collectWorkflowFailures(({ cursor, limit: pageLimit }) => client.listWorkflowRuns(resolvedAppId, workflowId, {
                 status: "failed",
-                limit: parseInt(options.limit),
+                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(items);
+                // #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;
             }
-            if (!items || items.length === 0) {
-                info("No failures found.");
-                return;
+            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 },
+                ]));
             }
-            console.log(formatTable(items, [
-                { header: "RUN ID", key: "runId", format: formatId },
-                { header: "ERROR", key: "errorMessage", format: (v) => v ? (v.length > 50 ? v.slice(0, 47) + "..." : v) : "-" },
-                { header: "STARTED", key: "startedAt", format: formatDate },
-                { header: "ENDED", key: "endedAt", format: formatDate },
-            ]));
+            // #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);
+        }
     });
     // ── Iterations: inspect / reset iterate-users singleton iterations (#1209) ──
     const iterations = workflows
@@ -1631,80 +1707,6 @@ Examples:
             process.exit(1);
         }
     });
-    // Analytics overview
-    const analyticsCmd = workflows.command("analytics").description("View workflow performance analytics");
-    analyticsCmd
-        .command("overview")
-        .description("View workflow performance metrics")
-        .option("--app <app-id>", "App ID")
-        .option("--days <n>", "Time window in days", "7")
-        .option("--json", "Output as JSON")
-        .action(async (options) => {
-        const resolvedAppId = resolveAppId(undefined, options);
-        const client = new ApiClient();
-        try {
-            const result = await client.getWorkflowAnalytics(resolvedAppId, {
-                windowDays: parseInt(options.days),
-            });
-            if (options.json) {
-                json(result);
-                return;
-            }
-            info(`Workflow Analytics (${result.windowDays || options.days} days)`);
-            console.log();
-            keyValue("Total Runs", String(result.totals?.totalRuns ?? 0));
-            keyValue("Success Rate", `${((result.totals?.successRate ?? 0) * 100).toFixed(1)}%`);
-            keyValue("Avg Duration", formatDuration(result.totals?.avgDurationMs));
-            if (result.tokenUsage) {
-                console.log();
-                info("Token Usage:");
-                keyValue("  Input Tokens", String(result.tokenUsage.totalInputTokens ?? 0));
-                keyValue("  Output Tokens", String(result.tokenUsage.totalOutputTokens ?? 0));
-                keyValue("  Total Tokens", String(result.tokenUsage.totalTokens ?? 0));
-            }
-        }
-        catch (err) {
-            error(err.message);
-            process.exit(1);
-        }
-    });
-    analyticsCmd
-        .command("top")
-        .description("View top workflows by usage")
-        .option("--app <app-id>", "App ID")
-        .option("--days <n>", "Time window in days", "7")
-        .option("--limit <n>", "Number of workflows to show", "10")
-        .option("--json", "Output as JSON")
-        .action(async (options) => {
-        const resolvedAppId = resolveAppId(undefined, options);
-        const client = new ApiClient();
-        try {
-            const result = await client.getTopWorkflows(resolvedAppId, {
-                windowDays: parseInt(options.days),
-                limit: parseInt(options.limit),
-            });
-            if (options.json) {
-                json(result);
-                return;
-            }
-            if (!result.items || result.items.length === 0) {
-                info("No workflow activity in this period.");
-                return;
-            }
-            console.log(formatTable(result.items, [
-                { header: "WORKFLOW", key: "workflow" },
-                { header: "RUNS", key: "executions" },
-                { header: "SUCCESS", key: "success_pct", format: (v) => `${v}%` },
-                { header: "P50", key: "p50", format: (v) => formatDuration(v) },
-                { header: "P95", key: "p95", format: (v) => formatDuration(v) },
-                { header: "TOKENS", key: "total_tokens", format: (v) => v ? String(Math.round(v)).replace(/\B(?=(\d{3})+(?!\d))/g, ",") : "-" },
-            ]));
-        }
-        catch (err) {
-            error(err.message);
-            process.exit(1);
-        }
-    });
     // ============================================
     // CONFIGS SUBCOMMAND
     // ============================================
@@ -1715,9 +1717,10 @@ Examples:
 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"
+
+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 config push'.
 `);
     // List configs
     configs
@@ -1795,228 +1798,23 @@ Examples:
             process.exit(1);
         }
     });
-    // Create config
-    configs
-        .command("create")
-        .description("Create a new configuration")
-        .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")
-        .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.name) {
-            error("--name is required");
-            process.exit(1);
-        }
-        let steps = [];
-        if (options.fromFile) {
-            let tomlData;
-            try {
-                const content = readFileSync(options.fromFile, "utf-8");
-                tomlData = parseConfigToml(content);
-            }
-            catch (err) {
-                error(`Failed to read TOML file: ${err.message}`);
-                process.exit(1);
-            }
-            // `configs create` is step-only — it consumes only `steps`, never the
-            // `[workflow]` identity fields — so skip the #1447 identity lint (a
-            // false positive here; codex round-2 finding 2) but keep the structural
-            // #685 checks.
-            const tomlErrors = validateWorkflowToml(tomlData, {
-                skipWorkflowIdentity: true,
-            });
-            if (tomlErrors.length > 0) {
-                error(formatWorkflowTomlErrors(options.fromFile, tomlErrors));
-                process.exit(1);
-            }
-            steps = tomlData.steps || [];
-        }
-        const client = new ApiClient();
-        try {
-            const config = await client.createWorkflowConfig(resolvedAppId, workflowId, {
-                configName: options.name,
-                description: options.description,
-                steps,
-            });
-            if (options.json) {
-                json(config);
-                return;
-            }
-            success(`Configuration created: ${config.configName}`);
-            keyValue("Config ID", config.configId);
-        }
-        catch (err) {
-            error(err.message);
-            process.exit(1);
-        }
-    });
-    // Update config
-    configs
-        .command("update")
-        .description("Update a configuration")
-        .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")
-        .option("--description <desc>", "Description")
-        .option("--from-file <path>", "Update steps from TOML file")
-        .option("--json", "Output as JSON")
-        .action(async (workflowId, configId, 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) {
-            let tomlData;
-            try {
-                const content = readFileSync(options.fromFile, "utf-8");
-                tomlData = parseConfigToml(content);
-            }
-            catch (err) {
-                error(`Failed to read TOML file: ${err.message}`);
-                process.exit(1);
-            }
-            // `configs update` is step-only — it consumes only `steps`, never the
-            // `[workflow]` identity fields — so skip the #1447 identity lint (a
-            // false positive here; codex round-2 finding 2) but keep the structural
-            // #685 checks.
-            const tomlErrors = validateWorkflowToml(tomlData, {
-                skipWorkflowIdentity: true,
-            });
-            if (tomlErrors.length > 0) {
-                error(formatWorkflowTomlErrors(options.fromFile, tomlErrors));
-                process.exit(1);
-            }
-            payload.steps = tomlData.steps || [];
-        }
-        if (Object.keys(payload).length === 0) {
-            error("No update options specified. Use --name, --description, or --from-file.");
-            process.exit(1);
-        }
-        const client = new ApiClient();
-        try {
-            const config = await client.updateWorkflowConfig(resolvedAppId, workflowId, configId, payload);
-            if (options.json) {
-                json(config);
-                return;
-            }
-            success("Configuration updated.");
-            keyValue("Config ID", config.configId);
-            keyValue("Name", config.configName);
-        }
-        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 or key")
-        .argument("<config-id>", "Configuration ID")
-        .option("--app <app-id>", "App ID (uses current app if not specified)")
-        .option("--json", "Output as JSON")
-        .action(async (workflowId, configId, options) => {
-        const resolvedAppId = resolveAppId(undefined, options);
-        const client = new ApiClient();
-        try {
-            const result = await client.activateWorkflowConfig(resolvedAppId, workflowId, configId);
-            if (options.json) {
-                json(result);
-                return;
-            }
-            success("Configuration activated.");
-            keyValue("Active Config ID", result.activeConfigId || configId);
-        }
-        catch (err) {
-            error(err.message);
-            process.exit(1);
-        }
-    });
-    // Duplicate config
-    configs
-        .command("duplicate")
-        .description("Duplicate a configuration")
-        .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")
-        .option("--json", "Output as JSON")
-        .action(async (workflowId, configId, options) => {
-        const resolvedAppId = resolveAppId(undefined, options);
-        const client = new ApiClient();
-        try {
-            const config = await client.duplicateWorkflowConfig(resolvedAppId, workflowId, configId, {
-                configName: options.name,
-            });
-            if (options.json) {
-                json(config);
-                return;
-            }
-            success(`Configuration duplicated: ${config.configName}`);
-            keyValue("New Config ID", config.configId);
-        }
-        catch (err) {
-            error(err.message);
-            process.exit(1);
-        }
-    });
-    // Archive config
-    configs
-        .command("archive")
-        .description("Archive a configuration")
-        .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")
-        .action(async (workflowId, configId, options) => {
-        const resolvedAppId = resolveAppId(undefined, options);
-        if (!options.yes) {
-            let confirm;
-            try {
-                confirm = await confirmPrompt(`Are you sure you want to archive configuration ${configId}?`);
-            }
-            catch (err) {
-                error(err.message);
-                process.exit(1);
-            }
-            if (!confirm) {
-                info("Cancelled.");
-                return;
-            }
-        }
-        const client = new ApiClient();
-        try {
-            await client.archiveWorkflowConfig(resolvedAppId, workflowId, configId);
-            success("Configuration archived.");
-        }
-        catch (err) {
-            error(err.message);
-            process.exit(1);
-        }
-    });
     // ============================================
     // TESTS SUBCOMMAND
     // ============================================
     const tests = workflows
         .command("tests")
-        .description("Manage and run workflow test cases")
+        .description("Run and inspect workflow test cases")
         .addHelpText("after", `
+Test cases are authored in TOML at workflows/<key>.tests/<name>.toml and applied
+with \`primitive config push\` (issue #2769); \`config fields workflow\` lists the
+fields. Deleting a case is removing its file and running \`config push --prune\`.
+
 Examples:
   $ primitive workflows tests list <workflow-id>
-  $ primitive workflows tests create <workflow-id> --name "Basic test" --vars '{"input":"hello"}'
   $ primitive workflows tests run <workflow-id> <test-case-id>
   $ 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")
@@ -2047,73 +1845,6 @@ Examples:
             process.exit(1);
         }
     });
-    // Create test case
-    tests
-        .command("create")
-        .description("Create a test case for a workflow")
-        .argument("<workflow-id>", "Workflow ID")
-        .option("--app <app-id>", "App ID (uses current app if not specified)")
-        .option("--name <name>", "Test case name (required)")
-        .option("--vars <json>", "Input variables as JSON (required)")
-        .option("--pattern <regex>", "Expected output pattern (regex)")
-        .option("--contains <json>", "Expected strings to contain (JSON array)")
-        .option("--json-subset <json>", "Expected JSON subset to match")
-        .option("--json", "Output as JSON")
-        .action(async (workflowId, options) => {
-        const resolvedAppId = resolveAppId(undefined, options);
-        if (!options.name || !options.vars) {
-            error("Required: --name and --vars");
-            process.exit(1);
-        }
-        let inputVariables;
-        try {
-            inputVariables = JSON.parse(options.vars);
-        }
-        catch {
-            error("Invalid JSON in --vars");
-            process.exit(1);
-        }
-        let expectedOutputContains;
-        if (options.contains) {
-            try {
-                expectedOutputContains = JSON.parse(options.contains);
-            }
-            catch {
-                error("Invalid JSON in --contains");
-                process.exit(1);
-            }
-        }
-        let expectedJsonSubset;
-        if (options.jsonSubset) {
-            try {
-                expectedJsonSubset = JSON.parse(options.jsonSubset);
-            }
-            catch {
-                error("Invalid JSON in --json-subset");
-                process.exit(1);
-            }
-        }
-        const client = new ApiClient();
-        try {
-            const result = await client.createTestCase(resolvedAppId, "workflow", workflowId, {
-                name: options.name,
-                inputVariables,
-                expectedOutputPattern: options.pattern,
-                expectedOutputContains,
-                expectedJsonSubset,
-            });
-            if (options.json) {
-                json(result);
-                return;
-            }
-            success(`Test case created: ${result.name}`);
-            keyValue("Test Case ID", result.testCaseId);
-        }
-        catch (err) {
-            error(err.message);
-            process.exit(1);
-        }
-    });
     // Get test case
     tests
         .command("get")
@@ -2181,118 +1912,6 @@ Examples:
             process.exit(1);
         }
     });
-    // Update test case
-    tests
-        .command("update")
-        .description("Update a test case")
-        .argument("<workflow-id>", "Workflow ID")
-        .argument("<test-case-id>", "Test Case ID")
-        .option("--app <app-id>", "App ID (uses current app if not specified)")
-        .option("--name <name>", "Test case name")
-        .option("--vars <json>", "Input variables as JSON")
-        .option("--pattern <regex>", "Expected output pattern (regex)")
-        .option("--contains <json>", "Expected strings to contain (JSON array)")
-        .option("--json-subset <json>", "Expected JSON subset to match")
-        .option("--clear-pattern", "Clear expected pattern")
-        .option("--clear-contains", "Clear expected contains")
-        .option("--clear-json-subset", "Clear expected JSON subset")
-        .option("--json", "Output as JSON")
-        .action(async (workflowId, testCaseId, options) => {
-        const resolvedAppId = resolveAppId(undefined, options);
-        const payload = {};
-        if (options.name)
-            payload.name = options.name;
-        if (options.vars) {
-            try {
-                payload.inputVariables = JSON.parse(options.vars);
-            }
-            catch {
-                error("Invalid JSON in --vars");
-                process.exit(1);
-            }
-        }
-        if (options.clearPattern) {
-            payload.expectedOutputPattern = null;
-        }
-        else if (options.pattern) {
-            payload.expectedOutputPattern = options.pattern;
-        }
-        if (options.clearContains) {
-            payload.expectedOutputContains = null;
-        }
-        else if (options.contains) {
-            try {
-                payload.expectedOutputContains = JSON.parse(options.contains);
-            }
-            catch {
-                error("Invalid JSON in --contains");
-                process.exit(1);
-            }
-        }
-        if (options.clearJsonSubset) {
-            payload.expectedJsonSubset = null;
-        }
-        else if (options.jsonSubset) {
-            try {
-                payload.expectedJsonSubset = JSON.parse(options.jsonSubset);
-            }
-            catch {
-                error("Invalid JSON in --json-subset");
-                process.exit(1);
-            }
-        }
-        if (Object.keys(payload).length === 0) {
-            error("No update options specified.");
-            process.exit(1);
-        }
-        const client = new ApiClient();
-        try {
-            const result = await client.updateTestCase(resolvedAppId, "workflow", workflowId, testCaseId, payload);
-            if (options.json) {
-                json(result);
-                return;
-            }
-            success("Test case updated.");
-        }
-        catch (err) {
-            error(err.message);
-            process.exit(1);
-        }
-    });
-    // Delete test case
-    tests
-        .command("delete")
-        .description("Delete a test case")
-        .argument("<workflow-id>", "Workflow ID")
-        .argument("<test-case-id>", "Test Case ID")
-        .option("--app <app-id>", "App ID (uses current app if not specified)")
-        .option("-y, --yes", "Skip confirmation prompt")
-        .action(async (workflowId, testCaseId, options) => {
-        const resolvedAppId = resolveAppId(undefined, options);
-        if (!options.yes) {
-            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;
-            }
-        }
-        const client = new ApiClient();
-        try {
-            await client.deleteTestCase(resolvedAppId, "workflow", workflowId, testCaseId);
-            success("Test case deleted.");
-        }
-        catch (err) {
-            error(err.message);
-            process.exit(1);
-        }
-    });
     // Run a single test case
     tests
         .command("run")
@@ -2547,12 +2166,20 @@ 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();
+                // #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.
-                    progress(`  Completed: ${result.completed}/${result.results?.length || 0}  `);
-                }
+                    onValue: (r) => progress(`  Completed: ${r.completed}/${r.results?.length || 0}  `),
+                });
                 progressEnd();
             }
             if (options.json) {
@@ -2644,13 +2271,15 @@ Examples:
     // ============================================
     const attachments = tests
         .command("attachments")
-        .description("Manage test case file attachments")
+        .description("Inspect test case file attachments")
         .addHelpText("after", `
+Attachments are authored as files in workflows/<key>.tests/<name>/ and applied
+with \`primitive config push\` (#2769); removing one and running
+\`config push --prune\` deletes it server-side. These verbs read server state.
+
 Examples:
   $ primitive workflows tests attachments list <workflow-id> <test-case-id>
-  $ primitive workflows tests attachments upload <workflow-id> <test-case-id> ./document.pdf
   $ primitive workflows tests attachments download <workflow-id> <test-case-id> document.pdf
-  $ primitive workflows tests attachments delete <workflow-id> <test-case-id> document.pdf
 `);
     // List attachments
     attachments
@@ -2688,49 +2317,6 @@ Examples:
             process.exit(1);
         }
     });
-    // Upload attachment
-    attachments
-        .command("upload")
-        .description("Upload a file attachment to a test case")
-        .argument("<workflow-id>", "Workflow ID")
-        .argument("<test-case-id>", "Test Case ID")
-        .argument("<file-path>", "Path to the file to upload")
-        .option("--app <app-id>", "App ID (uses current app if not specified)")
-        .option("--name <name>", "Override the filename")
-        .option("--json", "Output as JSON")
-        .action(async (workflowId, testCaseId, filePath, options) => {
-        const resolvedAppId = resolveAppId(undefined, options);
-        const client = new ApiClient();
-        try {
-            // Check file exists and get stats
-            const stats = statSync(filePath);
-            if (!stats.isFile()) {
-                error(`Not a file: ${filePath}`);
-                process.exit(1);
-            }
-            // Check file size (10 MB limit)
-            const TEN_MB = 10 * 1024 * 1024;
-            if (stats.size > TEN_MB) {
-                error(`File too large (max 10MB): ${formatFileSize(stats.size)}`);
-                process.exit(1);
-            }
-            const filename = options.name || basename(filePath);
-            const data = readFileSync(filePath);
-            const contentType = mimeLookup(filePath) || "application/octet-stream";
-            const result = await client.uploadTestCaseAttachment(resolvedAppId, "workflow", workflowId, testCaseId, filename, data, contentType);
-            if (options.json) {
-                json(result);
-                return;
-            }
-            success(`Uploaded: ${filename}`);
-            keyValue("Size", formatFileSize(result.attachment.size));
-            keyValue("Type", result.attachment.contentType);
-        }
-        catch (err) {
-            error(err.message);
-            process.exit(1);
-        }
-    });
     // Download attachment
     attachments
         .command("download")
@@ -2756,41 +2342,6 @@ Examples:
             process.exit(1);
         }
     });
-    // Delete attachment
-    attachments
-        .command("delete")
-        .description("Delete a file attachment from a test case")
-        .argument("<workflow-id>", "Workflow ID")
-        .argument("<test-case-id>", "Test Case ID")
-        .argument("<filename>", "Name of the file to delete")
-        .option("--app <app-id>", "App ID (uses current app if not specified)")
-        .option("-y, --yes", "Skip confirmation prompt")
-        .action(async (workflowId, testCaseId, filename, options) => {
-        const resolvedAppId = resolveAppId(undefined, options);
-        if (!options.yes) {
-            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;
-            }
-        }
-        const client = new ApiClient();
-        try {
-            await client.deleteTestCaseAttachment(resolvedAppId, "workflow", workflowId, testCaseId, filename);
-            success(`Deleted: ${filename}`);
-        }
-        catch (err) {
-            error(err.message);
-            process.exit(1);
-        }
-    });
     // ============================================
     // Codegen command (issue #1442)
     // ============================================
@@ -2799,8 +2350,9 @@ Examples:
         .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("--dir <path>", "Config directory (overrides the auto-resolved per-env path)")
+        .addOption(new Option("--sync-dir <path>", "Deprecated alias of --dir").hideHelp())
+        .option("-o, --output <dir>", "Output directory for the generated files (defaults to <config-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")
@@ -2814,13 +2366,16 @@ Examples:
                 process.exit(1);
             }
             // 1. Resolve the single source workflows/ directory via the shared
-            //    active-environment resolver (issue #1510). Honors --sync-dir /
+            //    active-environment resolver (issue #1510). Honors --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 },
+                options: {
+                    app: options.app,
+                    syncDir: resolveSyncDirOverride(options, "workflows codegen"),
+                },
             });
             // 2. Collect the source .toml files (one per workflow), filtered to a
             //    single workflow when an argument is given. Match on the file stem;
@@ -2878,9 +2433,20 @@ Examples:
                         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.");
+                        // Echo back the options that decide WHERE and WHAT was
+                        // checked. Suggesting a bare `workflows codegen` after a
+                        // `--check -o <dir>` sent people to regenerate into the
+                        // default <config-dir>/workflows/generated/ instead of the
+                        // directory that is actually out of date, so the files stayed
+                        // stale and the next check failed the same way.
+                        const regenerate = ["primitive workflows codegen"];
+                        if (workflowKey)
+                            regenerate.push(workflowKey);
+                        if (lang === "swift")
+                            regenerate.push("--lang swift");
+                        if (options.output)
+                            regenerate.push(`-o ${options.output}`);
+                        info(`Run \`${regenerate.join(" ")}\` to regenerate.`);
                     }
                     process.exit(1);
                 }