feat(cloud): add --cancel-previous to supersede the previous CI run

Sends the opt-in flag with the submission; the API derives the CI context
(repo + branch/PR + check name) from the run metadata and cancels the
previous run's still-queued tests.

The superseded run's own CLI, still polling, now exits 0 instead of failing
the build: any result carrying `superseded_by:` settles the verdict as
SUPERSEDED, even alongside a test that had already failed, because this run
no longer speaks for the commit. The failure is still printed and still in
tests[] under --json, where SUPERSEDED is a third value of an existing
documented field.

Sent as its own field rather than inside `config`, which is stamped onto
every result row and shipped to the runner — this is a submission directive,
not run configuration. Not exposed on the MCP tool: it has no CI metadata to
derive a context from, so the flag could only ever be a no-op there.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: finalerock44

src/commands/cloud.ts

@@ -194,6 +194,7 @@ export const cloudCommand = defineCommand({
         collectRepeatedFlag(rawArgs, ['--exclude-tags']),
       );
       let flows = args.flows as string | undefined;
+      const cancelPrevious = Boolean(args['cancel-previous']);
       const googlePlay = Boolean(args['google-play']);
       const ignoreShaCheck = Boolean(args['ignore-sha-check']);
       // Single opt-in for client-side envelope encryption of every sensitive
@@ -819,6 +820,7 @@ export const cloudCommand = defineCommand({
         androidNoSnapshot,
         apiUrl,
         appBinaryId: finalBinaryId,
+        cancelPrevious,
         cliVersion,
         commonRoot,
         continueOnFailure,

src/config/flags/execution.flags.ts

@@ -4,6 +4,12 @@ import type { ArgsDef } from 'citty';
  * Test execution and flow management flags
  */
 export const executionFlags = {
+  'cancel-previous': {
+    type: 'boolean',
+    default: false,
+    description:
+      'Cancel the still-queued tests of the previous run from the same CI context (repo + branch/PR + check name, read from your CI metadata). Tests already running are left to finish; cancelled tests are refunded at 75%. Does nothing outside CI.',
+  },
   config: {
     type: 'string',
     description:

src/services/results-polling.service.ts

@@ -81,9 +81,36 @@ export function deviceFromResultRow(r: {
   };
 }
 
+/**
+ * Was this row cancelled because a newer run from the same CI context
+ * replaced it (`dcd cloud --cancel-previous`)?
+ *
+ * Read through a structural cast for the same reason deviceFromResultRow
+ * does: the committed generated types are regenerated wholesale from dev's
+ * swagger and lag the API, and this must work against an API that already
+ * sends the field.
+ */
+export function isSupersededRow(r: unknown): boolean {
+  const reason = (r as { cancellation_reason?: string | null } | null)
+    ?.cancellation_reason;
+  return typeof reason === 'string' && reason.startsWith('superseded_by:');
+}
+
+/** The upload that superseded this run, for the console link. */
+export function supersedingUploadId(results: unknown[]): string | undefined {
+  for (const r of results) {
+    const reason = (r as { cancellation_reason?: string | null } | null)
+      ?.cancellation_reason;
+    if (typeof reason === 'string' && reason.startsWith('superseded_by:')) {
+      return reason.slice('superseded_by:'.length) || undefined;
+    }
+  }
+  return undefined;
+}
+
 export interface PollingResult {
   consoleUrl: string;
-  status: 'FAILED' | 'PASSED';
+  status: 'FAILED' | 'PASSED' | 'SUPERSEDED';
   tests: Array<{
     /** Device this result ran on (present when the API reports it). */
     device?: TestDevice;
@@ -339,13 +366,24 @@ export class ResultsPollingService {
   ): PollingResult {
     const resultsWithoutEarlierTries = this.filterLatestResults(results);
 
+    // ANY superseded row settles the whole verdict, even alongside a test
+    // that had genuinely failed before the newer run replaced this one: this
+    // run no longer speaks for the commit, so failing the build on its behalf
+    // is wrong. Actions reaches the same conclusion — a cancelled run's
+    // conclusion is `cancelled`, whatever had already failed inside it. The
+    // failure is still printed and still in `tests[]`; only the exit code
+    // changes.
+    const superseded = resultsWithoutEarlierTries.some(isSupersededRow);
+
     return {
       consoleUrl,
       // Anything other than an explicit pass (CANCELLED, ERROR, a status we
       // don't know about yet) must fail the run — this gates CI exit codes.
-      status: resultsWithoutEarlierTries.every((result) => result.status === 'PASSED')
-        ? 'PASSED'
-        : 'FAILED',
+      status: superseded
+        ? 'SUPERSEDED'
+        : resultsWithoutEarlierTries.every((result) => result.status === 'PASSED')
+          ? 'PASSED'
+          : 'FAILED',
       tests: resultsWithoutEarlierTries.map((r) => ({
         // r carries config/simulator_name at runtime; the committed generated
         // types lag the API (regenerated wholesale from dev's swagger), so read
@@ -386,8 +424,12 @@ export class ResultsPollingService {
     const pending = statusCounts.PENDING || 0;
     const queued = statusCounts.QUEUED || 0;
     const running = statusCounts.RUNNING || 0;
+    // CANCELLED is terminal, so it counts as completed. Without it a
+    // cancelled or superseded run's footer sticks at "8/12 completed"
+    // forever, having already stopped polling.
+    const cancelled = statusCounts.CANCELLED || 0;
     const total = results.length;
-    const completed = passed + failed;
+    const completed = passed + failed + cancelled;
 
     const summary = formatTestSummary({
       completed,
@@ -562,6 +604,37 @@ export class ResultsPollingService {
       testMetadata,
     );
 
+    if (output.status === 'SUPERSEDED') {
+      // Exit 0: a newer run of the same CI context replaced this one, so
+      // failing the build here would fail it for work nobody is waiting on.
+      // Falls through to the success return below — RunFailedError, and with
+      // it the exit code 2 in `dcd cloud`, is never reached.
+      if (logger && !json) {
+        const newer = supersedingUploadId(updatedResults);
+        logger('\n');
+        logger(
+          ui.warn(
+            'Run superseded by a newer run from the same CI context — exiting 0',
+          ),
+        );
+        if (newer) {
+          logger(
+            ui.branch(
+              ui.fields([
+                [
+                  'superseded by',
+                  colors.url(consoleUrl.replace(uploadId, newer)),
+                ],
+              ]),
+            ),
+          );
+        }
+        logger('\n');
+      }
+
+      return output;
+    }
+
     if (output.status === 'FAILED') {
       if (debug && logger) {
         logger(`[DEBUG] Some tests failed, returning failed status`);

src/services/test-submission.service.ts

@@ -18,6 +18,13 @@ export interface TestSubmissionConfig {
   androidNoSnapshot?: boolean;
   apiUrl?: string;
   appBinaryId: string;
+  /**
+   * Ask the API to cancel the still-queued tests of the previous run from
+   * the same CI context. Sent as its own field rather than inside `config`,
+   * which is stamped onto every result row and shipped to the runner — this
+   * is a one-off submission directive, not run configuration.
+   */
+  cancelPrevious?: boolean;
   cliVersion: string;
   commonRoot: string;
   continueOnFailure?: boolean;
@@ -86,6 +93,7 @@ export class TestSubmissionService {
       cliVersion,
       env = [],
       metadata = [],
+      cancelPrevious = false,
       googlePlay = false,
       androidApiLevel,
       androidDevice,
@@ -308,6 +316,12 @@ export class TestSubmissionService {
       );
     }
 
+    // Only sent when asked for, so every other submission's wire shape is
+    // unchanged and the flag is simply ignored by an older API.
+    if (cancelPrevious) {
+      fields.cancelPrevious = 'true';
+    }
+
     this.setOptionalFields(fields, {
       androidApiLevel,
       androidDevice,

test/unit/superseded-run.test.ts

@@ -0,0 +1,106 @@
+import { expect } from 'chai';
+
+import {
+  isSupersededRow,
+  ResultsPollingService,
+  supersedingUploadId,
+} from '../../src/services/results-polling.service.js';
+
+// A superseded run is one `dcd cloud --cancel-previous` replaced: a newer run
+// of the same CI context cancelled its queued tests. The verdict below is what
+// decides whether that older CI job exits 0 or fails the build, so it is worth
+// pinning down separately from the polling loop around it.
+const row = (overrides: Record<string, unknown> = {}) => ({
+  id: 1,
+  test_file_name: 'flow.yaml',
+  status: 'PASSED',
+  retry_of: null,
+  created_at: '2026-09-17T10:00:00.000Z',
+  duration_seconds: 1,
+  fail_reason: null,
+  simulator_name: 'pixel-7',
+  ...overrides,
+});
+
+const cancelledBySupersede = (id: number) =>
+  row({
+    id,
+    status: 'CANCELLED',
+    cancellation_reason: 'superseded_by:newer-upload',
+  });
+
+// buildPollingResult is private; it is the whole point of this file, so reach
+// it rather than re-implementing the verdict in the test.
+const verdict = (results: unknown[]) =>
+  (
+    new ResultsPollingService() as unknown as {
+      buildPollingResult: (
+        r: unknown[],
+        uploadId: string,
+        consoleUrl: string,
+      ) => { status: string };
+    }
+  ).buildPollingResult(results, 'upload-1', 'https://console/upload-1').status;
+
+describe('superseded runs', () => {
+  describe('isSupersededRow', () => {
+    it('matches only the superseded token', () => {
+      expect(isSupersededRow(cancelledBySupersede(1))).to.equal(true);
+      expect(isSupersededRow(row({ status: 'CANCELLED' }))).to.equal(false);
+      expect(
+        isSupersededRow(row({ cancellation_reason: 'user' })),
+      ).to.equal(false);
+      expect(isSupersededRow(row())).to.equal(false);
+      expect(isSupersededRow(null)).to.equal(false);
+    });
+  });
+
+  describe('supersedingUploadId', () => {
+    it('reads the newer upload id out of the reason', () => {
+      expect(supersedingUploadId([row(), cancelledBySupersede(2)])).to.equal(
+        'newer-upload',
+      );
+    });
+
+    it('is undefined when nothing was superseded', () => {
+      expect(supersedingUploadId([row()])).to.equal(undefined);
+    });
+  });
+
+  describe('the run verdict', () => {
+    it('is PASSED when every test passed', () => {
+      expect(verdict([row(), row({ id: 2 })])).to.equal('PASSED');
+    });
+
+    it('is FAILED for an ordinary cancel, as before', () => {
+      // No reason on the row: someone cancelled this run by hand, and the
+      // build should still go red.
+      expect(verdict([row(), row({ id: 2, status: 'CANCELLED' })])).to.equal(
+        'FAILED',
+      );
+    });
+
+    it('is SUPERSEDED when a newer run replaced this one', () => {
+      expect(verdict([row(), cancelledBySupersede(2)])).to.equal('SUPERSEDED');
+    });
+
+    it('is SUPERSEDED even when a test had already genuinely failed', () => {
+      // This run no longer speaks for the commit — the newer one does — so it
+      // must not fail the build. The failure is still reported in tests[].
+      const results = [
+        row({ id: 1, status: 'FAILED', fail_reason: 'assertion failed' }),
+        cancelledBySupersede(2),
+      ];
+
+      expect(verdict(results)).to.equal('SUPERSEDED');
+    });
+
+    it('is unchanged when every test finished before the newer run arrived', () => {
+      // Nothing was still queued, so nothing was cancelled and no marker was
+      // written: the verdict is whatever it would have been.
+      expect(
+        verdict([row(), row({ id: 2, status: 'FAILED' })]),
+      ).to.equal('FAILED');
+    });
+  });
+});