@devicecloud.dev/dcd 5.0.1-beta.1 → 5.2.0-beta.1

package/dist/commands/cloud.d.ts

@@ -185,6 +185,14 @@ export declare const cloudCommand: import("citty").CommandDef<{
         readonly type: "string";
         readonly description: `[iOS only] iOS version to run your flow against (options: ${string})`;
     };
+    readonly 'ios-config': {
+        readonly type: "string";
+        readonly description: "[iOS only] Device-matrix cell as <device>:<version>, e.g. iphone-16:18. Repeatable — every flow runs once per cell (no cross-product). Cannot be combined with --android-config.";
+    };
+    readonly 'android-config': {
+        readonly type: "string";
+        readonly description: "[Android only] Device-matrix cell as <device>:<apiLevel> (append :play for Google Play), e.g. pixel-7:34 or pixel-7:34:play. Repeatable — every flow runs once per cell (no cross-product). Cannot be combined with --ios-config.";
+    };
     readonly orientation: {
         readonly type: "string";
         readonly description: "[Android only] The orientation of the device to run your flow against (0 = portrait, 90 = landscape)";

package/dist/commands/cloud.js

@@ -10,12 +10,13 @@ import { plan } from '../services/execution-plan.service.js';
 import { buildTestMetadataMap, computeCommonRoot, } from '../services/flow-paths.js';
 import { MoropoService } from '../services/moropo.service.js';
 import { ReportDownloadService } from '../services/report-download.service.js';
-import { ResultsPollingService, RunFailedError, } from '../services/results-polling.service.js';
+import { deviceFromResultRow, ResultsPollingService, RunFailedError, } from '../services/results-polling.service.js';
 import { telemetry } from '../services/telemetry.service.js';
 import { TestSubmissionService } from '../services/test-submission.service.js';
 import { VersionService } from '../services/version.service.js';
-import { EAndroidApiLevels, EAndroidDevices, EiOSDevices, EiOSVersions, } from '../types/domain/device.types.js';
+import { EAndroidApiLevels, EAndroidDevices, EiOSDevices, EiOSVersions, isIosMatrixConfig, } from '../types/domain/device.types.js';
 import { resolveAuth } from '../utils/auth.js';
+import { matrixIsIos, parseDeviceMatrix } from '../utils/device-matrix.js';
 import { detectCiContext, isCI } from '../utils/ci.js';
 import { CliError, coerceArray, collectRepeatedFlag, getCliVersion, getUpgradeCommand, logger, parseIntFlag, validateEnum, } from '../utils/cli.js';
 import { fetchCompatibilityData, } from '../utils/compatibility.js';
@@ -137,6 +138,10 @@ export const cloudCommand = defineCommand({
             const androidApiLevel = validateEnum(args['android-api-level'], Object.values(EAndroidApiLevels), 'android-api-level');
             const androidDevice = validateEnum(args['android-device'], Object.values(EAndroidDevices), 'android-device');
             const androidNoSnapshot = Boolean(args['android-no-snapshot']);
+            // Repeatable device-matrix flags: one validated cell each, no cross-product.
+            const iosConfigFlags = collectRepeatedFlag(rawArgs, ['--ios-config']);
+            const androidConfigFlags = collectRepeatedFlag(rawArgs, ['--android-config']);
+            const deviceMatrix = parseDeviceMatrix(iosConfigFlags, androidConfigFlags);
             const json = Boolean(args.json);
             const jsonFileFlag = Boolean(args['json-file']);
             const jsonFileName = args['json-file-name'];
@@ -326,6 +331,17 @@ export const cloudCommand = defineCommand({
                 ci_wrapper_version: ciContext.wrapperVersion,
             }, { out });
             deviceValidationService.validateAndroidDevice(androidApiLevel, androidDevice, googlePlay, compatibilityData, { debug, logger: (m) => out(m) });
+            // Validate every device-matrix cell up front — each on its own, against
+            // the same compatibility matrix — so an unsupported cell fails fast,
+            // naming it, before anything is uploaded.
+            for (const cfg of deviceMatrix) {
+                if (isIosMatrixConfig(cfg)) {
+                    deviceValidationService.validateiOSDevice(cfg.iOSVersion, cfg.iOSDevice, compatibilityData, { debug, logger: (m) => out(m) });
+                }
+                else {
+                    deviceValidationService.validateAndroidDevice(cfg.androidApiLevel, cfg.androidDevice, cfg.googlePlay ?? googlePlay, compatibilityData, { debug, logger: (m) => out(m) });
+                }
+            }
             if (maestroChromeOnboarding && !androidApiLevel && !androidDevice) {
                 warnOut('The --maestro-chrome-onboarding flag only applies to Android tests and will be ignored for iOS tests.');
             }
@@ -417,6 +433,8 @@ export const cloudCommand = defineCommand({
                 'include-tags': includeTags,
                 'exclude-tags': excludeTags,
                 'exclude-flows': excludeFlows,
+                'ios-config': iosConfigFlags,
+                'android-config': androidConfigFlags,
             };
             for (const [k, v] of Object.entries(args)) {
                 if (!canonicalFlagKeys.has(k))
@@ -514,6 +532,7 @@ export const cloudCommand = defineCommand({
                 continueOnFailure,
                 debug,
                 deviceLocale,
+                deviceMatrix,
                 env,
                 executionPlan,
                 flowFile,
@@ -535,6 +554,40 @@ export const cloudCommand = defineCommand({
                 maestroChromeOnboarding,
                 disableAnimations,
             });
+            // Device-matrix cost preview: the server prices the exact fan-out (quote
+            // == charge) so the user sees the cell count and estimated cost before the
+            // flow zip is uploaded. An unsupported cell fails fast here. Skipped when
+            // there is no matrix, and tolerant of older APIs that lack the endpoint.
+            if (deviceMatrix.length > 0) {
+                const estimate = await ApiGateway.estimateMatrix(apiUrl, auth, fields);
+                if (estimate) {
+                    const osPrefix = matrixIsIos(deviceMatrix) ? 'iOS' : 'API';
+                    const rows = ui.fields([
+                        ['cells', colors.highlight(String(estimate.cellCount))],
+                        ['est. cost', colors.highlight(`$${estimate.totalCost.toFixed(2)}`)],
+                    ]);
+                    for (const col of estimate.columns) {
+                        const label = [
+                            col.deviceName,
+                            col.osVersion && `${osPrefix} ${col.osVersion}`,
+                            col.googlePlay && 'Play',
+                        ]
+                            .filter(Boolean)
+                            .join(' · ');
+                        rows.push(...ui.fields([
+                            [
+                                label,
+                                colors.dim(`${col.flowCount} flow${col.flowCount === 1 ? '' : 's'} · $${col.cost.toFixed(2)}`),
+                            ],
+                        ]));
+                    }
+                    if (estimate.excludedFlows.length > 0) {
+                        rows.push(colors.dim(`${estimate.excludedFlows.length} flow${estimate.excludedFlows.length === 1 ? '' : 's'} target their own device (excluded from the matrix)`));
+                    }
+                    out(ui.section('Device matrix'));
+                    out(ui.branch(rows));
+                }
+            }
             // New path: upload the zip directly to storage, then submit a JSON test
             // referencing it. Older API deployments lack these endpoints — a real API
             // 404s (route undefined), some proxies 405 (path/method not allowed); in
@@ -600,6 +653,7 @@ export const cloudCommand = defineCommand({
                     consoleUrl: url,
                     status: 'PENDING',
                     tests: results.map((r) => ({
+                        device: deviceFromResultRow(r),
                         fileName: r.test_file_name,
                         flowName: testMetadataMap[r.test_file_name]?.flowName ||
                             path.parse(r.test_file_name).name,

package/dist/commands/login.js

@@ -10,8 +10,11 @@
  *  2. CLI opens <frontend>/cli-login?state=...&code_challenge=... in the browser.
  *  3. User signs in (OTP or SSO) and explicitly authorizes the handoff on
  *     the frontend.
- *  4. Frontend POSTs {state, code_challenge, session...} to the dcd api at
- *     POST /cli-login/handoff. The api stores a short-TTL row keyed by state.
+ *  4. Frontend POSTs {state, code_challenge, access_token} to the dcd api at
+ *     POST /cli-login/handoff — the access token is proof of identity only.
+ *     The api verifies it, mints a *dedicated* Supabase session for the CLI
+ *     (its own refresh-token family, so browser token rotation can't
+ *     invalidate it), and stores it in a short-TTL row keyed by state.
  *  5. Meanwhile, the CLI polls POST /cli-login/claim with {state, code_verifier}.
  *     Once the api has the row, it verifies sha256(verifier) === challenge,
  *     deletes the row, and returns the session.
@@ -68,19 +71,28 @@ export const loginCommand = defineCommand({
         const noBrowser = args.browser === false;
         // If there's an existing stored session, make the user confirm before we
         // overwrite it. Silent clobber is fine for power users but surprising if
-        // someone runs `dcd login` by mistake while already authenticated.
+        // someone runs `dcd login` by mistake while already authenticated. An
+        // already-expired session gets no confirm: the user is here because a
+        // command told them to re-login, and "Already logged in… keep session?"
+        // would dead-end them on a session that no longer works.
         const existing = readConfig();
         if (existing?.session) {
-            const currentOrg = existing.current_org_name ?? existing.current_org_id;
-            const ok = await p.confirm({
-                message: `Already logged in as ${existing.session.user_email}` +
-                    (currentOrg ? ` (org ${currentOrg})` : '') +
-                    `. Sign out and log in again?`,
-                initialValue: false,
-            });
-            if (p.isCancel(ok) || !ok) {
-                logger.log(ui.info('Keeping existing session.'));
-                return;
+            const now = Math.floor(Date.now() / 1000);
+            if (existing.session.expires_at <= now) {
+                logger.log(ui.info(`Your session for ${existing.session.user_email} has expired — signing in again.`));
+            }
+            else {
+                const currentOrg = existing.current_org_name ?? existing.current_org_id;
+                const ok = await p.confirm({
+                    message: `Already logged in as ${existing.session.user_email}` +
+                        (currentOrg ? ` (org ${currentOrg})` : '') +
+                        `. Sign out and log in again?`,
+                    initialValue: true,
+                });
+                if (p.isCancel(ok) || !ok) {
+                    logger.log(ui.info('Keeping existing session.'));
+                    return;
+                }
             }
         }
         const env = inferEnvFromApiUrl(apiUrl);

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

@@ -27,6 +27,14 @@ export declare const deviceFlags: {
         readonly type: "string";
         readonly description: `[iOS only] iOS version to run your flow against (options: ${string})`;
     };
+    readonly 'ios-config': {
+        readonly type: "string";
+        readonly description: "[iOS only] Device-matrix cell as <device>:<version>, e.g. iphone-16:18. Repeatable — every flow runs once per cell (no cross-product). Cannot be combined with --android-config.";
+    };
+    readonly 'android-config': {
+        readonly type: "string";
+        readonly description: "[Android only] Device-matrix cell as <device>:<apiLevel> (append :play for Google Play), e.g. pixel-7:34 or pixel-7:34:play. Repeatable — every flow runs once per cell (no cross-product). Cannot be combined with --ios-config.";
+    };
     readonly orientation: {
         readonly type: "string";
         readonly description: "[Android only] The orientation of the device to run your flow against (0 = portrait, 90 = landscape)";

package/dist/config/flags/device.flags.js

@@ -32,6 +32,14 @@ export const deviceFlags = {
         type: 'string',
         description: `[iOS only] iOS version to run your flow against (options: ${iosVersions})`,
     },
+    'ios-config': {
+        type: 'string',
+        description: `[iOS only] Device-matrix cell as <device>:<version>, e.g. iphone-16:18. Repeatable — every flow runs once per cell (no cross-product). Cannot be combined with --android-config.`,
+    },
+    'android-config': {
+        type: 'string',
+        description: `[Android only] Device-matrix cell as <device>:<apiLevel> (append :play for Google Play), e.g. pixel-7:34 or pixel-7:34:play. Repeatable — every flow runs once per cell (no cross-product). Cannot be combined with --ios-config.`,
+    },
     orientation: {
         type: 'string',
         description: '[Android only] The orientation of the device to run your flow against (0 = portrait, 90 = landscape)',

package/dist/constants.d.ts

@@ -171,6 +171,14 @@ export declare const flags: {
         readonly type: "string";
         readonly description: `[iOS only] iOS version to run your flow against (options: ${string})`;
     };
+    readonly 'ios-config': {
+        readonly type: "string";
+        readonly description: "[iOS only] Device-matrix cell as <device>:<version>, e.g. iphone-16:18. Repeatable — every flow runs once per cell (no cross-product). Cannot be combined with --android-config.";
+    };
+    readonly 'android-config': {
+        readonly type: "string";
+        readonly description: "[Android only] Device-matrix cell as <device>:<apiLevel> (append :play for Google Play), e.g. pixel-7:34 or pixel-7:34:play. Repeatable — every flow runs once per cell (no cross-product). Cannot be combined with --ios-config.";
+    };
     readonly orientation: {
         readonly type: "string";
         readonly description: "[Android only] The orientation of the device to run your flow against (0 = portrait, 90 = landscape)";

package/dist/gateways/api-gateway.d.ts

@@ -120,6 +120,27 @@ export declare const ApiGateway: {
         message?: string;
         results?: components["schemas"]["IDBResult"][];
     }>;
+    /**
+     * Dry-run cost + cell-count estimate for a (possibly device-matrix)
+     * submission. Runs the same resolve → validate → fan-out → price core as the
+     * submit path server-side, without persisting. The preview is best-effort:
+     * an API that predates this endpoint 404s (route undefined) or 405s (route
+     * matched a sibling path, no POST) — in either case return null so the caller
+     * proceeds without a preview. A 400 (an invalid config) still surfaces as a
+     * normal API error so the CLI can fail fast before uploading the flow zip.
+     */
+    estimateMatrix(baseUrl: string, auth: AuthContext, body: Record<string, unknown>): Promise<{
+        cellCount: number;
+        totalCost: number;
+        excludedFlows: string[];
+        columns: Array<{
+            deviceName: string;
+            osVersion: string;
+            googlePlay: boolean;
+            flowCount: number;
+            cost: number;
+        }>;
+    } | null>;
     /**
      * Generic report download method that handles both junit and allure reports
      * @param baseUrl - API base URL

package/dist/gateways/api-gateway.js

@@ -418,6 +418,40 @@ export const ApiGateway = {
             throw error;
         }
     },
+    /**
+     * Dry-run cost + cell-count estimate for a (possibly device-matrix)
+     * submission. Runs the same resolve → validate → fan-out → price core as the
+     * submit path server-side, without persisting. The preview is best-effort:
+     * an API that predates this endpoint 404s (route undefined) or 405s (route
+     * matched a sibling path, no POST) — in either case return null so the caller
+     * proceeds without a preview. A 400 (an invalid config) still surfaces as a
+     * normal API error so the CLI can fail fast before uploading the flow zip.
+     */
+    async estimateMatrix(baseUrl, auth, body) {
+        try {
+            const res = await fetch(`${baseUrl}/uploads/estimateMatrix`, {
+                body: JSON.stringify(body),
+                headers: {
+                    'content-type': 'application/json',
+                    ...auth.headers,
+                },
+                method: 'POST',
+            });
+            if (res.status === 404 || res.status === 405) {
+                return null;
+            }
+            if (!res.ok) {
+                await this.handleApiError(res, 'Failed to estimate device matrix');
+            }
+            return await parseJsonResponse(res, 'Failed to estimate device matrix');
+        }
+        catch (error) {
+            if (error instanceof TypeError && error.message === 'fetch failed') {
+                throw this.enhanceFetchError(error, `${baseUrl}/uploads/estimateMatrix`);
+            }
+            throw error;
+        }
+    },
     /**
      * Generic report download method that handles both junit and allure reports
      * @param baseUrl - API base URL

package/dist/gateways/cli-auth-gateway.d.ts

@@ -1,4 +1,14 @@
 import type { StoredSession } from '../utils/config-store.js';
+/**
+ * Thrown when a session refresh fails. `definitive` distinguishes "Supabase
+ * rejected this refresh token" (revoked, already used, malformed — re-login
+ * is the only fix) from transient failures (network, GoTrue 5xx) where the
+ * stored session may still be good on the next attempt.
+ */
+export declare class SessionRefreshError extends Error {
+    readonly definitive: boolean;
+    constructor(message: string, definitive: boolean);
+}
 export interface RefreshedSession {
     access_token: string;
     refresh_token: string;

package/dist/gateways/cli-auth-gateway.js

@@ -3,9 +3,23 @@
  * and sign-out (best-effort revocation on the Supabase side).
  *
  * Does not talk to the dcd API — the dcd-side session exchange lives in the
- * login command's loopback flow, where the frontend POSTs ciphertext back.
+ * login command's PKCE rendezvous flow (see src/commands/login.ts).
  */
-import { createClient } from '@supabase/supabase-js';
+import { createClient, isAuthApiError } from '@supabase/supabase-js';
+/**
+ * Thrown when a session refresh fails. `definitive` distinguishes "Supabase
+ * rejected this refresh token" (revoked, already used, malformed — re-login
+ * is the only fix) from transient failures (network, GoTrue 5xx) where the
+ * stored session may still be good on the next attempt.
+ */
+export class SessionRefreshError extends Error {
+    definitive;
+    constructor(message, definitive) {
+        super(message);
+        this.definitive = definitive;
+        this.name = 'SessionRefreshError';
+    }
+}
 function client(supabaseUrl, supabaseAnonKey) {
     return createClient(supabaseUrl, supabaseAnonKey, {
         auth: { persistSession: false, autoRefreshToken: false, detectSessionInUrl: false },
@@ -18,8 +32,14 @@ export const CliAuthGateway = {
             refresh_token: session.refresh_token,
         });
         if (error || !data.session || !data.user) {
-            throw new Error(`Failed to refresh session: ${error?.message ?? 'no session returned'}. ` +
-                `Run \`dcd login\` again.`);
+            // 4xx from GoTrue means the token itself was rejected; anything else
+            // (fetch failure, 5xx) could succeed on retry with the same token.
+            const definitive = error != null &&
+                isAuthApiError(error) &&
+                error.status >= 400 &&
+                error.status < 500;
+            throw new SessionRefreshError(`Failed to refresh session: ${error?.message ?? 'no session returned'}. ` +
+                `Run \`dcd login\` again.`, definitive);
         }
         const s = data.session;
         const u = data.user;

package/dist/services/notices.service.js

@@ -1,5 +1,5 @@
 import { ui } from '../utils/ui.js';
-import { colors, symbols } from '../utils/styling.js';
+import { colors } from '../utils/styling.js';
 import { compareSemver } from './version.service.js';
 function isPresent(raw) {
     return raw !== null && raw !== undefined && raw !== false && raw !== '';
@@ -48,12 +48,11 @@ function renderNotice(notice, opts) {
     }
     switch (notice.level) {
         case 'deprecation':
-            // Red ⚠ so a deprecation reads as more serious than a plain (yellow) warn.
-            opts.out(`${colors.error('⚠')} ${colors.bold(notice.title)}`);
+            opts.out(ui.deprecation(colors.bold(notice.title)));
             opts.out(ui.branch(rows));
             break;
         case 'warn':
-            opts.out(`${symbols.warning} ${colors.bold(notice.title)}`);
+            opts.out(ui.warn(colors.bold(notice.title)));
             opts.out(ui.branch(rows));
             break;
         case 'marketing':

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

@@ -23,10 +23,34 @@ export interface TestMetadata {
     /** Tags from YAML config 'tags' field */
     tags: string[];
 }
+/**
+ * The device a result ran on. Additive: single-device runs are unchanged, and
+ * a device matrix disambiguates two `tests[]` entries that share a `name` (the
+ * same flow on two devices) by their device.
+ */
+export interface TestDevice {
+    googlePlay?: boolean;
+    name?: string;
+    osVersion?: string;
+}
+/**
+ * Structured device for a result row. Prefers the friendly deviceName/osVersion
+ * the per-flow targeting / matrix fan-out stamps onto each result's config
+ * (#1097), falling back to the raw simulator_name for older rows. Returns
+ * undefined when neither is present, so single-device runs that predate the
+ * field simply omit `device`. Shared by the sync polling path and the async
+ * (--async --json) path so both emit an identical device shape.
+ */
+export declare function deviceFromResultRow(r: {
+    config?: unknown;
+    simulator_name?: string | null;
+}): TestDevice | undefined;
 export interface PollingResult {
     consoleUrl: string;
     status: 'FAILED' | 'PASSED';
     tests: Array<{
+        /** Device this result ran on (present when the API reports it). */
+        device?: TestDevice;
         durationSeconds: null | number;
         failReason?: string;
         /** File path of the test (same as name, for clarity) */

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

@@ -18,6 +18,26 @@ export class RunFailedError extends Error {
         this.name = 'RunFailedError';
     }
 }
+/**
+ * Structured device for a result row. Prefers the friendly deviceName/osVersion
+ * the per-flow targeting / matrix fan-out stamps onto each result's config
+ * (#1097), falling back to the raw simulator_name for older rows. Returns
+ * undefined when neither is present, so single-device runs that predate the
+ * field simply omit `device`. Shared by the sync polling path and the async
+ * (--async --json) path so both emit an identical device shape.
+ */
+export function deviceFromResultRow(r) {
+    const config = (r.config ?? {});
+    const sim = r.simulator_name ?? undefined;
+    const name = config.deviceName ?? sim;
+    if (!name && !config.osVersion)
+        return undefined;
+    return {
+        name,
+        osVersion: config.osVersion,
+        googlePlay: sim ? /(_PLAY|-play)$/.test(sim) : undefined,
+    };
+}
 /**
  * Service for polling test results from the API
  */
@@ -214,6 +234,10 @@ export class ResultsPollingService {
                 ? '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
+                // them through the helper's structural type.
+                device: deviceFromResultRow(r),
                 durationSeconds: r.duration_seconds ?? null,
                 failReason: r.status === 'FAILED' ? r.fail_reason || 'No reason provided' : undefined,
                 fileName: r.test_file_name,

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

@@ -1,3 +1,4 @@
+import { DeviceMatrixConfig } from '../types/domain/device.types.js';
 import { IExecutionPlan } from './execution-plan.service.js';
 export interface TestSubmissionConfig {
     androidApiLevel?: string;
@@ -9,6 +10,7 @@ export interface TestSubmissionConfig {
     continueOnFailure?: boolean;
     debug?: boolean;
     deviceLocale?: string;
+    deviceMatrix?: DeviceMatrixConfig[];
     disableAnimations?: boolean;
     env?: string[];
     executionPlan: IExecutionPlan;

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

@@ -19,7 +19,7 @@ export class TestSubmissionService {
      * @returns The flow zip buffer, its SHA-256, and the string-encoded fields
      */
     async buildTestPayload(config) {
-        const { appBinaryId, flowFile, executionPlan, commonRoot, cliVersion, env = [], metadata = [], googlePlay = false, androidApiLevel, androidDevice, androidNoSnapshot, iOSVersion, iOSDevice, name, runnerType, maestroVersion, deviceLocale, orientation, mitmHost, mitmPath, retry, continueOnFailure = true, report, showCrosshairs, maestroChromeOnboarding, raw, disableAnimations, debug = false, logger, } = config;
+        const { appBinaryId, flowFile, executionPlan, commonRoot, cliVersion, env = [], metadata = [], googlePlay = false, androidApiLevel, androidDevice, androidNoSnapshot, iOSVersion, iOSDevice, name, runnerType, maestroVersion, deviceLocale, orientation, mitmHost, mitmPath, retry, continueOnFailure = true, report, showCrosshairs, maestroChromeOnboarding, raw, disableAnimations, deviceMatrix, debug = false, logger, } = config;
         const { allExcludeTags, allIncludeTags, flowMetadata, flowOverrides, flowsToRun: testFileNames, referencedFiles, sequence, workspaceConfig, } = executionPlan;
         const { flows: sequentialFlows = [] } = sequence ?? {};
         const envObject = this.parseKeyValuePairs(env);
@@ -67,7 +67,20 @@ export class TestSubmissionService {
         fields.env = JSON.stringify(envObject);
         // Note: googlePlay is now included in configPayload below instead of as a separate field
         // to work around a FormData parsing issue in the API
-        const targetPlatform = iOSDevice || iOSVersion ? 'ios' : 'android';
+        // Explicit device matrix (one upload, N cells). Only sent when present, so
+        // single-device submissions stay byte-identical.
+        if (deviceMatrix && deviceMatrix.length > 0) {
+            fields.deviceMatrix = JSON.stringify(deviceMatrix);
+        }
+        // Platform used only to pick which workspace-config disableAnimations flag
+        // applies. A device matrix is single-platform; its first cell decides. Fall
+        // back to the scalar iOS flags for single-device submissions.
+        const matrixPlatform = deviceMatrix && deviceMatrix.length > 0
+            ? 'iOSDevice' in deviceMatrix[0]
+                ? 'ios'
+                : 'android'
+            : undefined;
+        const targetPlatform = matrixPlatform ?? (iOSDevice || iOSVersion ? 'ios' : 'android');
         const configYamlDisableAnimations = targetPlatform === 'ios'
             ? Boolean(workspaceConfig?.platform?.ios?.disableAnimations)
             : Boolean(workspaceConfig?.platform?.android?.disableAnimations);

package/dist/types/domain/device.types.d.ts

@@ -36,3 +36,21 @@ export declare enum EAndroidApiLevels {
     'thirtyTwo' = "32",
     'twentyNine' = "29"
 }
+/**
+ * One explicit device-matrix cell. iOS entries carry {iOSDevice, iOSVersion};
+ * Android entries carry {androidDevice, androidApiLevel} plus an optional Play
+ * channel. Sent to the API as the `deviceMatrix` array; every non-targeted flow
+ * runs once per cell. There is no cross-product — each entry is one cell.
+ */
+export type DeviceMatrixConfig = {
+    iOSDevice: string;
+    iOSVersion: string;
+} | {
+    androidApiLevel: string;
+    androidDevice: string;
+    googlePlay?: boolean;
+};
+export declare const isIosMatrixConfig: (c: DeviceMatrixConfig) => c is {
+    iOSDevice: string;
+    iOSVersion: string;
+};

package/dist/types/domain/device.types.js

@@ -40,3 +40,4 @@ export var EAndroidApiLevels;
     EAndroidApiLevels["thirtyTwo"] = "32";
     EAndroidApiLevels["twentyNine"] = "29";
 })(EAndroidApiLevels || (EAndroidApiLevels = {}));
+export const isIosMatrixConfig = (c) => 'iOSDevice' in c;

package/dist/utils/auth.d.ts

@@ -11,3 +11,11 @@ export interface ResolveAuthOptions {
     sessionOnly?: boolean;
 }
 export declare function resolveAuth(opts: ResolveAuthOptions): Promise<AuthContext>;
+/**
+ * Remove only the (definitively dead) session from the stored config, keeping
+ * env/api_url/org so a re-login lands back in the same environment. With the
+ * dead session gone, subsequent commands report "Not authenticated" instead
+ * of failing the same refresh, and `dcd login` skips its "already logged in"
+ * confirm. Exported for tests.
+ */
+export declare function dropStoredSession(): void;

package/dist/utils/auth.js

@@ -9,7 +9,7 @@
  */
 import { closeSync, openSync, rmSync, statSync } from 'node:fs';
 import { ENVIRONMENTS } from '../config/environments.js';
-import { CliAuthGateway } from '../gateways/cli-auth-gateway.js';
+import { CliAuthGateway, SessionRefreshError, } from '../gateways/cli-auth-gateway.js';
 import { telemetry } from '../services/telemetry.service.js';
 import { CliError } from './cli.js';
 import { getConfigPath, readConfig, writeConfig, } from './config-store.js';
@@ -86,7 +86,16 @@ async function refreshSessionWithLock(initial) {
             return { config: current, session };
         }
         const { anonKey } = ENVIRONMENTS[current.env].supabase;
-        const refreshed = await CliAuthGateway.refresh(current.supabase_url, anonKey, session);
+        let refreshed;
+        try {
+            refreshed = await CliAuthGateway.refresh(current.supabase_url, anonKey, session);
+        }
+        catch (error) {
+            if (error instanceof SessionRefreshError && error.definitive) {
+                dropStoredSession();
+            }
+            throw error;
+        }
         // Re-read again and merge only `session` so a concurrent `switch-org`
         // write (org fields) isn't reverted by our pre-refresh snapshot.
         const merged = { ...(readConfig() ?? current), session: refreshed };
@@ -100,6 +109,20 @@ async function refreshSessionWithLock(initial) {
         catch { /* best effort */ }
     }
 }
+/**
+ * Remove only the (definitively dead) session from the stored config, keeping
+ * env/api_url/org so a re-login lands back in the same environment. With the
+ * dead session gone, subsequent commands report "Not authenticated" instead
+ * of failing the same refresh, and `dcd login` skips its "already logged in"
+ * confirm. Exported for tests.
+ */
+export function dropStoredSession() {
+    const config = readConfig();
+    if (!config?.session)
+        return;
+    delete config.session;
+    writeConfig(config);
+}
 async function acquireRefreshLock(lockPath) {
     const deadline = Date.now() + LOCK_WAIT_MS;
     for (;;) {

package/dist/utils/device-matrix.d.ts

@@ -0,0 +1,16 @@
+import { DeviceMatrixConfig } from '../types/domain/device.types.js';
+/**
+ * Parse repeated `--ios-config <device>:<version>` and
+ * `--android-config <device>:<apiLevel>[:play]` flags into an explicit device
+ * matrix. Each entry is one validated cell — there is NO cross-product, because
+ * the compatibility matrix is ragged and a cross-product would invent cells the
+ * user never asked for.
+ *
+ * A device matrix is single-platform (one upload, one binary), so mixing iOS
+ * and Android configs is rejected here before anything is uploaded.
+ *
+ * @throws CliError on malformed syntax or a mixed-platform matrix.
+ */
+export declare function parseDeviceMatrix(iosConfigs: string[], androidConfigs: string[]): DeviceMatrixConfig[];
+/** True when the matrix targets iOS (used to pick the validation lookup). */
+export declare function matrixIsIos(configs: DeviceMatrixConfig[]): boolean;

package/dist/utils/device-matrix.js

@@ -0,0 +1,48 @@
+import { isIosMatrixConfig, } from '../types/domain/device.types.js';
+import { CliError } from './cli.js';
+/**
+ * Parse repeated `--ios-config <device>:<version>` and
+ * `--android-config <device>:<apiLevel>[:play]` flags into an explicit device
+ * matrix. Each entry is one validated cell — there is NO cross-product, because
+ * the compatibility matrix is ragged and a cross-product would invent cells the
+ * user never asked for.
+ *
+ * A device matrix is single-platform (one upload, one binary), so mixing iOS
+ * and Android configs is rejected here before anything is uploaded.
+ *
+ * @throws CliError on malformed syntax or a mixed-platform matrix.
+ */
+export function parseDeviceMatrix(iosConfigs, androidConfigs) {
+    if (iosConfigs.length > 0 && androidConfigs.length > 0) {
+        throw new CliError('A device matrix cannot mix platforms: use either --ios-config or --android-config, not both. One upload runs one binary.');
+    }
+    const configs = [];
+    for (const raw of iosConfigs) {
+        const parts = raw.split(':');
+        if (parts.length !== 2 || !parts[0] || !parts[1]) {
+            throw new CliError(`Invalid --ios-config "${raw}". Expected <device>:<version>, e.g. iphone-16:18.`);
+        }
+        configs.push({ iOSDevice: parts[0], iOSVersion: parts[1] });
+    }
+    for (const raw of androidConfigs) {
+        const parts = raw.split(':');
+        // <device>:<apiLevel> with an optional trailing :play for a Play cell.
+        if (parts.length < 2 ||
+            parts.length > 3 ||
+            !parts[0] ||
+            !parts[1] ||
+            (parts.length === 3 && parts[2] !== 'play')) {
+            throw new CliError(`Invalid --android-config "${raw}". Expected <device>:<apiLevel> or <device>:<apiLevel>:play, e.g. pixel-7:34 or pixel-7:34:play.`);
+        }
+        configs.push({
+            androidDevice: parts[0],
+            androidApiLevel: parts[1],
+            ...(parts.length === 3 ? { googlePlay: true } : {}),
+        });
+    }
+    return configs;
+}
+/** True when the matrix targets iOS (used to pick the validation lookup). */
+export function matrixIsIos(configs) {
+    return configs.length > 0 && isIosMatrixConfig(configs[0]);
+}

package/dist/utils/styling.d.ts

@@ -9,6 +9,7 @@ export declare const stripAnsi: (s: string) => string;
  */
 export declare const symbols: {
     readonly cancelled: string;
+    readonly deprecation: string;
     readonly error: string;
     readonly info: string;
     readonly pending: string;

package/dist/utils/styling.js

@@ -12,6 +12,7 @@ export const stripAnsi = (s) => s.replace(/\u001B\[[0-9;]*m/g, '');
  */
 export const symbols = {
     cancelled: chalk.gray('⊘'),
+    deprecation: chalk.red('⚠'),
     error: chalk.red('✗'),
     info: chalk.blue('ℹ'),
     pending: chalk.yellow('⏸'),

package/dist/utils/ui.d.ts

@@ -17,6 +17,8 @@ export declare const ui: {
      * visible width so ANSI colours never throw the columns off.
      */
     readonly fields: (pairs: Field[]) => string[];
+    /** `⚠ message` in red — a deprecation; reads as more serious than a (yellow) {@link warn}. */
+    readonly deprecation: (message: string) => string;
     /** `ℹ message` — neutral, standalone information. */
     readonly info: (message: string) => string;
     /** Dimmed secondary text — hints, tips, "you can close this terminal", etc. */

package/dist/utils/ui.js

@@ -52,6 +52,10 @@ export const ui = {
             return `${styled}${padding}   ${value}`;
         });
     },
+    /** `⚠ message` in red — a deprecation; reads as more serious than a (yellow) {@link warn}. */
+    deprecation(message) {
+        return `${symbols.deprecation} ${message}`;
+    },
     /** `ℹ message` — neutral, standalone information. */
     info(message) {
         return `${symbols.info} ${message}`;

package/package.json

@@ -32,7 +32,7 @@
     "eslint": "^10.5.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-import": "^2.32.0",
-    "eslint-plugin-unicorn": "^68.0.0",
+    "eslint-plugin-unicorn": "^69.0.0",
     "husky": "^9.1.7",
     "mocha": "^11.7.6",
     "prettier": "^3.8.4",
@@ -60,7 +60,7 @@
     "type": "git",
     "url": "https://devicecloud.dev"
   },
-  "version": "5.0.1-beta.1",
+  "version": "5.2.0-beta.1",
   "bugs": {
     "url": "https://discord.gg/gm3mJwcNw8"
   },