@qawolf/cli 1.36.0 → 1.38.0

package/dist/cli.js

@@ -16617,6 +16617,10 @@ var publicRunStatusValues = [
   "failed",
   "canceled"
 ];
+var publicRunSummaryStatusValues = [
+  ...publicRunStatusValues,
+  "superseded"
+];
 var makeRunSummaryFields = (ids) => ({
   completedAt: exports_iso.datetime().optional().describe("When the run finished executing. Absent while queued or running, and also absent for a terminal run that never completed execution (e.g. every flow was canceled or skipped)."),
   createdAt: exports_iso.datetime(),
@@ -16628,7 +16632,11 @@ var makeRunSummaryFields = (ids) => ({
   }).describe("The branch and commit under test. The fields are present when a deploy notification started the run, and absent for runs started another way, for example manually or with run.create."),
   needsReview: boolean2().optional().describe("True once every flow has finished its attempts and at least one failed flow still has no diagnosis, including one whose investigation carried over to a later run. `status` stays `running` until that failure is diagnosed, so a caller that is not waiting for a diagnosis can stop polling here and read the run's failed flows."),
   runId: ids.run,
-  status: _enum(publicRunStatusValues).describe("Whole-run status, and the value to gate a pipeline on. Terminal statuses are passed, failed, and canceled; poll until one is reached. `failed` means the run found a bug that is still open and serious enough to block — a lower-priority bug, or one since resolved, reads `passed`, and the per-flow diagnoses are still in `flows`. The run stays `running` while any investigation is unresolved, including one that carried over to a later run, so a terminal status always means a settled answer. `needsReview` tells such a run apart from one that is still executing.")
+  status: _enum(publicRunSummaryStatusValues).describe("Whole-run status, and the value to gate a pipeline on. Terminal statuses are passed, failed, canceled, and superseded; poll until one is reached. `failed` means the run found a bug that is still open and serious enough to block — a lower-priority bug, or one since resolved, reads `passed`, and the per-flow diagnoses are still in `flows`. The run stays `running` while any investigation is unresolved, including one that carried over to a later run, so a terminal status always means a settled answer, and `needsReview` tells such a run apart from one that is still executing. `superseded` means a newer run replaced this one before it finished: it is not a pass, this run will never change again, and the verdict belongs to the run in `supersededBy`."),
+  supersededBy: object({
+    runId: ids.run,
+    url: url().describe("Absolute URL of the replacement run's page.")
+  }).optional().describe("The run that replaced this one, present only when `status` is `superseded`. A newer deployment to the same branch and environment (and service, when the deployment named one) cancels the older run's unfinished flows and takes over. Deduplication ignores the commit, so the replacement may be testing a later commit than this run did. Only the direct replacement is named; that run can itself be superseded.")
 });
 
 // node_modules/@qawolf/api-contracts/dist/v1/deployment/didNotRunReason.js
@@ -16843,6 +16851,7 @@ var defaultIdSchemas = {
   issue: string2().min(1).describe("The id of the issue."),
   legacyTrigger: string2().min(1).describe("The id of the legacy trigger, from legacyTrigger.find."),
   run: string2().min(1).describe("The id of the run."),
+  runAttempt: string2().min(1).describe("The id of the run attempt."),
   trigger: string2().min(1).describe("The id of the trigger."),
   workspace: string2().min(1).describe("The id of the workspace.")
 };
@@ -16894,6 +16903,72 @@ var makeCreateRunContract = (ids) => {
   };
 };
 
+// node_modules/@qawolf/api-contracts/dist/v1/run/listScreenshotComparisons.js
+var maxListedScreenshotAttempts = 20;
+var makeListScreenshotComparisonsContract = (ids) => {
+  const input = object({
+    flowIds: array(ids.flow).min(1).max(100).refine((flowIds) => new Set(flowIds).size === flowIds.length, "flowIds must be unique").optional().describe("Only list the comparisons of these flows. Each flow must have a result in the run. Omit to list every failed flow of the run."),
+    runId: ids.run
+  });
+  const imageUrl = (image) => url().describe(`Signed URL of the full-size ${image} PNG. It stops working at expiresAt.`);
+  const previewUrl = (image) => url().optional().describe(`Signed URL of a JPEG copy of the ${image} image, scaled down so its long edge is at most 1568 pixels. ` + "Fetch this one to look at the image: it is small enough to view inline, while the full-size PNG can be too large. " + "It stops working at expiresAt. Absent when QA Wolf could not make the copy, for example because the full-size image is gone.");
+  const passedEnvironment = object({
+    environmentId: ids.environment,
+    lastPassedAt: exports_iso.datetime().describe("When the latest passing comparison in this environment ran.")
+  });
+  const passingElsewhere = discriminatedUnion("status", [
+    object({
+      status: literal("not-tracked").describe("QA Wolf does not record screenshot comparisons for this workspace, so it cannot tell.")
+    }),
+    object({
+      environments: array(passedEnvironment).describe("Other environments where the current baseline passed this screenshot in the last 14 days, most recent first. " + "Empty when it passed nowhere else, or when the baseline no longer exists."),
+      status: literal("tracked")
+    })
+  ]).describe("Whether the current baseline still passes in other environments. " + "A baseline that passes elsewhere points to a difference in this environment rather than an outdated baseline.");
+  const comparison = object({
+    actualPreviewUrl: previewUrl("actual"),
+    actualUrl: imageUrl("actual (the screenshot the flow took)"),
+    attemptCompletedAt: exports_iso.datetime().describe("When the run attempt that made the comparison finished."),
+    baselineStatus: _enum([
+      "unchanged",
+      "accepted",
+      "changed-since-run",
+      "deleted",
+      "unknown"
+    ]).describe('How the current baseline relates to the expected image this comparison used. "unchanged": the baseline is still the expected image. ' + `"accepted": the baseline is now this comparison's actual screenshot, because someone accepted it, so a reattempt should pass. ` + '"changed-since-run": someone replaced the baseline with another image after this run, so rerun the flow before deciding anything. ' + '"deleted": the baseline no longer exists, and the next run will save its screenshot as the new baseline. ' + `"unknown": the run's copy of the expected image is gone, so QA Wolf cannot compare.`),
+    comparisonId: string2().describe("Identifies this comparison: the run attempt id and the position of the comparison in that attempt."),
+    diffPreviewUrl: previewUrl("diff"),
+    diffUrl: imageUrl("diff (the pixels that differ are highlighted)"),
+    expectedPreviewUrl: previewUrl("expected"),
+    expectedUrl: imageUrl("expected (the baseline as it was when the flow ran)"),
+    filePath: string2().optional().describe("The flow file that made the comparison."),
+    flowId: ids.flow,
+    lineNumber: number2().int().optional().describe("The line of filePath that made the comparison."),
+    name: string2().describe("The screenshot name the flow passed to toHaveScreenshot. The baseline is stored as _screenshots_/<name>.png in team storage."),
+    passingElsewhere,
+    runAttemptId: string2(),
+    similarity: number2().describe("How much of the actual image matches the expected image, in percent."),
+    sizeMismatch: boolean2().describe("The actual and expected images have different dimensions. That fails the comparison whatever the pixels show, and similarity reads 0.")
+  });
+  const output = object({
+    comparisons: array(comparison).describe(`Each screenshot comparison that failed its flow, from the ${maxListedScreenshotAttempts} most recent failed attempts of the selected flows, oldest attempt first.`),
+    expiresAt: exports_iso.datetime().describe("When the image URLs stop working. Call run.listScreenshotComparisons again for fresh ones after it."),
+    truncated: boolean2().describe(`True when the selected flows have more than ${maxListedScreenshotAttempts} failed attempts. Only the ${maxListedScreenshotAttempts} most recent are listed, and the older attempts cannot be listed.`)
+  });
+  return {
+    annotations: {
+      destructiveHint: false,
+      openWorldHint: false,
+      readOnlyHint: false
+    },
+    description: "List the screenshot comparisons that failed a run's flows, with the expected, actual and diff images of each. " + "Only comparisons that caused a failure are listed: a screenshot that differs within tolerance, or that differs on a line that did not fail, is left out. " + "Each comparison tells whether its baseline changed since the run and whether the baseline still passes in other environments. " + "The image URLs expire after a few minutes; fetch the preview URLs to look at the images. " + "The first call for an image makes its missing JPEG preview and keeps it in team storage, so later calls reuse it.",
+    input,
+    kind: "read",
+    name: "run.listScreenshotComparisons",
+    output
+  };
+};
+
 // node_modules/@qawolf/api-contracts/dist/v1/runner/actionSequence.js
 var maxActionsPerRequest = 10;
 var screenshotModes = ["none", "final", "each"];
