@sanity/workflow-cli 0.23.0 → 0.25.0

package/CHANGELOG.md

@@ -1,5 +1,63 @@
 # @sanity/workflow-cli
 
+## 0.25.0
+
+### Minor Changes
+
+- 177d600: Deployed workflow environment tags are now discoverable.
+
+  The engine gains two cross-partition GROQ builders: `deployedTagsGroq()` lists
+  every tag holding a deployed definition in a resource, and
+  `definitionTagsGroq()` narrows that to one definition name via `$definition`.
+  Both deliberately span tag partitions — every other read is tag-scoped, and
+  `workflow.query` refuses GROQ that isn't — so they answer "which environments
+  exist here" for a caller holding a resource but no tag. They report what is
+  _observed_: a tag with nothing deployed does not appear.
+
+  The stdio MCP server adds a `list_workflow_tags` tool taking a
+  `workflow_resource` and no tag. It is registered by the host rather than exported
+  as a tool def, because a def is only ever handed an engine and an engine is
+  pinned to one tag. `LIST_WORKFLOW_TAGS_TOOL_NAME` and
+  `LIST_WORKFLOW_TAGS_DESCRIPTION` are exported so an embedding host registers the
+  same capability under the same name without re-authoring the model-facing
+  wording. The `tag` parameter's description now points an agent at that tool where
+  a server offers it and at the user otherwise, and requires confirmation either
+  way — having the list does not license picking from it.
+
+  Both registration paths share one outcome path, `withToolTelemetry`, so the
+  result envelope, error rendering, and the `Editorial Workflows MCP Tool Called`
+  event cannot diverge between a def-backed tool and a host-registered one. Tag
+  discovery reports its adoption event like every other tool, and because it names
+  a resource it can also initialize the stdio server's deferred telemetry shell —
+  which matters when discovery is an agent's first call.
+
+  The CLI's definition-tags probe runs the engine's builder instead of its own
+  copy of the query, so its `params` key is `definition` rather than `name`, and
+  the tag partitions it names in an ambiguity error arrive sorted from the lake.
+
+### Patch Changes
+
+- Updated dependencies [177d600]
+- Updated dependencies [fc12989]
+  - @sanity/workflow-engine@0.25.0
+
+## 0.24.0
+
+### Minor Changes
+
+- e359f4b: Add `nuke --instance <id>`: delete a single terminal workflow instance and its guard documents (swept across every alias-bound resource), instead of wiping a whole deployment tag. In-flight instances are refused — abort them first, and so is any document that is not an engine instance, so a bare id can never reach co-located content. Prints a dry-run plan, then a `y/N` confirmation (`--force` skips it).
+
+  Instance mode locates its target by lake-side projection rather than a gated engine read, so it can delete an instance whose reader floor is ahead of the running engine — the state the reset exists to clear, and which tag mode could already handle.
+
+  Instance mode deletes the instance document in its LAST wave, after the guards. A nuke is never a single transaction, so an interrupted run always leaves something behind — and that document is the handle a re-run locates by, so deleting it first would strand any guard the run had not yet reached with nothing left to name them. Tag mode keeps deleting instance documents first, unchanged: it re-plans from a query, so a re-run sweeps whatever survived either way.
+
+### Patch Changes
+
+- fc02505: `deploy --only` now fails fast: the definition name is checked against the config before any deployment is selected, so a bogus value errors immediately instead of after the interactive deployment picker has been answered. When the value names a deployment rather than a definition, the failure points at the flag it belongs to — `"review-prod" is a deployment — did you mean --deployment review-prod?`.
+- Updated dependencies [0bc4328]
+- Updated dependencies [41a3f02]
+  - @sanity/workflow-engine@0.24.0
+
 ## 0.23.0
 
 ### Minor Changes

package/README.md

@@ -156,27 +156,28 @@ 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, removes guards)                                                                                                                                                                                                                                                           |
-| `set-stage <instance-id> --to <stage>`          | wired — calls `workflow.setStage` (admin override: skips declared transitions/filters; enter lifecycle + cascade still run)                                                                                                                                                                                                                           |
-| `reset-activity <instance-id> <activity>`       | wired — calls `workflow.resetActivity` (recovery override: reset a failed activity to `active`, or `--skip` to bypass it; then cascade)                                                                                                                                                                                                               |
-| `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 --deployment <name>` / `nuke --tag <tag>` | wired — dev-period reset (exists only until the versioned upgrade framework): deletes every engine-owned doc for the deployment's tag (instances, definitions, guards across resources); exactly one selector required; refuses while another same-tag deployment sweeps an overlapping resource (guard ids embed only the tag); plan + typed confirm |
+| 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, removes guards)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `set-stage <instance-id> --to <stage>`          | wired — calls `workflow.setStage` (admin override: skips declared transitions/filters; enter lifecycle + cascade still run)                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `reset-activity <instance-id> <activity>`       | wired — calls `workflow.resetActivity` (recovery override: reset a failed activity to `active`, or `--skip` to bypass it; then cascade)                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `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 --deployment <name>` / `nuke --tag <tag>` | wired — dev-period reset (exists only until the versioned upgrade framework): deletes every engine-owned doc for the deployment's tag (instances, definitions, guards across resources); exactly one of these two selectors required; refuses while another same-tag deployment sweeps an overlapping resource (guard ids embed only the tag); plan + typed confirm                                                                                                                                                                                                                  |
+| `nuke --instance <id>`                          | wired — dev-period reset, same fence as the tag mode above: deletes ONE terminal instance plus the guards it owns, swept across every alias-bound resource (matched by `sourceInstanceId`, with an id-prefix leg as redundant cover; matching provenance rather than the live instance set is what catches a partial-delete orphan); definitions are never in scope; refuses an in-flight instance (abort it first) and anything that is not an engine instance document; takes no `--tag`, and `--deployment` only to disambiguate a tag spanning deployments; plan + `y/N` confirm |
 
 ## Telemetry
 

package/dist/commands/editorial-workflows/definition/show.js

