@sanity/workflow-cli 0.11.0 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # @sanity/workflow-cli
 
+## 0.12.0
+
+### Minor Changes
+
+- e3a7ba2: `start` gains `--instance-id` — for retries: the id is the start's idempotency key, so passing the id of a start that failed partway resumes it instead of creating a duplicate (an already-settled start replays as a no-op). A start whose first auto-advance fails after the instance was created and primed (`StartNotSettledError`) now reports as STARTED with the cause and the retry id — a warn, not the "Start rejected" failure path — and the `--json` payload carries `{instanceId, notSettled: true, detail}`. A start that fails before priming (`StartNotPrimedError`) still fails, with the `--instance-id` retry hint appended so the operator can resume instead of duplicating.
+- a8ace4d: New `nuke --tag <tag>` command — the dev-period big red button that deletes every engine-owned document for a deployment tag: instances, definitions, and guard docs (matched by instance-id prefix, so guards orphaned by earlier partial deletions are swept too) across the deployment's workflow resource and every alias-bound resource. Content documents are never touched. The command always prints a per-dataset dry-run plan, then requires typing back every involved `project.dataset` target; `--force` skips the prompt for scripts/CI (the plan still prints). Unlike `definition delete` (the governed lifecycle path), `nuke` deletes raw docs without reading them, so it works on pre-amendment shapes a newer engine can no longer read — the sanctioned reset while the versioned upgrade framework doesn't exist.
+- 5a1a9fe: Direct reads of engine-owned documents adopt the data-model gate (`assertReadableModel`): the CLI's instance and definition reads (`show`, `tail`, `list`, `definition show`, `definition list`, deploy lookups, the share read-back) and the MCP tools that interpret rows from the ungated `engine.query` escape hatch (`list_workflow_definitions`, `list_workflow_instances`, the definition lookup behind `start_workflow` / `get_workflow_definition`). A document written by a newer engine data model now fails with the governed "upgrade `@sanity/workflow-engine`" error instead of rendering unchecked; list projections carry the stamp pair so projected rows gate too.
+
+### Patch Changes
+
+- 092a0d4: **BREAKING:** runtime-supplied refs written into field state are gated on the deployment's declared resource surface.
+  - A `doc.ref` / `doc.refs` / `release.ref` value a caller or effect handler supplies — start `initialFields` input, an action's param-sourced op values, `editField` values, effect-completion ops — must target a declared resource: the `workflowResource` itself or a resource the `resourceClients` resolver serves. An off-surface ref throws the new `RefResourceUndeclaredError` and the commit aborts, instead of writing cleanly and failing later when something dereferences it. The check is advisory like every engine check; stored documents are unchanged.
+  - Definition-authored refs are exempt: literal `initialValue` seeds, `type: 'query'` texts, spawn `with` projections, and op values that bind no action param were validated (and alias-expanded) at deploy, so they materialize into field state without re-checking.
+  - Resource aliases stay a deploy-time abstraction: `deployDefinitions({definitions, resourceAliases?})` expands every `@<alias>:` reference to its physical GDR before fingerprinting, and nothing alias-shaped survives past deploy — the runtime holds no alias map, and an alias-shaped ref supplied to a runtime verb is rejected as malformed like any other non-GDR string.
+  - `createBench` takes `serveResources` (dataset siblings served — and thereby declared — straight from the bench's own store) plus a raw `resourceClients` resolver for anything beyond same-store siblings. The engine also exports `sameResource` alongside the existing GDR helpers.
+  - The CLI wires no `resourceClients`, so refs supplied at runtime through it (`start --field`, `fire-action` ref params) admit the workflow resource only.
+
+- Updated dependencies [f9389e5]
+- Updated dependencies [d0c62ea]
+- Updated dependencies [c3eed2e]
+- Updated dependencies [df4bd80]
+- Updated dependencies [092a0d4]
+- Updated dependencies [5a1a9fe]
+- Updated dependencies [e3a7ba2]
+- Updated dependencies [30fed9e]
+- Updated dependencies [1321ba5]
+- Updated dependencies [e683875]
+- Updated dependencies [a8ace4d]
+  - @sanity/workflow-engine@0.17.0
+
 ## 0.11.0
 
 ### Minor Changes

package/README.md

@@ -74,11 +74,20 @@ config fails with a clean, path-prefixed error before the command runs.
 `resourceAliases` is only for content that lives in a _different_ resource from
 `workflowResource`. A definition can reference a document in the **same**
 resource by bare id, no alias needed — bare ids root at `workflowResource` at
-runtime. Rule of thumb: **different resource → bind an alias and reference it as
-`@<handle>:<id>`; same resource → use a bare id and omit `resourceAliases`
+runtime. Bindings exist at deploy time only: `deploy` expands each `@<handle>:`
+reference to its bound physical GDR, and nothing alias-shaped survives into the
+deployed definition or the runtime. Rule of thumb: **different resource →
+bind an alias; same resource → use a bare id and omit `resourceAliases`
 entirely.** So the simplest single-dataset setup is just a `workflowResource`
 and `definitions`, with no `resourceAliases` at all.
 
+Refs supplied at runtime (`start --field`, `fire-action` ref params) are gated
+separately: they may target the `workflowResource` itself, and anything else is
+rejected at the write with `RefResourceUndeclaredError`. The CLI wires no
+`resourceClients` resolver, so it has no way to widen that surface — a runtime
+foreign-resource ref goes through an engine consumer that serves the target
+resource, not through the CLI.
+
 | Var                 | Purpose                                                                                              |
 | ------------------- | ---------------------------------------------------------------------------------------------------- |
 | `SANITY_AUTH_TOKEN` | Explicit token for CI / scripted use — wins over the `sanity login` session (editor role for writes) |
@@ -118,25 +127,26 @@ stale compiled output.
 
 ## Command status
 
-| Command                                | Status                                                                                                                      |
-| -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
-| `deploy`                               | wired — calls `workflow.deployDefinitions` over the selected deployment's definitions                                       |
-| `deploy --all-tags`                    | wired — deploys every deployment in the config, continuing past per-deployment failures                                     |
-| `deploy --check`                       | wired — runs `validateDefinition` over the local batch + a duplicate-name check                                             |
-| `deploy --dry-run`                     | wired — fetches existing docs and renders a coloured JSON diff per change                                                   |
-| `deploy --only <name>`                 | wired — filters deploy/check/dry-run to one definition by `name`                                                            |
-| `start <name>`                         | wired — calls `workflow.startInstance` (`--field` for input fields)                                                         |
-| `list`                                 | wired — `client.fetch` over `sanity.workflow.instance` documents (`--definition <name>` to filter)                          |
-| `show <instance-id>`                   | wired — `client.getDocument`                                                                                                |
-| `diagnose <instance-id>`               | wired — calls `workflow.diagnose`, classifies why the instance is/isn't progressing                                         |
-| `tail <instance-id>`                   | wired — `client.listen()` over the instance, prints new history entries                                                     |
-| `abort <instance-id>`                  | wired — calls `workflow.abortInstance` (hard stop: cancels pending effects, lifts guards)                                   |
-| `set-stage <instance-id> --to <stage>` | wired — calls `workflow.setStage` (admin override: skips declared transitions/filters; enter lifecycle + cascade still run) |
-| `fire-action <instance-id>`            | wired — `workflow.availableActions` lists actions; `workflow.fireAction` fires one                                          |
-| `definition list`                      | wired — `client.fetch` over `sanity.workflow.definition` documents                                                          |
-| `definition show <name>`               | wired — `client.fetch`, latest version unless `--version`                                                                   |
-| `definition diff <name>`               | wired — diffs the in-code definition against the deployed latest (`--version` to pin)                                       |
-| `definition delete <name>`             | wired — calls `workflow.deleteDefinition` (refuses on live instances unless `--cascade`)                                    |
+| Command                                | Status                                                                                                                                                                                           |
+| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `deploy`                               | wired — calls `workflow.deployDefinitions` over the selected deployment's definitions                                                                                                            |
+| `deploy --all-tags`                    | wired — deploys every deployment in the config, continuing past per-deployment failures                                                                                                          |
+| `deploy --check`                       | wired — runs `validateDefinition` over the local batch + a duplicate-name check                                                                                                                  |
+| `deploy --dry-run`                     | wired — fetches existing docs and renders a coloured JSON diff per change                                                                                                                        |
+| `deploy --only <name>`                 | wired — filters deploy/check/dry-run to one definition by `name`                                                                                                                                 |
+| `start <name>`                         | wired — calls `workflow.startInstance` (`--field` for input fields)                                                                                                                              |
+| `list`                                 | wired — `client.fetch` over `sanity.workflow.instance` documents (`--definition <name>` to filter)                                                                                               |
+| `show <instance-id>`                   | wired — `client.getDocument`                                                                                                                                                                     |
+| `diagnose <instance-id>`               | wired — calls `workflow.diagnose`, classifies why the instance is/isn't progressing                                                                                                              |
+| `tail <instance-id>`                   | wired — `client.listen()` over the instance, prints new history entries                                                                                                                          |
+| `abort <instance-id>`                  | wired — calls `workflow.abortInstance` (hard stop: cancels pending effects, lifts guards)                                                                                                        |
+| `set-stage <instance-id> --to <stage>` | wired — calls `workflow.setStage` (admin override: skips declared transitions/filters; enter lifecycle + cascade still run)                                                                      |
+| `fire-action <instance-id>`            | wired — `workflow.availableActions` lists actions; `workflow.fireAction` fires one                                                                                                               |
+| `definition list`                      | wired — `client.fetch` over `sanity.workflow.definition` documents                                                                                                                               |
+| `definition show <name>`               | wired — `client.fetch`, latest version unless `--version`                                                                                                                                        |
+| `definition diff <name>`               | wired — diffs the in-code definition against the deployed latest (`--version` to pin)                                                                                                            |
+| `definition delete <name>`             | wired — calls `workflow.deleteDefinition` (refuses on live instances unless `--cascade`)                                                                                                         |
+| `nuke --tag <tag>`                     | wired — dev-period reset (exists only until the versioned upgrade framework): deletes every engine-owned doc for the tag (instances, definitions, guards across resources); plan + typed confirm |
 
 ## Telemetry
 

package/dist/commands/definition/list.d.ts

@@ -5,6 +5,7 @@ interface DefinitionListFlags {
     limit: number;
 }
 export interface DefinitionListRow {
+    _id: string;
     name: string;
     version: number;
     title: string;
@@ -13,6 +14,8 @@ export interface DefinitionListRow {
     inFlightCount: number;
     totalInstances: number;
     _createdAt: string;
+    modelVersion?: number | null;
+    minReaderModel?: number | null;
 }
 export declare function buildDefinitionListQuery(flags: DefinitionListFlags): {
     groq: string;

package/dist/commands/definition/list.js

@@ -1,5 +1,5 @@
 import { Flags } from '@oclif/core';
-import { WORKFLOW_DEFINITION_TYPE, WORKFLOW_INSTANCE_TYPE, inFlightFilter, tagScopeFilter, } from '@sanity/workflow-engine';
+import { WORKFLOW_DEFINITION_TYPE, WORKFLOW_INSTANCE_TYPE, assertReadableModel, inFlightFilter, tagScopeFilter, } from '@sanity/workflow-engine';
 import logSymbols from 'log-symbols';
 import { WorkflowCommand } from "../../lib/base-command.js";
 import { resolveReadTargets } from "../../lib/context.js";
@@ -25,11 +25,14 @@ export function buildDefinitionListQuery(flags) {
     }
     const instanceMatch = instanceFilters.join(' && ');
     const groq = `*[${filters.join(' && ')}] | order(name asc, version desc) [0...$limit]{
+      _id,
       name,
       version,
       title,
       tag,
       _createdAt,
+      modelVersion,
+      minReaderModel,
       "stageCount": count(stages),
       "inFlightCount": count(*[${instanceMatch} && ${inFlightFilter()}]),
       "totalInstances": count(*[${instanceMatch}])
@@ -60,9 +63,9 @@ export default class DefinitionList extends WorkflowCommand {
             targets,
             log: (line) => this.log(line),
             run: async ({ client }) => {
-                const fetched = await client.fetch(groq, params, {
+                const fetched = (await client.fetch(groq, params, {
                     tag: 'definition.list',
-                });
+                })).map(assertReadableModel);
                 if (!fetched.length) {
                     this.log(`${logSymbols.info} no definitions found`);
                     return;

package/dist/commands/definition/show.js

@@ -1,6 +1,6 @@
 import { styleText } from 'node:util';
 import { Args, Flags } from '@oclif/core';
-import { isTerminalStage, } from '@sanity/workflow-engine';
+import { assertReadableModel, isTerminalStage, } from '@sanity/workflow-engine';
 import logSymbols from 'log-symbols';
 import { WorkflowCommand } from "../../lib/base-command.js";
 import { resolveReadTargets, soleHitOrFail } from "../../lib/context.js";
@@ -64,7 +64,7 @@ export async function fetchDefinitionHits({ targets, groq, params, }) {
         const def = await target.client.fetch(groq, params, {
             tag: 'definition.show',
         });
-        return def === null ? undefined : { resource: target.resource, def };
+        return def === null ? undefined : { resource: target.resource, def: assertReadableModel(def) };
     }));
     return probes.filter((hit) => hit !== undefined);
 }

package/dist/commands/list.d.ts

@@ -8,6 +8,8 @@ interface InstanceRow {
     completedAt?: string | null;
     abortedAt?: string | null;
     lastChangedAt: string;
+    modelVersion?: number | null;
+    minReaderModel?: number | null;
 }
 interface ListFlags {
     'include-completed': boolean;

package/dist/commands/list.js

@@ -1,5 +1,5 @@
 import { Flags } from '@oclif/core';
-import { WORKFLOW_INSTANCE_TYPE, documentPrefilter, inFlightFilter, instanceWatchesDocument, tagScopeFilter, terminalState, } from '@sanity/workflow-engine';
+import { WORKFLOW_INSTANCE_TYPE, assertReadableModel, documentPrefilter, inFlightFilter, instanceWatchesDocument, tagScopeFilter, terminalState, } from '@sanity/workflow-engine';
 import logSymbols from 'log-symbols';
 import { WorkflowCommand } from "../lib/base-command.js";
 import { resolveReadTargets } from "../lib/context.js";
@@ -36,7 +36,9 @@ export function buildListQuery(flags) {
       currentStage,
       completedAt,
       abortedAt,
-      lastChangedAt
+      lastChangedAt,
+      modelVersion,
+      minReaderModel
     }`;
     return { groq, params };
 }
@@ -125,8 +127,11 @@ export default class List extends WorkflowCommand {
 }
 async function fetchRows({ client, groq, params, document, }) {
     if (document === undefined) {
-        return client.fetch(groq, params, { tag: 'list' });
+        const rows = await client.fetch(groq, params, { tag: 'list' });
+        return rows.map(assertReadableModel);
     }
     const candidates = await client.fetch(groq, params, { tag: 'list' });
-    return candidates.filter((instance) => instanceWatchesDocument(instance, document));
+    return candidates
+        .map(assertReadableModel)
+        .filter((instance) => instanceWatchesDocument(instance, document));
 }

package/dist/commands/nuke.d.ts

@@ -0,0 +1,11 @@
+import { WorkflowCommand } from '../lib/base-command.ts';
+export default class Nuke extends WorkflowCommand {
+    static summary: string;
+    static description: string;
+    static examples: string[];
+    static flags: {
+        tag: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        force: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/nuke.js

@@ -0,0 +1,76 @@
+import { Flags } from '@oclif/core';
+import { input } from '@sanity/cli-core/ux';
+import { resourceGdr } from '@sanity/workflow-engine';
+import logSymbols from 'log-symbols';
+import { WorkflowCommand } from "../lib/base-command.js";
+import { clientFor, resolveApiHost, resolveTokenOrFail } from "../lib/client.js";
+import { dedupeResources } from "../lib/context.js";
+import { fail } from "../lib/fail.js";
+import { loadWorkflowConfig } from "../lib/load-config.js";
+import { confirmationMatches, executeNuke, formatNukeSummary, involvedTargets, planCounts, renderNukePlan, resolveNukePlan, } from "../lib/nuke.js";
+import { runWriteVerb } from "../lib/ops-report.js";
+import { canPromptOnStderr } from "../lib/prompt.js";
+import { selectDeployment } from "../lib/select-deployment.js";
+export default class Nuke extends WorkflowCommand {
+    static summary = 'Delete every engine-owned document for a deployment tag — the dev-period big red button.';
+    static description = 'The reset for a dataset holding engine documents the versioned upgrade framework cannot yet ' +
+        "migrate: deletes the tag's instances, definitions, and guards (across every alias-bound " +
+        'resource). Content documents are never touched. Prints a dry-run plan, then requires you to ' +
+        'type back every involved dataset (--force skips the prompt; the plan still prints).';
+    static examples = [
+        '<%= config.bin %> nuke --tag plugin-dev',
+        '<%= config.bin %> nuke --tag plugin-dev --force',
+    ];
+    static flags = {
+        tag: Flags.string({
+            description: 'The deployment tag to reset. Required — a destructive reset never guesses the environment.',
+            required: true,
+        }),
+        force: Flags.boolean({
+            description: 'Skip the confirmation prompt (for scripts/CI). The plan still prints.',
+            default: false,
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(Nuke);
+        const config = await loadWorkflowConfig();
+        const deployment = selectDeployment(config, { tag: flags.tag });
+        const targets = buildTargets(deployment, await resolveTokenOrFail());
+        const plan = await resolveNukePlan({ tag: deployment.tag, targets });
+        const apiHost = resolveApiHost() ?? 'https://api.sanity.io (production default)';
+        renderNukePlan(plan, apiHost).forEach((line) => this.log(line));
+        const counts = planCounts(plan);
+        if (counts.total === 0) {
+            this.log(`${logSymbols.info} Nothing to nuke for tag "${deployment.tag}".`);
+            return;
+        }
+        if (!flags.force)
+            await confirmOrFail(involvedTargets(plan));
+        await runWriteVerb({
+            startLabel: 'Nuking…',
+            failLabel: 'Nuke failed',
+            failHeadline: 'workflow nuke error:',
+            run: () => executeNuke(plan),
+            report: () => ({ changed: true, message: formatNukeSummary(deployment.tag, counts) }),
+            log: (line) => this.log(line),
+        });
+    }
+}
+function buildTargets(deployment, token) {
+    const engineResource = deployment.workflowResource;
+    const aliasResources = (deployment.resourceAliases ?? []).map((binding) => binding.resource);
+    return dedupeResources([engineResource, ...aliasResources]).map((resource) => ({
+        resource,
+        client: clientFor(resource, token),
+        holdsEngineDocs: resourceGdr(resource) === resourceGdr(engineResource),
+    }));
+}
+async function confirmOrFail(targets) {
+    if (!canPromptOnStderr()) {
+        fail('Refusing to nuke without confirmation in a non-interactive shell.', 'Re-run with --force to skip the prompt.');
+    }
+    const answer = await input({ message: `Type every target to confirm deletion (space-separated):\n  ${targets.join(' ')}\n` }, { output: process.stderr });
+    if (!confirmationMatches(answer, targets)) {
+        fail('Confirmation did not match — nothing was deleted.', `Expected: ${targets.join(' ')}`);
+    }
+}

package/dist/commands/start.d.ts

@@ -1,4 +1,4 @@
-import { type InitialFieldValue, type StartInstanceArgs, type WorkflowInstance } from '@sanity/workflow-engine';
+import { StartNotSettledError, type InitialFieldValue, type StartInstanceArgs, type WorkflowInstance } from '@sanity/workflow-engine';
 import { WorkflowCommand } from '../lib/base-command.ts';
 import { type EngineScope } from '../lib/operation-args.ts';
 export default class Start extends WorkflowCommand {
@@ -11,20 +11,35 @@ export default class Start extends WorkflowCommand {
         json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         version: import("@oclif/core/interfaces").OptionFlag<number | undefined, import("@oclif/core/interfaces").CustomOptions>;
         field: import("@oclif/core/interfaces").OptionFlag<string[], import("@oclif/core/interfaces").CustomOptions>;
+        'instance-id': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         tag: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
     };
     run(): Promise<void>;
 }
+/** A created-but-unprimed failure is resumable — the engine message names
+ *  the id and the generic remediation; operators need the CLI's own retry
+ *  spelling appended. Every other error passes through untouched. */
+export declare function withRetryHint(error: unknown): unknown;
+/** The spinner message for a start whose first cascade failed after the
+ *  instance was created and primed: the run exists — say so, name the cause,
+ *  and point at the retry rail instead of reporting a rejection. */
+export declare function startNotSettledReport(error: StartNotSettledError): string;
+/** The `--json` payload for a not-settled start — same `instanceId` key as
+ *  the success payload so scripts can pick up the retry id either way. */
+export declare function startNotSettledJson(error: StartNotSettledError): Record<string, unknown>;
 /**
  * The shared engine args ({@link baseEngineArgs}) plus the start-specific
  * fields. Optionals spread conditionally because the engine's optional args
  * reject an explicit `undefined` under `exactOptionalPropertyTypes`.
  */
-export declare function buildStartArgs({ scope, name, version, initialFields, }: {
+export declare function buildStartArgs({ scope, name, version, initialFields, instanceId, }: {
     scope: EngineScope;
     name: string;
     version: number | undefined;
     initialFields: InitialFieldValue[];
+    /** The start's idempotency key (`--instance-id`) — a retry carrying it
+     *  resumes the earlier attempt instead of creating a duplicate. */
+    instanceId?: string | undefined;
 }): StartInstanceArgs & EngineScope;
 /** The success spinner message. Pure so the in-flight / immediately-terminal
  *  permutations can be asserted without driving a real start. */

package/dist/commands/start.js

@@ -1,6 +1,6 @@
 import { styleText } from 'node:util';
 import { Args, Flags } from '@oclif/core';
-import { buildInitialFields, startRefusal, workflow, } from '@sanity/workflow-engine';
+import { buildInitialFields, errorMessage, StartNotPrimedError, StartNotSettledError, startRefusal, workflow, } from '@sanity/workflow-engine';
 import { WorkflowCommand } from "../lib/base-command.js";
 import { resolveContext } from "../lib/context.js";
 import { fetchDeployedDefinition } from "../lib/definitions.js";
@@ -16,6 +16,7 @@ export default class Start extends WorkflowCommand {
         '<%= config.bin %> start productLaunch',
         '<%= config.bin %> start article-review --field subject=\'{"id":"dataset:proj:ds:article-1","type":"article"}\'',
         '<%= config.bin %> start productLaunch --version 2 --tag prod',
+        '<%= config.bin %> start productLaunch --instance-id prod.wf-instance.a1b2c3d4e5f6',
     ];
     static args = {
         name: Args.string({ required: true, description: 'Workflow definition name.' }),
@@ -32,6 +33,12 @@ export default class Start extends WorkflowCommand {
             multiple: true,
             default: [],
         }),
+        'instance-id': Flags.string({
+            description: "Start under this instance id — for retries. The id is the start's idempotency key: " +
+                'pass the id of a start that failed partway and the engine resumes it instead of ' +
+                'creating a duplicate (an already-settled start replays as a no-op). Omit to mint ' +
+                'a fresh id.',
+        }),
         ...jsonFlags,
     };
     async run() {
@@ -52,25 +59,58 @@ export default class Start extends WorkflowCommand {
                 name: args.name,
                 version: flags.version,
                 initialFields,
+                instanceId: flags['instance-id'],
             }),
         };
         if (flags.json) {
-            const result = await workflow
-                .startInstance(startArgs)
-                .catch((error) => fail('start error:', failureDetail(error)));
-            this.log(JSON.stringify(startResultJson(result.instance), null, 2));
+            const result = await workflow.startInstance(startArgs).catch((error) => {
+                if (error instanceof StartNotSettledError) {
+                    this.log(JSON.stringify(startNotSettledJson(error), null, 2));
+                    return undefined;
+                }
+                fail('start error:', failureDetail(withRetryHint(error)));
+            });
+            if (result !== undefined) {
+                this.log(JSON.stringify(startResultJson(result.instance), null, 2));
+            }
             return;
         }
         await runWriteVerb({
             startLabel: `Starting ${args.name}…`,
             failLabel: 'Start rejected',
             failHeadline: 'start error:',
-            run: () => workflow.startInstance(startArgs),
-            report: (result) => ({ changed: true, message: startReport(result.instance) }),
+            run: () => workflow.startInstance(startArgs).catch((error) => {
+                if (error instanceof StartNotSettledError)
+                    return error;
+                throw withRetryHint(error);
+            }),
+            report: (result) => result instanceof StartNotSettledError
+                ? { changed: false, message: startNotSettledReport(result) }
+                : { changed: true, message: startReport(result.instance) },
             log: (line) => this.log(line),
         });
     }
 }
+export function withRetryHint(error) {
+    return error instanceof StartNotPrimedError
+        ? new Error(`${errorMessage(error)} (--instance-id ${error.instanceId})`)
+        : error;
+}
+export function startNotSettledReport(error) {
+    const id = styleText('bold', error.instanceId);
+    return (`Started ${id} — but its first auto-advance failed: ${errorMessage(error.cause)}. ` +
+        `It settles on the next tick, or retry with --instance-id ${error.instanceId}.`);
+}
+export function startNotSettledJson(error) {
+    return {
+        instanceId: error.instanceId,
+        notSettled: true,
+        detail: errorMessage(error.cause),
+        ...(error.instance !== undefined
+            ? { currentStage: error.instance.currentStage, definition: error.instance.definition }
+            : {}),
+    };
+}
 async function resolveStartInputs({ client, name, tag, version, values, }) {
     const deployed = await fetchDeployedDefinition({ client, name, tag, version });
     if (deployed === undefined) {
@@ -82,12 +122,13 @@ async function resolveStartInputs({ client, name, tag, version, values, }) {
     }
     return failOnThrow('start usage error:', () => buildInitialFields({ declared: deployed.fields ?? [], values }));
 }
-export function buildStartArgs({ scope, name, version, initialFields, }) {
+export function buildStartArgs({ scope, name, version, initialFields, instanceId, }) {
     return {
         ...baseEngineArgs(scope),
         definition: name,
         ...(version !== undefined ? { version } : {}),
         ...(initialFields.length > 0 ? { initialFields } : {}),
+        ...(instanceId !== undefined ? { instanceId } : {}),
     };
 }
 export function startReport(instance) {

package/dist/commands/tail.js

@@ -1,6 +1,6 @@
 import { styleText } from 'node:util';
 import { Args } from '@oclif/core';
-import { displayTitle, errorMessage } from '@sanity/workflow-engine';
+import { assertReadableModel, displayTitle, errorMessage, } from '@sanity/workflow-engine';
 import logSymbols from 'log-symbols';
 import { WorkflowCommand } from "../lib/base-command.js";
 import { findInstance, resolveReadTargets } from "../lib/context.js";
@@ -64,9 +64,10 @@ export default class Tail extends WorkflowCommand {
         });
     }
     async printNewEntries({ client, instanceId, seen, }) {
-        const next = await client.getDocument(instanceId, { tag: TAIL_TAG });
-        if (!next)
+        const raw = await client.getDocument(instanceId, { tag: TAIL_TAG });
+        if (!raw)
             return seen;
+        const next = assertReadableModel(raw);
         const newEntries = next.history.slice(seen);
         for (const entry of newEntries) {
             this.log(`${styleText('dim', `[${formatTimestamp(entry.at)}]`)} ${styleText('cyan', displayTitle(entry._type))}`);

package/dist/lib/client.d.ts

@@ -1,5 +1,13 @@
 import { type SanityClient } from '@sanity/client';
 import { type WorkflowResource } from '@sanity/workflow-engine';
+/**
+ * The API host to hit: an explicit `SANITY_API_HOST` wins; otherwise mirror
+ * the Sanity CLI — staging routes to the staging API, prod falls through to
+ * `@sanity/client`'s default (`undefined` here). Pairs with
+ * {@link resolveToken}, which reads the matching session token. Exported so a
+ * destructive command can display the environment its clients will hit.
+ */
+export declare function resolveApiHost(): string | undefined;
 /**
  * Resolve the Sanity auth token. An explicit `SANITY_AUTH_TOKEN` wins (CI /
  * scripted use); otherwise fall back to the `sanity login` session token.

package/dist/lib/client.js

@@ -5,7 +5,7 @@ import { ENV, envAuthToken } from "./env.js";
 import { fail } from "./fail.js";
 const API_VERSION = ENGINE_API_VERSION;
 const STAGING_API_HOST = 'https://api.sanity.work';
-function resolveApiHost() {
+export function resolveApiHost() {
     return process.env[ENV.SANITY_API_HOST] ?? (isStaging() ? STAGING_API_HOST : undefined);
 }
 export async function resolveToken() {

package/dist/lib/context.d.ts

@@ -1,5 +1,5 @@
 import type { SanityClient } from '@sanity/client';
-import type { WorkflowConfig, WorkflowDeployment, WorkflowInstance, WorkflowResource } from '@sanity/workflow-engine';
+import { type WorkflowConfig, type WorkflowDeployment, type WorkflowInstance, type WorkflowResource } from '@sanity/workflow-engine';
 import type { EngineScope } from './operation-args.ts';
 export interface DeploymentContext {
     deployment: WorkflowDeployment;
@@ -40,9 +40,13 @@ export interface ReadTarget {
 export declare function resolveReadTargets(flags: {
     tag?: string | undefined;
 }): Promise<ReadTarget[]>;
+/** Distinct resources, keyed by their resource-shaped GDR (`<type>:<id>`).
+ *  The first occurrence wins its position, so a caller-ordered list (e.g. the
+ *  engine resource first) keeps its lead entry. */
+export declare function dedupeResources(resources: WorkflowResource[]): WorkflowResource[];
 /** The distinct resources a read targets: the tagged deployment's sole
  *  resource, or — untagged — every distinct one the config's deployments
- *  mention (deduped by `type:id`). */
+ *  mention ({@link dedupeResources}). */
 export declare function resolveReadResources(config: WorkflowConfig, tag: string | undefined): WorkflowResource[];
 /** The single resource a read should target, or fail asking which when the
  *  config spans more than one. For the paths that need one definite dataset

package/dist/lib/context.js

@@ -1,3 +1,4 @@
+import { assertReadableModel, resourceGdr, } from '@sanity/workflow-engine';
 import { clientFor, resolveTokenOrFail } from "./client.js";
 import { fail } from "./fail.js";
 import { loadWorkflowConfig } from "./load-config.js";
@@ -14,15 +15,14 @@ export async function resolveReadTargets(flags) {
     const token = await resolveTokenOrFail();
     return resources.map((resource) => ({ resource, client: clientFor(resource, token) }));
 }
+export function dedupeResources(resources) {
+    return [...new Map(resources.map((resource) => [resourceGdr(resource), resource])).values()];
+}
 export function resolveReadResources(config, tag) {
     if (tag !== undefined) {
         return [selectDeployment(config, { tag }).workflowResource];
     }
-    const byKey = new Map(config.deployments.map((d) => [
-        `${d.workflowResource.type}:${d.workflowResource.id}`,
-        d.workflowResource,
-    ]));
-    const resources = [...byKey.values()];
+    const resources = dedupeResources(config.deployments.map((d) => d.workflowResource));
     if (resources.length === 0) {
         fail('No deployments configured.');
     }
@@ -51,7 +51,7 @@ export async function loadInstanceOrFail(client, instanceId) {
     if (!instance) {
         fail(`Workflow instance ${instanceId} not found`);
     }
-    return instance;
+    return assertReadableModel(instance);
 }
 export function soleHitOrFail(hits, subject) {
     const [sole, ...rest] = hits;
@@ -65,7 +65,9 @@ export async function findInstance({ targets, instanceId, requestTag, }) {
         const instance = await target.client.getDocument(instanceId, {
             tag: requestTag,
         });
-        return instance === undefined ? undefined : { ...target, instance };
+        return instance === undefined
+            ? undefined
+            : { ...target, instance: assertReadableModel(instance) };
     }));
     const hits = probes
         .filter((probe) => probe.status === 'fulfilled')

package/dist/lib/definitions.js

@@ -1,4 +1,4 @@
-import { WORKFLOW_DEFINITION_TYPE, errorMessage, tagScopeFilter, validateDefinition, } from '@sanity/workflow-engine';
+import { WORKFLOW_DEFINITION_TYPE, assertReadableModel, errorMessage, tagScopeFilter, validateDefinition, } from '@sanity/workflow-engine';
 import { fail } from "./fail.js";
 export function buildDefinitionShowQuery(flags) {
     const params = { name: flags.name };
@@ -28,7 +28,7 @@ export async function fetchDeployedDefinition({ client, name, tag, version, }) {
     if (deployed === null && version !== undefined) {
         fail(`No deployed definition "${name}" v${version}.`);
     }
-    return deployed ?? undefined;
+    return deployed === null ? undefined : assertReadableModel(deployed);
 }
 export function selectDefinitions(allDefinitions, { only, context = '' }) {
     if (!only) {

package/dist/lib/nuke.d.ts

@@ -0,0 +1,89 @@
+import { type WorkflowClient, type WorkflowResource } from '@sanity/workflow-engine';
+/** A resource a nuke may delete from, with the client that reads/writes it and
+ *  whether it is the engine's own resource — the only one that holds instances
+ *  and definitions (guards can co-locate with subjects in any resource). */
+export interface NukeTarget {
+    resource: WorkflowResource;
+    client: WorkflowClient;
+    holdsEngineDocs: boolean;
+}
+/** One resolved resource of a {@link NukePlan}: the ids to delete, by doc type. */
+export interface NukeResourcePlan {
+    resource: WorkflowResource;
+    /** The `project.dataset` (or `<type>:<id>`) label the operator confirms by. */
+    label: string;
+    client: WorkflowClient;
+    holdsEngineDocs: boolean;
+    instanceIds: string[];
+    definitionIds: string[];
+    guardIds: string[];
+}
+/** The dry-run plan: what a `nuke --tag <tag>` would delete, per resource. */
+export interface NukePlan {
+    tag: string;
+    resources: NukeResourcePlan[];
+}
+/** Per-doc-type totals across the whole plan, plus the count of resources that
+ *  actually hold something to delete ({@link involvedTargets}). */
+export interface PlanCounts {
+    instances: number;
+    definitions: number;
+    guards: number;
+    datasets: number;
+    total: number;
+}
+/**
+ * Resolve what a tag-scoped nuke would delete, per resource — the dry-run plan
+ * printed before any deletion. Instances and definitions are read only from the
+ * engine's own resource; guards are read from every target, since a guard
+ * co-locates with the subject it locks and may live in a foreign dataset.
+ *
+ * Every read uses the raw perspective, so a draft-form or otherwise
+ * perspective-hidden copy is still surfaced (and swept).
+ */
+export declare function resolveNukePlan(args: {
+    tag: string;
+    targets: NukeTarget[];
+}): Promise<NukePlan>;
+/**
+ * Does a guard doc belong to `tag`? A guard's `sourceInstanceId` is the id of
+ * the instance that registered it (`<tag>.wf-instance.<random>`), and its own
+ * `_id` embeds that same instance id
+ * (`temp.system.guard.<tag>.wf-instance.<random>.<name>`). Matching on either —
+ * with the trailing `.` so `prod` never matches `prod-eu` — catches guards
+ * whose `sourceInstanceId` was never written as well as guards whose instance
+ * is already gone.
+ */
+export declare function guardMatchesTag(guard: {
+    _id: string;
+    sourceInstanceId?: string;
+}, tag: string): boolean;
+/** The `project.dataset` labels of resources the plan actually deletes from —
+ *  the exact set the operator must type back to confirm. A resource with
+ *  nothing to delete is not "involved" and is omitted. */
+export declare function involvedTargets(plan: NukePlan): string[];
+/** Roll the plan up into per-doc-type totals for the summary and the
+ *  nothing-to-do short-circuit. */
+export declare function planCounts(plan: NukePlan): PlanCounts;
+/**
+ * Does the operator's typed confirmation name every involved target, and only
+ * those? Order-independent, whitespace-tolerant set equality: the operator
+ * pastes back all `project.dataset` targets the plan listed.
+ */
+export declare function confirmationMatches(input: string, targets: string[]): boolean;
+/** The dry-run plan as printable lines: a heading, the content-safety
+ *  invariant, the API host the deletes will hit (plan rows alone can't tell
+ *  same-named projects on different environments apart), and a per-resource,
+ *  per-doc-type count table. A guard-only foreign resource shows `—` for the
+ *  engine-only columns, since those docs can't live there. */
+export declare function renderNukePlan(plan: NukePlan, apiHost: string): string[];
+/** The success line: what was deleted, and across how many datasets. */
+export declare function formatNukeSummary(tag: string, counts: PlanCounts): string;
+/**
+ * Delete exactly what the plan printed, in uniform waves over every resource.
+ * Wave order is referrers-first — instances, then definitions, then guards —
+ * a nicety for an interrupted run (engine docs link by plain strings, so the
+ * lake enforces no order); non-engine resources simply carry empty
+ * instance/definition lists. Idempotent: an empty plan deletes nothing.
+ */
+export declare function executeNuke(plan: NukePlan): Promise<void>;

package/dist/lib/nuke.js

@@ -0,0 +1,111 @@
+import { styleText } from 'node:util';
+import { GUARD_DOC_TYPE, WORKFLOW_DEFINITION_TYPE, WORKFLOW_INSTANCE_TYPE, tagScopeFilter, } from '@sanity/workflow-engine';
+import { formatTable, resourceLabel, sectionHeader } from "./ui.js";
+const CHUNK = 200;
+const REQUEST_TAG = 'nuke';
+export async function resolveNukePlan(args) {
+    const { tag, targets } = args;
+    const resources = await Promise.all(targets.map((target) => resolveResourcePlan({ tag, target })));
+    return { tag, resources };
+}
+async function resolveResourcePlan(args) {
+    const { tag, target } = args;
+    const { resource, client, holdsEngineDocs } = target;
+    const noIds = [];
+    const [instanceIds, definitionIds, guardIds] = await Promise.all([
+        holdsEngineDocs ? engineDocIds({ client, type: WORKFLOW_INSTANCE_TYPE, tag }) : noIds,
+        holdsEngineDocs ? engineDocIds({ client, type: WORKFLOW_DEFINITION_TYPE, tag }) : noIds,
+        tagGuardIds({ client, tag }),
+    ]);
+    return {
+        resource,
+        label: resourceLabel(resource),
+        client,
+        holdsEngineDocs,
+        instanceIds,
+        definitionIds,
+        guardIds,
+    };
+}
+function engineDocIds(args) {
+    return args.client.fetch(`*[_type == $type && ${tagScopeFilter()}]._id`, { type: args.type, tag: args.tag }, { perspective: 'raw', tag: REQUEST_TAG });
+}
+async function tagGuardIds(args) {
+    const guards = await args.client.fetch(`*[_type == $type]{_id, sourceInstanceId}`, { type: GUARD_DOC_TYPE }, { perspective: 'raw', tag: REQUEST_TAG });
+    return guards.filter((guard) => guardMatchesTag(guard, args.tag)).map((guard) => guard._id);
+}
+export function guardMatchesTag(guard, tag) {
+    const instancePrefix = `${tag}.wf-instance.`;
+    const guardIdPrefix = `${GUARD_DOC_TYPE}.${instancePrefix}`;
+    return ((guard.sourceInstanceId?.startsWith(instancePrefix) ?? false) ||
+        guard._id.startsWith(guardIdPrefix));
+}
+export function involvedTargets(plan) {
+    return plan.resources
+        .filter((resource) => resourceTotal(resource) > 0)
+        .map((resource) => resource.label);
+}
+function resourceTotal(resource) {
+    return resource.instanceIds.length + resource.definitionIds.length + resource.guardIds.length;
+}
+export function planCounts(plan) {
+    const totals = plan.resources.reduce((acc, resource) => ({
+        instances: acc.instances + resource.instanceIds.length,
+        definitions: acc.definitions + resource.definitionIds.length,
+        guards: acc.guards + resource.guardIds.length,
+    }), { instances: 0, definitions: 0, guards: 0 });
+    return {
+        ...totals,
+        datasets: involvedTargets(plan).length,
+        total: totals.instances + totals.definitions + totals.guards,
+    };
+}
+export function confirmationMatches(input, targets) {
+    const typed = new Set(input.trim().split(/\s+/).filter(Boolean));
+    const expected = new Set(targets);
+    return typed.size === expected.size && [...expected].every((target) => typed.has(target));
+}
+export function renderNukePlan(plan, apiHost) {
+    const rows = plan.resources.map((resource) => [
+        resource.label,
+        resource.holdsEngineDocs ? String(resource.instanceIds.length) : styleText('dim', '—'),
+        resource.holdsEngineDocs ? String(resource.definitionIds.length) : styleText('dim', '—'),
+        String(resource.guardIds.length),
+    ]);
+    return [
+        sectionHeader(`nuke — tag "${plan.tag}"`),
+        styleText('dim', 'engine-owned documents only — content is never touched'),
+        styleText('dim', `API host: ${apiHost}`),
+        ...formatTable(['target', 'instances', 'definitions', 'guards'], rows),
+    ];
+}
+export function formatNukeSummary(tag, counts) {
+    const parts = [
+        pluralize(counts.instances, 'instance'),
+        pluralize(counts.definitions, 'definition'),
+        pluralize(counts.guards, 'guard'),
+    ].join(', ');
+    return `Nuked tag "${tag}": ${parts} across ${pluralize(counts.datasets, 'dataset')}.`;
+}
+function pluralize(count, noun) {
+    return `${count} ${noun}${count === 1 ? '' : 's'}`;
+}
+export async function executeNuke(plan) {
+    for (const resource of plan.resources) {
+        await deleteIds(resource.client, resource.instanceIds);
+    }
+    for (const resource of plan.resources) {
+        await deleteIds(resource.client, resource.definitionIds);
+    }
+    for (const resource of plan.resources) {
+        await deleteIds(resource.client, resource.guardIds);
+    }
+}
+async function deleteIds(client, ids) {
+    for (let start = 0; start < ids.length; start += CHUNK) {
+        const tx = client.transaction();
+        for (const id of ids.slice(start, start + CHUNK))
+            tx.delete(id);
+        await tx.commit({ tag: REQUEST_TAG });
+    }
+}

package/dist/lib/operation-args.d.ts

@@ -3,7 +3,9 @@ import { type EngineScopeArgs, type OperationArgs, type WorkflowTelemetryLogger
  * The engine-scope a CLI verb needs: which tag partition and which resource
  * the engine's own data lives in — {@link EngineScopeArgs} minus the client.
  * A {@link import('@sanity/workflow-engine').WorkflowDeployment} satisfies it,
- * so commands pass their resolved deployment straight through.
+ * so commands pass their resolved deployment straight through. The CLI passes
+ * no `resourceClients`, so its writes admit runtime-supplied refs to the
+ * workflow resource only.
  */
 export type EngineScope = Pick<EngineScopeArgs, 'tag' | 'workflowResource'>;
 /**

package/dist/lib/ops-report.d.ts

@@ -38,7 +38,8 @@ export declare function cascadeTail(cascaded: number): string;
  * emit the report — warn and bail on a no-op (`changed: false`), otherwise
  * succeed and print the ops block. A throw fails the spinner and exits
  * through {@link fail}. The one spinner + report + catch shape every write
- * command (abort, set-stage, fire-action, start, definition delete) shares.
+ * command (abort, set-stage, fire-action, start, definition delete, nuke)
+ * shares.
  */
 export declare function runWriteVerb<T>({ startLabel, failLabel, failHeadline, run, report, log, }: {
     startLabel: string;

package/dist/lib/prompt.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Can this process ask a question on stderr? A strict superset of the
+ * {@link isInteractive} gate cli-core's own prompts enforce (stdin TTY,
+ * `TERM` not dumb, no `CI` — so its `NonInteractiveError` can never escape a
+ * caller that checked here first), adding stderr-TTY because this package's
+ * prompts render on stderr: a redirected stderr must refuse rather than block
+ * on stdin with the question swallowed. The one predicate every prompt site
+ * (the deploy consent prompt, nuke's confirmation) shares.
+ */
+export declare function canPromptOnStderr(): boolean;

package/dist/lib/prompt.js

@@ -0,0 +1,4 @@
+import { isInteractive } from '@sanity/cli-core';
+export function canPromptOnStderr() {
+    return isInteractive() && process.stderr.isTTY === true;
+}

package/dist/lib/share-definitions.js

@@ -1,8 +1,9 @@
 import { styleText } from 'node:util';
-import { getUserConfig, isInteractive } from '@sanity/cli-core';
+import { getUserConfig } from '@sanity/cli-core';
 import { confirm } from '@sanity/cli-core/ux';
-import { definitionDeployedData, errorMessage, isTelemetryEnvDenied, } from '@sanity/workflow-engine';
+import { assertReadableModel, definitionDeployedData, errorMessage, isTelemetryEnvDenied, } from '@sanity/workflow-engine';
 import { buildDefinitionShowQuery } from "./definitions.js";
+import { canPromptOnStderr } from "./prompt.js";
 import { cliTelemetry, WorkflowDefinitionShared, WorkflowDefinitionSharingDecided, } from "./telemetry.js";
 export const SHARE_ENDPOINT_URI = '/workflow/definition-feedback';
 const SHARE_TAG = 'definition.share';
@@ -70,6 +71,7 @@ async function loadDeployedForShare(args) {
             warn(`Could not read back ${result.name} v${result.version} — not shared.`);
             return undefined;
         }
+        assertReadableModel(deployed);
         return deployed;
     }
     catch (error) {
@@ -171,7 +173,7 @@ export async function shareDefinitionsAfterDeploy(args) {
     try {
         const { share, decision } = await resolveShareIntent({
             flag: args.flag,
-            interactive: args.interactive ?? (isInteractive() && process.stderr.isTTY === true),
+            interactive: args.interactive ?? canPromptOnStderr(),
             envDenied: args.envDenied ?? isTelemetryEnvDenied(process.env),
             userConfig: args.userConfig ?? getUserConfig(),
             writeStderr: args.writeStderr ?? ((message) => void process.stderr.write(message)),

package/oclif.manifest.json

@@ -290,6 +290,45 @@
         "list.js"
       ]
     },
+    "nuke": {
+      "aliases": [],
+      "args": {},
+      "description": "The reset for a dataset holding engine documents the versioned upgrade framework cannot yet migrate: deletes the tag's instances, definitions, and guards (across every alias-bound resource). Content documents are never touched. Prints a dry-run plan, then requires you to type back every involved dataset (--force skips the prompt; the plan still prints).",
+      "examples": [
+        "<%= config.bin %> nuke --tag plugin-dev",
+        "<%= config.bin %> nuke --tag plugin-dev --force"
+      ],
+      "flags": {
+        "tag": {
+          "description": "The deployment tag to reset. Required — a destructive reset never guesses the environment.",
+          "name": "tag",
+          "required": true,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "force": {
+          "description": "Skip the confirmation prompt (for scripts/CI). The plan still prints.",
+          "name": "force",
+          "allowNo": false,
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "nuke",
+      "pluginAlias": "@sanity/workflow-cli",
+      "pluginName": "@sanity/workflow-cli",
+      "pluginType": "core",
+      "strict": true,
+      "summary": "Delete every engine-owned document for a deployment tag — the dev-period big red button.",
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "nuke.js"
+      ]
+    },
     "reset-activity": {
       "aliases": [],
       "args": {
@@ -434,7 +473,8 @@
       "examples": [
         "<%= config.bin %> start productLaunch",
         "<%= config.bin %> start article-review --field subject='{\"id\":\"dataset:proj:ds:article-1\",\"type\":\"article\"}'",
-        "<%= config.bin %> start productLaunch --version 2 --tag prod"
+        "<%= config.bin %> start productLaunch --version 2 --tag prod",
+        "<%= config.bin %> start productLaunch --instance-id prod.wf-instance.a1b2c3d4e5f6"
       ],
       "flags": {
         "tag": {
@@ -459,6 +499,13 @@
           "multiple": true,
           "type": "option"
         },
+        "instance-id": {
+          "description": "Start under this instance id — for retries. The id is the start's idempotency key: pass the id of a start that failed partway and the engine resumes it instead of creating a duplicate (an already-settled start replays as a no-op). Omit to mint a fresh id.",
+          "name": "instance-id",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
         "json": {
           "description": "Emit structured JSON instead of rendered output.",
           "name": "json",
@@ -709,5 +756,5 @@
       ]
     }
   },
-  "version": "0.11.0"
+  "version": "0.12.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanity/workflow-cli",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Command-line tool for deploying, inspecting, and administering Sanity workflow definitions and instances.",
   "keywords": [
     "cli",
@@ -56,15 +56,15 @@
     "jiti": "^2.7.0",
     "log-symbols": "^7.0.1",
     "ora": "^9.4.0",
-    "@sanity/workflow-engine": "0.16.0"
+    "@sanity/workflow-engine": "0.17.0"
   },
   "devDependencies": {
     "@types/diff": "^8.0.0",
     "@types/node": "^24.12.4",
     "oclif": "^4.23.16",
     "vitest": "^4.1.8",
-    "@sanity/workflow-engine-test": "0.11.0",
-    "@sanity/workflow-examples": "0.6.0"
+    "@sanity/workflow-engine-test": "0.12.0",
+    "@sanity/workflow-examples": "0.7.0"
   },
   "oclif": {
     "bin": "sanity-workflows",