@devicecloud.dev/dcd 5.5.0 → 5.6.0-beta.3

package/dist/commands/cloud.d.ts

@@ -98,6 +98,11 @@ export declare const cloudCommand: import("citty").CommandDef<{
         readonly type: "string";
         readonly description: "Pull request URL for this run (stored as gh_pr_url metadata)";
     };
+    readonly 'cancel-previous': {
+        readonly type: "boolean";
+        readonly default: false;
+        readonly 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.";
+    };
     readonly config: {
         readonly type: "string";
         readonly description: "Path to custom config.yaml file. If not provided, defaults to config.yaml in root flows folders.";

package/dist/commands/cloud.js

@@ -132,6 +132,7 @@ export const cloudCommand = defineCommand({
             const excludeFlows = coerceArray(collectRepeatedFlag(rawArgs, ['--exclude-flows']));
             const excludeTags = coerceArray(collectRepeatedFlag(rawArgs, ['--exclude-tags']));
             let flows = args.flows;
+            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
@@ -401,15 +402,22 @@ export const cloudCommand = defineCommand({
                 }
                 throw error;
             }
-            const { allExcludeTags, allIncludeTags, flowMetadata, flowOverrides, flowsToRun: testFileNames, referencedFiles, sequence, } = executionPlan;
+            const { allExcludeTags, allIncludeTags, flowMetadata, flowOverrides, flowsToRun: testFileNames, includedFiles, referencedFiles, sequence, } = executionPlan;
             if (debug) {
                 out(`[DEBUG] All include tags: ${allIncludeTags?.join(', ') || 'none'}`);
                 out(`[DEBUG] All exclude tags: ${allExcludeTags?.join(', ') || 'none'}`);
                 out(`[DEBUG] Test file names: ${testFileNames.join(', ')}`);
             }
-            const commonRoot = computeCommonRoot(testFileNames, referencedFiles);
+            const commonRoot = computeCommonRoot(testFileNames, referencedFiles, includedFiles);
             if (debug) {
                 out(`[DEBUG] Common root directory: ${commonRoot}`);
+                // `includedPaths` files sitting beside the flows tree rather than
+                // inside it raise the common root, so every server-side flow key gains
+                // a leading segment. Harmless but visible in the console, so say it.
+                const rootWithoutIncludes = computeCommonRoot(testFileNames, referencedFiles);
+                if (includedFiles.length > 0 && rootWithoutIncludes !== commonRoot) {
+                    out(`[DEBUG] \`includedPaths\` raised the common root from ${rootWithoutIncludes} to ${commonRoot} — flow paths gain a leading segment`);
+                }
             }
             const testMetadataMap = buildTestMetadataMap(flowMetadata, commonRoot);
             if (debug) {
@@ -549,6 +557,7 @@ export const cloudCommand = defineCommand({
                 androidNoSnapshot,
                 apiUrl,
                 appBinaryId: finalBinaryId,
+                cancelPrevious,
                 cliVersion,
                 commonRoot,
                 continueOnFailure,

package/dist/config/flags/execution.flags.d.ts

@@ -2,6 +2,11 @@
  * Test execution and flow management flags
  */
 export declare const executionFlags: {
+    readonly 'cancel-previous': {
+        readonly type: "boolean";
+        readonly default: false;
+        readonly 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.";
+    };
     readonly config: {
         readonly type: "string";
         readonly description: "Path to custom config.yaml file. If not provided, defaults to config.yaml in root flows folders.";

package/dist/config/flags/execution.flags.js

@@ -2,6 +2,11 @@
  * 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: 'Path to custom config.yaml file. If not provided, defaults to config.yaml in root flows folders.',

package/dist/constants.d.ts

@@ -84,6 +84,11 @@ export declare const flags: {
         readonly type: "string";
         readonly description: "Pull request URL for this run (stored as gh_pr_url metadata)";
     };
+    readonly 'cancel-previous': {
+        readonly type: "boolean";
+        readonly default: false;
+        readonly 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.";
+    };
     readonly config: {
         readonly type: "string";
         readonly description: "Path to custom config.yaml file. If not provided, defaults to config.yaml in root flows folders.";

package/dist/mcp/tools/run-cloud-test.js

@@ -120,7 +120,7 @@ export function registerRunCloudTest(server) {
             // stdout is the JSON-RPC channel — config warnings must go to stderr.
             warn: logStderr,
         });
-        const commonRoot = computeCommonRoot(executionPlan.flowsToRun, executionPlan.referencedFiles);
+        const commonRoot = computeCommonRoot(executionPlan.flowsToRun, executionPlan.referencedFiles, executionPlan.includedFiles);
         const testMetadataMap = buildTestMetadataMap(executionPlan.flowMetadata, commonRoot);
         if (args.dryRun) {
             return jsonResult({

package/dist/services/execution-plan.service.d.ts

@@ -21,6 +21,12 @@ export interface IExecutionPlan {
     flowMetadata: Record<string, Record<string, unknown>>;
     flowOverrides: Record<string, Record<string, unknown>>;
     flowsToRun: string[];
+    /**
+     * Extra files pulled in by `config.yaml`'s `includedPaths`. Kept separate
+     * from `referencedFiles` (which is derived from flow commands) so the zip
+     * manifest and the common-root calculation can tell the two apart.
+     */
+    includedFiles: string[];
     referencedFiles: string[];
     sequence?: IFlowSequence | null;
     totalFlowFiles: number;

package/dist/services/execution-plan.service.js

@@ -90,7 +90,7 @@ function extractDeviceCloudOverrides(config) {
  * @param resolvedConfigFile - Optional absolute path to a custom config file
  * @returns Execution plan for the single file with dependencies
  */
-async function planSingleFile(normalizedInput, warn, resolvedConfigFile) {
+async function planSingleFile(normalizedInput, warn, resolvedConfigFile, debug = false) {
     const inputBasename = path.basename(normalizedInput);
     if (inputBasename === 'config.yaml' ||
         inputBasename === 'config.yml' ||
@@ -118,11 +118,18 @@ async function planSingleFile(normalizedInput, warn, resolvedConfigFile) {
                 `Pass the workspace folder instead so the named flows can be discovered and sequenced.`);
         }
     }
+    // A single-file input has no workspace directory, so `includedPaths` (which
+    // only reaches here via --config) anchors on the flow file's own directory —
+    // the same place Maestro resolves an assertScreenshot baseline from.
+    const includedFiles = workspaceConfig
+        ? resolveIncludedPaths(workspaceConfig, path.dirname(normalizedInput), warn, debug)
+        : [];
     const checkedDependancies = await checkDependencies(normalizedInput);
     return {
         flowMetadata,
         flowOverrides,
         flowsToRun: [normalizedInput],
+        includedFiles,
         referencedFiles: [...new Set(checkedDependancies)],
         totalFlowFiles: 1,
         workspaceConfig,
@@ -176,6 +183,94 @@ async function applyFlowGlobs(workspaceConfig, normalizedInput, unfilteredFlowFi
     }
     return unfilteredFlowFiles.filter((file) => !isExcludedConfig(file));
 }
+/**
+ * The whole archive is buffered in memory by `compressFilesFromRelativePath`,
+ * so an unbounded `**` glob is a real footgun. These are warn thresholds, not
+ * hard limits — a legitimately large baseline set should still upload.
+ */
+const INCLUDED_PATHS_FILE_WARN_THRESHOLD = 200;
+const INCLUDED_PATHS_BYTES_WARN_THRESHOLD = 50 * 1024 * 1024;
+/**
+ * Resolve `config.yaml`'s `includedPaths` globs into absolute file paths.
+ *
+ * This is the general-purpose escape hatch for shipping files the flow
+ * commands don't reference: `assertScreenshot` baselines above all, but also
+ * fixtures, test data and certificates. Only `addMedia` / `runFlow` /
+ * `runScript` arguments are discovered by walking the flows, so without this
+ * key such files are silently absent from the uploaded zip.
+ *
+ * Glob semantics deliberately mirror `flows:` (`applyFlowGlobs`): patterns
+ * resolve against the workspace root, never the config file's directory, so
+ * `--config ci/workspace.yaml` behaves identically to an auto-detected config.
+ *
+ * @param workspaceConfig - Validated workspace config
+ * @param normalizedInput - Normalized path to the workspace directory
+ * @param warn - Sink for non-fatal problems
+ * @param debug - Whether to emit debug logging
+ * @returns Absolute paths of every matched file, deduped and sorted
+ * @throws Error if a pattern escapes the workspace root
+ */
+function resolveIncludedPaths(workspaceConfig, normalizedInput, warn, debug = false) {
+    const patterns = workspaceConfig.includedPaths;
+    if (!patterns || patterns.length === 0)
+        return [];
+    const workspaceRoot = path.resolve(normalizedInput);
+    const resolved = new Set();
+    const unmatched = [];
+    for (const pattern of patterns) {
+        // fs.globSync lands in Node 22; the CLI's `engines.node` already requires
+        // it. No `nodir` option — directories are stripped by the stat check below.
+        const matches = fs.globSync(pattern, { cwd: normalizedInput });
+        let matchedFile = false;
+        for (const match of matches) {
+            const absolute = path.resolve(normalizedInput, match);
+            // Containment guard: `flows:` has none because its matches are only ever
+            // parsed as YAML, but this key ships arbitrary bytes to a remote runner,
+            // so a `../../../` climb must not silently leave the workspace.
+            const relative = path.relative(workspaceRoot, absolute);
+            if (relative.startsWith('..') || path.isAbsolute(relative)) {
+                throw new Error(`\`includedPaths\` pattern "${pattern}" resolves outside the workspace: ${absolute}\n\n` +
+                    `Included paths must stay within ${workspaceRoot}.`);
+            }
+            try {
+                if (!fs.statSync(absolute).isFile())
+                    continue;
+            }
+            catch {
+                continue;
+            }
+            matchedFile = true;
+            resolved.add(absolute);
+        }
+        if (!matchedFile)
+            unmatched.push(pattern);
+    }
+    if (unmatched.length > 0) {
+        warn(`Warning: \`includedPaths\` pattern(s) in config matched no files:\n` +
+            `${unmatched.map((pattern) => `  ${pattern}`).join('\n')}\n\n` +
+            `Patterns are resolved relative to ${workspaceRoot}.`);
+    }
+    const files = [...resolved].sort((a, b) => a.localeCompare(b));
+    let totalBytes = 0;
+    for (const file of files) {
+        try {
+            totalBytes += fs.statSync(file).size;
+        }
+        catch {
+            // Raced away between glob and stat; the zip step reports it properly.
+        }
+    }
+    if (files.length > INCLUDED_PATHS_FILE_WARN_THRESHOLD ||
+        totalBytes > INCLUDED_PATHS_BYTES_WARN_THRESHOLD) {
+        warn(`Warning: \`includedPaths\` matched ${files.length} file(s) totalling ` +
+            `${Math.round(totalBytes / (1024 * 1024))} MB. The flow archive is built in ` +
+            `memory, so consider narrowing the patterns.`);
+    }
+    if (debug) {
+        console.log(`[DEBUG] includedPaths matched ${files.length} file(s):\n${files.join('\n')}`);
+    }
+    return files;
+}
 /**
  * Resolve sequential execution order from workspace config
  * @param workspaceConfig - Workspace configuration with executionOrder
@@ -241,7 +336,7 @@ export async function plan(options) {
         throw new Error(`Flow path does not exist: ${path.resolve(normalizedInput)}`);
     }
     if (fs.lstatSync(normalizedInput).isFile()) {
-        return planSingleFile(normalizedInput, warn, resolvedConfigFile);
+        return planSingleFile(normalizedInput, warn, resolvedConfigFile, debug);
     }
     let unfilteredFlowFiles = await readDirectory(normalizedInput, isFlowFile);
     if (unfilteredFlowFiles.length === 0) {
@@ -325,6 +420,7 @@ export async function plan(options) {
         flowMetadata,
         flowOverrides,
         flowsToRun: normalFlows,
+        includedFiles: resolveIncludedPaths(workspaceConfig, normalizedInput, warn, debug),
         referencedFiles: [...new Set(allFiles)],
         sequence: {
             continueOnFailure: workspaceConfig.executionOrder?.continueOnFailure,

package/dist/services/execution-plan.utils.js

@@ -2,7 +2,50 @@ import * as yaml from 'js-yaml';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { parseWorkspaceConfig, WORKSPACE_CONFIG_KEYS, } from './workspace-config.schema.js';
-const commandsThatRequireFiles = new Set(['addMedia', 'runFlow', 'runScript']);
+const commandsThatRequireFiles = new Set([
+    'addMedia',
+    'assertScreenshot',
+    'runFlow',
+    'runScript',
+]);
+/**
+ * Commands whose file references are best-effort rather than mandatory.
+ *
+ * `assertScreenshot` baselines are legitimately absent on a first run, and
+ * Maestro's own "Screenshot file not found — searched in: …" error is more
+ * useful than ours, so a missing baseline must not abort the upload the way a
+ * missing `addMedia` file does.
+ */
+const commandsWithOptionalFiles = new Set(['assertScreenshot']);
+/**
+ * Extensions Maestro's `normalizeScreenshotPath` recognises; anything else
+ * gets `.png` appended, so `assertScreenshot: home` means `home.png`.
+ */
+const SCREENSHOT_EXTENSIONS = new Set([
+    '.bmp',
+    '.gif',
+    '.heic',
+    '.heif',
+    '.jpeg',
+    '.jpg',
+    '.png',
+    '.tiff',
+    '.wbmp',
+]);
+/**
+ * Mirror Maestro's `Orchestra.normalizeScreenshotPath`: a screenshot path with
+ * no image extension gets `.png`. Without this, `assertScreenshot: home` looks
+ * like a missing file here while resolving fine on the device.
+ *
+ * @param relativePath - The path as written in the flow
+ * @returns The path with an image extension guaranteed
+ */
+function normalizeScreenshotPath(relativePath) {
+    const extension = path.extname(relativePath).toLowerCase();
+    return SCREENSHOT_EXTENSIONS.has(extension)
+        ? relativePath
+        : `${relativePath}.png`;
+}
 export function getFlowsToRunInSequence(paths, flowOrder, debug = false) {
     if (flowOrder.length === 0) {
         if (debug) {
@@ -145,12 +188,27 @@ export const checkIfFilesExistInWorkspace = (commandName, command, absoluteFileP
     const errors = [];
     const files = [];
     const directory = path.dirname(absoluteFilePath);
+    const isScreenshot = commandName === 'assertScreenshot';
+    const isOptional = commandsWithOptionalFiles.has(commandName);
     const buildError = (error) => `Flow file "${absoluteFilePath}" has a command "${commandName}" that references a ${error} ${JSON.stringify(command)}`;
     const processFilePath = (relativePath) => {
-        const absoluteFilePath = path.normalize(path.resolve(directory, relativePath));
+        // A JS/variable-interpolated path (`screenshots/${DCD_DEVICE}/home`) can't
+        // be resolved without running the flow. Skip it rather than guessing — the
+        // config.yaml `includedPaths` key is how those files get bundled.
+        if (relativePath.includes('${'))
+            return;
+        const resolvedRelativePath = isScreenshot
+            ? normalizeScreenshotPath(relativePath)
+            : relativePath;
+        const absoluteFilePath = path.normalize(path.resolve(directory, resolvedRelativePath));
         const error = checkFile(absoluteFilePath);
-        if (error)
+        if (error) {
+            // Optional references drop out entirely when missing: pushing them onto
+            // `files` would put a non-existent path into the zip manifest.
+            if (isOptional)
+                return;
             errors.push(buildError(error));
+        }
         files.push(absoluteFilePath);
     };
     // simple command — processFilePath already resolves against `directory`
@@ -163,10 +221,15 @@ export const checkIfFilesExistInWorkspace = (commandName, command, absoluteFileP
             processFilePath(file);
         }
     }
-    // object command
+    // object command. `file` is addMedia/runFlow/runScript; `path` is
+    // assertScreenshot's own key for the same thing.
     const x = command; // prevent annoying ts error
-    if (typeof command === 'object' && x?.file)
-        processFilePath(x.file);
+    if (typeof command === 'object' && !Array.isArray(command)) {
+        if (x?.file)
+            processFilePath(x.file);
+        if (isScreenshot && typeof x?.path === 'string')
+            processFilePath(x.path);
+    }
     return { errors, files };
 };
 const checkFile = (filePath) => {

package/dist/services/flow-paths.d.ts

@@ -3,8 +3,16 @@
  * file path. Segment comparison (not `startsWith`) so sibling dirs like
  * `flows`/`flows-extra` can't merge, and the file segment itself is never
  * consumed. Returns '' when the paths share no root at all (or none are given).
+ *
+ * `includedFiles` (config.yaml `includedPaths`) must be folded in for the same
+ * reason referenced files are: the zip strips this root as an anchored prefix,
+ * so a file outside it would get a non-relative entry name. Folding them in
+ * can raise the root — flows in `flows/` beside baselines in `screenshots/`
+ * shifts it from `<root>/flows` to `<root>`, so flow keys gain a `flows/`
+ * segment. That shift is what preserves the flow→baseline relative offset
+ * Maestro resolves against, and is already how `addMedia` behaves.
  */
-export declare function computeCommonRoot(testFileNames: string[], referencedFiles: string[]): string;
+export declare function computeCommonRoot(testFileNames: string[], referencedFiles: string[], includedFiles?: string[]): string;
 export interface FlowMetadataEntry {
     flowName: string;
     tags: string[];

package/dist/services/flow-paths.js

@@ -12,9 +12,21 @@ import { toPortableRelativePath } from '../utils/paths.js';
  * file path. Segment comparison (not `startsWith`) so sibling dirs like
  * `flows`/`flows-extra` can't merge, and the file segment itself is never
  * consumed. Returns '' when the paths share no root at all (or none are given).
+ *
+ * `includedFiles` (config.yaml `includedPaths`) must be folded in for the same
+ * reason referenced files are: the zip strips this root as an anchored prefix,
+ * so a file outside it would get a non-relative entry name. Folding them in
+ * can raise the root — flows in `flows/` beside baselines in `screenshots/`
+ * shifts it from `<root>/flows` to `<root>`, so flow keys gain a `flows/`
+ * segment. That shift is what preserves the flow→baseline relative offset
+ * Maestro resolves against, and is already how `addMedia` behaves.
  */
-export function computeCommonRoot(testFileNames, referencedFiles) {
-    const pathsShortestToLongest = [...testFileNames, ...referencedFiles].sort((a, b) => a.split(path.sep).length - b.split(path.sep).length);
+export function computeCommonRoot(testFileNames, referencedFiles, includedFiles = []) {
+    const pathsShortestToLongest = [
+        ...testFileNames,
+        ...referencedFiles,
+        ...includedFiles,
+    ].sort((a, b) => a.split(path.sep).length - b.split(path.sep).length);
     if (pathsShortestToLongest.length === 0)
         return '';
     const splitPaths = pathsShortestToLongest.map((p) => p.split(path.sep));

package/dist/services/results-polling.service.d.ts

@@ -45,9 +45,29 @@ export declare function deviceFromResultRow(r: {
     config?: unknown;
     simulator_name?: string | null;
 }): TestDevice | undefined;
+/**
+ * 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 declare function isSupersededRow(r: unknown): boolean;
+/** The upload that superseded this run, for the console link. */
+export declare function supersedingUploadId(results: unknown[]): string | undefined;
+/**
+ * The superseding run's console link, derived from this run's.
+ *
+ * The `result` parameter deep-links a single test, and that id belongs to
+ * THIS upload — carrying it over would point at a result the newer upload
+ * does not contain. Swap the upload id and drop it.
+ */
+export declare function supersedingConsoleUrl(consoleUrl: string, uploadId: string, supersededBy: string): string;
 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;

package/dist/services/results-polling.service.js

@@ -38,6 +38,45 @@ export function deviceFromResultRow(r) {
         googlePlay: sim ? /(_PLAY|-play)$/.test(sim) : undefined,
     };
 }
+/**
+ * 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) {
+    const reason = r
+        ?.cancellation_reason;
+    return typeof reason === 'string' && reason.startsWith('superseded_by:');
+}
+/** The upload that superseded this run, for the console link. */
+export function supersedingUploadId(results) {
+    for (const r of results) {
+        const reason = r
+            ?.cancellation_reason;
+        if (typeof reason === 'string' && reason.startsWith('superseded_by:')) {
+            return reason.slice('superseded_by:'.length) || undefined;
+        }
+    }
+    return undefined;
+}
+/**
+ * The superseding run's console link, derived from this run's.
+ *
+ * The `result` parameter deep-links a single test, and that id belongs to
+ * THIS upload — carrying it over would point at a result the newer upload
+ * does not contain. Swap the upload id and drop it.
+ */
+export function supersedingConsoleUrl(consoleUrl, uploadId, supersededBy) {
+    return consoleUrl
+        .replace(uploadId, supersededBy)
+        .replace(/&result=[^&]*/, '')
+        .replace(/\?result=[^&]*&/, '?')
+        .replace(/\?result=[^&]*$/, '');
+}
 /**
  * Service for polling test results from the API
  */
@@ -226,13 +265,23 @@ export class ResultsPollingService {
     }
     buildPollingResult(results, uploadId, consoleUrl, testMetadata) {
         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
@@ -259,8 +308,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,
             failed,
@@ -386,6 +439,27 @@ export class ResultsPollingService {
         }
         this.displayFinalResults(updatedResults, consoleUrl, json, logger);
         const output = this.buildPollingResult(updatedResults, uploadId, consoleUrl, 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(supersedingConsoleUrl(consoleUrl, uploadId, newer)),
+                        ],
+                    ])));
+                }
+                logger('\n');
+            }
+            return output;
+        }
         if (output.status === 'FAILED') {
             if (debug && logger) {
                 logger(`[DEBUG] Some tests failed, returning failed status`);

package/dist/services/test-submission.service.d.ts

@@ -6,6 +6,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;

package/dist/services/test-submission.service.js

@@ -20,8 +20,8 @@ export class TestSubmissionService {
      * @returns The flow zip buffer, its SHA-256, and the string-encoded fields
      */
     async buildTestPayload(config) {
-        const { apiUrl, appBinaryId, encrypt = false, flowFile, executionPlan, commonRoot, cliVersion, env = [], metadata = [], googlePlay = false, androidApiLevel, androidDevice, androidNoSnapshot, iOSVersion, iOSDevice, name, runnerType, maestroVersion, deviceLocale, orientation, retry, continueOnFailure = true, renderEngine, report, showCrosshairs, maestroChromeOnboarding, raw, disableAnimations, deviceMatrix, debug = false, logger, } = config;
-        const { allExcludeTags, allIncludeTags, flowMetadata, flowOverrides, flowsToRun: testFileNames, referencedFiles, sequence, workspaceConfig, } = executionPlan;
+        const { apiUrl, appBinaryId, encrypt = false, flowFile, executionPlan, commonRoot, cliVersion, env = [], metadata = [], cancelPrevious = false, googlePlay = false, androidApiLevel, androidDevice, androidNoSnapshot, iOSVersion, iOSDevice, name, runnerType, maestroVersion, deviceLocale, orientation, retry, continueOnFailure = true, renderEngine, report, showCrosshairs, maestroChromeOnboarding, raw, disableAnimations, deviceMatrix, debug = false, logger, } = config;
+        const { allExcludeTags, allIncludeTags, flowMetadata, flowOverrides, flowsToRun: testFileNames, includedFiles = [], referencedFiles, sequence, workspaceConfig, } = executionPlan;
         const { flows: sequentialFlows = [] } = sequence ?? {};
         const envObject = this.parseKeyValuePairs(env);
         const metadataObject = this.parseKeyValuePairs(metadata);
@@ -42,6 +42,17 @@ export class TestSubmissionService {
                 }
             }
         }
+        // Logged separately from referencedFiles: these come from config.yaml's
+        // `includedPaths` rather than from a flow command, and they can raise the
+        // common root (see computeCommonRoot) — which shows up here as every flow
+        // key gaining a leading directory segment.
+        if (includedFiles.length > 0) {
+            this.logDebug(debug, logger, `[DEBUG] Uploading ${includedFiles.length} file(s) from \`includedPaths\`:`);
+            for (const file of includedFiles) {
+                const normalizedPath = this.normalizeFilePath(file, commonRoot);
+                this.logDebug(debug, logger, `[DEBUG]   - ${normalizedPath}`);
+            }
+        }
         this.logDebug(debug, logger, `[DEBUG] Compressing files from path: ${flowFile}`);
         const plaintextZip = await compressFilesFromRelativePath(flowFile?.endsWith('.yaml') || flowFile?.endsWith('.yml')
             ? path.dirname(flowFile)
@@ -50,6 +61,7 @@ export class TestSubmissionService {
                 ...referencedFiles,
                 ...testFileNames,
                 ...sequentialFlows,
+                ...includedFiles,
             ]),
         ], commonRoot);
         this.logDebug(debug, logger, `[DEBUG] Compressed file size: ${plaintextZip.length} bytes`);
@@ -144,6 +156,11 @@ export class TestSubmissionService {
             fields.metadata = JSON.stringify(metadataPayload);
             this.logDebug(debug, logger, `[DEBUG] Sending metadata to API: ${JSON.stringify(metadataPayload)}`);
         }
+        // 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,

package/dist/services/workspace-config.schema.d.ts

@@ -12,6 +12,7 @@ export declare const WorkspaceConfigSchema: z.ZodObject<{
         flowsOrder: z.ZodArray<z.ZodString>;
     }, z.core.$strip>>>;
     flows: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
+    includedPaths: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
     includeTags: z.ZodOptional<z.ZodNullable<z.ZodPreprocess<z.ZodArray<z.ZodString>, unknown>>>;
     local: z.ZodOptional<z.ZodNullable<z.ZodObject<{
         deterministicOrder: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;

package/dist/services/workspace-config.schema.js

@@ -42,6 +42,7 @@ export const WorkspaceConfigSchema = z.looseObject({
     excludeTags: tagList.nullish(),
     executionOrder: ExecutionOrderSchema.nullish(),
     flows: z.array(z.string()).nullish(),
+    includedPaths: z.array(z.string()).nullish(),
     includeTags: tagList.nullish(),
     local: z
         .looseObject({ deterministicOrder: z.boolean().nullish() })
@@ -80,10 +81,15 @@ export const WORKSPACE_CONFIG_KEYS = new Set(Object.keys(WorkspaceConfigSchema.s
  * Near-misses that aren't just a casing slip on a real key. Keyed lowercase.
  */
 const KEY_ALIASES = {
+    assets: 'includedPaths',
     continueonfailure: 'executionOrder.continueOnFailure',
     excludetag: 'excludeTags',
+    files: 'includedPaths',
     floworder: 'executionOrder.flowsOrder',
     flowsorder: 'executionOrder.flowsOrder',
+    includedpath: 'includedPaths',
+    includefiles: 'includedPaths',
+    includepaths: 'includedPaths',
     includetag: 'includeTags',
     tags: 'includeTags / excludeTags',
 };

package/package.json

@@ -57,9 +57,19 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://devicecloud.dev"
+    "url": "git+https://github.com/devicecloud-dev/dcd-cli.git"
   },
-  "version": "5.5.0",
+  "scripts": {
+    "dcd": "tsx src/index.ts",
+    "build": "shx rm -rf dist && tsc -b && shx chmod +x dist/index.js dist/mcp/index.js",
+    "build:binaries": "node scripts/build-binaries.mjs",
+    "lint": "eslint src test --ext .ts",
+    "prepare": "pnpm build && husky",
+    "test": "node scripts/test-runner.mjs",
+    "test:unit": "node scripts/test-runner.mjs --unit",
+    "typecheck": "tsc --noEmit -p tsconfig.test.json"
+  },
+  "version": "5.6.0-beta.3",
   "bugs": {
     "url": "https://discord.gg/gm3mJwcNw8"
   },
@@ -72,13 +82,43 @@
     "testing"
   ],
   "types": "dist/index.d.ts",
-  "scripts": {
-    "dcd": "tsx src/index.ts",
-    "build": "shx rm -rf dist && tsc -b && shx chmod +x dist/index.js dist/mcp/index.js",
-    "build:binaries": "node scripts/build-binaries.mjs",
-    "lint": "eslint src test --ext .ts",
-    "test": "node scripts/test-runner.mjs",
-    "test:unit": "node scripts/test-runner.mjs --unit",
-    "typecheck": "tsc --noEmit -p tsconfig.test.json"
+  "packageManager": "pnpm@10.17.1",
+  "pnpm": {
+    "overrides": {
+      "js-yaml@<3.14.2": ">=3.14.2",
+      "js-yaml@>=4.0.0 <4.2.0": ">=4.2.0",
+      "js-yaml@>=5.0.0 <5.2.2": ">=5.2.2",
+      "tar@<7.5.16": ">=7.5.16",
+      "@isaacs/brace-expansion": ">=5.0.1",
+      "fast-xml-parser": ">=5.5.7",
+      "flatted": ">=3.4.2",
+      "lodash": ">=4.18.0",
+      "@xmldom/xmldom": ">=0.9.12",
+      "minimatch@<3.1.4": "3.1.4",
+      "minimatch@>=5.0.0 <5.1.8": "5.1.8",
+      "minimatch@>=9.0.0 <9.0.7": "9.0.7",
+      "minimatch@>=10.0.0 <10.2.3": "10.2.3",
+      "picomatch@<2.3.2": "2.3.2",
+      "picomatch@>=4.0.0 <4.0.4": "4.0.4",
+      "serialize-javascript": ">=7.0.5",
+      "ajv@<7.0.0": "6.14.0",
+      "diff@>=4.0.0 <6.0.0": "4.0.4",
+      "diff@>=6.0.0": "8.0.3",
+      "brace-expansion@<1.1.16": "1.1.16",
+      "brace-expansion@>=2.0.0 <2.0.3": "2.0.3",
+      "brace-expansion@>=3.0.0 <5.0.9": "5.0.9",
+      "ws@>=8.0.0 <8.21.0": "8.21.0",
+      "esbuild@<0.28.1": ">=0.28.1",
+      "qs@<6.16.0": "6.16.0",
+      "fast-uri@>=3.0.0 <3.1.6": "3.1.6",
+      "hono@>=4.0.0 <4.13.5": "4.13.5",
+      "micromatch>picomatch": "^2.3.2",
+      "tinyglobby>picomatch": "^4.0.4"
+    },
+    "auditConfig": {
+      "ignoreGhsas": [
+        "GHSA-frvp-7c67-39w9"
+      ]
+    }
   }
-}
+}