@@ -61,7 +61,7 @@ async function assertSingleTagPartition({ targets, name, }) {
         const tags = await target.client.fetch(groq, params, { tag: 'definition.show' });
         if (tags.length > 1) {
             fail(`Definition "${name}" exists in several tag partitions in ` +
-                `${resourceLabel(target.resource)} — pass --tag to choose one.`, tags.toSorted().join('\n'));
+                `${resourceLabel(target.resource)} — pass --tag to choose one.`, tags.join('\n'));
         }
     }));
 }

package/dist/commands/editorial-workflows/deploy.d.ts

@@ -1,5 +1,6 @@
-import { type DeployDefinitionResult, type WorkflowDefinition, type WorkflowDeployment } from '@sanity/workflow-engine';
+import { type DeployDefinitionResult, type WorkflowConfig, type WorkflowDefinition, type WorkflowDeployment } from '@sanity/workflow-engine';
 import { WorkflowCommand } from '../../lib/base-command.ts';
+import { type DeploymentSelectionOptions } from '../../lib/select-deployment.ts';
 /** A deployment paired with the definitions selected + validated for it. */
 interface DeployBatch {
     deployment: WorkflowDeployment;
@@ -33,6 +34,15 @@ export default class Deploy extends WorkflowCommand {
 }
 /** Reject the contradictory `--check --dry-run` combination. */
 export declare function validateModeFlags(check: boolean, dryRun: boolean): void;
+/**
+ * The batches a run acts on. The order is load-bearing: gating `--only` before
+ * selection is what spares the user an interactive deployment picker they were
+ * always going to fail behind.
+ */
+export declare function resolveBatches(config: WorkflowConfig, { only, selection }: {
+    only: string | undefined;
+    selection: DeploymentSelectionOptions;
+}): Promise<DeployBatch[]>;
 /**
  * Select and validate every deployment's definitions up front. Validation runs
  * before any network write ({@link validateOrFail} exits on a bad definition),

package/dist/commands/editorial-workflows/deploy.js

@@ -5,7 +5,7 @@ import logSymbols from 'log-symbols';
 import ora from 'ora';
 import { WorkflowCommand } from "../../lib/base-command.js";
 import { clientFor, resolveTokenOrFail } from "../../lib/client.js";
-import { selectDefinitions, validateOrFail } from "../../lib/definitions.js";
+import { assertKnownDefinition, selectDefinitions, validateOrFail } from "../../lib/definitions.js";
 import { diffReport } from "../../lib/diff.js";
 import { fail, isAuthRejection } from "../../lib/fail.js";
 import { deploymentFlags } from "../../lib/flags.js";
@@ -45,7 +45,7 @@ export default class Deploy extends WorkflowCommand {
             default: false,
         }),
         only: Flags.string({
-            description: 'Limit deploy/check/diff to a single workflow definition by name. Every targeted deployment must contain it.',
+            description: 'Limit deploy/check/diff to a single workflow definition by name (deployments are selected with --deployment). Every targeted deployment must contain it.',
         }),
         'share-defs': Flags.boolean({
             allowNo: true,
@@ -56,11 +56,10 @@ export default class Deploy extends WorkflowCommand {
         const { flags } = await this.parse(Deploy);
         validateModeFlags(flags.check, flags['dry-run']);
         const config = await loadWorkflowConfig();
-        const batches = buildBatches(await selectDeployments(config, {
-            name: flags.deployment,
-            tag: flags.tag,
-            allTags: flags['all-tags'],
-        }), flags.only);
+        const batches = await resolveBatches(config, {
+            only: flags.only,
+            selection: { name: flags.deployment, tag: flags.tag, allTags: flags['all-tags'] },
+        });
         const log = (line) => this.log(line);
         if (flags.check) {
             await reconcileBatches({
@@ -156,6 +155,10 @@ export function validateModeFlags(check, dryRun) {
         fail('Pass either --check or --dry-run, not both.');
     }
 }
+export async function resolveBatches(config, { only, selection }) {
+    assertKnownDefinition(config, only);
+    return buildBatches(await selectDeployments(config, selection), only);
+}
 export function buildBatches(deployments, only) {
     return deployments.map((deployment) => {
         const context = deployments.length > 1 ? `${deploymentLabel(deployment)} — ` : '';

package/dist/commands/editorial-workflows/nuke.d.ts

@@ -1,3 +1,4 @@
+import { type WorkflowConfig, type WorkflowDeployment, type WorkflowInstance, type WorkflowResource } from '@sanity/workflow-engine';
 import { WorkflowCommand } from '../../lib/base-command.ts';
 export default class Nuke extends WorkflowCommand {
     static aliases: string[];
@@ -7,7 +8,70 @@ export default class Nuke extends WorkflowCommand {
     static flags: {
         deployment: 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>;
+        instance: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         force: import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };
     run(): Promise<void>;
+    /** Tag mode: delete every engine-owned document for the selected deployment. */
+    private nukePartition;
+    /**
+     * Instance mode: delete ONE terminal instance plus its guard docs. Refuses an
+     * in-flight instance — abort it first, so pending effects are cancelled and
+     * children condemned; this command only removes what is already settled. The
+     * guard sweep runs regardless of how it terminated: a normally completed
+     * instance still holds its terminal-stage guards.
+     *
+     * Deliberately does NOT run {@link refuseOverlappingNuke}, which tag mode must.
+     * That refusal exists because guard ids embed only the tag, so a tag sweep
+     * cannot tell two same-tag deployments' guards apart in a shared resource. The
+     * instance sweep matches `sourceInstanceId` (and a `<type>.<instanceId>.` id
+     * prefix), both of which name one instance — so same-tag siblings cannot
+     * collide and adding the gate back would refuse valid deletes.
+     */
+    private deleteInstance;
 }