@@ -18959,11 +19034,22 @@ var makeGetIssueContract = (ids) => {
 var investigationFindingStateDescription = 'What the investigation concluded about the cause. Known values: "investigating", "fixed", "fix-proposed", "reported", "report-proposed", "flake", "question" and "dismissed". New values can appear.';
 var makeInvestigationFindingSchema = (ids) => object({
   actual: string2().optional(),
-  commitHash: string2().optional(),
+  commitHash: string2().optional().describe("The commit of a commit fix. Same as `fix.commitHash`."),
   decidedBy: _enum(["agent", "user"]).optional().describe("Who decided: the AI on its own, or a person who approved or dismissed it. Absent until someone decides."),
   disputeReason: string2().optional().describe("Why a person disputed what the AI did. Present on a proposal the AI made again after that dispute."),
   expected: string2().optional(),
   findingId: string2(),
+  fix: discriminatedUnion("type", [
+    object({
+      commitHash: string2().describe("The commit that changes the flow code."),
+      type: literal("commit")
+    }),
+    object({
+      baselineChangeId: string2().optional().describe('The baseline change that made the new screenshot the baseline, on a "fixed" finding. `run restoreScreenshotBaseline` undoes it.'),
+      comparisonId: string2().describe("The failed screenshot comparison whose new screenshot becomes the baseline, as `run listScreenshotComparisons` names it."),
+      type: literal("baseline")
+    })
+  ]).optional().describe('The fix of a "fixed" or "fix-proposed" finding: a commit to the flow code, or a new screenshot baseline.'),
   flowIds: array(ids.flow),
   headline: string2().optional(),
   issueId: ids.issue.optional(),
@@ -18974,8 +19060,9 @@ var makeInvestigationFindingSchema = (ids) => object({
     answers: array(object({
       description: string2().optional(),
       title: string2(),
-      value: string2().describe('What choosing this answer means. Known values: "apply", "dismiss", "report", "maintenance" and "bug". New values can appear.')
+      value: string2().describe('What choosing this answer means. Known values: "apply", "dismiss", "report", "maintenance", "bug" and "baseline". New values can appear.')
     })),
+    comparisonId: string2().optional().describe('The failed screenshot comparison a screenshot question is about, as `run listScreenshotComparisons` names it. Its answers are "bug" (the old screenshot is right), "maintenance" (both are right) and "baseline" (the new screenshot is right).'),
     text: string2()
   }).optional().describe("The question waiting for a person, with the answers offered."),
   response: object({
@@ -18995,6 +19082,7 @@ var makeInvestigationFindingSchema = (ids) => object({
 var makeGetInvestigationContract = (ids) => {
   const input = object({ runId: ids.run });
   const output = resource({
+    baselineChanges: _enum(["automatic", "needs-approval"]).describe('How the investigation can make a new screenshot the baseline. "automatic": it can accept a baseline on its own. ' + '"needs-approval": it proposes the baseline on a fix-proposed finding, and accepts it only after a person applies the proposal.'),
     findings: array(makeInvestigationFindingSchema(ids)),
     runId: ids.run,
     sessionId: ids.chatSession.optional().describe("The investigation session. Absent when the run has none."),
@@ -19045,7 +19133,7 @@ var makeAddFlowsToIssueContract = (ids) => {
 // node_modules/@qawolf/api-contracts/dist/v1/issue/create.js
 var makeCreateIssueContract = (ids) => {
   const commonFields = {
-    description: string2().optional().describe("The issue description as plain text; each line becomes a paragraph. Markdown is not parsed."),
+    description: string2().optional().describe("The issue description in Markdown, which is stored as rich text. Text without Markdown is stored as written, one paragraph per line."),
     name: string2().trim().min(1).max(255),
     priority: issuePrioritySchema.optional().describe('Defaults to "unprioritized" for bug reports and coverage requests.'),
     workspaceId: ids.workspace.optional().describe("The workspace to create the issue in. Required when authenticating with an organization or user API key.")
@@ -19088,7 +19176,8 @@ var makeCreateIssueContract = (ids) => {
 // node_modules/@qawolf/api-contracts/dist/v1/issue/removeFlows.js
 var makeRemoveFlowsFromIssueContract = (ids) => {
   const input = object({
-    flowIds: array(ids.flow).min(1).max(300).refine((flowIds) => new Set(flowIds).size === flowIds.length, "flowIds must be unique").describe("The flows the coverage request no longer covers."),
+    environmentId: ids.environment.optional().describe("The environment whose bug or maintenance reproductions to remove. Required when a selected flow is linked in more than one environment."),
+    flowIds: array(ids.flow).min(1).max(300).refine((flowIds) => new Set(flowIds).size === flowIds.length, "flowIds must be unique").describe("The flows to remove from the issue."),
     issueId: ids.issue
   });
   const output = object({
@@ -19097,10 +19186,10 @@ var makeRemoveFlowsFromIssueContract = (ids) => {
   return {
     annotations: {
       destructiveHint: true,
-      openWorldHint: false,
+      openWorldHint: true,
       readOnlyHint: false
     },
-    description: "Remove flows from a coverage request owned by the caller's team. " + "Flows the request does not cover are left alone. " + "Bug and maintenance reports link to flows through the runs that reproduce them, so their flows cannot be set directly.",
+    description: "Remove flows from a coverage request or remove bug/maintenance reproductions in an environment. " + "Unlinked flows are left alone. Reports auto-close when no active reproductions remain and auto-close is enabled. " + "For reports, omit environmentId only when each selected flow is linked in at most one environment.",
     input,
     kind: "write",
     name: "issue.removeFlows",
@@ -19110,7 +19199,7 @@ var makeRemoveFlowsFromIssueContract = (ids) => {
 
 // node_modules/@qawolf/api-contracts/dist/v1/issue/update.js
 var makeUpdateIssueContract = (ids) => {
-  const descriptionSchema = string2().describe("The issue description as plain text; each line becomes a paragraph. Markdown is not parsed.");
+  const descriptionSchema = string2().describe("The issue description in Markdown, which is stored as rich text. Text without Markdown is stored as written, one paragraph per line.");
   const nameSchema = string2().trim().min(1).max(255);
   const input = object({
     description: descriptionSchema.optional(),
@@ -19260,6 +19349,49 @@ var makeLegacyTriggerContracts = (ids) => ({
   resume: makeResumeLegacyTriggerContract(ids)
 });
 
+// node_modules/@qawolf/api-contracts/dist/v1/run/investigationSessionId.js
+var investigationSessionId = string2().trim().min(1).max(100).optional();
+
+// node_modules/@qawolf/api-contracts/dist/v1/run/acceptScreenshotBaseline.js
+var makeAcceptScreenshotBaselineContract = (ids) => {
+  const input = object({
+    chatSessionId: investigationSessionId.describe("The chat session of the investigation that accepts the baseline. A workspace or organization API key acts as an automation, so it must send the session that investigates the run. A person's call ignores it."),
+    comparisonId: string2().trim().min(1).max(100).describe("The failed screenshot comparison whose new screenshot becomes the baseline, as `run.listScreenshotComparisons` names it."),
+    runId: ids.run
+  });
+  const output = discriminatedUnion("outcome", [
+    object({
+      baselineChangeId: string2().describe("The baseline change. Record it on the fixed finding, and pass it to `run.restoreScreenshotBaseline` with this runId to put the old baseline back."),
+      name: string2().describe("The screenshot name whose baseline changed."),
+      outcome: literal("accepted").describe("The new screenshot is now the baseline. The old baseline is kept, so the change can be restored.")
+    }),
+    object({
+      outcome: literal("baseline-changed").describe("The baseline is no longer the one the run compared with: someone changed or deleted it since. Nothing changed. List the comparisons again to see the current baseline.")
+    }),
+    object({
+      outcome: literal("needs-approval").describe("Only a person can approve this change. Nothing changed. Propose the new baseline on a fix-proposed finding and wait for a person to apply it.")
+    }),
+    object({
+      outcome: literal("not-investigation-session").describe("An API key that is not a person's can change a baseline only as the investigation of the run, and chatSessionId is missing or is not the session that investigates the run. Nothing changed.")
+    }),
+    object({
+      outcome: literal("nothing-to-accept").describe("The comparison did not fail, or has no new screenshot to accept. Nothing changed.")
+    })
+  ]);
+  return {
+    annotations: {
+      destructiveHint: true,
+      openWorldHint: false,
+      readOnlyHint: false
+    },
+    description: "Make the new screenshot of a failed screenshot comparison the baseline, so later runs compare with it. " + "Use it only when the difference is an intended change of the app, not a bug, noise, or a page that was not ready. " + "Every later run of every environment of the workspace compares with the new baseline. " + "Refuses without changing anything when the baseline changed since the run.",
+    input,
+    kind: "write",
+    name: "run.acceptScreenshotBaseline",
+    output
+  };
+};
+
 // node_modules/@qawolf/api-contracts/dist/v1/run/diagnose.js
 var makeDiagnoseRunContract = (ids) => {
   const input = object({
@@ -19276,7 +19408,7 @@ var makeDiagnoseRunContract = (ids) => {
       openWorldHint: true,
       readOnlyHint: false
     },
-    description: "Diagnose failed flows in a run as reproductions of a bug or maintenance report owned by the caller's team. " + "The issue's type selects the diagnosis. " + "Each flow must have failed in the run. " + "A flow that is already diagnosed moves to this issue. " + "The diagnosis appears on the run, and the reproduction appears under the issue's reproductions. " + "Coverage requests cannot be diagnosed; use issue.addFlows to cover flows instead.",
+    description: "Diagnose failed flows in a run as reproductions of a bug or maintenance report owned by the caller's team. " + "The issue's type selects the diagnosis. " + "Each flow must have failed in the run. " + "A flow that is already diagnosed in the run moves to this issue, and may stay linked to other open reports. " + "The diagnosis appears on the run, and the reproduction appears under the issue's reproductions. " + "Coverage requests cannot be diagnosed; use issue.addFlows to cover flows instead.",
     input,
     kind: "write",
     name: "run.diagnose",
@@ -19294,9 +19426,11 @@ var makeFindRunsContract = (ids) => {
   });
   const output = object({
     nextCursor: nextCursorSchema,
-    runs: array(resource(makeRunSummaryFields(ids), {
-      urlFieldDescription: "Absolute URL of the run page."
-    })).describe("The environment's runs, newest first. Per-flow results are available via run.get.")
+    runs: array(resource({
+      ...makeRunSummaryFields(ids),
+      failedAttemptCount: number2().int().nonnegative().optional(),
+      hasFailedAttempts: boolean2().optional()
+    }, { urlFieldDescription: "Absolute URL of the run page." })).describe("The environment's runs, newest first. Per-flow results are available via run.get.")
   });
   return {
     annotations: {
@@ -19304,7 +19438,7 @@ var makeFindRunsContract = (ids) => {
       openWorldHint: false,
       readOnlyHint: true
     },
-    description: "List an environment's recent runs, newest first.",
+    description: "List an environment's recent runs, newest first, including failed-attempt discovery metadata.",
     input,
     kind: "read",
     name: "run.find",
@@ -19312,6 +19446,22 @@ var makeFindRunsContract = (ids) => {
   };
 };
 
+// node_modules/@qawolf/api-contracts/dist/v1/run/flowFailure.js
+var makeFlowFailureSchema = (ids) => {
+  const diagnosis = object({
+    issueId: ids.issue,
+    type: _enum(["bug", "maintenance"])
+  }).optional().describe("QA Wolf's investigation verdict for the failure: `bug` means the " + "application is broken, `maintenance` means the test needed an " + "update and the failure does not indicate an application problem. " + "Absent until the investigation reaches a verdict, and absent when " + "the flow was opted out of investigation. Pass issueId to issue.get " + "for details.");
+  const optedOutOfInvestigation = object({
+    by: _enum(["user", "system"]).describe("Who stopped the investigation: `user` is a person, in the app or " + "with a user API key, or the workspace's automation user for a " + "team or organization API key, for example through " + "run.optOutOfInvestigation; `system` is QA Wolf, when the " + "investigation expired.")
+  }).optional().describe('Present when the failure was marked "do not investigate" (DNI): ' + "it will get no bug or maintenance verdict.");
+  return object({
+    diagnosis,
+    error: string2(),
+    optedOutOfInvestigation
+  });
+};
+
 // node_modules/@qawolf/api-contracts/dist/v1/run/get.js
 var makeGetRunContract = (ids) => {
   const flowStatus = _enum(publicRunStatusValues);
@@ -19328,6 +19478,7 @@ var makeGetRunContract = (ids) => {
   const automatedAttempt = discriminatedUnion("status", [
     object({
       ...artifactUrls,
+      attemptId: ids.runAttempt.optional(),
       completedAt: exports_iso.datetime(),
       kind: automatedKind,
       startedAt: exports_iso.datetime(),
@@ -19335,12 +19486,14 @@ var makeGetRunContract = (ids) => {
     }),
     object({
       ...artifactUrls,
+      attemptId: ids.runAttempt.optional(),
       completedAt: exports_iso.datetime(),
       kind: automatedKind,
       startedAt: exports_iso.datetime().optional().describe("Absent when the attempt failed before it could start."),
       status: literal("failed")
     }),
     object({
+      attemptId: ids.runAttempt.optional(),
       completedAt: exports_iso.datetime().optional(),
       kind: automatedKind,
       startedAt: exports_iso.datetime().optional(),
@@ -19348,6 +19501,7 @@ var makeGetRunContract = (ids) => {
     })
   ]);
   const manualAttempt = object({
+    attemptId: ids.runAttempt.optional(),
     completedAt: exports_iso.datetime(),
     kind: literal("manual").describe("The attempt ran by hand in the Wolf Browser."),
     startedAt: exports_iso.datetime(),
@@ -19355,16 +19509,9 @@ var makeGetRunContract = (ids) => {
   });
   const attempt = union([automatedAttempt, manualAttempt]);
   const attempts = array(attempt).optional().describe("The flow's finished execution attempts, oldest first, including " + "manual Wolf Browser attempts. Present once at least one attempt has " + "finished, so a flow that passed after retries also lists its failed " + "attempts. Artifact URLs appear only on automated attempts that " + "reached a verdict, stay valid for at least a day (call run.get " + "again for fresh ones), and can return 404 when the attempt did not " + "produce that artifact.");
-  const diagnosis = object({
-    issueId: ids.issue,
-    type: _enum(["bug", "maintenance"])
-  }).optional().describe("QA Wolf's investigation verdict for the failure: `bug` means the " + "application is broken, `maintenance` means the test needed an " + "update and the failure does not indicate an application problem. " + "Absent until the investigation reaches a verdict. Pass issueId to " + "issue.get for details.");
   const failedFlow = object({
     attempts,
-    failure: object({
-      diagnosis,
-      error: string2()
-    }),
+    failure: makeFlowFailureSchema(ids),
     flowId: ids.flow,
     name: string2(),
     status: literal("failed")
@@ -19396,6 +19543,107 @@ var makeGetRunContract = (ids) => {
   };
 };
 
+// node_modules/@qawolf/api-contracts/dist/v1/run/getAttemptArtifacts.js
+var makeGetRunAttemptArtifactsContract = (ids) => {
+  const input = object({ attemptId: ids.runAttempt });
+  const attemptStatus = _enum([
+    "passed",
+    "failed",
+    "canceled",
+    "aborted",
+    "skipped"
+  ]);
+  const attemptNeighbor = object({
+    attemptId: ids.runAttempt,
+    status: attemptStatus
+  });
+  const response = object({
+    flowId: ids.flow,
+    flowStatus: _enum(publicRunStatusValues),
+    retryContext: object({
+      currentOrdinal: number2().int().min(1),
+      next: attemptNeighbor.optional(),
+      previous: attemptNeighbor.optional(),
+      total: number2().int().min(1)
+    }),
+    runId: ids.run,
+    runStatus: _enum(publicRunSummaryStatusValues)
+  });
+  const attempt = object({
+    attemptId: ids.runAttempt,
+    completedAt: exports_iso.datetime().optional(),
+    createdAt: exports_iso.datetime(),
+    error: string2().optional(),
+    startedAt: exports_iso.datetime().optional()
+  });
+  const output = discriminatedUnion("artifactStatus", [
+    response.extend({
+      artifacts: object({
+        logsUrl: url().optional(),
+        traceUrl: url().optional(),
+        videoUrl: url().optional()
+      }),
+      artifactStatus: literal("signed"),
+      attempt: attempt.extend({
+        kind: literal("automated"),
+        status: attemptStatus
+      })
+    }),
+    response.extend({
+      artifacts: object({}).strict(),
+      artifactStatus: literal("signing-failed"),
+      attempt: attempt.extend({
+        kind: literal("automated"),
+        status: attemptStatus
+      })
+    }),
+    response.extend({
+      artifacts: object({}).strict(),
+      artifactStatus: literal("not-captured"),
+      attempt: attempt.extend({
+        kind: literal("manual"),
+        status: literal("passed")
+      })
+    })
+  ]);
+  return {
+    annotations: {
+      destructiveHint: false,
+      openWorldHint: false,
+      readOnlyHint: true
+    },
+    description: "Get metadata and signed artifact URLs for one finished run attempt.",
+    input,
+    kind: "read",
+    name: "run.getAttemptArtifacts",
+    output
+  };
+};
+
+// node_modules/@qawolf/api-contracts/dist/v1/run/optOutOfInvestigation.js
+var makeOptOutOfInvestigationRunContract = (ids) => {
+  const input = object({
+    flowIds: array(ids.flow).min(1).max(100).refine((flowIds) => new Set(flowIds).size === flowIds.length, "flowIds must be unique").describe("The failed flows to stop investigating. Every named flow must be " + "eligible or the whole request is rejected."),
+    runId: ids.run
+  });
+  const output = resource({
+    optedOutFlowIds: array(ids.flow).describe("The flows that no longer need investigation."),
+    runId: ids.run
+  }, { urlFieldDescription: "Absolute URL of the run page." });
+  return {
+    annotations: {
+      destructiveHint: true,
+      openWorldHint: true,
+      readOnlyHint: false
+    },
+    description: 'Mark failed flows in a run as "do not investigate" (DNI): the failures need no bug or maintenance report. ' + "Each flow must have failed in the run and still be under investigation. " + "A flow that already has a diagnosis cannot be opted out. " + "A team or organization key records the opt-out as the workspace's automation user. " + "To link a failure to a report instead, use run.diagnose.",
+    input,
+    kind: "write",
+    name: "run.optOutOfInvestigation",
+    output
+  };
+};
+
 // node_modules/@qawolf/api-contracts/dist/v1/run/reattempt.js
 var makeReattemptRunContract = (ids) => {
   const input = object({
@@ -19420,6 +19668,45 @@ var makeReattemptRunContract = (ids) => {
   };
 };
 
+// node_modules/@qawolf/api-contracts/dist/v1/run/restoreScreenshotBaseline.js
+var makeRestoreScreenshotBaselineContract = (ids) => {
+  const input = object({
+    baselineChangeId: string2().trim().min(1).max(100).describe("The baseline change to undo, as `run.acceptScreenshotBaseline` returned it for this run."),
+    chatSessionId: investigationSessionId.describe("The chat session of the investigation that restores the baseline. A workspace or organization API key acts as an automation, so it must send the session that investigates the run. A person's call ignores it."),
+    runId: ids.run
+  });
+  const output = discriminatedUnion("outcome", [
+    object({
+      name: string2().describe("The screenshot name whose baseline changed."),
+      outcome: literal("restored").describe("The baseline the change replaced is the baseline again.")
+    }),
+    object({
+      outcome: literal("baseline-changed").describe("The baseline changed again after this change, so restoring it would undo someone else's change. Nothing changed.")
+    }),
+    object({
+      outcome: literal("needs-dispute").describe("Only a person can restore this change, unless a person disputed the finding that made it. Nothing changed.")
+    }),
+    object({
+      outcome: literal("not-investigation-session").describe("An API key that is not a person's can change a baseline only as the investigation of the run, and chatSessionId is missing or is not the session that investigates the run. Nothing changed.")
+    }),
+    object({
+      outcome: literal("nothing-to-restore").describe("The change was already restored, the name had no baseline before it, or the kept copy of the old baseline is missing or is not the baseline the change replaced. Nothing changed.")
+    })
+  ]);
+  return {
+    annotations: {
+      destructiveHint: true,
+      openWorldHint: false,
+      readOnlyHint: false
+    },
+    description: "Undo a screenshot baseline change that accepted a failed comparison of the run: put back the baseline it replaced, so later runs compare with the old baseline again. " + "Use it when a person disputes a baseline the AI accepted. " + "Refuses without changing anything when the baseline changed again since.",
+    input,
+    kind: "write",
+    name: "run.restoreScreenshotBaseline",
+    output
+  };
+};
+
 // node_modules/@qawolf/api-contracts/dist/v1/run/stop.js
 var makeStopRunContract = (ids) => {
   const input = object({ runId: ids.run });
@@ -19740,7 +20027,7 @@ var makeRunFlowOnRunnerContract = (ids) => {
     env: runEnvironmentSchema.optional().describe("Environment variables to make available to the run."),
     environmentId: ids.environmentRef.optional().describe("A QA Wolf environment whose variables the run is given, by id or alias. QA Wolf reads and decrypts them itself, so they never travel in the request and the count and length limits on `env` do not apply to them. Send this or `env`, not both."),
     files: runFilesSchema.describe("Every file the run needs keyed by its path — the flow file, everything it imports, package.json and tsconfig.json. A runner holds no copy of your project, so what runs is exactly what is sent here."),
-    flowId: ids.flow.optional().describe("The QA Wolf flow this run is for. The run then sees it as `QAWOLF_WORKFLOW_ID`, the same value a platform run of that flow sees, so fixtures named and cleaned up by it match across both. Omit it when the flow is not in QA Wolf yet, and the run has no `QAWOLF_WORKFLOW_ID`."),
+    flowId: ids.flow.optional().describe("The QA Wolf flow this run is for. The run then sees it as `QAWOLF_WORKFLOW_ID`, the same value a platform run of that flow sees, so fixtures named and cleaned up by it match across both. Omitted, the flow whose file is at `entryPointPath` on the named environment's flow-code branch stands in; a file not in QA Wolf yet, or a run given no environment, leaves the run with no `QAWOLF_WORKFLOW_ID`."),
     id: runnerIdSchema.describe("Id of the runner to run the flow on."),
     selection: runSelectionSchema.optional().describe("Run only these lines, inside the page the runner is already on, instead of running the whole flow from a fresh browser. Omit to run the whole entry point."),
     unchangedFiles: unchangedFilesSchema.optional().describe("Files this runner already holds from an earlier run, keyed by path with a hex SHA-256 of the content it should hold. Send this to make `files` only what changed. The runner refuses with `needs-full-sync` if it holds none of a referenced path, so it never runs something other than what was asked for. Omit it to send every file."),
@@ -19956,7 +20243,11 @@ var makeListTagsContract = (ids) => {
 
 // node_modules/@qawolf/api-contracts/dist/v1/index.js
 var makeContractsV1 = (ids) => {
-  const resolvedIds = { ...defaultIdSchemas, ...ids };
+  const resolvedIds = {
+    ...defaultIdSchemas,
+    ...ids,
+    runAttempt: ids.runAttempt ?? defaultIdSchemas.runAttempt
+  };
   return {
     agent: {
       get: makeAgentGetContract(resolvedIds),
@@ -20003,11 +20294,16 @@ var makeContractsV1 = (ids) => {
     },
     legacyTrigger: makeLegacyTriggerContracts(resolvedIds),
     run: {
+      acceptScreenshotBaseline: makeAcceptScreenshotBaselineContract(resolvedIds),
       create: makeCreateRunContract(resolvedIds),
       diagnose: makeDiagnoseRunContract(resolvedIds),
       find: makeFindRunsContract(resolvedIds),
       get: makeGetRunContract(resolvedIds),
+      getAttemptArtifacts: makeGetRunAttemptArtifactsContract(resolvedIds),
+      listScreenshotComparisons: makeListScreenshotComparisonsContract(resolvedIds),
+      optOutOfInvestigation: makeOptOutOfInvestigationRunContract(resolvedIds),
       reattempt: makeReattemptRunContract(resolvedIds),
+      restoreScreenshotBaseline: makeRestoreScreenshotBaselineContract(resolvedIds),
       stop: makeStopRunContract(resolvedIds)
     },
     runner: makeRunnerContracts(resolvedIds),
@@ -22524,7 +22820,7 @@ function startUpdateCheck(deps) {
 // package.json
 var package_default = {
   name: "@qawolf/cli",
-  version: "1.36.0",
+  version: "1.38.0",
   description: "Run and manage QA Wolf flows from the terminal, CI, or an AI agent",
   keywords: [
     "automation",
@@ -22595,7 +22891,7 @@ var package_default = {
     "@clack/prompts": "1.5.1",
     "@napi-rs/keyring": "1.3.0",
     "@oxc-node/core": "0.1.0",
-    "@qawolf/api-contracts": "0.73.0",
+    "@qawolf/api-contracts": "0.77.0",
     "@qawolf/emails": "1.1.1",
     "@qawolf/flow-targets": "1.0.0",
     "@qawolf/flows": "0.1.4",
@@ -38846,4 +39142,4 @@ createProgram({ signals }).parseAsync().catch(() => {
     process.exitCode = 1;
 }).finally(() => exitWhenIdle(typeof process.exitCode === "number" ? process.exitCode : 0));
 
-//# debugId=9A39ADF2531708B264756E2164756E21
+//# debugId=4535AB8728B9D01A64756E2164756E21

package/dist/runner-sdk.js

@@ -6979,6 +6979,10 @@ var publicRunStatusValues = [
   "failed",
   "canceled"
 ];
+var publicRunSummaryStatusValues = [
+  ...publicRunStatusValues,
+  "superseded"
+];
 var makeRunSummaryFields = (ids) => ({
   completedAt: exports_iso.datetime().optional().describe("When the run finished executing. Absent while queued or running, and also absent for a terminal run that never completed execution (e.g. every flow was canceled or skipped)."),
   createdAt: exports_iso.datetime(),
@@ -6990,7 +6994,11 @@ var makeRunSummaryFields = (ids) => ({
   }).describe("The branch and commit under test. The fields are present when a deploy notification started the run, and absent for runs started another way, for example manually or with run.create."),
   needsReview: boolean2().optional().describe("True once every flow has finished its attempts and at least one failed flow still has no diagnosis, including one whose investigation carried over to a later run. `status` stays `running` until that failure is diagnosed, so a caller that is not waiting for a diagnosis can stop polling here and read the run's failed flows."),
   runId: ids.run,
-  status: _enum(publicRunStatusValues).describe("Whole-run status, and the value to gate a pipeline on. Terminal statuses are passed, failed, and canceled; poll until one is reached. `failed` means the run found a bug that is still open and serious enough to block — a lower-priority bug, or one since resolved, reads `passed`, and the per-flow diagnoses are still in `flows`. The run stays `running` while any investigation is unresolved, including one that carried over to a later run, so a terminal status always means a settled answer. `needsReview` tells such a run apart from one that is still executing.")
+  status: _enum(publicRunSummaryStatusValues).describe("Whole-run status, and the value to gate a pipeline on. Terminal statuses are passed, failed, canceled, and superseded; poll until one is reached. `failed` means the run found a bug that is still open and serious enough to block — a lower-priority bug, or one since resolved, reads `passed`, and the per-flow diagnoses are still in `flows`. The run stays `running` while any investigation is unresolved, including one that carried over to a later run, so a terminal status always means a settled answer, and `needsReview` tells such a run apart from one that is still executing. `superseded` means a newer run replaced this one before it finished: it is not a pass, this run will never change again, and the verdict belongs to the run in `supersededBy`."),
+  supersededBy: object({
+    runId: ids.run,
+    url: url().describe("Absolute URL of the replacement run's page.")
+  }).optional().describe("The run that replaced this one, present only when `status` is `superseded`. A newer deployment to the same branch and environment (and service, when the deployment named one) cancels the older run's unfinished flows and takes over. Deduplication ignores the commit, so the replacement may be testing a later commit than this run did. Only the direct replacement is named; that run can itself be superseded.")
 });
 
 // node_modules/@qawolf/api-contracts/dist/v1/deployment/didNotRunReason.js
@@ -7205,6 +7213,7 @@ var defaultIdSchemas = {
   issue: string2().min(1).describe("The id of the issue."),
   legacyTrigger: string2().min(1).describe("The id of the legacy trigger, from legacyTrigger.find."),
   run: string2().min(1).describe("The id of the run."),
+  runAttempt: string2().min(1).describe("The id of the run attempt."),
   trigger: string2().min(1).describe("The id of the trigger."),
   workspace: string2().min(1).describe("The id of the workspace.")
 };
@@ -7256,6 +7265,72 @@ var makeCreateRunContract = (ids) => {
   };
 };
 
+// node_modules/@qawolf/api-contracts/dist/v1/run/listScreenshotComparisons.js
+var maxListedScreenshotAttempts = 20;
+var makeListScreenshotComparisonsContract = (ids) => {
+  const input = object({
+    flowIds: array(ids.flow).min(1).max(100).refine((flowIds) => new Set(flowIds).size === flowIds.length, "flowIds must be unique").optional().describe("Only list the comparisons of these flows. Each flow must have a result in the run. Omit to list every failed flow of the run."),
+    runId: ids.run
+  });
+  const imageUrl = (image) => url().describe(`Signed URL of the full-size ${image} PNG. It stops working at expiresAt.`);
+  const previewUrl = (image) => url().optional().describe(`Signed URL of a JPEG copy of the ${image} image, scaled down so its long edge is at most 1568 pixels. ` + "Fetch this one to look at the image: it is small enough to view inline, while the full-size PNG can be too large. " + "It stops working at expiresAt. Absent when QA Wolf could not make the copy, for example because the full-size image is gone.");
+  const passedEnvironment = object({
+    environmentId: ids.environment,
+    lastPassedAt: exports_iso.datetime().describe("When the latest passing comparison in this environment ran.")
+  });
+  const passingElsewhere = discriminatedUnion("status", [
+    object({
+      status: literal("not-tracked").describe("QA Wolf does not record screenshot comparisons for this workspace, so it cannot tell.")
+    }),
+    object({
+      environments: array(passedEnvironment).describe("Other environments where the current baseline passed this screenshot in the last 14 days, most recent first. " + "Empty when it passed nowhere else, or when the baseline no longer exists."),
+      status: literal("tracked")
+    })
+  ]).describe("Whether the current baseline still passes in other environments. " + "A baseline that passes elsewhere points to a difference in this environment rather than an outdated baseline.");
+  const comparison = object({
+    actualPreviewUrl: previewUrl("actual"),
+    actualUrl: imageUrl("actual (the screenshot the flow took)"),
+    attemptCompletedAt: exports_iso.datetime().describe("When the run attempt that made the comparison finished."),
+    baselineStatus: _enum([
+      "unchanged",
+      "accepted",
+      "changed-since-run",
+      "deleted",
+      "unknown"
+    ]).describe('How the current baseline relates to the expected image this comparison used. "unchanged": the baseline is still the expected image. ' + `"accepted": the baseline is now this comparison's actual screenshot, because someone accepted it, so a reattempt should pass. ` + '"changed-since-run": someone replaced the baseline with another image after this run, so rerun the flow before deciding anything. ' + '"deleted": the baseline no longer exists, and the next run will save its screenshot as the new baseline. ' + `"unknown": the run's copy of the expected image is gone, so QA Wolf cannot compare.`),
+    comparisonId: string2().describe("Identifies this comparison: the run attempt id and the position of the comparison in that attempt."),
+    diffPreviewUrl: previewUrl("diff"),
+    diffUrl: imageUrl("diff (the pixels that differ are highlighted)"),
+    expectedPreviewUrl: previewUrl("expected"),
+    expectedUrl: imageUrl("expected (the baseline as it was when the flow ran)"),
+    filePath: string2().optional().describe("The flow file that made the comparison."),
+    flowId: ids.flow,
+    lineNumber: number2().int().optional().describe("The line of filePath that made the comparison."),
+    name: string2().describe("The screenshot name the flow passed to toHaveScreenshot. The baseline is stored as _screenshots_/<name>.png in team storage."),
+    passingElsewhere,
+    runAttemptId: string2(),
+    similarity: number2().describe("How much of the actual image matches the expected image, in percent."),
+    sizeMismatch: boolean2().describe("The actual and expected images have different dimensions. That fails the comparison whatever the pixels show, and similarity reads 0.")
+  });
+  const output = object({
+    comparisons: array(comparison).describe(`Each screenshot comparison that failed its flow, from the ${maxListedScreenshotAttempts} most recent failed attempts of the selected flows, oldest attempt first.`),
+    expiresAt: exports_iso.datetime().describe("When the image URLs stop working. Call run.listScreenshotComparisons again for fresh ones after it."),
+    truncated: boolean2().describe(`True when the selected flows have more than ${maxListedScreenshotAttempts} failed attempts. Only the ${maxListedScreenshotAttempts} most recent are listed, and the older attempts cannot be listed.`)
+  });
+  return {
+    annotations: {
+      destructiveHint: false,
+      openWorldHint: false,
+      readOnlyHint: false
+    },
+    description: "List the screenshot comparisons that failed a run's flows, with the expected, actual and diff images of each. " + "Only comparisons that caused a failure are listed: a screenshot that differs within tolerance, or that differs on a line that did not fail, is left out. " + "Each comparison tells whether its baseline changed since the run and whether the baseline still passes in other environments. " + "The image URLs expire after a few minutes; fetch the preview URLs to look at the images. " + "The first call for an image makes its missing JPEG preview and keeps it in team storage, so later calls reuse it.",
+    input,
+    kind: "read",
+    name: "run.listScreenshotComparisons",
+    output
+  };
+};
+
 // node_modules/@qawolf/api-contracts/dist/v1/runner/actionSequence.js
 var maxActionsPerRequest = 10;
 var screenshotModes = ["none", "final", "each"];
@@ -9328,11 +9403,22 @@ var makeGetIssueContract = (ids) => {
 var investigationFindingStateDescription = 'What the investigation concluded about the cause. Known values: "investigating", "fixed", "fix-proposed", "reported", "report-proposed", "flake", "question" and "dismissed". New values can appear.';
 var makeInvestigationFindingSchema = (ids) => object({
   actual: string2().optional(),
-  commitHash: string2().optional(),
+  commitHash: string2().optional().describe("The commit of a commit fix. Same as `fix.commitHash`."),
   decidedBy: _enum(["agent", "user"]).optional().describe("Who decided: the AI on its own, or a person who approved or dismissed it. Absent until someone decides."),
   disputeReason: string2().optional().describe("Why a person disputed what the AI did. Present on a proposal the AI made again after that dispute."),
   expected: string2().optional(),
   findingId: string2(),
+  fix: discriminatedUnion("type", [
+    object({
+      commitHash: string2().describe("The commit that changes the flow code."),
+      type: literal("commit")
+    }),
+    object({
+      baselineChangeId: string2().optional().describe('The baseline change that made the new screenshot the baseline, on a "fixed" finding. `run restoreScreenshotBaseline` undoes it.'),
+      comparisonId: string2().describe("The failed screenshot comparison whose new screenshot becomes the baseline, as `run listScreenshotComparisons` names it."),
+      type: literal("baseline")
+    })
+  ]).optional().describe('The fix of a "fixed" or "fix-proposed" finding: a commit to the flow code, or a new screenshot baseline.'),
   flowIds: array(ids.flow),
   headline: string2().optional(),
   issueId: ids.issue.optional(),
@@ -9343,8 +9429,9 @@ var makeInvestigationFindingSchema = (ids) => object({
     answers: array(object({
       description: string2().optional(),
       title: string2(),
-      value: string2().describe('What choosing this answer means. Known values: "apply", "dismiss", "report", "maintenance" and "bug". New values can appear.')
+      value: string2().describe('What choosing this answer means. Known values: "apply", "dismiss", "report", "maintenance", "bug" and "baseline". New values can appear.')
     })),
+    comparisonId: string2().optional().describe('The failed screenshot comparison a screenshot question is about, as `run listScreenshotComparisons` names it. Its answers are "bug" (the old screenshot is right), "maintenance" (both are right) and "baseline" (the new screenshot is right).'),
     text: string2()
   }).optional().describe("The question waiting for a person, with the answers offered."),
   response: object({
@@ -9364,6 +9451,7 @@ var makeInvestigationFindingSchema = (ids) => object({
 var makeGetInvestigationContract = (ids) => {
   const input = object({ runId: ids.run });
   const output = resource({
+    baselineChanges: _enum(["automatic", "needs-approval"]).describe('How the investigation can make a new screenshot the baseline. "automatic": it can accept a baseline on its own. ' + '"needs-approval": it proposes the baseline on a fix-proposed finding, and accepts it only after a person applies the proposal.'),
     findings: array(makeInvestigationFindingSchema(ids)),
     runId: ids.run,
     sessionId: ids.chatSession.optional().describe("The investigation session. Absent when the run has none."),
@@ -9414,7 +9502,7 @@ var makeAddFlowsToIssueContract = (ids) => {
 // node_modules/@qawolf/api-contracts/dist/v1/issue/create.js
 var makeCreateIssueContract = (ids) => {
   const commonFields = {
-    description: string2().optional().describe("The issue description as plain text; each line becomes a paragraph. Markdown is not parsed."),
+    description: string2().optional().describe("The issue description in Markdown, which is stored as rich text. Text without Markdown is stored as written, one paragraph per line."),
     name: string2().trim().min(1).max(255),
     priority: issuePrioritySchema.optional().describe('Defaults to "unprioritized" for bug reports and coverage requests.'),
     workspaceId: ids.workspace.optional().describe("The workspace to create the issue in. Required when authenticating with an organization or user API key.")
@@ -9457,7 +9545,8 @@ var makeCreateIssueContract = (ids) => {
 // node_modules/@qawolf/api-contracts/dist/v1/issue/removeFlows.js
 var makeRemoveFlowsFromIssueContract = (ids) => {
   const input = object({
-    flowIds: array(ids.flow).min(1).max(300).refine((flowIds) => new Set(flowIds).size === flowIds.length, "flowIds must be unique").describe("The flows the coverage request no longer covers."),
+    environmentId: ids.environment.optional().describe("The environment whose bug or maintenance reproductions to remove. Required when a selected flow is linked in more than one environment."),
+    flowIds: array(ids.flow).min(1).max(300).refine((flowIds) => new Set(flowIds).size === flowIds.length, "flowIds must be unique").describe("The flows to remove from the issue."),
     issueId: ids.issue
   });
   const output = object({
@@ -9466,10 +9555,10 @@ var makeRemoveFlowsFromIssueContract = (ids) => {
   return {
     annotations: {
       destructiveHint: true,
-      openWorldHint: false,
+      openWorldHint: true,
       readOnlyHint: false
     },
-    description: "Remove flows from a coverage request owned by the caller's team. " + "Flows the request does not cover are left alone. " + "Bug and maintenance reports link to flows through the runs that reproduce them, so their flows cannot be set directly.",
+    description: "Remove flows from a coverage request or remove bug/maintenance reproductions in an environment. " + "Unlinked flows are left alone. Reports auto-close when no active reproductions remain and auto-close is enabled. " + "For reports, omit environmentId only when each selected flow is linked in at most one environment.",
     input,
     kind: "write",
     name: "issue.removeFlows",
@@ -9479,7 +9568,7 @@ var makeRemoveFlowsFromIssueContract = (ids) => {
 
 // node_modules/@qawolf/api-contracts/dist/v1/issue/update.js
 var makeUpdateIssueContract = (ids) => {
-  const descriptionSchema = string2().describe("The issue description as plain text; each line becomes a paragraph. Markdown is not parsed.");
+  const descriptionSchema = string2().describe("The issue description in Markdown, which is stored as rich text. Text without Markdown is stored as written, one paragraph per line.");
   const nameSchema = string2().trim().min(1).max(255);
   const input = object({
     description: descriptionSchema.optional(),
@@ -9629,6 +9718,49 @@ var makeLegacyTriggerContracts = (ids) => ({
   resume: makeResumeLegacyTriggerContract(ids)
 });
 
+// node_modules/@qawolf/api-contracts/dist/v1/run/investigationSessionId.js
+var investigationSessionId = string2().trim().min(1).max(100).optional();
+
+// node_modules/@qawolf/api-contracts/dist/v1/run/acceptScreenshotBaseline.js
+var makeAcceptScreenshotBaselineContract = (ids) => {
+  const input = object({
+    chatSessionId: investigationSessionId.describe("The chat session of the investigation that accepts the baseline. A workspace or organization API key acts as an automation, so it must send the session that investigates the run. A person's call ignores it."),
+    comparisonId: string2().trim().min(1).max(100).describe("The failed screenshot comparison whose new screenshot becomes the baseline, as `run.listScreenshotComparisons` names it."),
+    runId: ids.run
+  });
+  const output = discriminatedUnion("outcome", [
+    object({
+      baselineChangeId: string2().describe("The baseline change. Record it on the fixed finding, and pass it to `run.restoreScreenshotBaseline` with this runId to put the old baseline back."),
+      name: string2().describe("The screenshot name whose baseline changed."),
+      outcome: literal("accepted").describe("The new screenshot is now the baseline. The old baseline is kept, so the change can be restored.")
+    }),
+    object({
+      outcome: literal("baseline-changed").describe("The baseline is no longer the one the run compared with: someone changed or deleted it since. Nothing changed. List the comparisons again to see the current baseline.")
+    }),
+    object({
+      outcome: literal("needs-approval").describe("Only a person can approve this change. Nothing changed. Propose the new baseline on a fix-proposed finding and wait for a person to apply it.")
+    }),
+    object({
+      outcome: literal("not-investigation-session").describe("An API key that is not a person's can change a baseline only as the investigation of the run, and chatSessionId is missing or is not the session that investigates the run. Nothing changed.")
+    }),
+    object({
+      outcome: literal("nothing-to-accept").describe("The comparison did not fail, or has no new screenshot to accept. Nothing changed.")
+    })
+  ]);
+  return {
+    annotations: {
+      destructiveHint: true,
+      openWorldHint: false,
+      readOnlyHint: false
+    },
+    description: "Make the new screenshot of a failed screenshot comparison the baseline, so later runs compare with it. " + "Use it only when the difference is an intended change of the app, not a bug, noise, or a page that was not ready. " + "Every later run of every environment of the workspace compares with the new baseline. " + "Refuses without changing anything when the baseline changed since the run.",
+    input,
+    kind: "write",
+    name: "run.acceptScreenshotBaseline",
+    output
+  };
+};
+
 // node_modules/@qawolf/api-contracts/dist/v1/run/diagnose.js
 var makeDiagnoseRunContract = (ids) => {
   const input = object({
@@ -9645,7 +9777,7 @@ var makeDiagnoseRunContract = (ids) => {
       openWorldHint: true,
       readOnlyHint: false
     },
-    description: "Diagnose failed flows in a run as reproductions of a bug or maintenance report owned by the caller's team. " + "The issue's type selects the diagnosis. " + "Each flow must have failed in the run. " + "A flow that is already diagnosed moves to this issue. " + "The diagnosis appears on the run, and the reproduction appears under the issue's reproductions. " + "Coverage requests cannot be diagnosed; use issue.addFlows to cover flows instead.",
+    description: "Diagnose failed flows in a run as reproductions of a bug or maintenance report owned by the caller's team. " + "The issue's type selects the diagnosis. " + "Each flow must have failed in the run. " + "A flow that is already diagnosed in the run moves to this issue, and may stay linked to other open reports. " + "The diagnosis appears on the run, and the reproduction appears under the issue's reproductions. " + "Coverage requests cannot be diagnosed; use issue.addFlows to cover flows instead.",
     input,
     kind: "write",
     name: "run.diagnose",
@@ -9663,9 +9795,11 @@ var makeFindRunsContract = (ids) => {
   });
   const output = object({
     nextCursor: nextCursorSchema,
-    runs: array(resource(makeRunSummaryFields(ids), {
-      urlFieldDescription: "Absolute URL of the run page."
-    })).describe("The environment's runs, newest first. Per-flow results are available via run.get.")
+    runs: array(resource({
+      ...makeRunSummaryFields(ids),
+      failedAttemptCount: number2().int().nonnegative().optional(),
+      hasFailedAttempts: boolean2().optional()
+    }, { urlFieldDescription: "Absolute URL of the run page." })).describe("The environment's runs, newest first. Per-flow results are available via run.get.")
   });
   return {
     annotations: {
@@ -9673,7 +9807,7 @@ var makeFindRunsContract = (ids) => {
       openWorldHint: false,
       readOnlyHint: true
     },
-    description: "List an environment's recent runs, newest first.",
+    description: "List an environment's recent runs, newest first, including failed-attempt discovery metadata.",
     input,
     kind: "read",
     name: "run.find",
@@ -9681,6 +9815,22 @@ var makeFindRunsContract = (ids) => {
   };
 };
 
+// node_modules/@qawolf/api-contracts/dist/v1/run/flowFailure.js
+var makeFlowFailureSchema = (ids) => {
+  const diagnosis = object({
+    issueId: ids.issue,
+    type: _enum(["bug", "maintenance"])
+  }).optional().describe("QA Wolf's investigation verdict for the failure: `bug` means the " + "application is broken, `maintenance` means the test needed an " + "update and the failure does not indicate an application problem. " + "Absent until the investigation reaches a verdict, and absent when " + "the flow was opted out of investigation. Pass issueId to issue.get " + "for details.");
+  const optedOutOfInvestigation = object({
+    by: _enum(["user", "system"]).describe("Who stopped the investigation: `user` is a person, in the app or " + "with a user API key, or the workspace's automation user for a " + "team or organization API key, for example through " + "run.optOutOfInvestigation; `system` is QA Wolf, when the " + "investigation expired.")
+  }).optional().describe('Present when the failure was marked "do not investigate" (DNI): ' + "it will get no bug or maintenance verdict.");
+  return object({
+    diagnosis,
+    error: string2(),
+    optedOutOfInvestigation
+  });
+};
+
 // node_modules/@qawolf/api-contracts/dist/v1/run/get.js
 var makeGetRunContract = (ids) => {
   const flowStatus = _enum(publicRunStatusValues);
@@ -9697,6 +9847,7 @@ var makeGetRunContract = (ids) => {
   const automatedAttempt = discriminatedUnion("status", [
     object({
       ...artifactUrls,
+      attemptId: ids.runAttempt.optional(),
       completedAt: exports_iso.datetime(),
       kind: automatedKind,
       startedAt: exports_iso.datetime(),
@@ -9704,12 +9855,14 @@ var makeGetRunContract = (ids) => {
     }),
     object({
       ...artifactUrls,
+      attemptId: ids.runAttempt.optional(),
       completedAt: exports_iso.datetime(),
       kind: automatedKind,
       startedAt: exports_iso.datetime().optional().describe("Absent when the attempt failed before it could start."),
       status: literal("failed")
     }),
     object({
+      attemptId: ids.runAttempt.optional(),
       completedAt: exports_iso.datetime().optional(),
       kind: automatedKind,
       startedAt: exports_iso.datetime().optional(),
@@ -9717,6 +9870,7 @@ var makeGetRunContract = (ids) => {
     })
   ]);
   const manualAttempt = object({
+    attemptId: ids.runAttempt.optional(),
     completedAt: exports_iso.datetime(),
     kind: literal("manual").describe("The attempt ran by hand in the Wolf Browser."),
     startedAt: exports_iso.datetime(),
@@ -9724,16 +9878,9 @@ var makeGetRunContract = (ids) => {
   });
   const attempt = union([automatedAttempt, manualAttempt]);
   const attempts = array(attempt).optional().describe("The flow's finished execution attempts, oldest first, including " + "manual Wolf Browser attempts. Present once at least one attempt has " + "finished, so a flow that passed after retries also lists its failed " + "attempts. Artifact URLs appear only on automated attempts that " + "reached a verdict, stay valid for at least a day (call run.get " + "again for fresh ones), and can return 404 when the attempt did not " + "produce that artifact.");
-  const diagnosis = object({
-    issueId: ids.issue,
-    type: _enum(["bug", "maintenance"])
-  }).optional().describe("QA Wolf's investigation verdict for the failure: `bug` means the " + "application is broken, `maintenance` means the test needed an " + "update and the failure does not indicate an application problem. " + "Absent until the investigation reaches a verdict. Pass issueId to " + "issue.get for details.");
   const failedFlow = object({
     attempts,
-    failure: object({
-      diagnosis,
-      error: string2()
-    }),
+    failure: makeFlowFailureSchema(ids),
     flowId: ids.flow,
     name: string2(),
     status: literal("failed")
@@ -9765,6 +9912,107 @@ var makeGetRunContract = (ids) => {
   };
 };
 
+// node_modules/@qawolf/api-contracts/dist/v1/run/getAttemptArtifacts.js
+var makeGetRunAttemptArtifactsContract = (ids) => {
+  const input = object({ attemptId: ids.runAttempt });
+  const attemptStatus = _enum([
+    "passed",
+    "failed",
+    "canceled",
+    "aborted",
+    "skipped"
+  ]);
+  const attemptNeighbor = object({
+    attemptId: ids.runAttempt,
+    status: attemptStatus
+  });
+  const response = object({
+    flowId: ids.flow,
+    flowStatus: _enum(publicRunStatusValues),
+    retryContext: object({
+      currentOrdinal: number2().int().min(1),
+      next: attemptNeighbor.optional(),
+      previous: attemptNeighbor.optional(),
+      total: number2().int().min(1)
+    }),
+    runId: ids.run,
+    runStatus: _enum(publicRunSummaryStatusValues)
+  });
+  const attempt = object({
+    attemptId: ids.runAttempt,
+    completedAt: exports_iso.datetime().optional(),
+    createdAt: exports_iso.datetime(),
+    error: string2().optional(),
+    startedAt: exports_iso.datetime().optional()
+  });
+  const output = discriminatedUnion("artifactStatus", [
+    response.extend({
+      artifacts: object({
+        logsUrl: url().optional(),
+        traceUrl: url().optional(),
+        videoUrl: url().optional()
+      }),
+      artifactStatus: literal("signed"),
+      attempt: attempt.extend({
+        kind: literal("automated"),
+        status: attemptStatus
+      })
+    }),
+    response.extend({
+      artifacts: object({}).strict(),
+      artifactStatus: literal("signing-failed"),
+      attempt: attempt.extend({
+        kind: literal("automated"),
+        status: attemptStatus
+      })
+    }),
+    response.extend({
+      artifacts: object({}).strict(),
+      artifactStatus: literal("not-captured"),
+      attempt: attempt.extend({
+        kind: literal("manual"),
+        status: literal("passed")
+      })
+    })
+  ]);
+  return {
+    annotations: {
+      destructiveHint: false,
+      openWorldHint: false,
+      readOnlyHint: true
+    },
+    description: "Get metadata and signed artifact URLs for one finished run attempt.",
+    input,
+    kind: "read",
+    name: "run.getAttemptArtifacts",
+    output
+  };
+};
+
+// node_modules/@qawolf/api-contracts/dist/v1/run/optOutOfInvestigation.js
+var makeOptOutOfInvestigationRunContract = (ids) => {
+  const input = object({
+    flowIds: array(ids.flow).min(1).max(100).refine((flowIds) => new Set(flowIds).size === flowIds.length, "flowIds must be unique").describe("The failed flows to stop investigating. Every named flow must be " + "eligible or the whole request is rejected."),
+    runId: ids.run
+  });
+  const output = resource({
+    optedOutFlowIds: array(ids.flow).describe("The flows that no longer need investigation."),
+    runId: ids.run
+  }, { urlFieldDescription: "Absolute URL of the run page." });
+  return {
+    annotations: {
+      destructiveHint: true,
+      openWorldHint: true,
+      readOnlyHint: false
+    },
+    description: 'Mark failed flows in a run as "do not investigate" (DNI): the failures need no bug or maintenance report. ' + "Each flow must have failed in the run and still be under investigation. " + "A flow that already has a diagnosis cannot be opted out. " + "A team or organization key records the opt-out as the workspace's automation user. " + "To link a failure to a report instead, use run.diagnose.",
+    input,
+    kind: "write",
+    name: "run.optOutOfInvestigation",
+    output
+  };
+};
+
 // node_modules/@qawolf/api-contracts/dist/v1/run/reattempt.js
 var makeReattemptRunContract = (ids) => {
   const input = object({
@@ -9789,6 +10037,45 @@ var makeReattemptRunContract = (ids) => {
   };
 };
 
+// node_modules/@qawolf/api-contracts/dist/v1/run/restoreScreenshotBaseline.js
+var makeRestoreScreenshotBaselineContract = (ids) => {
+  const input = object({
+    baselineChangeId: string2().trim().min(1).max(100).describe("The baseline change to undo, as `run.acceptScreenshotBaseline` returned it for this run."),
+    chatSessionId: investigationSessionId.describe("The chat session of the investigation that restores the baseline. A workspace or organization API key acts as an automation, so it must send the session that investigates the run. A person's call ignores it."),
+    runId: ids.run
+  });
+  const output = discriminatedUnion("outcome", [
+    object({
+      name: string2().describe("The screenshot name whose baseline changed."),
+      outcome: literal("restored").describe("The baseline the change replaced is the baseline again.")
+    }),
+    object({
+      outcome: literal("baseline-changed").describe("The baseline changed again after this change, so restoring it would undo someone else's change. Nothing changed.")
+    }),
+    object({
+      outcome: literal("needs-dispute").describe("Only a person can restore this change, unless a person disputed the finding that made it. Nothing changed.")
+    }),
+    object({
+      outcome: literal("not-investigation-session").describe("An API key that is not a person's can change a baseline only as the investigation of the run, and chatSessionId is missing or is not the session that investigates the run. Nothing changed.")
+    }),
+    object({
+      outcome: literal("nothing-to-restore").describe("The change was already restored, the name had no baseline before it, or the kept copy of the old baseline is missing or is not the baseline the change replaced. Nothing changed.")
+    })
+  ]);
+  return {
+    annotations: {
+      destructiveHint: true,
+      openWorldHint: false,
+      readOnlyHint: false
+    },
+    description: "Undo a screenshot baseline change that accepted a failed comparison of the run: put back the baseline it replaced, so later runs compare with the old baseline again. " + "Use it when a person disputes a baseline the AI accepted. " + "Refuses without changing anything when the baseline changed again since.",
+    input,
+    kind: "write",
+    name: "run.restoreScreenshotBaseline",
+    output
+  };
+};
+
 // node_modules/@qawolf/api-contracts/dist/v1/run/stop.js
 var makeStopRunContract = (ids) => {
   const input = object({ runId: ids.run });
@@ -10109,7 +10396,7 @@ var makeRunFlowOnRunnerContract = (ids) => {
     env: runEnvironmentSchema.optional().describe("Environment variables to make available to the run."),
     environmentId: ids.environmentRef.optional().describe("A QA Wolf environment whose variables the run is given, by id or alias. QA Wolf reads and decrypts them itself, so they never travel in the request and the count and length limits on `env` do not apply to them. Send this or `env`, not both."),
     files: runFilesSchema.describe("Every file the run needs keyed by its path — the flow file, everything it imports, package.json and tsconfig.json. A runner holds no copy of your project, so what runs is exactly what is sent here."),
-    flowId: ids.flow.optional().describe("The QA Wolf flow this run is for. The run then sees it as `QAWOLF_WORKFLOW_ID`, the same value a platform run of that flow sees, so fixtures named and cleaned up by it match across both. Omit it when the flow is not in QA Wolf yet, and the run has no `QAWOLF_WORKFLOW_ID`."),
+    flowId: ids.flow.optional().describe("The QA Wolf flow this run is for. The run then sees it as `QAWOLF_WORKFLOW_ID`, the same value a platform run of that flow sees, so fixtures named and cleaned up by it match across both. Omitted, the flow whose file is at `entryPointPath` on the named environment's flow-code branch stands in; a file not in QA Wolf yet, or a run given no environment, leaves the run with no `QAWOLF_WORKFLOW_ID`."),
     id: runnerIdSchema.describe("Id of the runner to run the flow on."),
     selection: runSelectionSchema.optional().describe("Run only these lines, inside the page the runner is already on, instead of running the whole flow from a fresh browser. Omit to run the whole entry point."),
     unchangedFiles: unchangedFilesSchema.optional().describe("Files this runner already holds from an earlier run, keyed by path with a hex SHA-256 of the content it should hold. Send this to make `files` only what changed. The runner refuses with `needs-full-sync` if it holds none of a referenced path, so it never runs something other than what was asked for. Omit it to send every file."),
@@ -10325,7 +10612,11 @@ var makeListTagsContract = (ids) => {
 
 // node_modules/@qawolf/api-contracts/dist/v1/index.js
 var makeContractsV1 = (ids) => {
-  const resolvedIds = { ...defaultIdSchemas, ...ids };
+  const resolvedIds = {
+    ...defaultIdSchemas,
+    ...ids,
+    runAttempt: ids.runAttempt ?? defaultIdSchemas.runAttempt
+  };
   return {
     agent: {
       get: makeAgentGetContract(resolvedIds),
@@ -10372,11 +10663,16 @@ var makeContractsV1 = (ids) => {
     },
     legacyTrigger: makeLegacyTriggerContracts(resolvedIds),
     run: {
+      acceptScreenshotBaseline: makeAcceptScreenshotBaselineContract(resolvedIds),
       create: makeCreateRunContract(resolvedIds),
       diagnose: makeDiagnoseRunContract(resolvedIds),
       find: makeFindRunsContract(resolvedIds),
       get: makeGetRunContract(resolvedIds),
+      getAttemptArtifacts: makeGetRunAttemptArtifactsContract(resolvedIds),
+      listScreenshotComparisons: makeListScreenshotComparisonsContract(resolvedIds),
+      optOutOfInvestigation: makeOptOutOfInvestigationRunContract(resolvedIds),
       reattempt: makeReattemptRunContract(resolvedIds),
+      restoreScreenshotBaseline: makeRestoreScreenshotBaselineContract(resolvedIds),
       stop: makeStopRunContract(resolvedIds)
     },
     runner: makeRunnerContracts(resolvedIds),
@@ -15011,4 +15307,4 @@ export {
   createRunnerSdk
 };
 
-//# debugId=CBFC365D381BD6E864756E2164756E21
+//# debugId=6A1EED78FDDC38F864756E2164756E21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qawolf/cli",
-  "version": "1.36.0",
+  "version": "1.38.0",
   "description": "Run and manage QA Wolf flows from the terminal, CI, or an AI agent",
   "keywords": [
     "automation",
@@ -71,7 +71,7 @@
     "@clack/prompts": "1.5.1",
     "@napi-rs/keyring": "1.3.0",
     "@oxc-node/core": "0.1.0",
-    "@qawolf/api-contracts": "0.73.0",
+    "@qawolf/api-contracts": "0.77.0",
     "@qawolf/emails": "1.1.1",
     "@qawolf/flow-targets": "1.0.0",
     "@qawolf/flows": "0.1.4",

package/skills/qawolf-cli/SKILL.md

@@ -171,16 +171,21 @@ that `url`; never guess a route and never send a repository link in its place.
 | `qawolf issue create` | write | Create a bug report, maintenance report, or coverage request issue for the caller's team. A user can create a maintenance report only when they can see the workspace's maintenance reports; a team or organization API key credits it to the workspace's automation user. Link its failed flows afterwards with run.diagnose. |
 | `qawolf issue find` | read | List the team's bug reports, maintenance reports, or coverage requests, newest first. |
 | `qawolf issue get` | read | Get an issue by id. |
-| `qawolf issue removeFlows` | write | Remove flows from a coverage request owned by the caller's team. Flows the request does not cover are left alone. Bug and maintenance reports link to flows through the runs that reproduce them, so their flows cannot be set directly. |
+| `qawolf issue removeFlows` | write | Remove flows from a coverage request or remove bug/maintenance reproductions in an environment. Unlinked flows are left alone. Reports auto-close when no active reproductions remain and auto-close is enabled. For reports, omit environmentId only when each selected flow is linked in at most one environment. |
 | `qawolf issue update` | write | Update an issue owned by the caller's team. Omitted fields remain unchanged. |
 | `qawolf legacyTrigger find` | read | List a workspace's legacy per-environment triggers; trigger.find lists the current ones. For migration only; it goes when legacy triggers go. adaptiveFlowSelection becomes a generativeSuite action, which takes no tags. |
 | `qawolf legacyTrigger pause` | write | Pause one legacy trigger, the older per-environment kind, so it stops firing; use trigger.pause for a current one. Its copies in pull request environments pause too. For migration only; it goes when legacy triggers go. |
 | `qawolf legacyTrigger resume` | write | Resume one legacy trigger, the older per-environment kind; use trigger.resume for a current one. Its copies in pull request environments resume too, and a scheduled one jumps to the next upcoming slot even if it was not paused. For migration only; it goes when legacy triggers go. |
+| `qawolf run acceptScreenshotBaseline` | write | Make the new screenshot of a failed screenshot comparison the baseline, so later runs compare with it. Use it only when the difference is an intended change of the app, not a bug, noise, or a page that was not ready. Every later run of every environment of the workspace compares with the new baseline. Refuses without changing anything when the baseline changed since the run. |
 | `qawolf run create` | write | Create a run for the selected flows and/or tags in an environment. |
-| `qawolf run diagnose` | write | Diagnose failed flows in a run as reproductions of a bug or maintenance report owned by the caller's team. The issue's type selects the diagnosis. Each flow must have failed in the run. A flow that is already diagnosed moves to this issue. The diagnosis appears on the run, and the reproduction appears under the issue's reproductions. Coverage requests cannot be diagnosed; use issue.addFlows to cover flows instead. |
-| `qawolf run find` | read | List an environment's recent runs, newest first. |
+| `qawolf run diagnose` | write | Diagnose failed flows in a run as reproductions of a bug or maintenance report owned by the caller's team. The issue's type selects the diagnosis. Each flow must have failed in the run. A flow that is already diagnosed in the run moves to this issue, and may stay linked to other open reports. The diagnosis appears on the run, and the reproduction appears under the issue's reproductions. Coverage requests cannot be diagnosed; use issue.addFlows to cover flows instead. |
+| `qawolf run find` | read | List an environment's recent runs, newest first, including failed-attempt discovery metadata. |
 | `qawolf run get` | read | Get a run's status, per-flow results, links, and how many of its bugs are blocking. |
+| `qawolf run getAttemptArtifacts` | read | Get metadata and signed artifact URLs for one finished run attempt. |
+| `qawolf run listScreenshotComparisons` | read | List the screenshot comparisons that failed a run's flows, with the expected, actual and diff images of each. Only comparisons that caused a failure are listed: a screenshot that differs within tolerance, or that differs on a line that did not fail, is left out. Each comparison tells whether its baseline changed since the run and whether the baseline still passes in other environments. The image URLs expire after a few minutes; fetch the preview URLs to look at the images. The first call for an image makes its missing JPEG preview and keeps it in team storage, so later calls reuse it. |
+| `qawolf run optOutOfInvestigation` | write | Mark failed flows in a run as "do not investigate" (DNI): the failures need no bug or maintenance report. Each flow must have failed in the run and still be under investigation. A flow that already has a diagnosis cannot be opted out. A team or organization key records the opt-out as the workspace's automation user. To link a failure to a report instead, use run.diagnose. |
 | `qawolf run reattempt` | write | Request new attempts for a run's flows, in the same run. A flow is eligible once its result is failed or canceled and QA Wolf's automatic retries have finished. A fully investigated run no longer accepts reattempts. Attempts run with the latest flow code. Poll run.get for results. |
+| `qawolf run restoreScreenshotBaseline` | write | Undo a screenshot baseline change that accepted a failed comparison of the run: put back the baseline it replaced, so later runs compare with the old baseline again. Use it when a person disputes a baseline the AI accepted. Refuses without changing anything when the baseline changed again since. |
 | `qawolf run stop` | write | Stop a run, including its queued flows and automatic retries. Stopping is asynchronous and can update run-status messages and commit statuses in connected integrations. Repeated requests are safe, and finished runs keep their results. A run that is still being created returns not found; retry once run.get returns the run. If run.get returns a different runId, use that ID. Poll run.get for results. |
 | `qawolf runner act` | write | Perform one raw action on a runner's screen. A browser runner takes click, double_click, scroll, move, drag, keypress, navigate and type; a mobile runner takes tap, swipe, fill and type. A browser runner answers mobile actions with action-not-supported-on-browser; a mobile runner answers the other browser actions with action-not-supported-on-mobile. Use - to read a whole action as JSON from stdin |
 | `qawolf runner actions` | write | Perform a sequence of up to ten raw actions on a runner's screen in one request, as a JSON array of the same actions `runner act` takes. Use - to read the array from stdin. Actions run back to back, so batch only steps whose targets are on the screen you last saw, and end the sequence at the step that changes the page. Each result carries an effect: performed, not-performed, or unknown when the runner stopped answering and the action may have landed |

package/skills/qawolf-cli/references/run-results.md

@@ -59,8 +59,10 @@ A run that has been requested but not yet created answers exit `8` too, and
 says it is still being created. That one clears on its own, so read the message
 rather than the code before deciding whether to poll.
 
-Poll `status` until it reaches `passed`, `failed` or `canceled`. The other
-values mean the run is still going.
+Poll `status` until it reaches `passed`, `failed`, `canceled` or `superseded`.
+When it is `superseded`, this run will never change again. Read the replacement
+run in `supersededBy.runId` for the verdict. `queued` and `running` mean the run
+is still going.
 
 ## Fields a passing run does not show you
 
@@ -185,19 +187,25 @@ Every documented field of the `run.get` response. `[]` marks an array, so
 - `git.commitUrl` — Link to the commit on the code host.
 - `needsReview` — True once every flow has finished its attempts and at least one failed flow still has no diagnosis, including one whose investigation carried over to a later run. `status` stays `running` until that failure is diagnosed, so a caller that is not waiting for a diagnosis can stop polling here and read the run's failed flows.
 - `runId` — The run this response describes. Treat it as canonical: it can differ from the id you asked for. A deploy notification returns a run id before the run exists, and if a second notification for the same commit is folded into an earlier run, that id resolves to the earlier run instead.
-- `status` — One of: queued, running, passed, failed, canceled
+- `status` — One of: queued, running, passed, failed, canceled, superseded
+- `supersededBy` — The run that replaced this one, present only when `status` is `superseded`. A newer deployment to the same branch and environment (and service, when the deployment named one) cancels the older run's unfinished flows and takes over. Deduplication ignores the commit, so the replacement may be testing a later commit than this run did. Only the direct replacement is named; that run can itself be superseded.
+- `supersededBy.runId` — The id of the run.
+- `supersededBy.url` — Absolute URL of the replacement run's page.
 - `blockingBugCount` — How many bugs this run found are blocking: still open, and priority urgent, high, or unprioritized — unprioritized counts because nobody has ruled it out yet. This is what `failed` is derived from, so it explains a failure rather than adding a second verdict: gate on `status`, then read this to say how many bugs are holding the build. It counts a bug filed against a later run by an investigation that carried over from this one, and it drops a bug once that bug is resolved.
 - `flows` — The run's flows, ordered alphabetically by name. Only the flows matching flowStatuses when the request set it.
 - `flows[].attempts` — The flow's finished execution attempts, oldest first, including manual Wolf Browser attempts. Present once at least one attempt has finished, so a flow that passed after retries also lists its failed attempts. Artifact URLs appear only on automated attempts that reached a verdict, stay valid for at least a day (call run.get again for fresh ones), and can return 404 when the attempt did not produce that artifact.
 - `flows[].attempts[].logsUrl` — Signed URL for the attempt's execution logs.
 - `flows[].attempts[].traceUrl` — Signed URL for the attempt's Playwright trace (a trace.zip; open it with `npx playwright show-trace`).
 - `flows[].attempts[].videoUrl` — Signed URL for the attempt's screen recording.
+- `flows[].attempts[].attemptId` — The id of the run attempt.
 - `flows[].attempts[].kind` — One of: automated, manual
 - `flows[].attempts[].startedAt` — Absent when the attempt failed before it could start.
 - `flows[].attempts[].status` — One of: passed, failed, canceled
-- `flows[].failure.diagnosis` — QA Wolf's investigation verdict for the failure: `bug` means the application is broken, `maintenance` means the test needed an update and the failure does not indicate an application problem. Absent until the investigation reaches a verdict. Pass issueId to issue.get for details.
+- `flows[].failure.diagnosis` — QA Wolf's investigation verdict for the failure: `bug` means the application is broken, `maintenance` means the test needed an update and the failure does not indicate an application problem. Absent until the investigation reaches a verdict, and absent when the flow was opted out of investigation. Pass issueId to issue.get for details.
 - `flows[].failure.diagnosis.issueId` — The id of the issue.
 - `flows[].failure.diagnosis.type` — One of: bug, maintenance
+- `flows[].failure.optedOutOfInvestigation` — Present when the failure was marked "do not investigate" (DNI): it will get no bug or maintenance verdict.
+- `flows[].failure.optedOutOfInvestigation.by` — One of: user, system
 - `flows[].flowId` — The id of the flow.
 - `flows[].status` — One of: failed, queued, running, passed, canceled
 - `url` — Absolute URL of the run page.