@@ -6,6 +6,7 @@ All notable changes to `@testingbot/cli` are documented here. Releases are publi
 
 ### Added
 
+- `testingbot maestro --cancel-previous`: before starting, cancels your queued or running runs of the same repository and branch or pull request from an earlier commit (`cancelPrevious` on the run API). Runs on the same commit are left alone.
 - `testingbot maestro` detects the repository URL, branch, commit and pull request in GitHub Actions, GitLab CI, Bitbucket Pipelines, Azure Pipelines and CircleCI and sends them as run metadata (`repoUrl` is new), so the dashboard can link to the commit and PR on any Git host. On a GitHub pull request the PR's head commit is used, not the merge commit. Explicit flags win.
 - `testingbot espresso` and `testingbot xcuitest` take the same CI/CD metadata as `maestro`: `--branch`, `--pr-url`, `-m/--metadata` and the CI environment detection, through one shared code path.
 - `--retry <count>`, `--download-artifacts [all|failed]` and `--artifacts-output-dir` for `testingbot espresso` and `testingbot xcuitest`. A retried run is started again on the uploaded app; the last attempt decides the exit code, the `--report` and the artifacts. Artifacts (video, logs, screenshots) are zipped with a folder per run, like `maestro`.
 
@@ -203,6 +203,7 @@ Values passed with `-e` are stored in plain text: they are returned in the run's
 | `--repo-owner <owner>`       | Repository owner (e.g., GitHub organization or username)                                                                                                                   |
 | `-m, --metadata <KEY=VALUE>` | Free-form metadata attached to the run and shown in the dashboard (repeatable, e.g. `-m team=mobile -m env=staging`)                                                       |
 | `--check-name <name>`        | Name the GitHub pull request check `TestingBot / <name>` so several runs on one commit (iOS, Android) post separate checks that branch protection can require individually |
+| `--cancel-previous`          | Before starting, cancel your queued or running runs of the same repository and branch (or pull request) from an earlier commit. Runs on the same commit are left alone     |
 
 **Allure reports:** `--report allure` converts each run's results into Allure result files under `<report-output-dir>/allure-results/`, one JSON per flow with its steps, status and failure details. Render them with `allure serve <report-output-dir>/allure-results` (requires the [Allure CLI](https://allurereport.org/docs/install/)). Results from several runs or shards accumulate in the same directory.
 
@@ -695,6 +696,8 @@ testingbot xcuitest app.ipa app-test.zip \
 
 `maestro`, `espresso` and `xcuitest` all take `--branch`, `--commit-sha`, `--pull-request-id`, `--pr-url`, `--repo-owner`, `--repo-name` and `-m, --metadata <KEY=VALUE>` (repeatable). Inside GitHub Actions, GitLab CI, Bitbucket Pipelines, Azure Pipelines or CircleCI, the repository URL, branch, commit and pull request are read from the CI environment, so the dashboard links the run to them on whichever host the repository lives (GitHub, GitLab, Bitbucket, Azure Repos or self-hosted). Any flag overrides what was detected.
 
+`testingbot maestro --cancel-previous` uses this context to cancel the runs of a previous push: your queued or running Maestro runs with the same repository and the same pull request (or branch) but a different commit. Runs on the same commit, such as the iOS and Android jobs of one pipeline, keep running.
+
 ### Real-time Progress
 
 By default, the CLI shows real-time progress updates including:
 
@@ -851,6 +851,10 @@ program
     'Arbitrary metadata to attach to the run, shown in the dashboard (repeatable).',
     collectRepeatable,
   )