+/**
+ * Guard the two mutually exclusive modes. Instance mode reads its tag from the
+ * id, so `--tag` is meaningless there (`--deployment` still disambiguates a tag
+ * that spans deployments); tag mode requires exactly one selector, never
+ * guessing the environment.
+ */
+export declare function assertNukeFlags(flags: {
+    instance?: string | undefined;
+    deployment?: string | undefined;
+    tag?: string | undefined;
+}): void;
+/**
+ * The configured deployment that owns an instance — matched by the instance's
+ * own tag AND the resource that held it. Config forbids two deployments sharing
+ * tag + workflow resource, so this is unambiguous. Needed for the alias-bound
+ * resources a single-instance guard sweep must also cover.
+ *
+ * Both halves of the match are named on failure: a tag that IS configured but on
+ * another resource is the likelier miss of the two, and naming only the tag
+ * makes that read as though the tag were unknown.
+ */
+export declare function deploymentForInstanceScope(config: WorkflowConfig, located: {
+    tag: string | undefined;
+    resource: WorkflowResource;
+}): WorkflowDeployment;
+/**
+ * Refuse anything that is not an engine instance document. The locate reads a
+ * projection by raw id, so nothing upstream has proved the id names an instance
+ * — and engine documents can share a dataset with the content they govern, where
+ * a bare id would otherwise let a delete reach a content document. The plan
+ * promises "content is never touched"; this is what makes that true.
+ */
+export declare function assertEngineInstanceOrFail(document: {
+    _type: string;
+}, instanceId: string): void;
+/**
+ * Refuse to delete an in-flight instance — abort it first, so its pending
+ * effects are cancelled and children condemned. This command only removes what
+ * is already settled ({@link terminalState} is not `'in-flight'`); it performs
+ * no engine mutation of its own.
+ */
+export declare function assertInstanceTerminalOrFail(instance: Pick<WorkflowInstance, 'completedAt' | 'abortedAt'>, { instanceId, bin }: {
+    instanceId: string;
+    bin: string;
+}): void;

package/dist/commands/editorial-workflows/nuke.js

@@ -1,35 +1,44 @@
 import { Flags } from '@oclif/core';
 import { input } from '@sanity/cli-core/ux';
-import { resourceGdr } from '@sanity/workflow-engine';
+import { WORKFLOW_INSTANCE_TYPE, resourceGdr, terminalState, } 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 { dedupeResources, resolveInstanceStamps } from "../../lib/context.js";
 import { fail } from "../../lib/fail.js";
 import { loadWorkflowConfig } from "../../lib/load-config.js";
-import { confirmationMatches, executeNuke, formatNukeSummary, involvedTargets, planCounts, refuseOverlappingNuke, renderNukePlan, resolveNukePlan, sweptResources, } from "../../lib/nuke.js";
+import { confirmationMatches, executeNuke, formatInstanceNukeSummary, formatNukeSummary, involvedTargets, planCounts, refuseOverlappingNuke, renderNukePlan, resolveInstanceNukePlan, resolveNukePlan, sweptResources, } from "../../lib/nuke.js";
 import { runWriteVerb } from "../../lib/ops-report.js";
-import { canPromptOnStderr } from "../../lib/prompt.js";
+import { canPromptOnStderr, confirmOnStderr } from "../../lib/prompt.js";
 import { selectDeployment } from "../../lib/select-deployment.js";
+import { resourceLabel } from "../../lib/ui.js";
+function planApiHost() {
+    return resolveApiHost() ?? 'https://api.sanity.io (production default)';
+}
 export default class Nuke extends WorkflowCommand {
     static aliases = ['nuke'];
-    static summary = 'Delete every engine-owned document for a deployment tag — the dev-period big red button.';
+    static summary = 'Delete engine-owned documents — a whole deployment tag, or a single instance.';
     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).';
