common-qa-mcp 0.4.1 → 0.6.0

package/dist/adapters/simplifyqa/adapter.js

@@ -1,21 +1,17 @@
 import os from 'node:os';
 import { makeClient } from '../http.js';
 import { RemoteMcpAdapter } from '../remoteMcp/adapter.js';
-import { applyCollectionSteps, buildTestcasePayload, deriveTcType, extractParamNames, fromSqaStep, looksSensitive, normalizeSuiteEntry, numericId, paramDefault, pickArray, str, SUITE_UPDATE_ALLOWED_KEYS, TECH_BY_STEPTYPE, toDefectSummary, toEpic, toEpicSummary, toFeature, toFeatureSummary, toFunction, toFunctionSummary, toModuleSummary, toObject, toReleaseSummary, toSavedRef, toSprintSummary, toStory, toStorySummary, toSuite, toSuiteSummary, toTaskSummary, toTcSummary, toTestCase, toVersionEntries, withTotal, } from './mapper.js';
-const PROJECT_URL_SEGMENT = {
-    testcase: 'testcase',
-    suite: 'suite',
-    run: 'reports/execution',
-    function: 'function',
-};
+import { applyCollectionSteps, buildTestcasePayload, deriveTcType, extractParamNames, fromSqaStep, looksSensitive, normalizeSuiteEntry, numericId, paramDefault, pickArray, str, SUITE_UPDATE_ALLOWED_KEYS, TECH_BY_STEPTYPE, toDefectSummary, toEpic, toEpicSummary, toFeature, toFeatureSummary, toFunction, toFunctionSummary, toModuleSaved, toModuleSummary, toObject, toReleaseSummary, toSavedRef, toSprintSummary, toStory, toStorySummary, toSuite, toSuiteSummary, toTaskSummary, toTcSummary, toTestCase, toVersionEntries, withTotal, } from './mapper.js';
 /** SQA run-row status → neutral RunStatus.state. */
 function mapRunState(s) {
     switch (s.toUpperCase()) {
         case 'PASSED': return 'passed';
         case 'FAILED': return 'failed';
         case 'STOPPED': return 'stopped';
-        case 'RUNNING': return 'running';
-        case 'QUEUED': return 'queued';
+        case 'RUNNING':
+        case 'INPROGRESS': return 'running';
+        case 'QUEUED':
+        case 'NOTEXECUTED': return 'queued';
         default: return 'queued';
     }
 }
@@ -106,10 +102,14 @@ const STEP_ALLOWED_KEYS = [
     'captureScreenshot', 'screenshotEnabled', 'fnVersionId', 'description', 'expectedResult',
     'conditions', 'stepLevelActions', 'skipParamInReport', 'paramLoopduration', 'showGroups',
     'isConditional', 'if', 'else', 'loop', 'isLoop', 'loopType', 'startFor', 'endFor',
-    'loopDuration', 'executionType', 'recordedParam', 'switchToAndroidData', 'switchToIOSData',
+    'loopDuration', 'executionType', 'switchToAndroidData', 'switchToIOSData',
     'isDebug', 'manualStepsTopreview', 'sharedFnProjectName', 'isMigrated', 'customFields',
     // ponytail: id / versionId are in the schema but always stripped for SAVENEWVERSION — the
     // backend re-assigns them to the fresh version row, and keeping the old id would resurrect it.
+    // ponytail: recordedParam is intentionally dropped — the FE clears it on every save-as-new
+    // (testcase.component.ts:1370 `if (shouldClearRecordedParam) step.recordedParam = {}`) so the
+    // backend's prepareDataObjet doesn't burn recorded values into fresh ITR-1 rows. MCP has no
+    // recording flow, so nothing needs it kept.
 ];
 function pick(obj, keys) {
     const out = {};
@@ -120,22 +120,6 @@ function pick(obj, keys) {
             out[k] = obj[k];
     return out;
 }
-/** Filter a fetched list of source version names by the caller's `requested` subset. Empty request
- *  or undefined means "all". Unknown names hard-fail with the valid list so the LLM can retry with
- *  a corrected name instead of silently cloning nothing. Empty request array = user error. */
-function filterVersionNames(available, requested, entityId) {
-    if (requested === undefined)
-        return available;
-    if (requested.length === 0) {
-        throw new Error(`versions: [] is not valid — omit the parameter to clone all versions, or pass at least one name. Source ${entityId} has: ${available.join(', ')}.`);
-    }
-    const availSet = new Set(available);
-    const unknown = requested.filter((n) => !availSet.has(n));
-    if (unknown.length) {
-        throw new Error(`Unknown version name(s) on ${entityId}: ${unknown.join(', ')}. Available versions: ${available.join(', ')}.`);
-    }
-    return [...new Set(requested)];
-}
 /** Guard against feeding an FN business key into a TC-only endpoint (or vice-versa). `numericId`
  *  strips ANY alpha prefix — so "FN-22" → "22" and would silently target TC-22 if the caller
  *  routed to the wrong tool. Reject any business key whose prefix doesn't match the expected
@@ -231,6 +215,9 @@ export class SimplifyQaAdapter {
         // (from the Promise.all in saveGeneratedIterations) all await the same fetch instead of each firing
         // their own /tm/syncFormulas/fetch before the cache is populated.
         this.formulaCache = null;
+        // Same rationale for the backlog default state/priority per parentId (1=Epic, 2=Feature, 3=Story).
+        // Fields config barely changes mid-session; cache the in-flight promise so parallel creates share it.
+        this.backlogDefaultsCache = new Map();
         // ---------------------------------------------------------------------- Automation resolvers
         /** POST /tm/action/search → per (technology, name) → row (id + objectRequired + objectTemplate).
          *  Cached per adapter instance: the catalog is customer-wide and rarely changes during a session.
@@ -244,6 +231,9 @@ export class SimplifyQaAdapter {
          *  formulaCache. Populated from `POST /tm/objectTemplate/search` (confirmed endpoint,
          *  api-endpoints.ts `object.search`'s sibling `objectTemplate.search`). */
         this.objectTemplateCache = null;
+        /** Gather every identifier this process can claim: bare hostname, non-loopback MAC addresses,
+         *  non-loopback IPs. Cached per-adapter — network interfaces do not change mid-session. */
+        this.localIdsCache = null;
         if (!cfg.baseUrl) {
             throw new Error('SimplifyQaAdapter requires a baseUrl — set QA_BASE_URL or use a JWT with a `url` claim.');
         }
@@ -570,9 +560,16 @@ export class SimplifyQaAdapter {
         }
     }
     /** For every step with an objectRef, resolve the object's display name (`disname`) via
-     *  /tm/object/search (batched by distinct objectId). Mutates `objectRef.name` in place. Non-fatal
-     *  on failure — the bare id still renders. Mirrors the FE's `defaultFieldsMap.get('objectId').map`
-     *  behavior used by the Excel export (tcfn.service.js:2876) so the tool surface matches the UI. */
+     *  /tm/object/search (batched by distinct objectId). Mutates `objectRef.name` in place. Mirrors the
+     *  FE's `defaultFieldsMap.get('objectId').map` behavior used by the Excel export
+     *  (tcfn.service.js:2876) so the tool surface matches the UI.
+     *
+     *  An id that does NOT come back from the search (deleted, or never existed) is flagged
+     *  `objectRef.missing = true` — this must NOT be silently indistinguishable from "the object
+     *  exists but has no disname set" (see the "show me the objects in this test case" incident:
+     *  falling back to the bare id with no signal made a genuinely-deleted object's step look
+     *  identical to a normal one). Only a hard failure of the search call itself (network/auth) skips
+     *  this — we can't tell missing-from-deleted apart from missing-from-can't-check in that case. */
     async hydrateObjectNames(tc) {
         const ids = new Set();
         for (const s of tc.steps) {
@@ -605,10 +602,13 @@ export class SimplifyQaAdapter {
                 const name = byId.get(s.objectRef.id);
                 if (name)
                     s.objectRef.name = name;
+                else
+                    s.objectRef.missing = true;
             }
         }
         catch {
-            // Non-fatal: fall back to bare id in the render.
+            // Search call itself failed — can't distinguish missing-from-deleted vs. couldn't-check, so
+            // don't flag anything; the bare id still renders (existing best-effort behavior).
         }
     }
     // ---------------------------------------------------------------------- Suites (read)
@@ -738,12 +738,102 @@ export class SimplifyQaAdapter {
         const rows = pickArray(raw, 'data', 'content', 'tasks');
         return withTotal(rows.map(toTaskSummary), raw);
     }