+  .option(
+    '--cancel-previous',
+    'Cancel your queued or running runs of the same repository and branch (or pull request) from an earlier commit before starting this one.',
+  )
   .option(
     '--check-name <name>',
     'Name the GitHub pull request check "TestingBot / <name>" so several runs on one commit (iOS, Android) post separate checks.',
@@ -1031,6 +1035,7 @@ program
         ignoreChecksumCheck: args.ignoreChecksumCheck,
         shardSplit: args.shardSplit,
         retry: args.retry,
+        cancelPrevious: args.cancelPrevious,
         debug: args.debug,
         googlePlayStore: args.googlePlay,
         disableAnimations: args.disableAnimations,
 
@@ -136,6 +136,7 @@ export default class MaestroOptions {
   private _ignoreChecksumCheck: boolean;
   private _shardSplit?: number;
   private _retry: number;
+  private _cancelPrevious: boolean;
   private _debug: boolean;
   private _configFile?: string;
   private _groups?: string[];
@@ -177,6 +178,7 @@ export default class MaestroOptions {
       ignoreChecksumCheck?: boolean;
       shardSplit?: number;
       retry?: number;
+      cancelPrevious?: boolean;
       debug?: boolean;
       configFile?: string;
       groups?: string[];
@@ -244,6 +246,7 @@ export default class MaestroOptions {
     this._artifactsOutputDir = options?.artifactsOutputDir;
     this._ignoreChecksumCheck = options?.ignoreChecksumCheck ?? false;
     this._shardSplit = options?.shardSplit;
+    this._cancelPrevious = options?.cancelPrevious ?? false;
     this._retry = options?.retry ?? 0;
     if (
       !Number.isInteger(this._retry) ||
@@ -410,6 +413,10 @@ export default class MaestroOptions {
     return this._retry;
   }
 
+  public get cancelPrevious(): boolean {
+    return this._cancelPrevious;
+  }
+
   public get debug(): boolean {
     return this._debug;
   }
 
@@ -491,6 +491,7 @@ export default class Maestro extends BaseProvider<MaestroOptions> {
             shardSplit: this.options.shardSplit,
           }),
           ...(metadata && { metadata }),
+          ...(this.options.cancelPrevious && { cancelPrevious: true }),
           ...(otherApps.length > 0 && {
             otherApps: previewOtherAppUrls,
           }),
@@ -2468,6 +2469,7 @@ export default class Maestro extends BaseProvider<MaestroOptions> {
             shardSplit: this.options.shardSplit,
           }),
           ...(metadata && { metadata }),
+          ...(this.options.cancelPrevious && { cancelPrevious: true }),
           ...(this.otherAppUrls.length > 0 && {
             otherApps: this.otherAppUrls,
           }),
@@ -2497,6 +2499,10 @@ export default class Maestro extends BaseProvider<MaestroOptions> {
         this.updateKey = result.update_key;
       }
 
+      if (result.cancelled_previous) {
+        this.logCancelledPrevious(result.cancelled_previous);
+      }
+
       // The server registers a GitHub check when the run carries repo + commit
       // metadata and the TestingBot GitHub App is installed for that repo.
       if (result.ci_check?.repo && !this.options.quiet) {
@@ -4259,6 +4265,26 @@ export default class Maestro extends BaseProvider<MaestroOptions> {
     }
   }
 
+  /** What --cancel-previous did, as the run response reports it. */
+  private logCancelledPrevious(cancelled: {
+    run_ids?: number[];
+    skipped?: string;
+  }): void {
+    if (cancelled.skipped) {
+      logger.warn(
+        `--cancel-previous: nothing cancelled, ${cancelled.skipped}.`,
+      );
+      return;
+    }
+    const ids = cancelled.run_ids ?? [];
+    if (this.options.quiet) return;
+    logger.info(
+      ids.length > 0
+        ? `Cancelled ${ids.length} run(s) of the previous push: ${ids.join(', ')}`
+        : 'No runs of a previous push were still running.',
+    );
+  }
+
   private async createZipFromDirectory(
     sourceDir: string,
     zipPath: string,
 
@@ -2017,6 +2017,21 @@ describe('TestingBotCTL CLI', () => {
       expect(mockUploadOnly).toHaveBeenCalledTimes(1);
     });
 
+    test('maestro --cancel-previous reaches the options', async () => {
+      await program.parseAsync([
+        'node',
+        'cli',
+        'maestro',
+        'app.apk',
+        './flows',
+        '--cancel-previous',
+      ]);
+      expect(
+        lastConstructorOptions<{ cancelPrevious?: boolean }>(Maestro)
+          .cancelPrevious,
+      ).toBe(true);
+    });
+
     test('detected CI repository metadata fills in what flags leave out', async () => {
       (ciRepoMetadata as jest.Mock).mockReturnValueOnce({
         repoUrl: 'https://dev.azure.com/acme/mobile/_git/app',
 
@@ -921,6 +921,78 @@ describe('Maestro', () => {
       logSpy.mockRestore();
     });
 
+    describe('--cancel-previous', () => {
+      const cancelling = () => {
+        const provider = new Maestro(
+          mockCredentials,
+          new MaestroOptions('path/to/app.apk', 'path/to/flows', 'Pixel 6', {
+            cancelPrevious: true,
+          }),
+        );
+        provider['appId'] = 1234;
+        return provider;
+      };
+
+      it('asks the server to cancel the previous push and logs what it did', async () => {
+        const provider = cancelling();
+        axios.post = jest.fn().mockResolvedValueOnce({
+          data: {
+            success: true,
+            runs: [],
+            cancelled_previous: { run_ids: [7, 8] },
+          },
+          headers: {},
+        });
+        const logSpy = jest.spyOn(logger, 'info').mockImplementation(() => {});
+
+        await provider['runTests']();
+
+        expect((axios.post as jest.Mock).mock.calls[0][1].cancelPrevious).toBe(
+          true,
+        );
+        expect(logSpy).toHaveBeenCalledWith(
+          'Cancelled 2 run(s) of the previous push: 7, 8',
+        );
+        logSpy.mockRestore();
+      });
+
+      it('warns when the server could not tell which runs to cancel', async () => {
+        const provider = cancelling();
+        axios.post = jest.fn().mockResolvedValueOnce({
+          data: {
+            success: true,
+            runs: [],
+            cancelled_previous: {
+              run_ids: [],
+              skipped: 'metadata has no commitSha',
+            },
+          },
+          headers: {},
+        });
+        const warnSpy = jest.spyOn(logger, 'warn').mockImplementation(() => {});
+
+        await provider['runTests']();
+
+        expect(warnSpy).toHaveBeenCalledWith(
+          '--cancel-previous: nothing cancelled, metadata has no commitSha.',
+        );
+        warnSpy.mockRestore();
+      });
+
+      it('is not sent unless asked', async () => {
+        maestro['appId'] = 1234;
+        axios.post = jest
+          .fn()
+          .mockResolvedValueOnce({ data: { success: true }, headers: {} });
+
+        await maestro['runTests']();
+
+        expect((axios.post as jest.Mock).mock.calls[0][1]).not.toHaveProperty(
+          'cancelPrevious',
+        );
+      });
+    });
+
     it('should not include maestroOptions when none are set', async () => {
       maestro['appId'] = 1234;