+        'resource). --instance <id> instead deletes one terminal instance plus its guards. Content ' +
+        'documents are never touched. Prints a dry-run plan, then confirms (--force skips the prompt; ' +
+        'the plan still prints).';
     static examples = [
         '<%= config.bin %> nuke --deployment plugin-dev',
         '<%= config.bin %> nuke --tag plugin-dev --force',
+        '<%= config.bin %> nuke --instance plugin-dev.wf-instance.abc123',
     ];
     static flags = {
         deployment: Flags.string({
-            description: 'The deployment name to reset.',
-            exactlyOne: ['deployment', 'tag'],
+            description: 'The deployment name to reset. With --instance, narrows which deployment the ' +
+                'instance is looked up in when its tag spans several.',
         }),
         tag: Flags.string({
-            description: 'The deployment tag to reset (while it names exactly one deployment).',
-            exactlyOne: ['deployment', 'tag'],
+            description: 'The deployment tag to reset (while it names exactly one deployment). Not valid ' +
+                'with --instance, which reads its tag from the instance id.',
+        }),
+        instance: Flags.string({
+            description: 'Delete a single terminal instance by id, plus its guard docs, instead of a tag.',
         }),
         force: Flags.boolean({
             description: 'Skip the confirmation prompt (for scripts/CI). The plan still prints.',
@@ -38,13 +47,20 @@ export default class Nuke extends WorkflowCommand {
     };
     async run() {
         const { flags } = await this.parse(Nuke);
+        assertNukeFlags(flags);
+        if (flags.instance !== undefined) {
+            await this.deleteInstance(flags.instance, flags);
+            return;
+        }
+        await this.nukePartition(flags);
+    }
+    async nukePartition(flags) {
         const config = await loadWorkflowConfig();
         const deployment = await selectDeployment(config, { name: flags.deployment, tag: flags.tag });
         refuseOverlappingNuke(config.deployments, deployment);
         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));
+        renderNukePlan(plan, { apiHost: planApiHost() }).forEach((line) => this.log(line));
         const counts = planCounts(plan);
         if (counts.total === 0) {
             this.log(`${logSymbols.info} Nothing to nuke for tag "${deployment.tag}".`);
@@ -61,6 +77,67 @@ export default class Nuke extends WorkflowCommand {
             log: (line) => this.log(line),
         });
     }
+    async deleteInstance(instanceId, flags) {
+        const config = await loadWorkflowConfig();
+        const { resource, stamps } = await resolveInstanceStamps(flags, instanceId);
+        assertEngineInstanceOrFail(stamps, instanceId);
+        assertInstanceTerminalOrFail(stamps, { instanceId, bin: this.config.bin });
+        const deployment = deploymentForInstanceScope(config, { tag: stamps.tag, resource });
+        const targets = buildTargets(deployment, await resolveTokenOrFail());
+        const plan = await resolveInstanceNukePlan({
+            instance: { id: instanceId, resource },
+            tag: deployment.tag,
+            targets,
+        });
+        renderNukePlan(plan, {
+            apiHost: planApiHost(),
+            heading: `nuke — instance "${instanceId}"`,
+        }).forEach((line) => this.log(line));
+        const counts = planCounts(plan);
+        if (!flags.force)
+            await confirmInstanceDeleteOrFail(instanceId);
+        await runWriteVerb({
+            startLabel: `Deleting ${instanceId}…`,
+            failLabel: 'Delete failed',
+            failHeadline: 'workflow nuke error:',
+            run: () => executeNuke(plan),
+            report: () => ({ changed: true, message: formatInstanceNukeSummary(instanceId, counts) }),
+            log: (line) => this.log(line),
+        });
+    }
+}
+export function assertNukeFlags(flags) {
+    if (flags.instance !== undefined) {
+        if (flags.tag !== undefined) {
+            fail('--instance cannot be combined with --tag.', 'The tag is read from the instance id; pass --deployment to disambiguate if needed.');
+        }
+        return;
+    }
+    const selectors = [flags.deployment, flags.tag].filter((value) => value !== undefined);
+    if (selectors.length !== 1) {
+        fail('Pass exactly one of --deployment or --tag (or --instance <id> to delete one instance).');
+    }
+}
+export function deploymentForInstanceScope(config, located) {
+    const gdr = resourceGdr(located.resource);
+    const deployment = config.deployments.find((candidate) => candidate.tag === located.tag && resourceGdr(candidate.workflowResource) === gdr);
+    if (deployment === undefined) {
+        fail(`No deployment in this workflow config has tag "${located.tag}" on ` +
+            `${resourceLabel(located.resource)}.`, 'A single-instance delete resolves the deployment to find the alias-bound resources its ' +
+            'guards can live in. Add that deployment to the config, or pass --deployment to name ' +
+            'the one that should own it.');
+    }
+    return deployment;
+}
+export function assertEngineInstanceOrFail(document, instanceId) {
+    if (document._type !== WORKFLOW_INSTANCE_TYPE) {
+        fail(`${instanceId} is not a workflow instance (its _type is "${document._type}").`, `Only ${WORKFLOW_INSTANCE_TYPE} documents can be deleted this way.`);
+    }
+}
+export function assertInstanceTerminalOrFail(instance, { instanceId, bin }) {
+    if (terminalState(instance) === 'in-flight') {
+        fail('Instance is in-flight — abort it first, then delete.', `Run: ${bin} abort ${instanceId}`);
+    }
 }
 function buildTargets(deployment, token) {
     const engineGdr = resourceGdr(deployment.workflowResource);
@@ -70,12 +147,21 @@ function buildTargets(deployment, token) {
         holdsEngineDocs: resourceGdr(resource) === engineGdr,
     }));
 }