+    // ---------------------------------------------------------------------- Backlog defaults
+    /** Fetch the project's default `state` and `priority` for a backlog entity.
+     *  parentId: 1 = Epic, 2 = Feature, 3 = User Story. Two-source resolution, in order:
+     *
+     *    1. `/pm/fields/:parentId?fieldType=defaultFld` — pick the field value marked `isDefault: true`;
+     *       fall back to the first non-archived value (seed ships with `isDefault: false` everywhere
+     *       until a customer configures one).
+     *    2. If either state or priority is still missing, hit the entity's `/search` endpoint for one
+     *       existing row in the project and steal its state / priority. Real data is a more reliable
+     *       signal than the fields config, which is customer-scoped for Epic/Feature (parentIds 1/2)
+     *       and can be missing entirely on customers that pre-date the seeding step.
+     *
+     *  Returns the value's `.key` (uppercase enum like `PROPOSED`, `MEDIUM`) — that is what the entity
+     *  row stores; the field metadata declares `keyname: "key"` / `type: "KEY"` and the SQA UI binding
+     *  (see epic-form.component.html: `keyname="key" type="KEY" [displayKeys]="{'field':'value'}"`) confirms
+     *  key is stored, `.value` is only for display. Both sources are wrapped in try/catch: a transient
+     *  upstream error must not block create; the backend surfaces its own error if invalid. */
+    async getBacklogDefaults(parentId) {
+        const cached = this.backlogDefaultsCache.get(parentId);
+        if (cached)
+            return cached;
+        const projectId = this.requireProjectId();
+        const p = (async () => {
+            const out = {};
+            // Source 1: /pm/fields config.
+            try {
+                const raw = await this.http.getJson(`/pm/fields/${parentId}?fieldType=defaultFld&projectId=${projectId}`);
+                const fields = Array.isArray(raw) ? raw : pickArray(raw, 'data', 'content', 'fields');
+                const pick = (key) => {
+                    const field = fields.find((f) => f?.key === key);
+                    const values = Array.isArray(field?.values) ? field.values : [];
+                    const chosen = values.find((v) => v?.isDefault === true && v?.archive !== true)
+                        ?? values.find((v) => v?.archive !== true);
+                    // Entity rows persist the uppercase enum (value.key). value.value is display-only.
+                    const stored = str(chosen ?? {}, 'key', 'value');
+                    return stored && stored.length > 0 ? stored : undefined;
+                };
+                const s = pick('state');
+                const pr = pick('priority');
+                if (s)
+                    out.state = s;
+                if (pr)
+                    out.priority = pr;
+            }
+            catch { /* fall through to Source 2 */ }
+            // Source 2: fall back to state/priority from an existing entity of the same kind in this project.
+            // Epic has no priority field, so we only need state for parentId=1.
+            const needsPriority = parentId !== 1 && !out.priority;
+            if (!out.state || needsPriority) {
+                try {
+                    const path = parentId === 1 ? '/pm/epic/search'
+                        : parentId === 2 ? '/pm/feature/search'
+                            : '/pm/userstory/search';
+                    // Story rows carry a scalar `projectId`; Epic/Feature rows carry an array `projectIds`.
+                    const filters = [
+                        { column: 'deleted', value: false },
+                        parentId === 3
+                            ? { column: 'projectId', value: projectId }
+                            : { column: 'projectIds', value: projectId },
+                    ];
+                    const body = this.searchBody(filters, { startIndex: 0, limit: 1 });
+                    const raw = await this.http.postJson(path, body);
+                    const rows = pickArray(raw, 'data', 'content');
+                    const row = rows[0];
+                    if (row) {
+                        if (!out.state) {
+                            const s = str(row, 'state', 'status');
+                            if (s)
+                                out.state = s;
+                        }
+                        if (needsPriority) {
+                            const pr = str(row, 'priority');
+                            if (pr)
+                                out.priority = pr;
+                        }
+                    }
+                }
+                catch { /* leave out.state / out.priority absent; caller can override */ }
+            }
+            return out;
+        })();
+        this.backlogDefaultsCache.set(parentId, p);
+        return p;
+    }
     // ---------------------------------------------------------------------- Stories (write)
     async createStory(input) {
+        const defaults = await this.getBacklogDefaults(3);
+        const state = input.state ?? defaults.state;
+        const priority = input.priority ?? defaults.priority;
         const body = {
             ...input,
             // SQA userstory expects a singular numeric projectId; fill from the connected project when omitted.
             projectId: input.projectId ?? this.requireProjectId(),
+            ...(state ? { state } : {}),
+            ...(priority ? { priority } : {}),
+            customFields: input.customFields ?? {},
         };
         const raw = await this.http.postJson('/pm/userstory', body);
         return toSavedRef(raw, true);
@@ -791,9 +881,13 @@ export class SimplifyQaAdapter {
         return toEpic(doc && typeof doc === 'object' ? doc : {});
     }
     async createEpic(input) {
+        const defaults = await this.getBacklogDefaults(1);
+        const state = input.state ?? defaults.state;
         const body = {
             ...input,
             projectIds: input.projectIds ?? [this.requireProjectId()],
+            ...(state ? { state } : {}),
+            customFields: input.customFields ?? {},
         };
         const raw = await this.http.postJson('/pm/epic', body);
         return toSavedRef(raw, true);
@@ -855,9 +949,15 @@ export class SimplifyQaAdapter {
         return toFeature(doc && typeof doc === 'object' ? doc : {});
     }
     async createFeature(input) {
+        const defaults = await this.getBacklogDefaults(2);
+        const state = input.state ?? defaults.state;
+        const priority = input.priority ?? defaults.priority;
         const body = {
             ...input,
             projectIds: input.projectIds ?? [this.requireProjectId()],
+            ...(state ? { state } : {}),
+            ...(priority ? { priority } : {}),
+            customFields: input.customFields ?? {},
         };
         const raw = await this.http.postJson('/pm/feature', body);
         return toSavedRef(raw, true);
@@ -886,7 +986,7 @@ export class SimplifyQaAdapter {
         const body = this.searchBody([
             { column: 'projectId', value: projectId },
             { column: 'deleted', value: false },
-        ], { selectFields: ['id', 'code', 'name', 'parentId'] });
+        ], { selectFields: ['id', 'code', 'name', 'parentId', 'isRoot', 'childIds'] });
         const raw = await this.http.postJson('/pm/module/search', body);
         const rows = pickArray(raw, 'data', 'content', 'modules');
         return withTotal(rows.map(toModuleSummary), raw);
@@ -916,19 +1016,71 @@ export class SimplifyQaAdapter {
         };
     }
     /** POST /pm/module — server validates: name+isRoot+projectId required; parentId ignored when
-     *  isRoot:true. Duplicate name per project is rejected server-side. */
+     *  isRoot:true. Duplicate name per project is rejected server-side. When `input.children` is
+     *  present, walks the subtree depth-first: creates the root, then each child under the id
+     *  returned for its parent. `childIds:[]` matches the working UI payload byte-for-byte.
+     *  Backend has no tx endpoint: on mid-walk failure the returned tree carries `failedAt`, and
+     *  every node BEFORE that point is already persisted. */
     async createModule(input) {
+        const root = await this.postOneModule(input.name, input.isRoot, input.projectId, input.description, input.parentId);
+        if (input.children?.length) {
+            root.children = await this.createSubtree(input.children, root.id, input.projectId, input.name, root);
+        }
+        return root;
+    }
+    /** Depth-first walk of a subtree. Stops at the first failure — everything already POSTed stays
+     *  (no rollback endpoint upstream) and the failure is bubbled back on the root via `failedAt`. */
+    async createSubtree(children, parentId, projectId, parentPath, root) {
+        const out = [];
+        for (const child of children) {
+            const path = `${parentPath}/${child.name}`;
+            if (root.failedAt)
+                return out;
+            let saved;
+            try {
+                saved = await this.postOneModule(child.name, false, projectId, child.description, parentId);
+            }
+            catch (e) {
+                root.failedAt = { path, error: e instanceof Error ? e.message : String(e) };
+                return out;
+            }
+            if (child.children?.length) {
+                saved.children = await this.createSubtree(child.children, saved.id, projectId, path, root);
+            }
+            out.push(saved);
+        }
+        return out;
+    }
+    async postOneModule(name, isRoot, projectId, description, parentId) {
         const payload = {
-            name: input.name,
-            isRoot: input.isRoot,
-            projectId: Number.parseInt(input.projectId, 10),
+            name,
+            isRoot,
+            projectId: Number.parseInt(projectId, 10),
+            childIds: [],
         };
-        if (input.description)
-            payload['description'] = input.description;
-        if (!input.isRoot && input.parentId)
-            payload['parentId'] = Number.parseInt(input.parentId, 10);
+        if (description)
+            payload['description'] = description;
+        if (!isRoot && parentId)
+            payload['parentId'] = Number.parseInt(parentId, 10);
         const raw = await this.http.postJson('/pm/module', payload);
-        return toSavedRef(raw, true);
+        return toModuleSaved(raw, name);
+    }
+    /** PUT /pm/module/:id — partial edit. Controller reads `projectId` off the body for its
+     *  `add_module` privilege check (module.controller.js:64), so it MUST be sent even when unchanged;
+     *  we default to the connected project. Only `name` / `description` are exposed — the controller
+     *  ignores everything else the validator accepts (isRoot, parentId, childIds). */
+    async updateModule(id, patch) {
+        const projectId = patch.projectId
+            ? Number.parseInt(numericId(patch.projectId), 10)
+            : this.requireProjectId();
+        const body = { projectId };
+        if (patch.name !== undefined)
+            body['name'] = patch.name;
+        if (patch.description !== undefined)
+            body['description'] = patch.description;
+        const resolvedId = numericId(id);
+        const raw = await this.http.putJson(`/pm/module/${resolvedId}`, body);
+        return toSavedRef(raw ?? { id: resolvedId }, false);
     }
     /** PATCH /pm/module — two-phase per module.controller.js:94. `confirm:false` returns the per-id
      *  dependency footprint (test cases, functions, params, objects, defects, user stories). `confirm:true`
@@ -1053,7 +1205,13 @@ export class SimplifyQaAdapter {
     // ---------------------------------------------------------------------- Deep links
     productUrlFor(entity) {
         const base = (this.cfg.baseUrl ?? '').replace(/\/+$/, '');
-        return `${base}/${PROJECT_URL_SEGMENT[entity.kind]}/${entity.id}`;
+        switch (entity.kind) {
+            case 'testcase': return `${base}/user/testcase/details/${entity.id}`;
+            case 'function': return `${base}/user/function/fnDetails/${entity.id}`;
+            case 'suite': return `${base}/user/suites/suite-details?id=${entity.id}`;
+            // ponytail: run URL is built inline where parentId/projectId are known (see reportUrl above). Fallback stays generic.
+            case 'run': return `${base}/user/reports/reports-page?id=${entity.id}`;
+        }
     }
     // ---------------------------------------------------------------------- Agent hop (recording + not-yet-ported ops)
     // Everything below either delegates to the local agent /mcp (recording surface, and writes/testdata/
@@ -1617,87 +1775,92 @@ export class SimplifyQaAdapter {
     }
     /** Clone a testcase in place (same project + module) with all steps, versions, testdata,
      *  parameters, object refs, and nested function calls carried over. Backed by the SQA native
-     *  `/tm/tcfnCopy/copytc` endpoint (see test-management/src/controllers/tcfnCopy.controller.js).
-     *
-     *  Requires the `copy_testcase_across_project` privilege on the current project — enforced
-     *  server-side regardless of whether the copy is in-project or across projects.
-     *
-     *  When `newTitle` is omitted the backend auto-names the copy as `{sourceName}_copy1`,
-     *  `_copy2`, etc. When provided, a follow-up PUT renames the freshly-created TC to that name.
-     *
-     *  IMPORTANT — the copy endpoint's `selversions` and `selectedEnv` fields are FILTERS, not
-     *  wildcards. Passing empty arrays makes the backend copy the TC shell only (no steps, no
-     *  testdata, since both live under versions and per-env iterations). So we fetch the source
-     *  TC's version names AND the project's environment names first and pass them explicitly. */
-    async cloneTestCase(id, newTitle, versions) {
+     *  the FE in-editor "Save as new TC" dialog — `PUT /tm/testcase` with `operation:SAVEASNEWTC`.
+     *  Same-project only (no cross-project copy — use the FE tree menu for that). Clones ONE
+     *  source version. `tdCopy:true` clones the source's testdata iterations across every env;
+     *  `tdCopy:false` copies only the column structure (one empty ITR-1 per env, values fall back
+     *  to project-level parameter defaultValue if any). Mirrors the FE's "COPY TEST DATA" modal. */
+    async cloneTestCase(id, newTitle, opts) {
         assertBusinessKeyKind(id, 'TC');
         const projectId = this.requireProjectId();
-        const src = await this.fetchRawTestcase(id);
-        if (!src || Object.keys(src).length === 0)
+        const title = newTitle?.trim();
+        if (!title)
+            throw new Error('newTitle is required for save-as-new-testcase.');
+        const rawTc = await this.fetchRawTestcase(id);
+        if (!rawTc || Object.keys(rawTc).length === 0)
             throw new Error(`test case ${id} not found`);
         const sourceId = Number.parseInt(numericId(id), 10);
-        const sourceProjId = typeof src.projectId === 'number' ? src.projectId : projectId;
-        const sourceModuleId = typeof src.moduleId === 'number' ? src.moduleId : 0;
-        // Fetch source's version names — required, empty means no versions get copied.
-        const versionsRaw = await this.http.getJson(`/tm/testcase/version/${sourceId}/${sourceProjId}`);
-        const versionsArr = Array.isArray(versionsRaw) ? versionsRaw : (versionsRaw?.data ?? []);
-        const availableNames = versionsArr
-            .map((v) => str(v, 'name'))
-            .filter((n) => !!n);
-        if (availableNames.length === 0) {
-            throw new Error(`Cannot clone ${id}: source has no versions to copy.`);
-        }
-        const versionNames = filterVersionNames(availableNames, versions, id);
-        // Fetch project's environment names — empty means per-env testdata rows are dropped
-        // (only the "general" fallback iteration survives).
-        const envsRaw = await this.http.getJson(`/pm/fields/8?projectId=${sourceProjId}&fieldType=environment`);
-        const envsArr = Array.isArray(envsRaw) ? envsRaw : (envsRaw?.data ?? []);
-        const envNames = envsArr
-            .map((e) => str(e, 'name'))
-            .filter((n) => !!n);
-        await this.http.postJson('/tm/tcfnCopy/copytc', {
-            type: 'TC',
-            tcfnList: [{ id: sourceId, selversions: versionNames }],
-            sourceProjId,
-            sourceModuleId,
-            destinationProjId: sourceProjId,
-            destinationModuleId: sourceModuleId,
-            selectedEnv: envNames,
-        });
-        // Find the newly-created copy: highest-id TC whose `projectLevelcopiedFrom.id` matches. Not
-        // going through `searchBody` because the SQA search protocol lets a searchField have EITHER a
-        // `value` (filter) OR a `sort` (ordering) — the helper only builds value entries.
-        const searchRaw = await this.http.postJson('/tm/testcase/search', {
-            searchFields: [
-                { column: 'deleted', value: false },
-                { column: 'projectId', value: sourceProjId },
-                { column: 'projectLevelcopiedFrom.id', value: sourceId },
-                { column: 'id', sort: 'dsc' },
-            ],
-            startIndex: 0,
-            limit: 1,
-            selectFields: ['id', 'code', 'name'],
-        });
-        const rows = pickArray(searchRaw, 'data', 'content', 'testCases');
-        if (rows.length === 0) {
-            throw new Error('Clone was requested but the newly-created testcase could not be located afterwards. ' +
-                'The backend may still be processing the copy, or the caller may lack the ' +
-                '`copy_testcase_across_project` privilege on this project.');
-        }
-        const created = rows[0];
-        const newIdNum = Number.parseInt(str(created, 'id', '_id') ?? '', 10);
-        // Optional rename: PUT /tm/testcase/:id with { name, projectId }.
-        if (newTitle && newTitle.trim() && Number.isFinite(newIdNum)) {
-            await this.http.putJson(`/tm/testcase/${newIdNum}`, {
-                name: newTitle.trim(),
-                projectId: sourceProjId,
-            });
-            created.name = newTitle.trim();
+        // Resolve source version — same fallback chain as saveAsNewVersion.
+        let sourceVersionId = opts.sourceVersionId;
+        if (!sourceVersionId) {
+            sourceVersionId = str(rawTc, 'versionId', 'selectedVersionId', 'selVersion');
+            if (!sourceVersionId && rawTc?.versionsDetails && typeof rawTc.versionsDetails === 'object') {
+                sourceVersionId = str(rawTc.versionsDetails, 'id', '_id', 'versionId');
+            }
+            if (!sourceVersionId && Array.isArray(rawTc?.versions) && rawTc.versions.length > 0) {
+                sourceVersionId = str(rawTc.versions[0], 'id', '_id');
+            }
+        }
+        // Source version's NAME (SAVEASNEWTC re-uses the same version name on the copy, per FE).
+        const sourceVersionName = (() => {
+            if (rawTc?.versionsDetails?.id === sourceVersionId)
+                return str(rawTc.versionsDetails, 'name');
+            const match = Array.isArray(rawTc?.versions)
+                ? rawTc.versions.find((v) => str(v, 'id', '_id') === sourceVersionId)
+                : undefined;
+            return match ? str(match, 'name') : str(rawTc?.versionsDetails, 'name');
+        })() ?? 'v1.0';
+        const rawSteps = await this.fetchStepsCollection(id, rawTc);
+        const automationSteps = [];
+        const manualSteps = [];
+        for (const s of rawSteps) {
+            const step = pick(s, STEP_ALLOWED_KEYS);
+            const et = typeof step['executionType'] === 'string' ? String(step['executionType']).toUpperCase() : '';
+            if (et === 'MANUAL')
+                manualSteps.push(step);
+            else
+                automationSteps.push(step);
         }
+        const tcfnObj = pick(rawTc, TCFNOBJ_ALLOWED_KEYS);
+        tcfnObj['deleted'] = false;
+        tcfnObj['projectId'] = typeof tcfnObj['projectId'] === 'number' ? tcfnObj['projectId'] : projectId;
+        if (typeof tcfnObj['obsolete'] !== 'boolean')
+            tcfnObj['obsolete'] = false;
+        tcfnObj['name'] = title;
+        tcfnObj['copiedFromTcId'] = sourceId;
+        const prevSync = rawTc?.versionsDetails && typeof rawTc.versionsDetails === 'object'
+            ? str(rawTc.versionsDetails, 'syncONOFF')
+            : undefined;
+        const versionsDetails = {
+            name: sourceVersionName,
+            id: '',
+            syncONOFF: prevSync === 'SYNCOFF' ? '' : (prevSync ?? ''),
+            deleted: false,
+            executionType: str(rawTc, 'executionType') ?? 'AUTOMATION',
+            functionProjectIds: [tcfnObj['projectId']],
+            reviewApproveStatus: '',
+        };
+        const verData = {
+            tdCopy: !!opts.tdCopy,
+            ...(sourceVersionId ? { selVersionId: sourceVersionId } : {}),
+        };
+        const payload = {
+            tcfnObj,
+            steps: { automationSteps, manualSteps },
+            versionsDetails,
+            operation: 'SAVEASNEWTC',
+            type: 'TC',
+            verData,
+        };
+        const raw = await this.http.putMultipart('/tm/testcase', 'testcaseObj', payload);
+        const flat = raw?.data ?? raw ?? {};
+        const newId = str(flat, 'id', '_id', 'testcaseId');
+        if (!newId)
+            throw new Error('SAVEASNEWTC succeeded but returned no id.');
         return {
-            id: String(newIdNum),
+            id: newId,
             created: true,
-            productUrl: this.productUrlFor({ kind: 'testcase', id: String(newIdNum) }),
+            productUrl: this.productUrlFor({ kind: 'testcase', id: newId }),
         };
     }
     // ---------------------------------------------------------------------- Functions (reusable)
@@ -1819,81 +1982,91 @@ export class SimplifyQaAdapter {
             ? `Not deleted — function is still referenced by ${refs.join('; ')}. Remove those references first.`
             : 'Not deleted — the backend reported blocking dependencies.');
     }
-    /** Copy a function in place — new tcfnObj row, all versions/steps/testdata carried over. Same
-     *  shape as `cloneTestCase`: version names + env names come from the source, then POST to
-     *  `/tm/tcfnCopy/copytc` with `type:'FN'` (backend enforces `copy_function_across_projects`).
-     *  When `newTitle` is omitted the backend auto-names as `{sourceName}_copy1`, etc.; when
-     *  provided a follow-up PUT `/tm/function/:id` renames the freshly-created FN. */
-    async cloneFunction(id, newTitle, versions) {
+    /** Save-as-new-function — same-project only. Mirrors FE's in-editor "Save as new function"
+     *  dialog: `PUT /tm/function` with `operation:SAVEASNEWFN`. Clones ONE source version.
+     *  `tdCopy:true` clones testdata; `tdCopy:false` copies structure only (empty ITR-1 per env). */
+    async cloneFunction(id, newTitle, opts) {
         assertBusinessKeyKind(id, 'FN');
         const projectId = this.requireProjectId();
+        const title = newTitle?.trim();
+        if (!title)
+            throw new Error('newTitle is required for save-as-new-function.');
         const fnNum = numericId(id);
         const rawFn = await this.http.getJson(`/tm/function/${fnNum}/${projectId}`);
-        let src = rawFn?.data ?? rawFn;
-        if (Array.isArray(src))
-            src = src.length > 0 ? src[0] : {};
-        if (!src || typeof src !== 'object' || Object.keys(src).length === 0) {
+        let rawTc = rawFn?.data ?? rawFn;
+        if (Array.isArray(rawTc))
+            rawTc = rawTc.length > 0 ? rawTc[0] : {};
+        if (!rawTc || typeof rawTc !== 'object' || Object.keys(rawTc).length === 0) {
             throw new Error(`function ${id} not found`);
         }
         const sourceId = Number.parseInt(fnNum, 10);
-        const sourceProjId = typeof src.projectId === 'number' ? src.projectId : projectId;
-        const sourceModuleId = typeof src.moduleId === 'number' ? src.moduleId : 0;
-        // Fetch source's version names — required, empty means no versions get copied.
-        const versionsRaw = await this.http.getJson(`/tm/function/version/${sourceId}/${sourceProjId}`);
-        const versionsArr = Array.isArray(versionsRaw) ? versionsRaw : (versionsRaw?.data ?? []);
-        const availableNames = versionsArr
-            .map((v) => str(v, 'name'))
-            .filter((n) => !!n);
-        if (availableNames.length === 0) {
-            throw new Error(`Cannot clone ${id}: source has no versions to copy.`);
-        }
-        const versionNames = filterVersionNames(availableNames, versions, id);
-        // Same environment fetch as cloneTestCase — empty means per-env testdata rows are dropped.
-        const envsRaw = await this.http.getJson(`/pm/fields/8?projectId=${sourceProjId}&fieldType=environment`);
-        const envsArr = Array.isArray(envsRaw) ? envsRaw : (envsRaw?.data ?? []);
-        const envNames = envsArr
-            .map((e) => str(e, 'name'))
-            .filter((n) => !!n);
-        await this.http.postJson('/tm/tcfnCopy/copytc', {
-            type: 'FN',
-            tcfnList: [{ id: sourceId, selversions: versionNames }],
-            sourceProjId,
-            sourceModuleId,
-            destinationProjId: sourceProjId,
-            destinationModuleId: sourceModuleId,
-            selectedEnv: envNames,
-        });
-        // Find the newly-created copy: highest-id FN whose `projectLevelcopiedFrom.id` matches source.
-        const searchRaw = await this.http.postJson('/tm/function/search', {
-            searchFields: [
-                { column: 'deleted', value: false },
-                { column: 'projectId', value: sourceProjId },
-                { column: 'projectLevelcopiedFrom.id', value: sourceId },
-                { column: 'id', sort: 'dsc' },
-            ],
-            startIndex: 0,
-            limit: 1,
-            selectFields: ['id', 'code', 'name'],
-        });
-        const rows = pickArray(searchRaw, 'data', 'content', 'functions');
-        if (rows.length === 0) {
-            throw new Error('Clone was requested but the newly-created function could not be located afterwards. ' +
-                'The backend may still be processing the copy, or the caller may lack the ' +
-                '`copy_function_across_projects` privilege on this project.');
-        }
-        const created = rows[0];
-        const newIdNum = Number.parseInt(str(created, 'id', '_id') ?? '', 10);
-        // Optional rename: PUT /tm/function/:id — inline validator accepts { name } only (no projectId).
-        if (newTitle && newTitle.trim() && Number.isFinite(newIdNum)) {
-            await this.http.putJson(`/tm/function/${newIdNum}`, {
-                name: newTitle.trim(),
-            });
-            created.name = newTitle.trim();
+        // Resolve source version — FN doc has no inline versionId, use version list.
+        let sourceVersionId = opts.sourceVersionId;
+        const versionRows = await this.fetchFunctionVersionRows(fnNum);
+        if (!sourceVersionId && versionRows.length > 0) {
+            sourceVersionId = str(versionRows[0], 'id', '_id', 'versionId');
+        }
+        const sourceVersionName = (() => {
+            const match = versionRows.find((v) => str(v, 'id', '_id', 'versionId') === sourceVersionId);
+            return match ? str(match, 'name') : (versionRows[0] ? str(versionRows[0], 'name') : undefined);
+        })() ?? 'v1.0';
+        const rawSteps = sourceVersionId
+            ? await this.http.getJson('/tm/function/steps' +
+                `?projectId=${projectId}` +
+                `&tcfnId=${fnNum}` +
+                `&versionId=${encodeURIComponent(sourceVersionId)}` +
+                '&type=FN').then((body) => (Array.isArray(body) ? body : Array.isArray(body?.data) ? body.data : []))
+            : [];
+        const automationSteps = [];
+        const manualSteps = [];
+        for (const s of rawSteps) {
+            const step = pick(s, STEP_ALLOWED_KEYS);
+            const et = typeof step['executionType'] === 'string' ? String(step['executionType']).toUpperCase() : '';
+            if (et === 'MANUAL')
+                manualSteps.push(step);
+            else
+                automationSteps.push(step);
         }
+        const tcfnObj = pick(rawTc, TCFNOBJ_FN_ALLOWED_KEYS);
+        tcfnObj['deleted'] = false;
+        tcfnObj['projectId'] = typeof tcfnObj['projectId'] === 'number' ? tcfnObj['projectId'] : projectId;
+        if (typeof tcfnObj['fnType'] !== 'string' || !tcfnObj['fnType']) {
+            tcfnObj['fnType'] = str(rawTc, 'fnType', 'tcType') ?? 'WEB';
+        }
+        tcfnObj['name'] = title;
+        tcfnObj['copiedFromFnId'] = sourceId;
+        const prevSync = rawTc?.versionsDetails && typeof rawTc.versionsDetails === 'object'
+            ? str(rawTc.versionsDetails, 'syncONOFF')
+            : undefined;
+        const versionsDetails = {
+            name: sourceVersionName,
+            id: '',
+            syncONOFF: prevSync === 'SYNCOFF' ? '' : (prevSync ?? ''),
+            deleted: false,
+            executionType: str(rawTc, 'executionType') ?? 'AUTOMATION',
+            reviewApproveStatus: '',
+        };
+        const verData = {
+            tdCopy: !!opts.tdCopy,
+            ...(sourceVersionId ? { selVersionId: sourceVersionId } : {}),
+        };
+        const payload = {
+            tcfnObj,
+            steps: { automationSteps, manualSteps },
+            versionsDetails,
+            operation: 'SAVEASNEWFN',
+            type: 'FN',
+            verData,
+        };
+        const raw = await this.http.putMultipart('/tm/function', 'functionObj', payload);
+        const flat = raw?.data ?? raw ?? {};
+        const newId = str(flat, 'id', '_id', 'functionId');
+        if (!newId)
+            throw new Error('SAVEASNEWFN succeeded but returned no id.');
         return {
-            id: String(newIdNum),
+            id: newId,
             created: true,
-            productUrl: this.productUrlFor({ kind: 'function', id: String(newIdNum) }),
+            productUrl: this.productUrlFor({ kind: 'function', id: newId }),
         };
     }
     /** Snapshot the CURRENT server state of a function under a NEW version name — same FN id, new
@@ -2211,11 +2384,58 @@ export class SimplifyQaAdapter {
     }
     // ---------------------------------------------------------------------- Suites (write)  [Step 4]
     async createSuite(s) {
-        // Java stubs this out ("create_suite is not supported yet on SimplifyQA"). Mirror that.
-        if (this.hop())
-            return this.requireHop('create_suite').createSuite(s);
-        throw new Error('create_suite is not supported yet on SimplifyQA — create the suite in the SimplifyQA UI, ' +
-            'then add test cases via suite_add_testcases.');
+        const projectId = this.requireProjectId();
+        const name = s.name?.trim();
+        if (!name)
+            throw new Error('name is required.');
+        if (!s.members?.length)
+            throw new Error('At least one test case is required to create a suite.');
+        const entries = [];
+        const categories = new Set();
+        for (const m of s.members) {
+            const tcNum = numericId(m.tcId);
+            const raw = await this.fetchRawTestcase(tcNum);
+            if (Object.keys(raw).length === 0)
+                throw new Error(`test case ${m.tcId} not found (cannot add to suite)`);
+            categories.add(String(str(raw, 'executionType') ?? '').toUpperCase() === 'MANUAL' ? 'MANUAL' : 'AUTOMATION');
+            entries.push(await this.buildSuiteEntryFromTestcase(tcNum));
+        }
+        if (categories.size > 1) {
+            throw new Error('Cannot create suite: the test cases are a mix of MANUAL and AUTOMATION — a suite can only ' +
+                'hold ONE category. Split them into two suites, or pick only same-category test cases.');
+        }
+        const suiteType = [...categories][0] ?? 'AUTOMATION';
+        entries.forEach((e, i) => { e['seq'] = i + 1; });
+        const payload = {
+            name,
+            description: s.description ?? '',
+            state: 'New',
+            suiteType,
+            projectId,
+            autoDefectLog: false,
+            autoReExecCount: 0,
+            newBrowserSession: false,
+            terminateOnFailure: false,
+            autoReExecTriggerOn: 'AFTER_SUITE',
+            minimumContainerCount: null,
+            maximumContainerCount: null,
+            testCases: entries,
+            mailersList: {},
+            tags: [],
+            customFields: {},
+            lastSelectedExecutionType: 'LOCAL',
+            tcChanged: true,
+        };
+        const raw = await this.http.postMultipart('/tm/suites', 'suiteObj', payload);
+        const flat = raw?.data ?? raw ?? {};
+        const savedId = str(flat, 'id', '_id') ?? '';
+        if (!savedId)
+            throw new Error(`Suite create returned no id: ${JSON.stringify(raw)}`);
+        return {
+            id: savedId,
+            created: true,
+            productUrl: this.productUrlFor({ kind: 'suite', id: savedId }),
+        };
     }
     /** Fetch raw suite, apply add/remove/reorder ops in memory, then PUT the whole doc back with a
      *  STRICT allow-listed payload (the SQA update validator rejects unknown keys on both suite-level
@@ -2407,15 +2627,23 @@ export class SimplifyQaAdapter {
      * delete is refused rather than silently breaking those test cases; only a dependency-free object
      * gets the real `isDelete:true` call.
      */
-    async deleteObject(id) {
+    /** `PATCH /tm/object` with `isDelete:false` — the SAME dependency-check pre-flight the real
+     *  product UI fires before its own delete-confirm modal (object.component.ts onClickTableDelete):
+     *  a read-only probe, no restore/undelete side effect. Split out from deleteObject so a caller
+     *  (object_delete's preview step) can show this BEFORE asking the user to confirm, not just
+     *  discover it as a thrown error after the fact. */
+    async checkObjectDependencies(id) {
         const projectId = this.requireProjectId();
         const numId = Number.parseInt(numericId(id), 10);
         const checkRes = await this.http.patchJson('/tm/object', { ids: [numId], projectId, isDelete: false });
         const row = checkRes?.data?.[0];
         const countRefs = (m) => m ? Object.values(m).reduce((n, arr) => n + (Array.isArray(arr) ? arr.length : 0), 0) : 0;
-        const tcCount = countRefs(row?.tcArr);
-        const fnCount = countRefs(row?.fnArr);
-        const wfCount = countRefs(row?.wfArr);
+        return { tcCount: countRefs(row?.tcArr), fnCount: countRefs(row?.fnArr), wfCount: countRefs(row?.wfArr) };
+    }
+    async deleteObject(id) {
+        const projectId = this.requireProjectId();
+        const numId = Number.parseInt(numericId(id), 10);
+        const { tcCount, fnCount, wfCount } = await this.checkObjectDependencies(id);
         if (tcCount || fnCount || wfCount) {
             const parts = [];
             if (tcCount)
@@ -2704,11 +2932,51 @@ export class SimplifyQaAdapter {
     }
     // ---------------------------------------------------------------------- Run status  [Step 6]
     /** Real status of a run — reads step-level results direct from SQA REST because the desktop agent's
-     *  get_run only returns queue state (often stale). start/stop still hop for v1. */
+     *  get_run only returns queue state (often stale). For a SUITE run, returns per-TC rollup
+     *  (`children[]`) instead of step details — a suite doc's `type` field flags it. start/stop still
+     *  hop for v1. */
     async getRun(runId) {
         const projectId = this.requireProjectId();
         const base = (this.cfg.baseUrl ?? '').replace(/\/+$/, '');
-        // GET /exec/report/{runId}/{projectId} — the run rows the /reports page reads.
+        const runIdNum = Number.parseInt(numericId(runId), 10);
+        // Top-level execution doc (carries `type` = 'TC' or 'SUITE', and `executionItems[]` for a suite).
+        // One extra POST per getRun call; a suite short-circuits here so no /exec/report is needed.
+        if (Number.isFinite(runIdNum)) {
+            const execBody = {
+                searchFields: [
+                    { column: 'id', value: runIdNum, regEx: false },
+                    { column: 'projectId', value: projectId, regEx: false },
+                    { column: 'deleted', value: false },
+                ],
+                startIndex: 0,
+                limit: 1,
+            };
+            const execRaw = await this.http.postJson('/exec/execution/search', execBody);
+            const execDoc = pickArray(execRaw, 'data', 'content', 'executions')[0];
+            if (execDoc && String(execDoc.type ?? '').toUpperCase() === 'SUITE') {
+                const items = Array.isArray(execDoc.executionItems) ? execDoc.executionItems : [];
+                const children = items.map((it) => {
+                    const child = {
+                        id: str(it, 'code') ?? String(it?.id ?? ''),
+                        state: mapRunState(str(it, 'status') ?? ''),
+                    };
+                    const name = str(it, 'name');
+                    if (name)
+                        child.title = name;
+                    return child;
+                });
+                const total = children.length;
+                const done = children.filter((c) => c.state !== 'queued' && c.state !== 'running').length;
+                const suiteNum = Number(execDoc.executionTypeId ?? 0);
+                return {
+                    runId,
+                    state: mapRunState(str(execDoc, 'status') ?? ''),
+                    ...(total > 0 ? { progress: { done, total }, children } : {}),
+                    reportUrl: `${base}/user/reports/reports-page?type=SUITE&parentId=${suiteNum}&id=${runIdNum}&projectId=${projectId}`,
+                };
+            }
+        }
+        // TC path — per-step results via /exec/report + /reports/execution/getstepResult.
         const runs = await this.http.getJson(`/exec/report/${runId}/${projectId}`);
         if (!Array.isArray(runs) || runs.length === 0) {
             return { runId, state: 'queued' };
@@ -2764,9 +3032,37 @@ export class SimplifyQaAdapter {
             runId,
             state: mapRunState(str(chosen, 'status') ?? ''),
             stepResults,
-            reportUrl: `${base}/reports/execution/${runId}`,
+            reportUrl: `${base}/user/reports/reports-page?type=TESTCASE&parentId=${parentId}&id=${Number.parseInt(numericId(runId), 10)}&projectId=${projectId}`,
         };
     }
+    /** Most recent execution runId for a SUITE — same `/exec/execution/search` the /reports UI's
+     *  current-executions view drives, filtered to `type=SUITE` + this suite's numeric id, sorted by
+     *  id desc, limit 1. Returns the numeric run id (what `getRun` accepts), or null if the suite has
+     *  never been executed. */
+    async getLatestSuiteRun(suiteId) {
+        const projectId = this.requireProjectId();
+        const suiteNum = Number.parseInt(numericId(suiteId), 10);
+        if (!Number.isFinite(suiteNum))
+            throw new Error(`getLatestSuiteRun: invalid suiteId ${suiteId}.`);
+        // Hand-rolled payload — searchBody doesn't emit `sort` or `operator` keys the /reports search wants.
+        const body = {
+            searchFields: [
+                { column: 'id', sort: 'dsc' },
+                { column: 'deleted', value: false },
+                { column: 'projectId', value: projectId, regEx: false },
+                { column: 'childExecution', value: false },
+                { column: 'parentExecutionCopy', value: true, operator: 'nor' },
+                { column: 'type', value: 'SUITE', regEx: false },
+                { column: 'executionTypeId', value: suiteNum, regEx: false },
+            ],
+            startIndex: 0,
+            limit: 1,
+        };
+        const raw = await this.http.postJson('/exec/execution/search', body);
+        const rows = pickArray(raw, 'data', 'content', 'executions');
+        const runId = str(rows[0], 'id', '_id');
+        return runId ?? null;
+    }
     /** Targeted name lookup for a single project by numeric id — the whole-list `listProjects`
      *  is paged (default 100) and API-key scoping can hide the selected project, which left
      *  callers with an empty projectName. */
@@ -2801,36 +3097,60 @@ export class SimplifyQaAdapter {
         if (!Number.isFinite(tcNum))
             throw new Error(`startRun: could not resolve numeric id for ${tcId}.`);
         const mode = (opts.mode ?? 'local').toUpperCase();
+        // LOCAL fast-fail: the desktop agent is what actually executes the TC (it polls the Redis queue
+        // the backend RPUSHes to). If :4040 isn't up, no roster / customer-search / dispatch will help —
+        // fail here with a clear message instead of enqueuing a job nothing will drain.
+        if (mode === 'LOCAL' && !(await this.probeLocalAgent())) {
+            throw new Error(`startRun (LOCAL): SimplifyQA desktop agent is not reachable at ` +
+                `${this.cfg.url ?? '(no agent URL configured — set QA_MCP_URL)'}. Start the desktop ` +
+                `agent, then try again. Use mode:'cloud' to run on a cloud runner instead — it does not ` +
+                `need the desktop agent.`);
+        }
         const rawTc = await this.fetchRawTestcase(tcId);
         if (!rawTc || Object.keys(rawTc).length === 0) {
             throw new Error(`startRun: test case ${tcId} not found.`);
         }
-        // Version resolution — same fallback chain buildTestcasePayload/getDefaultIteration use.
-        // Caller override (opts.versionId) wins; the name is looked up in the TC's versions[] so the
-        // exec payload's versionName matches the picked versionId.
+        // Version resolution. When the caller supplies an override we accept EITHER the version id or
+        // its name (matches the ask-user UX — a human types "v2.0", not a uuid) and hard-fail if it
+        // resolves to nothing. Silent fallback would send a mismatched {versionId, versionName} to
+        // /exec/execution: at best the backend 500s, at worst it silently runs the TC's current
+        // version instead of the one asked for. No override → the existing fallback chain picks the
+        // TC's current version, matching the UI's Version-chip default.
+        const versions = Array.isArray(rawTc?.versions) ? rawTc.versions : [];
         let versionName;
         let versionId;
         if (opts.versionId) {
-            versionId = opts.versionId;
-            if (Array.isArray(rawTc?.versions)) {
-                const picked = rawTc.versions.find((v) => str(v, 'id', '_id') === opts.versionId);
-                if (picked)
-                    versionName = str(picked, 'name');
+            const picked = versions.find((v) => {
+                const vid = str(v, 'id', '_id');
+                const vname = str(v, 'name');
+                return vid === opts.versionId || vname === opts.versionId;
+            });
+            if (!picked) {
+                if (!versions.length) {
+                    throw new Error(`startRun: test case ${tcId} has no versions available — cannot pin version "${opts.versionId}".`);
+                }
+                const listing = versions
+                    .map((v) => `  • \`${str(v, 'id', '_id')}\` — ${str(v, 'name')}`)
+                    .join('\n');
+                throw new Error(`startRun: version "${opts.versionId}" not found on ${tcId}. Available:\n${listing}`);
             }
+            versionId = str(picked, 'id', '_id');
+            versionName = str(picked, 'name');
+        }
+        else {
+            versionName = str(rawTc, 'versionName', 'selectedVersionName');
+            versionId = str(rawTc, 'versionId', 'selectedVersionId');
+            if ((!versionName || !versionId) && rawTc?.versionsDetails && typeof rawTc.versionsDetails === 'object') {
+                versionName ?? (versionName = str(rawTc.versionsDetails, 'name'));
+                versionId ?? (versionId = str(rawTc.versionsDetails, 'id', '_id', 'versionId'));
+            }
+            if ((!versionName || !versionId) && versions.length > 0) {
+                versionName ?? (versionName = str(versions[0], 'name'));
+                versionId ?? (versionId = str(versions[0], 'id', '_id'));
+            }
+            versionName ?? (versionName = 'v1.0');
+            versionId ?? (versionId = '');
         }
-        versionName ?? (versionName = str(rawTc, 'versionName', 'selectedVersionName'));
-        versionId ?? (versionId = str(rawTc, 'versionId', 'selectedVersionId'));
-        if ((!versionName || !versionId) && rawTc?.versionsDetails && typeof rawTc.versionsDetails === 'object') {
-            versionName ?? (versionName = str(rawTc.versionsDetails, 'name'));
-            versionId ?? (versionId = str(rawTc.versionsDetails, 'id', '_id', 'versionId'));
-        }
-        if ((!versionName || !versionId) && Array.isArray(rawTc?.versions) && rawTc.versions.length > 0) {
-            const v = rawTc.versions[0];
-            versionName ?? (versionName = str(v, 'name'));
-            versionId ?? (versionId = str(v, 'id', '_id'));
-        }
-        versionName ?? (versionName = 'v1.0');
-        versionId ?? (versionId = '');
         // ponytail: was `this.info()` — 5 round-trips (list_projects + 4 counts) for one field, and
         // returned projectName="" when the current project wasn't in the first 100-row page or was
         // filtered by API-key scope, which the /exec/execution endpoint rejects with HTTP 400.
@@ -2862,8 +3182,16 @@ export class SimplifyQaAdapter {
             }
             catch { /* leave empty */ }
         }
-        const agentId = mode === 'LOCAL' ? await this.resolveLocalAgentId(opts.agentId) : null;
-        const platform = this.buildRunPlatform(tcType, mode, opts.browser, opts.deviceId);
+        const agentId = mode === 'LOCAL' ? await this.resolveLocalAgentId(opts.agentId)
+            : mode === 'REMOTE' ? await this.resolveRemoteAgentId(opts.agentId)
+                : null;
+        const platform = this.buildRunPlatform(tcType, mode, {
+            ...(opts.browser !== undefined ? { browser: opts.browser } : {}),
+            ...(opts.deviceId !== undefined ? { deviceId: opts.deviceId } : {}),
+            ...(opts.deviceType !== undefined ? { deviceType: opts.deviceType } : {}),
+            ...(opts.osVersion !== undefined ? { osVersion: opts.osVersion } : {}),
+            ...(opts.cloudDeviceType !== undefined ? { cloudDeviceType: opts.cloudDeviceType } : {}),
+        });
         // UI uses `Math.random().toString(26).substr(5,6)` — plan doc confirms any string works.
         const stepId = Math.random().toString(36).slice(2, 8).padEnd(6, '0');
         const body = {
@@ -2935,6 +3263,25 @@ export class SimplifyQaAdapter {
             killType: 'STOP_EXECUTION',
         });
     }
+    /** GET the agent /mcp with a 1s timeout. Any HTTP response (incl. 4xx from an MCP server rejecting
+     *  a naked GET) proves the process is up; connect/DNS/timeout errors mean it is down. Replaces
+     *  the customer-wide `machineRegistration` round trip when all we needed was "is LOCAL possible?". */
+    async probeLocalAgent() {
+        if (!this.cfg.url)
+            return false;
+        const ac = new AbortController();
+        const timer = setTimeout(() => ac.abort(), 1000);
+        try {
+            await fetch(this.cfg.url, { method: 'GET', signal: ac.signal });
+            return true;
+        }
+        catch {
+            return false;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
     async listCloudRunners() {
         const projectId = this.requireProjectId();
         const body = this.searchBody([{ column: 'projectId', value: projectId }], { limit: 1000 });
@@ -2955,6 +3302,46 @@ export class SimplifyQaAdapter {
             };
         });
     }
+    getLocalIdentifiers() {
+        if (this.localIdsCache)
+            return this.localIdsCache;
+        const hostFull = os.hostname().toLowerCase();
+        const hostBare = hostFull.replace(/\.(local|lan|localdomain)$/, '').split('.')[0] ?? hostFull;
+        const macs = new Set();
+        const ips = new Set();
+        const ifaces = os.networkInterfaces();
+        for (const list of Object.values(ifaces)) {
+            if (!list)
+                continue;
+            for (const iface of list) {
+                if (iface.internal)
+                    continue;
+                if (iface.mac && iface.mac !== '00:00:00:00:00:00')
+                    macs.add(iface.mac.toLowerCase());
+                if (iface.address)
+                    ips.add(iface.address);
+            }
+        }
+        this.localIdsCache = { hostBare, macs, ips };
+        return this.localIdsCache;
+    }
+    /** Does a machineRegistration row belong to the machine this MCP is running on?
+     *  A single positive match on hostname, MAC, or IP is enough — the local agent registers with
+     *  ALL of these, but the surviving match on the SQA row depends on OS quirks (Windows writes a
+     *  padded hostname, macOS writes `foo.local`, IPs shift on Wi-Fi handoff). Any one match is
+     *  proof enough; we don't try to reconcile the others. */
+    isThisMachine(row, ids = this.getLocalIdentifiers()) {
+        const name = (str(row, 'machineName', 'name', 'host') ?? '').toLowerCase();
+        if (ids.hostBare.length > 0 && name.length > 0 && name.includes(ids.hostBare))
+            return true;
+        const mac = (str(row, 'macAddress') ?? '').toLowerCase();
+        if (mac.length > 0 && ids.macs.has(mac))
+            return true;
+        const ip = str(row, 'ipAddress', 'hostAddress') ?? '';
+        if (ip.length > 0 && ids.ips.has(ip))
+            return true;
+        return false;
+    }
     async listLocalAgents() {
         // ponytail: no projectId filter — machine_registration.projectId is never written by
         // test-management/services/machine_registration.service.js (create only stamps
@@ -2963,77 +3350,252 @@ export class SimplifyQaAdapter {
         const body = this.searchBody([{ column: 'deleted', value: false }], { limit: 1000 });
         const raw = await this.http.postJson('/tm/machineRegistration/search', body);
         const rows = pickArray(raw, 'data', 'content', 'agents', 'machines');
-        // ponytail: hostname override, same trick sqa-ui uses at
-        // sqa-ui/.../machine-registration.component.ts:169. The DB `active` flag is only
-        // written to `true` on first registration (fire-and-forget in executions/services/
-        // executionQueue.service.js:49) and back to `false` by a 7s-stale cron. Every other poll
-        // is a no-op, so a still-polling agent frequently shows `active:false`. When the row's
-        // machineName matches THIS box's hostname, MCP is running on the same machine as the
-        // agent — trust that over the stale DB flag. Upgrade path: if the backend adds a live
-        // Redis-presence endpoint (ZSCORE SQAAGENTTRACKER), consult that here instead.
-        const hostFull = os.hostname().toLowerCase();
-        // Bare hostname: strip trailing .local/.lan/.localdomain AND take the first label. Handles
-        // both directions of "short vs FQDN" mismatch — the agent may register as `Pratiks-MBP`
-        // while os.hostname() returns `pratiks-mbp.local`, or vice-versa.
-        const hostBare = hostFull.replace(/\.(local|lan|localdomain)$/, '').split('.')[0] ?? hostFull;
+        // ponytail: mirror sqa-ui/machine-registration.component.ts:169. The DB `active` flag is only
+        // written to `true` on FIRST registration (fire-and-forget in executions/services/
+        // executionQueue.service.js:49) and back to `false` by a 7s-stale cron. Every subsequent poll
+        // is a no-op for the DB — a still-polling agent frequently shows `active:false`. Executions
+        // service is off-limits for the fix, so when the row belongs to THIS machine (any of hostname
+        // / MAC / IP matches), trust that over the stale DB flag.
+        const ids = this.getLocalIdentifiers();
         return rows.map((n) => {
             const id = str(n, 'id', '_id', 'agentId') ?? '';
             const agentName = str(n, 'machineName', 'name', 'host');
             const owner = str(n, 'owner', 'userName', 'createdBy');
             const hostAddr = str(n, 'macAddress', 'hostAddress');
             const dbActive = typeof n?.active === 'boolean' ? n.active : false;
-            const nameLc = agentName?.toLowerCase() ?? '';
-            const isMyBox = nameLc.length > 0 && hostBare.length > 0 && nameLc.includes(hostBare);
+            const isMyBox = this.isThisMachine(n, ids);
             return {
                 id,
                 ...(agentName ? { name: agentName } : {}),
                 online: dbActive || isMyBox,
+                ...(isMyBox ? { isThisMachine: true } : {}),
                 ...(owner ? { owner } : {}),
                 ...(hostAddr ? { host: hostAddr } : {}),
             };
         });
     }
+    /** Mobile devices for the project — the union of:
+     *  (a) the LOCAL roster from `/tm/mobileDevices/search` (adb-visible reals, emulators,
+     *      simulators registered via the desktop agent) — same source the UI's "Real Devices /
+     *      Emulators / Simulators" tabs read; `active` is a last-known connection flag stale by
+     *      design (the desktop agent writes it, a 7s-stale cron flips it back).
+     *  (b) the CLOUD roster from whichever farm the project has integrated — probed in the same
+     *      order as the UI (`execution-popup-modal-v2.component.ts:198-204`): LambdaTest,
+     *      BrowserStack, SauceLabs, SimplifyQA Device Farm. First provider that answers with a
+     *      non-empty list wins (matches the UI's `mobileIntergation.type` single-provider model —
+     *      one cloud provider per project). Cloud rows carry `deviceType:'CLOUD_DEVICE'` and a
+     *      `cloudDeviceType` tag so `tc_run` knows which farm to submit to.
+     *  A failure fetching one source doesn't kill the other — the tool logs and returns whatever
+     *  it could resolve. */
+    async listMobileDevices(platform) {
+        const local = await this.fetchLocalMobileDevices(platform).catch(() => []);
+        const cloud = await this.fetchCloudMobileDevices(platform).catch(() => []);
+        return [...local, ...cloud];
+    }
+    async fetchLocalMobileDevices(platform) {
+        const body = this.searchBody([
+            { column: 'deleted', value: false },
+            { column: 'technologyType', value: platform },
+        ], { limit: 1000 });
+        const raw = await this.http.postJson('/tm/mobileDevices/search', body);
+        const rows = pickArray(raw, 'data', 'content', 'devices');
+        return rows.map((n) => {
+            const id = str(n, 'deviceId', 'udid', 'id', '_id') ?? '';
+            const name = str(n, 'deviceName', 'name', 'model') ?? id;
+            const rawType = String(str(n, 'deviceType') ?? 'REAL_DEVICE').toUpperCase();
+            // SQA stores "REAL" | "EMULATOR" | "SIMULATOR" — normalise "REAL" → "REAL_DEVICE" so the
+            // adapter's downstream wire mapping stays consistent with the executor's enum.
+            const deviceType = rawType === 'REAL' ? 'REAL_DEVICE'
+                : rawType;
+            const osVersion = str(n, 'osVersion');
+            const status = str(n, 'status');
+            const agentId = str(n, 'agentId');
+            return {
+                id, name, platform, deviceType,
+                ...(osVersion ? { osVersion } : {}),
+                ...(typeof n?.active === 'boolean' ? { active: n.active } : {}),
+                ...(status ? { status } : {}),
+                ...(agentId ? { agentId } : {}),
+            };
+        });
+    }
+    /** Probe cloud farms in the UI's order and return the first non-empty match. One provider per
+     *  project (the UI's `mobileIntergation.type` model), so no need to merge across farms. Every
+     *  fetch is wrapped so a 404/401 from one provider doesn't kill the whole list. */
+    async fetchCloudMobileDevices(platform) {
+        // Order matches execution-popup-modal-v2:198-204 (SauceLabs → BrowserStack → LambdaTest).
+        // SQA Device Farm is the fallback the UI only reaches when LambdaTest is inactive (line 203).
+        const attempts = [
+            ['SAUCE_LABS', () => this.fetchSauceLabsMobileDevices(platform)],
+            ['BROWSER_STACK', () => this.fetchBrowserStackMobileDevices(platform)],
+            ['LAMBDA_TEST', () => this.fetchLambdaTestMobileDevices(platform)],
+            ['SIMPLIFY_QA_DEVICE_FORM', () => this.fetchDeviceFarmMobileDevices(platform)],
+        ];
+        for (const [, fetcher] of attempts) {
+            const rows = await fetcher().catch(() => []);
+            if (rows.length)
+                return rows;
+        }
+        return [];
+    }
+    async fetchSauceLabsMobileDevices(platform) {
+        const projectId = this.requireProjectId();
+        const raw = await this.http.getJson(`/tm/marketPlace/sauceLabsDevices/SAUCE_LABS?projectId=${encodeURIComponent(projectId)}`);
+        const rows = pickArray(raw, 'data', 'content', 'devices');
+        // SauceLabs returns OS as UPPERCASE ("IOS"/"ANDROID") — mirror execution-popup-modal-v2:447-448.
+        const wanted = platform.toUpperCase();
+        return rows
+            .filter((n) => String(n?.os ?? '').toUpperCase() === wanted)
+            .map((n) => {
+            const id = str(n, 'id', 'udid', 'name') ?? '';
+            const name = str(n, 'name', 'deviceName', 'model') ?? id;
+            const osVersion = str(n, 'osVersion', 'os_version');
+            return {
+                id, name, platform, deviceType: 'CLOUD_DEVICE', cloudDeviceType: 'SAUCE_LABS',
+                ...(osVersion ? { osVersion } : {}),
+            };
+        });
+    }
+    async fetchBrowserStackMobileDevices(platform) {
+        const projectId = this.requireProjectId();
+        const raw = await this.http.getJson(`/tm/testdata/browserStackDevices/BROWSER_STACK?projectId=${encodeURIComponent(projectId)}`);
+        const rows = pickArray(raw, 'data', 'content', 'devices');
+        // BrowserStack returns OS as lowercase ("ios"/"android") — mirror execution-popup-modal-v2:434-435.
+        const wanted = platform.toLowerCase();
+        return rows
+            .filter((n) => String(n?.os ?? '').toLowerCase() === wanted)
+            .map((n) => {
+            const id = str(n, 'id', 'device') ?? '';
+            const name = str(n, 'device', 'name') ?? id;
+            const osVersion = str(n, 'os_version', 'osVersion');
+            return {
+                id, name, platform, deviceType: 'CLOUD_DEVICE', cloudDeviceType: 'BROWSER_STACK',
+                ...(osVersion ? { osVersion } : {}),
+            };
+        });
+    }
+    async fetchLambdaTestMobileDevices(platform) {
+        const projectId = this.requireProjectId();
+        const raw = await this.http.getJson(`/tm/marketPlace/lambdaTestDevices/LAMBDA_TEST?projectId=${encodeURIComponent(projectId)}`);
+        const rows = pickArray(raw, 'data', 'content', 'devices');
+        // LambdaTest returns OS as lowercase in `platformName`/`os` — mirror the mapping in
+        // execution-popup-modal-v2:472-493 (which composes a friendly display name + slug id).
+        const wantedLower = platform.toLowerCase();
+        const seen = new Set();
+        const mapped = [];
+        for (const d of rows) {
+            const os = String(d?.platformName ?? d?.os ?? '').toLowerCase();
+            if (os !== wantedLower)
+                continue;
+            const baseName = str(d, 'deviceName', 'name') ?? '';
+            const version = str(d, 'version', 'platformVersion', 'osVersion') ?? '';
+            const displayName = version
+                ? `${baseName} (${os === 'ios' ? 'iOS' : 'Android'} ${version})`
+                : baseName;
+            const udid = str(d, 'udid');
+            const slug = `${baseName}_${version}_${os}`.toLowerCase()
+                .replace(/[^a-z0-9_]+/g, '_').replace(/_+/g, '_').replace(/^_|_$/g, '');
+            const id = udid ? `cloud_${udid}` : `cloud_${slug}`;
+            if (seen.has(id))
+                continue;
+            seen.add(id);
+            mapped.push({
+                id, name: displayName, platform, deviceType: 'CLOUD_DEVICE', cloudDeviceType: 'LAMBDA_TEST',
+                ...(version ? { osVersion: version } : {}),
+            });
+        }
+        return mapped;
+    }
+    async fetchDeviceFarmMobileDevices(platform) {
+        const projectId = this.requireProjectId();
+        // SimplifyQA Device Farm is Appium-backed — endpoint mirrors marketPlace.route.js:25. The UI's
+        // `getCloudFormDevicesForExec()` reads the same source when LambdaTest is inactive.
+        const raw = await this.http.getJson(`/tm/marketPlace/deviceFarmDevices/SIMPLIFY_QA_DEVICE_FORM?projectId=${encodeURIComponent(projectId)}`);
+        const rows = pickArray(raw, 'data', 'content', 'devices');
+        // Farm rows include `platform` (ANDROID/IOS) and `sdk` (osVersion). Mirror device-dropdown.ts:413-419.
+        const wanted = platform.toUpperCase();
+        return rows
+            .filter((n) => String(n?.platform ?? '').toUpperCase() === wanted)
+            .map((n) => {
+            const id = str(n, 'udid', 'id') ?? '';
+            const name = str(n, 'name', 'deviceName') ?? id;
+            const osVersion = str(n, 'sdk', 'osVersion');
+            return {
+                id, name, platform, deviceType: 'CLOUD_DEVICE', cloudDeviceType: 'SIMPLIFY_QA_DEVICE_FORM',
+                ...(osVersion ? { osVersion } : {}),
+            };
+        });
+    }
     /**
-     * Pick THE ACTING USER'S OWN active agent — never row [0] of a shared-tenant roster (which
-     * would silently dispatch a local run to a teammate's box, and the run would sit queued until
-     * TTL because it lands in a Redis key that no local agent on the caller's machine polls).
+     * Pick THE ACTING USER'S OWN agent — never row [0] of a shared-tenant roster (which would
+     * silently dispatch a local run to a teammate's box, and the run would sit queued until TTL
+     * because it lands in a Redis key that no local agent on the caller's machine polls).
      *
      * SQA's `machineRegistration` row carries no owner_user_id column (unlike walnut, which matches
-     * the JWT `id` claim to `owner_user_id`), so we identify "your" agent by hostname: common-mcp
-     * runs on the caller's own box in the typical MCP setup, and SQA `machineName` is either the
-     * bare OS hostname or a bracketed display form (`USER.NAME [ Hostname.local ]`) — both contain
-     * `os.hostname()`. Filter → active only → hostname substring match → return the single hit.
-     * Zero/many matches refuse honestly; a silent guess would just repeat the exact bug we're fixing.
+     * the JWT `id` claim to `owner_user_id`), so we identify "your" agent by physical identity:
+     * hostname, MAC address, or IP — any one match against `os.networkInterfaces()` on the box this
+     * MCP is running on. When exactly one row is "this machine", pick it regardless of the DB
+     * `active` flag (that flag is stale by design — see listLocalAgents for the executionQueue bug).
      *
-     * ponytail: hostname heuristic. Upgrade to owner-user-id match if the backend adds that column
-     * to machineRegistration (mirror walnut's `resolveLocalAgentCredential` at that point).
+     * ponytail: multi-identifier heuristic. Upgrade to owner-user-id match if the backend adds that
+     * column to machineRegistration (mirror walnut's `resolveLocalAgentCredential` at that point).
      */
     async resolveLocalAgentId(preferred) {
-        if (preferred && preferred.length > 0)
-            return preferred;
         const agents = await this.listLocalAgents();
         if (agents.length === 0) {
             throw new Error('startRun (LOCAL): no local agent registered. Register a machine in the SimplifyQA UI ' +
                 'first, or pass mode: "cloud" if a cloud runner is provisioned.');
         }
-        const active = agents.filter((a) => a.online);
-        if (active.length === 0) {
-            throw new Error('startRun (LOCAL): no local agent is currently active (polling). Launch your SimplifyQA ' +
-                'desktop agent and retry — or pass `agentId` explicitly if you know the credential id.');
+        // Priority 1: rows that physically match this machine. Ignore the DB `active` flag — a running
+        // agent frequently shows `active:false` between the 5s stale-cron and the next heartbeat, and
+        // the executions service is off-limits for the real fix.
+        const mine = agents.filter((a) => a.isThisMachine);
+        // Explicit agentId: only accept it when it belongs to THIS machine. LOCAL dispatches to the
+        // desktop agent on this box (there is exactly one per machine); a teammate's credentialId under
+        // mode:'local' was the silent-misroute bug isThisMachine exists to prevent.
+        if (preferred && preferred.length > 0) {
+            if (mine.some((a) => a.id === preferred))
+                return preferred;
+            const listing = agents.map((a) => `  - ${a.name ?? a.id} \`${a.id}\`${a.isThisMachine ? ' (this machine)' : ''}`).join('\n');
+            throw new Error(`startRun (LOCAL): agentId "${preferred}" is not registered from THIS machine. LOCAL mode ` +
+                `dispatches to this box's own desktop agent — teammate agents are for a REMOTE run. ` +
+                `Omit agentId to auto-pick this machine's agent, or use mode:'cloud' for a cloud runner.\n` +
+                `Registered agents:\n${listing}`);
         }
-        const hostFull = os.hostname().toLowerCase();
-        // Same short-vs-FQDN handling as listLocalAgents — see the ponytail note there.
-        const host = hostFull.replace(/\.(local|lan|localdomain)$/, '').split('.')[0] ?? hostFull;
-        const mine = active.filter((a) => host.length > 0 && (a.name ?? '').toLowerCase().includes(host));
         if (mine.length === 1)
             return mine[0].id;
-        const listing = (arr) => arr.map((a) => `  - ${a.name ?? a.id} \`${a.id}\``).join('\n');
         if (mine.length > 1) {
-            throw new Error(`startRun (LOCAL): multiple active agents match this machine (${host}). Pass \`agentId\` ` +
-                `to pick one:\n${listing(mine)}`);
+            const listing = mine.map((a) => `  - ${a.name ?? a.id} \`${a.id}\``).join('\n');
+            throw new Error(`startRun (LOCAL): multiple agents registered from this machine. Pass \`agentId\` to ` +
+                `pick one:\n${listing}`);
+        }
+        // No physical match for this machine and no preferred — LOCAL cannot proceed.
+        const roster = agents.map((a) => `  - ${a.name ?? a.id} \`${a.id}\`${a.online ? '' : ' (offline)'}`).join('\n');
+        throw new Error(`startRun (LOCAL): no agent registered from this machine (hostname / MAC / IP did not match ` +
+            `any row). Launch the SimplifyQA desktop agent on this box, or use mode:'remote' to run on a ` +
+            `teammate's agent.\nRegistered agents:\n${roster}`);
+    }
+    /** REMOTE dispatches to ANOTHER machine's desktop agent — must pin a specific credentialId (auto-pick
+     *  across teammate boxes is the exact silent-misroute this exists to prevent). Enforces:
+     *  (1) preferred is present, (2) it exists in the roster, (3) it is NOT this machine (use LOCAL for
+     *  that). Reachability of the remote agent is not probed — the backend queues the job and the
+     *  remote agent picks it up when it polls. */
+    async resolveRemoteAgentId(preferred) {
+        if (!preferred || preferred.length === 0) {
+            throw new Error(`startRun (REMOTE): agentId is required. REMOTE dispatches to a specific teammate machine — ` +
+                `there is no auto-pick. Call remote_agents to see the roster and pass one as \`agentId\`.`);
+        }
+        const agents = await this.listLocalAgents();
+        const picked = agents.find((a) => a.id === preferred);
+        if (!picked) {
+            throw new Error(`startRun (REMOTE): agentId "${preferred}" is not a registered agent. Call remote_agents ` +
+                `for the current roster.`);
+        }
+        if (picked.isThisMachine) {
+            throw new Error(`startRun (REMOTE): agentId "${preferred}" is THIS machine's own agent — use mode:'local' ` +
+                `for a run on this box.`);
         }
-        throw new Error(`startRun (LOCAL): could not auto-pick your local agent — no active agent's name matches ` +
-            `this hostname (${host}). Pass \`agentId\` explicitly. Active agents:\n${listing(active)}`);
+        return preferred;
     }
     detectExecutionOS() {
         if (process.platform === 'win32')
@@ -3042,30 +3604,36 @@ export class SimplifyQaAdapter {
             return 'MAC';
         return 'LINUX';
     }
-    buildRunPlatform(tcType, mode, browser, deviceId) {
+    buildRunPlatform(tcType, mode, opts) {
         const t = tcType.toUpperCase();
         if (t === 'WEB') {
             if (mode === 'CLOUD') {
-                const key = `${(browser ?? 'CHROME').toUpperCase()}_HEADLESS`;
+                const key = `${(opts.browser ?? 'CHROME').toUpperCase()}_HEADLESS`;
                 return [{ name: key, id: key, technologyType: 'WEB', type: 'NONE' }];
             }
-            const b = (browser ?? 'CHROME').toUpperCase();
+            const b = (opts.browser ?? 'CHROME').toUpperCase();
             return [{ name: b, id: b, technologyType: 'WEB', type: 'NONE' }];
         }
         if (t === 'ANDROID' || t === 'IOS') {
             // Executor's AndroidSessionFactory.buildLocal calls requireDeviceId — no default. Fail
             // loud so the caller sees the fix (list devices, pick one) instead of a queued/error hang.
-            if (!deviceId) {
-                throw new Error(`${t} test cases need \`deviceId\`. Call android_list_devices to see the available ` +
+            if (!opts.deviceId) {
+                throw new Error(`${t} test cases need \`deviceId\`. Call mobile_list_devices to see the available ` +
                     `devices, then re-run with \`deviceId\` set to the adb serial (LOCAL) or marketplace ` +
                     `device name (CLOUD).`);
             }
-            // ponytail: CLOUD path still ships `cloudDeviceType: undefined` — the executor needs it
-            // (BROWSER_STACK / SAUCE_LABS / LAMBDA_INTEGRATION / SQA_DEVICE_FARM) to know which farm
-            // to route to. Deferred with the marketplace port; LOCAL runs unaffected.
+            // Default LOCAL to REAL_DEVICE when caller doesn't say — mirrors the pre-deviceType shape.
+            // CLOUD gets CLOUD_DEVICE for the same reason. Explicit deviceType wins over both.
+            const type = opts.deviceType ?? (mode === 'CLOUD' ? 'CLOUD_DEVICE' : 'REAL_DEVICE');
+            const isCloud = type.startsWith('CLOUD_');
+            // ponytail: LambdaTest cloud runs work without app-URL preload for most flows — the
+            // executor derives creds from the project's LT integration server-side. If a run fails
+            // with "app not found" we'll port the UI's preloadLambdaAppMap flow (execution-popup-
+            // modal-v2:613-641) and stamp appUrl/userName/accessKey here.
             return [{
-                    name: deviceId, id: deviceId, technologyType: t,
-                    type: mode === 'CLOUD' ? 'CLOUD_DEVICE' : 'NONE',
+                    name: opts.deviceId, id: opts.deviceId, technologyType: t, type,
+                    ...(opts.osVersion ? { osVersion: opts.osVersion } : {}),
+                    ...(isCloud && opts.cloudDeviceType ? { cloudDeviceType: opts.cloudDeviceType } : {}),
                 }];
         }
         return [{ name: t, id: t, technologyType: t, type: 'NONE' }];