-async function confirmOrFail(targets) {
+function assertPromptableOrFail(action) {
     if (!canPromptOnStderr()) {
-        fail('Refusing to nuke without confirmation in a non-interactive shell.', 'Re-run with --force to skip the prompt.');
+        fail(`Refusing to ${action} without confirmation in a non-interactive shell.`, 'Re-run with --force to skip the prompt.');
     }
+}
+async function confirmOrFail(targets) {
+    assertPromptableOrFail('nuke');
     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(' ')}`);
     }
 }
+async function confirmInstanceDeleteOrFail(instanceId) {
+    assertPromptableOrFail('delete');
+    if (!(await confirmOnStderr(`Delete instance ${instanceId}?`))) {
+        fail('Cancelled — nothing was deleted.');
+    }
+}

package/dist/lib/context.d.ts

@@ -11,8 +11,9 @@ export interface InstanceContext {
      *  ready to pass straight to an engine verb, so callers never re-assemble it. */
     scope: EngineScope;
     /** The located instance. Already fetched by the fan-out to derive the scope,
-     *  so a command that needs its state (set-stage's stage picker reads the
-     *  pinned definition snapshot and `currentStage`) reuses it, not re-fetch. */
+     *  so a command that needs its state reuses it rather than re-fetching —
+     *  set-stage's stage picker reads the pinned definition snapshot and
+     *  `currentStage`; nuke's instance mode reads the terminal state. */
     instance: WorkflowInstance;
 }
 /**
@@ -75,6 +76,25 @@ export declare function resolveInstanceContext(flags: {
     deployment?: string | undefined;
     tag?: string | undefined;
 }, instanceId: string): Promise<InstanceContext>;
+/** An instance located without interpreting its shape — the resource that held
+ *  it and the {@link InstanceStamps} a delete gates on. */
+export interface InstanceStampsContext {
+    resource: WorkflowResource;
+    stamps: InstanceStamps;
+}
+/**
+ * Locate an instance by the same fan-out and `<tag>.` fast-path as
+ * {@link resolveInstanceContext}, but reading only a projection — for the one
+ * caller that must not be refused by the reader-floor gate. See
+ * {@link findInstanceStamps} for why `nuke --instance` is that caller.
+ *
+ * Returns no client: a projection cannot be acted on through an engine verb, so
+ * the caller builds its own write clients from the deployment it resolves.
+ */
+export declare function resolveInstanceStamps(flags: {
+    deployment?: string | undefined;
+    tag?: string | undefined;
+}, instanceId: string): Promise<InstanceStampsContext>;
 /** A read target that turned out to hold the instance being looked up. */
 export interface InstanceHit extends ReadTarget {
     instance: WorkflowInstance;
@@ -88,16 +108,25 @@ export declare function soleHitOrFail<T extends {
     resource: WorkflowResource;
 }>(hits: T[], subject: string): T | undefined;
 /**
- * Look an instance id up across every read target. Exactly one hit wins —
- * instance ids are random and collision-free, so a single match IS the
- * instance. Several hits (id reuse across datasets) fail listing the
- * resources rather than silently picking one. `undefined` means confidently
- * not found: when a probe throws and no other target has the id, that error
- * propagates instead — an unreadable dataset must not masquerade as "no such
- * instance".
+ * Look an instance id up across every read target, reading each hit as a full
+ * engine-gated instance document — the locate every command that then acts
+ * through an engine verb uses. See {@link findAcrossTargets} for the
+ * one-hit-wins semantics.
  */
 export declare function findInstance({ targets, instanceId, requestTag, }: {
     targets: ReadTarget[];
     instanceId: string;
     requestTag: string;
 }): Promise<InstanceHit | undefined>;
+/**
+ * The four persisted fields a delete needs to decide it may proceed, read
+ * WITHOUT interpreting the document's shape: `_type` to prove it is an engine
+ * instance and not co-located content, `tag` to locate the owning deployment,
+ * and the terminal stamps to prove it has settled.
+ */
+export interface InstanceStamps {
+    _type: string;
+    tag?: string;
+    completedAt?: string;
+    abortedAt?: string;
+}

package/dist/lib/context.js

@@ -34,7 +34,13 @@ const LOCATE_TAG = 'instance.load';
 export async function resolveInstanceContext(flags, instanceId) {
     const config = await loadWorkflowConfig();
     const token = await resolveTokenOrFail();
-    const hit = await locateInstance({ config, flags, instanceId, token });
+    const hit = await locateInstance({
+        config,
+        flags,
+        instanceId,
+        token,
+        find: (targets) => findInstance({ targets, instanceId, requestTag: LOCATE_TAG }),
+    });
     if (hit === undefined) {
         fail(`Workflow instance ${instanceId} not found`);
     }
@@ -44,9 +50,24 @@ export async function resolveInstanceContext(flags, instanceId) {
         instance: hit.instance,
     };
 }
-async function locateInstance({ config, flags, instanceId, token, }) {
+export async function resolveInstanceStamps(flags, instanceId) {
+    const config = await loadWorkflowConfig();
+    const token = await resolveTokenOrFail();
+    const hit = await locateInstance({
+        config,
+        flags,
+        instanceId,
+        token,
+        find: (targets) => findInstanceStamps({ targets, instanceId, requestTag: LOCATE_TAG }),
+    });
+    if (hit === undefined) {
+        fail(`Workflow instance ${instanceId} not found`);
+    }
+    return { resource: hit.resource, stamps: hit.stamps };
+}
+async function locateInstance({ config, flags, instanceId, token, find, }) {
     const resources = await instanceCandidateResources(config, flags);
-    const fanOut = () => findInstance({ targets: targetsFor(resources, token), instanceId, requestTag: LOCATE_TAG });
+    const fanOut = () => find(targetsFor(resources, token));
     const explicit = flags.deployment !== undefined || flags.tag !== undefined;
     const hinted = explicit || resources.length <= 1
         ? []
@@ -54,12 +75,12 @@ async function locateInstance({ config, flags, instanceId, token, }) {
     if (hinted.length === 0 || hinted.length === resources.length) {
         return fanOut();
     }
-    const hit = await hintedProbe(targetsFor(hinted, token), instanceId);
+    const hit = await hintedProbe(() => find(targetsFor(hinted, token)));
     return hit ?? fanOut();
 }
-async function hintedProbe(targets, instanceId) {
+async function hintedProbe(probe) {
     try {
-        return await findInstance({ targets, instanceId, requestTag: LOCATE_TAG });
+        return await probe();
     }
     catch {
         return undefined;
@@ -89,26 +110,43 @@ export function soleHitOrFail(hits, subject) {
     }
     return sole;
 }
-export async function findInstance({ targets, instanceId, requestTag, }) {
-    const probes = await Promise.allSettled(targets.map(async (target) => {
-        const instance = await target.client.getDocument(instanceId, {
-            tag: requestTag,
-        });
-        return instance === undefined
-            ? undefined
-            : { ...target, instance: assertReadableModel(instance) };
-    }));
+async function findAcrossTargets({ targets, subject, probe, }) {
+    const probes = await Promise.allSettled(targets.map(probe));
     const hits = probes
-        .filter((probe) => probe.status === 'fulfilled')
-        .map((probe) => probe.value)
+        .filter((settled) => settled.status === 'fulfilled')
+        .map((settled) => settled.value)
         .filter((hit) => hit !== undefined);
-    const sole = soleHitOrFail(hits, `Instance ${instanceId}`);
+    const sole = soleHitOrFail(hits, subject);
     if (sole !== undefined) {
         return sole;
     }
-    const failedProbe = probes.find((probe) => probe.status === 'rejected');
+    const failedProbe = probes.find((settled) => settled.status === 'rejected');
     if (failedProbe !== undefined) {
         throw failedProbe.reason;
     }
     return undefined;
 }
+export function findInstance({ targets, instanceId, requestTag, }) {
+    return findAcrossTargets({
+        targets,
+        subject: `Instance ${instanceId}`,
+        probe: async (target) => {
+            const instance = await target.client.getDocument(instanceId, {
+                tag: requestTag,
+            });
+            return instance === undefined
+                ? undefined
+                : { ...target, instance: assertReadableModel(instance) };
+        },
+    });
+}
+function findInstanceStamps({ targets, instanceId, requestTag, }) {
+    return findAcrossTargets({
+        targets,
+        subject: `Instance ${instanceId}`,
+        probe: async (target) => {
+            const stamps = await target.client.fetch(`*[_id == $instanceId][0]{_type, tag, completedAt, abortedAt}`, { instanceId }, { perspective: 'raw', tag: requestTag });
+            return stamps === null ? undefined : { ...target, stamps };
+        },
+    });
+}

package/dist/lib/definitions.d.ts

@@ -1,5 +1,5 @@
 import type { SanityClient } from '@sanity/client';
-import { type DeployedDefinition, type WorkflowDefinition } from '@sanity/workflow-engine';
+import { type DeployedDefinition, type WorkflowConfig, type WorkflowDefinition } from '@sanity/workflow-engine';
 interface DefinitionShowQueryArgs {
     name: string;
     tag?: string | undefined;
@@ -10,10 +10,9 @@ export declare function buildDefinitionShowQuery(flags: DefinitionShowQueryArgs)
     params: Record<string, unknown>;
 };
 /**
- * The tag partitions holding any version of a definition name within one
- * dataset. An untagged lookup that would span several partitions must error
- * (the highest version ACROSS partitions is meaningless — it could show a
- * prod operator the dev definition), the same way a cross-dataset hit does.
+ * The engine's {@link definitionTagsGroq} in this package's `{groq, params}`
+ * calling shape. Refusing an untagged lookup that spans partitions mirrors the
+ * cross-dataset rule: ambiguity errors, never picks.
  */
 export declare function buildDefinitionTagsQuery(name: string): {
     groq: string;
@@ -31,6 +30,20 @@ export declare function fetchDeployedDefinition({ client, name, tag, version, }:
     tag: string;
     version: number | undefined;
 }): Promise<DeployedDefinition | undefined>;
+/**
+ * Gate a definition filter against the whole config before a command resolves
+ * which deployment it targets — a name that matches no definition anywhere can
+ * never deploy, whichever deployment is chosen, so it fails here rather than
+ * behind the interactive deployment picker. Membership in the targeted
+ * deployment stays with {@link selectDefinitions}, which fails on a name only
+ * some other deployment carries.
+ *
+ * The filter and the deployment selector both take a bare name, so a value
+ * naming a deployment is pointed at the flag it belongs to instead of getting a
+ * dead-end list of definitions it was never going to be in — in which case the
+ * available-definitions hint is replaced, not appended to.
+ */
+export declare function assertKnownDefinition(config: WorkflowConfig, only: string | undefined): void;
 /**
  * Narrow a batch to one definition name (`only`), failing with the available
  * names when there's no match. With `only` unset the whole batch passes through

package/dist/lib/definitions.js

@@ -1,4 +1,4 @@
-import { WORKFLOW_DEFINITION_TYPE, assertReadableModel, errorMessage, tagScopeFilter, validateDefinition, } from '@sanity/workflow-engine';
+import { WORKFLOW_DEFINITION_TYPE, assertReadableModel, definitionTagsGroq, errorMessage, tagScopeFilter, validateDefinition, } from '@sanity/workflow-engine';
 import { fail } from "./fail.js";
 export function buildDefinitionShowQuery(flags) {
     const params = { name: flags.name };
@@ -16,8 +16,8 @@ export function buildDefinitionShowQuery(flags) {
 }
 export function buildDefinitionTagsQuery(name) {
     return {
-        groq: `array::unique(*[_type == "${WORKFLOW_DEFINITION_TYPE}" && name == $name].tag)`,
-        params: { name },
+        groq: definitionTagsGroq(),
+        params: { definition: name },
     };
 }
 export async function fetchDeployedDefinition({ client, name, tag, version, }) {
@@ -30,14 +30,29 @@ export async function fetchDeployedDefinition({ client, name, tag, version, }) {
     }
     return deployed === null ? undefined : assertReadableModel(deployed);
 }
+function availableDefinitions(names) {
+    return `Available: ${names.join(', ')}`;
+}
+export function assertKnownDefinition(config, only) {
+    if (!only) {
+        return;
+    }
+    const names = new Set(config.deployments.flatMap((d) => d.definitions.map((def) => def.name)));
+    if (names.has(only)) {
+        return;
+    }
+    const namesADeployment = config.deployments.some((d) => d.name === only);
+    fail(`No definition named "${only}".`, namesADeployment
+        ? `"${only}" is a deployment — did you mean --deployment ${only}?`
+        : availableDefinitions([...names]));
+}
 export function selectDefinitions(allDefinitions, { only, context = '' }) {
     if (!only) {
         return [...allDefinitions];
     }
     const filtered = allDefinitions.filter((d) => d.name === only);
     if (filtered.length === 0) {
-        const available = allDefinitions.map((d) => d.name).join(', ');
-        fail(`${context}No definition named "${only}".`, `Available: ${available}`);
+        fail(`${context}No definition named "${only}".`, availableDefinitions(allDefinitions.map((d) => d.name)));
     }
     return filtered;
 }

package/dist/lib/nuke.d.ts

@@ -10,7 +10,8 @@ export interface NukeTarget {
 /** 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. */
+    /** The `project.dataset` (or `<type>:<id>`) label the plan shows this resource
+     *  as — and, in tag mode, the one the operator confirms by. */
     label: string;
     client: WorkflowClient;
     holdsEngineDocs: boolean;
@@ -18,9 +19,14 @@ export interface NukeResourcePlan {
     definitionIds: string[];
     guardIds: string[];
 }
-/** The dry-run plan: what a `nuke --tag <tag>` would delete, per resource. */
+/** Which selector resolved a plan. Decides the delete wave order — see
+ *  {@link WAVE_ORDER} — so it travels with the plan rather than being re-derived. */
+export type NukeMode = 'tag' | 'instance';
+/** The dry-run plan both modes render and execute: what a `nuke --tag <tag>` or
+ *  a `nuke --instance <id>` would delete, per resource. */
 export interface NukePlan {
     tag: string;
+    mode: NukeMode;
     resources: NukeResourcePlan[];
 }
 /** Per-doc-type totals across the whole plan, plus the count of resources that
@@ -59,9 +65,31 @@ export declare function resolveNukePlan(args: {
     tag: string;
     targets: NukeTarget[];
 }): Promise<NukePlan>;
-/** 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. */
+/** An instance a caller has already located: its id plus the resource whose
+ *  document the locate actually read. The plan derives its instance row from
+ *  that resource rather than assuming the engine one holds it, so a plan can
+ *  only ever claim an instance the caller really found. */
+export interface LocatedInstance {
+    id: string;
+    resource: WorkflowResource;
+}
+/**
+ * Resolve what deleting ONE located instance sweeps, per resource — the
+ * single-instance sibling of {@link resolveNukePlan}. The instance document is
+ * deleted from the resource that held it; its guards are read from every target,
+ * since a guard co-locates with the subject it locks and may live in an
+ * alias-bound dataset. Definitions are never in scope. Raw perspective, like the
+ * tag-scoped plan.
+ */
+export declare function resolveInstanceNukePlan(args: {
+    instance: LocatedInstance;
+    tag: string;
+    targets: NukeTarget[];
+}): Promise<NukePlan>;
+/** The `project.dataset` labels of resources the plan actually deletes from. A
+ *  resource with nothing to delete is not "involved" and is omitted. Tag mode
+ *  makes the operator type this set back; instance mode confirms with a plain
+ *  y/N and consumes it only for the dataset count in its summary. */
 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. */
@@ -77,14 +105,21 @@ export declare function confirmationMatches(input: string, targets: string[]): b
  *  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[];
+export declare function renderNukePlan(plan: NukePlan, { apiHost, heading }: {
+    apiHost: string;
+    heading?: string;
+}): string[];
 /** The success line: what was deleted, and across how many datasets. */
 export declare function formatNukeSummary(tag: string, counts: PlanCounts): string;
+/** The success line for a single-instance delete: the instance is named, so only
+ *  its swept guards need counting, across every dataset the delete touched (the
+ *  engine one counts for the instance doc alone, so a guardless instance still
+ *  reports one). */
+export declare function formatInstanceNukeSummary(instanceId: string, counts: Pick<PlanCounts, 'datasets' | 'guards'>): 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.
+ * Delete exactly what the plan printed, in uniform waves over every resource,
+ * ordered by the plan's mode ({@link WAVE_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

@@ -27,37 +27,66 @@ export function refuseOverlappingNuke(deployments, selected) {
 export async function resolveNukePlan(args) {
     const { tag, targets } = args;
     const resources = await Promise.all(targets.map((target) => resolveResourcePlan({ tag, target })));
-    return { tag, resources };
+    return { tag, mode: 'tag', resources };
 }
 async function resolveResourcePlan(args) {
     const { tag, target } = args;
-    const { resource, client, holdsEngineDocs } = target;
+    const { 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 resourcePlan(target, { instanceIds, definitionIds, guardIds });
+}
+function resourcePlan(target, ids) {
     return {
-        resource,
-        label: resourceLabel(resource),
-        client,
-        holdsEngineDocs,
-        instanceIds,
-        definitionIds,
-        guardIds,
+        resource: target.resource,
+        label: resourceLabel(target.resource),
+        client: target.client,
+        holdsEngineDocs: target.holdsEngineDocs,
+        ...ids,
     };
 }
+export async function resolveInstanceNukePlan(args) {
+    const { instance, tag, targets } = args;
+    const resources = await Promise.all(targets.map((target) => resolveInstanceResourcePlan({ instance, target })));
+    return { tag, mode: 'instance', resources };
+}
+async function resolveInstanceResourcePlan(args) {
+    const { instance, target } = args;
+    const guardIds = await instanceGuardIds({ client: target.client, instanceId: instance.id });
+    const holdsInstance = resourceGdr(target.resource) === resourceGdr(instance.resource);
+    return resourcePlan(target, {
+        instanceIds: holdsInstance ? [instance.id] : [],
+        definitionIds: [],
+        guardIds,
+    });
+}
+function instanceGuardIds(args) {
+    return guardIdsMatching({
+        client: args.client,
+        match: 'sourceInstanceId == $instanceId || string::startsWith(_id, $guardIdPrefix)',
+        params: {
+            instanceId: args.instanceId,
+            guardIdPrefix: `${GUARD_DOC_TYPE}.${args.instanceId}.`,
+        },
+    });
+}
 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) {
+function tagGuardIds(args) {
     const instancePrefix = `${args.tag}.wf-instance.`;
-    const guardIdPrefix = `${GUARD_DOC_TYPE}.${instancePrefix}`;
-    return args.client.fetch(`*[_type == $type && (
-      string::startsWith(sourceInstanceId, $instancePrefix) ||
-      string::startsWith(_id, $guardIdPrefix)
-    )]._id`, { type: GUARD_DOC_TYPE, instancePrefix, guardIdPrefix }, { perspective: 'raw', tag: REQUEST_TAG });
+    return guardIdsMatching({
+        client: args.client,
+        match: 'string::startsWith(sourceInstanceId, $instancePrefix) || string::startsWith(_id, $guardIdPrefix)',
+        params: { instancePrefix, guardIdPrefix: `${GUARD_DOC_TYPE}.${instancePrefix}` },
+    });
+}
+function guardIdsMatching(args) {
+    return args.client.fetch(`*[_type == $type && (${args.match})]._id`, { type: GUARD_DOC_TYPE, ...args.params }, { perspective: 'raw', tag: REQUEST_TAG });
 }
 export function involvedTargets(plan) {
     return plan.resources
@@ -84,7 +113,7 @@ export function confirmationMatches(input, targets) {
     const expected = new Set(targets);
     return typed.size === expected.size && [...expected].every((target) => typed.has(target));
 }
-export function renderNukePlan(plan, apiHost) {
+export function renderNukePlan(plan, { apiHost, heading = `nuke — tag "${plan.tag}"` }) {
     const rows = plan.resources.map((resource) => [
         resource.label,
         resource.holdsEngineDocs ? String(resource.instanceIds.length) : styleText('dim', '—'),
@@ -92,7 +121,7 @@ export function renderNukePlan(plan, apiHost) {
         String(resource.guardIds.length),
     ]);
     return [
-        sectionHeader(`nuke — tag "${plan.tag}"`),
+        sectionHeader(heading),
         styleText('dim', 'engine-owned documents only — content is never touched'),
         styleText('dim', `API host: ${apiHost}`),
         ...formatTable(['target', 'instances', 'definitions', 'guards'], rows),
@@ -106,18 +135,22 @@ export function formatNukeSummary(tag, counts) {
     ].join(', ');
     return `Nuked tag "${tag}": ${parts} across ${pluralize(counts.datasets, 'dataset')}.`;
 }
+export function formatInstanceNukeSummary(instanceId, counts) {
+    return (`Deleted instance ${instanceId}: ${pluralize(counts.guards, 'guard')} ` +
+        `across ${pluralize(counts.datasets, 'dataset')}.`);
+}
 function pluralize(count, noun) {
     return `${count} ${noun}${count === 1 ? '' : 's'}`;
 }
+const WAVE_ORDER = {
+    instance: ['guardIds', 'definitionIds', 'instanceIds'],
+    tag: ['instanceIds', 'definitionIds', 'guardIds'],
+};
 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);
+    for (const idField of WAVE_ORDER[plan.mode]) {
+        for (const resource of plan.resources) {
+            await deleteIds(resource.client, resource[idField]);
+        }
     }
 }
 async function deleteIds(client, ids) {

package/dist/lib/prompt.d.ts

@@ -26,3 +26,10 @@ export declare function selectOnStderr(config: {
      *  picker opens where it already is. */
     default?: string;
 }): Promise<string>;
+/**
+ * Ask a yes/no question on stderr, defaulting to NO — the {@link selectOnStderr}
+ * sibling for a destructive confirmation. `default: false` both renders the
+ * `[y/N]` hint and makes a bare Enter a decline, so proceeding always takes a
+ * deliberate keystroke.
+ */
+export declare function confirmOnStderr(message: string): Promise<boolean>;

package/dist/lib/prompt.js

@@ -1,8 +1,11 @@
 import { isInteractive } from '@sanity/cli-core';
-import { select } from '@sanity/cli-core/ux';
+import { confirm, select } from '@sanity/cli-core/ux';
 export function canPromptOnStderr() {
     return isInteractive() && process.stderr.isTTY === true;
 }
 export function selectOnStderr(config) {
     return select(config, { output: process.stderr });
 }
+export function confirmOnStderr(message) {
+    return confirm({ message, default: false }, { output: process.stderr });
+}

package/dist/lib/select-deployment.d.ts

@@ -1,6 +1,6 @@
 import { type DeployTarget, type WorkflowConfig, type WorkflowDeployment } from '@sanity/workflow-engine';
 export type ChooseDeploymentName = (deployments: WorkflowDeployment[]) => Promise<string>;
-interface DeploymentSelectionOptions {
+export interface DeploymentSelectionOptions {
     name: string | undefined;
     tag: string | undefined;
     allTags: boolean;
@@ -54,4 +54,3 @@ export declare function selectDeployments(config: WorkflowConfig, { name, tag, a
  * consume — expanding its handle bindings into the alias map in the same step.
  */
 export declare function deploymentToTarget(deployment: WorkflowDeployment): DeployTarget;
-export {};

package/oclif.manifest.json

@@ -118,7 +118,7 @@
           "type": "boolean"
         },
         "only": {
-          "description": "Limit deploy/check/diff to a single workflow definition by name. Every targeted deployment must contain it.",
+          "description": "Limit deploy/check/diff to a single workflow definition by name (deployments are selected with --deployment). Every targeted deployment must contain it.",
           "name": "only",
           "hasDynamicHelp": false,
           "multiple": false,
@@ -371,26 +371,34 @@
         "nuke"
       ],
       "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).",
+      "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). --instance <id> instead deletes one terminal instance plus its guards. Content documents are never touched. Prints a dry-run plan, then confirms (--force skips the prompt; the plan still prints).",
       "examples": [
         "<%= config.bin %> nuke --deployment plugin-dev",
-        "<%= config.bin %> nuke --tag plugin-dev --force"
+        "<%= config.bin %> nuke --tag plugin-dev --force",
+        "<%= config.bin %> nuke --instance plugin-dev.wf-instance.abc123"
       ],
       "flags": {
         "deployment": {
-          "description": "The deployment name to reset.",
+          "description": "The deployment name to reset. With --instance, narrows which deployment the instance is looked up in when its tag spans several.",
           "name": "deployment",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
         "tag": {
-          "description": "The deployment tag to reset (while it names exactly one deployment).",
+          "description": "The deployment tag to reset (while it names exactly one deployment). Not valid with --instance, which reads its tag from the instance id.",
           "name": "tag",
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
         },
+        "instance": {
+          "description": "Delete a single terminal instance by id, plus its guard docs, instead of a tag.",
+          "name": "instance",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
         "force": {
           "description": "Skip the confirmation prompt (for scripts/CI). The plan still prints.",
           "name": "force",
@@ -405,7 +413,7 @@
       "pluginName": "@sanity/workflow-cli",
       "pluginType": "core",
       "strict": true,
-      "summary": "Delete every engine-owned document for a deployment tag — the dev-period big red button.",
+      "summary": "Delete engine-owned documents — a whole deployment tag, or a single instance.",
       "isESM": true,
       "relativePath": [
         "dist",
@@ -970,5 +978,5 @@
       ]
     }
   },
-  "version": "0.23.0"
+  "version": "0.25.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanity/workflow-cli",
-  "version": "0.23.0",
+  "version": "0.25.0",
   "description": "Command-line tool for deploying, inspecting, and administering Sanity workflow definitions and instances.",
   "keywords": [
     "cli",
@@ -62,12 +62,12 @@
     "@types/node": "^24.12.4",
     "oclif": "^4.23.16",
     "vitest": "^4.1.8",
-    "@sanity/workflow-engine": "0.23.0",
-    "@sanity/workflow-engine-test": "0.23.0",
-    "@sanity/workflow-examples": "0.10.2"
+    "@sanity/workflow-engine": "0.25.0",
+    "@sanity/workflow-engine-test": "0.25.0",
+    "@sanity/workflow-examples": "0.10.4"
   },
   "peerDependencies": {
-    "@sanity/workflow-engine": "0.23.0"
+    "@sanity/workflow-engine": "0.25.0"
   },
   "oclif": {
     "bin": "sanity-workflows",