common-qa-mcp 0.3.0 → 0.4.1

package/dist/adapters/simplifyqa/adapter.js

@@ -1,11 +1,12 @@
 import os from 'node:os';
 import { makeClient } from '../http.js';
 import { RemoteMcpAdapter } from '../remoteMcp/adapter.js';
-import { applyCollectionSteps, buildTestcasePayload, extractParamNames, looksSensitive, normalizeSuiteEntry, numericId, paramDefault, pickArray, str, SUITE_UPDATE_ALLOWED_KEYS, toModuleSummary, toObject, toReleaseSummary, toSavedRef, toSprintSummary, toStory, toStorySummary, toSuite, toSuiteSummary, toTcSummary, toTestCase, } from './mapper.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',
 };
 /** SQA run-row status → neutral RunStatus.state. */
 function mapRunState(s) {
@@ -75,6 +76,132 @@ function mapStepStatus(s) {
         default: return s.toLowerCase();
     }
 }
+/** Allowed keys for save-as-new-version. The update joi validator
+ *  (testcaseValidator.js updateTcBodyValidation, ~line 187) is a STRICT allow-list — a raw doc's
+ *  extras (`code`, `createdBy`, `updatedBy`, `stepCount`, `versions`, ...) crash the save with
+ *  "is not allowed". Kept as string arrays so a schema drift is a one-line fix. */
+const TCFNOBJ_ALLOWED_KEYS = [
+    'id', 'name', 'projectId', 'deleted', 'moduleId', 'userstoryId', 'obsolete', 'tcType', 'mbType',
+    'executionType', 'description', 'prerequisite', 'updateVersion', 'linkedIssues', 'attachments',
+    'tags', 'suiteId', 'defectId', 'customFields', 'reviewApproveStatus', 'copiedFromTcId',
+    'projectLevelCopy', 'originalExecutinType', 'projectLevelcopiedFrom', 'mailersList',
+    'configuration', 'executionPlatform',
+];
+// FN update validator (functionValidator.js `updateFnBodyValidation.tcfnObj`) diverges from the TC
+// one in three ways that MATTER for SAVENEWVERSION: `fnType` REQUIRED (not `tcType`);
+// `obsolete`/`suiteId`/`defectId`/`configuration`/`executionPlatform`/`tcType`/`mbType` NOT
+// allowed; `copiedFromFnId` in place of `copiedFromTcId`. Sending TC's list to `/tm/function`
+// trips joi with "not allowed" on obsolete and "required" on fnType.
+const TCFNOBJ_FN_ALLOWED_KEYS = [
+    'id', 'name', 'projectId', 'deleted', 'moduleId', 'userstoryId', 'fnType',
+    'executionType', 'description', 'prerequisite', 'updateVersion', 'linkedIssues', 'attachments',
+    'tags', 'customFields', 'reviewApproveStatus', 'copiedFromFnId', 'projectLevelCopy',
+    'projectLevelcopiedFrom', 'mailersList', 'originalExecutinType', 'isMigrated', 'oldCode',
+];
+const STEP_ALLOWED_KEYS = [
+    'projectId', 'sharedFnProjectId', 'moduleId', 'apiData', 'lastActiveTab', 'userstoryId',
+    'updateVersion', 'type', 'parentId', 'objectId', 'stepType', 'functionId', 'actionId',
+    'parameterIds', 'objectParameterIds', 'parameterizedParamIds', 'attachments', 'compareFiles',
+    'compareFileType', 'deviceId', 'deleted', 'ignoreObject', 'browserType', 'technologyType', 'seq',
+    'captureScreenshot', 'screenshotEnabled', 'fnVersionId', 'description', 'expectedResult',
+    'conditions', 'stepLevelActions', 'skipParamInReport', 'paramLoopduration', 'showGroups',
+    'isConditional', 'if', 'else', 'loop', 'isLoop', 'loopType', 'startFor', 'endFor',
+    'loopDuration', 'executionType', 'recordedParam', '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.
+];
+function pick(obj, keys) {
+    const out = {};
+    if (!obj || typeof obj !== 'object')
+        return out;
+    for (const k of keys)
+        if (obj[k] !== undefined)
+            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
+ *  entity kind. Numeric ids and unrecognized-prefix strings pass through (leave that to backend). */
+function assertBusinessKeyKind(id, expected) {
+    const m = id?.match(/^([A-Za-z]+)[_-]\d+$/);
+    if (!m)
+        return;
+    const prefix = m[1].toUpperCase();
+    if ((expected === 'TC' && prefix === 'FN') || (expected === 'FN' && prefix === 'TC')) {
+        const otherTool = expected === 'TC'
+            ? 'this is a function key — use the fn_* tool (fn_clone, fn_save_as_new_version, get_function, delete_function)'
+            : 'this is a test-case key — use the tc_* tool (tc_clone, tc_save_as_new_version, tc_get, tc_delete)';
+        throw new Error(`Refusing to run against ${id}: ${otherTool}.`);
+    }
+}
+/** Coerce a raw {[projectId]: [ids]} map from a dep row into a plain Record<string, number[]>.
+ *  Absent/malformed inputs collapse to `{}`. */
+function toDepMap(v) {
+    if (!v || typeof v !== 'object' || Array.isArray(v))
+        return {};
+    const out = {};
+    for (const [k, arr] of Object.entries(v)) {
+        if (Array.isArray(arr))
+            out[k] = arr.filter((n) => Number.isFinite(n));
+    }
+    return out;
+}
+/** Normalise a raw dep row from PUT /tm/tcfnversion/delete into the neutral shape. Key set is
+ *  narrower for FN — the service emits `{tcArr, fnArr, wfArr}` there vs the TC keyset. */
+function normalizeVersionDep(row, parentType) {
+    const id = Number(row?.id ?? 0);
+    if (parentType === 'FN') {
+        return {
+            id,
+            tcArr: toDepMap(row?.tcArr),
+            fnArr: toDepMap(row?.fnArr),
+            wfArr: toDepMap(row?.wfArr),
+        };
+    }
+    const name = typeof row?.versionName === 'string' ? row.versionName : undefined;
+    return {
+        id,
+        ...(name ? { versionName: name } : {}),
+        defectArr: toDepMap(row?.defectArr),
+        suiteArr: toDepMap(row?.suiteArr),
+        epArr: toDepMap(row?.epArr),
+        scenarioArr: toDepMap(row?.scenarioArr),
+        schedulerArr: toDepMap(row?.schedulerArr),
+        pipelineArr: toDepMap(row?.pipelineArr),
+        workflowArr: toDepMap(row?.workflowArr),
+    };
+}
+/** True when every `*Arr` on the row is an empty map — i.e. no references block the delete.
+ *  Mirrors the UI's own check (testcase.component.ts:2142 / function.component.ts:1617). */
+function versionDepIsEmpty(dep) {
+    const maps = 'tcArr' in dep && 'wfArr' in dep && !('defectArr' in dep)
+        ? [dep.tcArr, dep.fnArr, dep.wfArr]
+        : [
+            dep.defectArr, dep.suiteArr,
+            dep.epArr, dep.scenarioArr,
+            dep.schedulerArr, dep.pipelineArr,
+            dep.workflowArr,
+        ];
+    return maps.every((m) => Object.keys(m).length === 0);
+}
 const NEEDS_PROJECT = 'No project selected. Call list_projects to see the available projects, then ' +
     'qa_switch_project({ projectId }) to choose one — test cases, runs and objects ' +
     'are all scoped to a project.';
@@ -83,7 +210,7 @@ const HOP_NEEDED_WRITE = 'This SimplifyQA operation is not yet ported to direct
 /**
  * SimplifyQaAdapter — DIRECT-to-backend REST driver for SimplifyQA, mirroring WalnutAdapter's
  * design. Reads (list/get for projects/testcases/suites/stories/modules/releases/sprints/objects)
- * hit the SQA TM backend REST directly via a `QaHttp` bound to `cfg.baseUrl`. Anything not yet
+ * hit the SimplifyQA backend REST directly via a `QaHttp` bound to `cfg.baseUrl`. Anything not yet
  * ported (writes, testdata, run dispatch, marketplace, and the recording surface) delegates to
  * the LOCAL AGENT's `/mcp` (`cfg.url`) via a lazily-built RemoteMcpAdapter — same "graceful hop"
  * pattern walnut uses for recording. When the hop is not configured, unported ops surface a clear
@@ -104,6 +231,19 @@ 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;
+        // ---------------------------------------------------------------------- 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.
+         *  Keyed by `${technologyType}::${lowerCaseName}` so the same action name across two techs
+         *  (e.g. "click" for WEB + ANDROID) resolves to the right numeric id. */
+        this.actionCatalogCache = null;
+        // ---------------------------------------------------------------------- Objects (read + delete)
+        // list/create/delete now go direct REST (same /tm/object base getObject already uses), mirroring
+        // the testcase/suite search + soft-delete convention.
+        /** name (UPPERCASE) → objecttemplateId. Rarely changes; cached per adapter instance like
+         *  formulaCache. Populated from `POST /tm/objectTemplate/search` (confirmed endpoint,
+         *  api-endpoints.ts `object.search`'s sibling `objectTemplate.search`). */
+        this.objectTemplateCache = null;
         if (!cfg.baseUrl) {
             throw new Error('SimplifyQaAdapter requires a baseUrl — set QA_BASE_URL or use a JWT with a `url` claim.');
         }
@@ -119,7 +259,6 @@ export class SimplifyQaAdapter {
         return {
             Authorization: `Bearer ${this.cfg.token}`,
             ...(this.cfg.projectId ? { 'x-project-id': this.cfg.projectId } : {}),
-            'Content-Type': 'application/json',
         };
     }
     requireProjectId() {
@@ -140,7 +279,7 @@ export class SimplifyQaAdapter {
                 ...(f.regEx ? { regEx: true } : {}),
             })),
             startIndex: opts.startIndex ?? 0,
-            limit: opts.limit ?? 1000,
+            limit: opts.limit ?? 100,
         };
         if (opts.selectFields)
             body['selectFields'] = opts.selectFields;
@@ -148,26 +287,124 @@ export class SimplifyQaAdapter {
     }
     // ---------------------------------------------------------------------- Info + projects
     /** Validates baseUrl + token + (optional) project by running the same list_projects search the
-     *  Java `infoResult` uses to resolve the project name — no separate /info endpoint on SQA. */
+     *  Java `infoResult` uses to resolve the project name — no separate /info endpoint on SQA.
+     *  `counts` is a best-effort row count per entity type (test cases/suites/stories/objects), read
+     *  from each `/search` endpoint's own `totalCount` (see searchTotalCount) — mirrors what Walnut's
+     *  info() already returns via its own `counts`. */
     async info() {
         const projects = await this.listProjects();
         const projectId = this.cfg.projectId ?? '';
         const found = projects.find((p) => p.id === projectId);
+        const [testCases, suites, stories, objects] = await Promise.all([
+            this.searchTotalCount('/tm/testcase/search'),
+            this.searchTotalCount('/tm/suites/search'),
+            this.searchTotalCount('/pm/userstory/search'),
+            this.searchTotalCount('/tm/object/search'),
+        ]);
         return {
             provider: 'simplifyqa',
             projectId,
             projectName: found?.name ?? '',
+            counts: { testCases, suites, stories, objects },
         };
     }
-    /** `POST /pm/project/search` — projects the token can see. NOT project-scoped. */
+    /** Projects the caller can access. Three code paths in priority order:
+     *
+     *  1. Config-supplied `QA_MCP_USER_ID` (needed for API-key auth — SQA keys are encrypted JWTs
+     *     with no client-decryptable userId, and no whoami endpoint exists yet) → user-scoped
+     *     two-step via `/pm/projectuserrole`.
+     *  2. Session JWT with `userId` claim → same two-step.
+     *  3. Neither → direct `/pm/project/search`; the backend scopes by the token owner where it
+     *     can (may return tenant-wide for API keys). `totalCount` uses `rows.length` (backend's
+     *     top-level `totalCount` is unreliable — counts pre-filter, includes deleted).
+     *
+     *  The two-step avoids both problems: correct user scoping AND an accurate count. */
     async listProjects() {
+        const userId = this.cfg.userId?.trim() || this.jwtUserId();
+        return userId ? this.listProjectsForUser(userId) : this.listProjectsDirect();
+    }
+    async listProjectsForUser(userId) {
+        const rolesRaw = await this.http.getJson(`/pm/projectuserrole?userId=${encodeURIComponent(userId)}`);
+        const roleRows = pickArray(rolesRaw, 'data', 'content');
+        const projectIds = Array.from(new Set(roleRows.map((r) => str(r, 'projectId')).filter((v) => !!v))).map((s) => Number.parseInt(s, 10)).filter((n) => Number.isFinite(n));
+        if (projectIds.length === 0)
+            return withTotal([], { totalCount: 0 });
+        const body = this.searchBody([
+            { column: 'id', value: projectIds },
+            { column: 'deleted', value: false },
+        ], { selectFields: ['id', 'code', 'name'], limit: projectIds.length });
+        const raw = await this.http.postJson('/pm/project/search', body);
+        const rows = pickArray(raw, 'data', 'content', 'projects');
+        const projects = rows.map((n) => {
+            const code = str(n, 'code');
+            return {
+                id: str(n, 'id', '_id', 'projectId') ?? '',
+                ...(code ? { code } : {}),
+                name: str(n, 'name', 'projectName') ?? '',
+            };
+        });
+        return withTotal(projects, { totalCount: projects.length });
+    }
+    /** Best-effort row count for an entity `/search` endpoint — posts a minimal (limit 1) project-scoped
+     *  search and reads the `totalCount` the backend returns alongside `data` (the same envelope shape
+     *  every /search endpoint in this codebase uses, confirmed via the real sqa-ui
+     *  `{ totalCount: number, data: [...] }` response typing). Never throws — counts are a nice-to-have
+     *  for project_info, not worth failing the whole call over; any failure (or a missing totalCount)
+     *  falls back to 0 / the returned row count. */
+    async searchTotalCount(path) {
+        try {
+            const projectId = this.requireProjectId();
+            const body = this.searchBody([{ column: 'deleted', value: false }, { column: 'projectId', value: projectId }], { limit: 1 });
+            const raw = await this.http.postJson(path, body);
+            if (typeof raw?.totalCount === 'number')
+                return raw.totalCount;
+            return pickArray(raw, 'data', 'content').length;
+        }
+        catch {
+            return 0;
+        }
+    }
+    async listProjectsDirect() {
         const body = this.searchBody([{ column: 'deleted', value: false }], { selectFields: ['id', 'code', 'name'] });
         const raw = await this.http.postJson('/pm/project/search', body);
         const rows = pickArray(raw, 'data', 'content', 'projects');
-        return rows.map((n) => ({
-            id: str(n, 'id', '_id', 'projectId') ?? '',
-            name: str(n, 'name', 'projectName') ?? '',
-        }));
+        const projects = rows.map((n) => {
+            const code = str(n, 'code');
+            return {
+                id: str(n, 'id', '_id', 'projectId') ?? '',
+                ...(code ? { code } : {}),
+                name: str(n, 'name', 'projectName') ?? '',
+            };
+        });
+        // ponytail: backend `totalCount` on /pm/project/search is unreliable (counts pre-filter). Trust
+        // rows.length instead — accurate for the page we actually returned.
+        return withTotal(projects, { totalCount: projects.length });
+    }
+    /** Decode the `userId` claim from the SQA JWT payload WITHOUT verifying the signature. Backend
+     *  re-verifies on every call; this only needs the id for `/pm/projectuserrole`. Returns undefined
+     *  on any parse failure or when the token isn't a JWT. */
+    jwtUserId() {
+        const token = this.cfg.token;
+        if (!token)
+            return undefined;
+        try {
+            const t = token.startsWith('Bearer ') ? token.slice(7).trim() : token.trim();
+            const seg = t.split('.')[1];
+            if (!seg)
+                return undefined;
+            let b64 = seg.replace(/-/g, '+').replace(/_/g, '/');
+            b64 += '='.repeat((4 - (b64.length % 4)) % 4);
+            const claims = JSON.parse(Buffer.from(b64, 'base64').toString('utf8'));
+            const v = claims['userId'] ?? claims['id'] ?? claims['sub'];
+            if (typeof v === 'string' && v.length)
+                return v;
+            if (typeof v === 'number')
+                return String(v);
+            return undefined;
+        }
+        catch {
+            return undefined;
+        }
     }
     // ---------------------------------------------------------------------- Test cases (read)
     async listTestCases(q) {
@@ -180,35 +417,78 @@ export class SimplifyQaAdapter {
             fields.push({ column: 'name', value: q.search, regEx: true });
         if (q.status)
             fields.push({ column: 'status', value: q.status });
+        const createdBy = this.resolveUserFilter(q.createdBy);
+        if (createdBy != null)
+            fields.push({ column: 'createdBy', value: createdBy });
+        const updatedBy = this.resolveUserFilter(q.updatedBy);
+        if (updatedBy != null)
+            fields.push({ column: 'updatedBy', value: updatedBy });
+        if (q.storyId)
+            fields.push({ column: 'userstoryId', value: Number.parseInt(numericId(q.storyId), 10) });
+        if (q.moduleId)
+            fields.push({ column: 'moduleId', value: Number.parseInt(numericId(q.moduleId), 10) });
+        if (typeof q.obsolete === 'boolean')
+            fields.push({ column: 'obsolete', value: q.obsolete });
+        if (q.filters?.length)
+            fields.push(...q.filters);
         const body = this.searchBody(fields, {
             startIndex: q.offset ?? 0,
             limit: q.limit ?? 100,
-            selectFields: ['id', 'code', 'name', 'priority', 'status', 'stepCount', 'tcType', 'executionType'],
+            selectFields: ['id', 'code', 'name', 'priority', 'status', 'stepCount', 'tcType', 'executionType', 'obsolete'],
         });
         const raw = await this.http.postJson('/tm/testcase/search', body);
         const rows = pickArray(raw, 'data', 'content', 'testCases');
-        return rows.map(toTcSummary);
+        return withTotal(rows.map(toTcSummary), raw);
     }
-    /** Neutral test case, steps included. Accepts numeric id or business code (`TC_123`). */
-    async getTestCase(id) {
+    /** "me" → cfg.userId (numeric); numeric string → number; anything else → undefined. Callers
+     *  should have resolved a name to a numeric id via `list_users` first. */
+    resolveUserFilter(v) {
+        if (!v)
+            return undefined;
+        const raw = v === 'me' ? (this.cfg.userId?.trim() ?? '') : v.trim();
+        if (!raw)
+            return undefined;
+        const n = Number.parseInt(raw, 10);
+        return Number.isFinite(n) ? n : undefined;
+    }
+    /** Neutral test case, steps included. Accepts numeric id or business code (`TC_123`).
+     *  `versionId` overrides which version's steps to load — omit to accept the TC's currently-
+     *  selected version. When the resolved version differs from the doc's current selection, we
+     *  also patch `currentVersionId` on the returned tc so callers can render "showing version X". */
+    async getTestCase(id, versionId) {
         const raw = await this.fetchRawTestcase(id);
         if (!raw || Object.keys(raw).length === 0) {
             throw new Error(`test case ${id} not found`);
         }
         const tc = toTestCase(raw);
-        // Prefer the steps COLLECTION — that's the source of truth the SQA UI, executor, and save
-        // paths use today. Inline steps.manualSteps / steps.automationSteps on the TC doc drift
-        // against it. Fall back to inline (already on `tc` from toTestCase) if the collection
-        // fetch is empty or throws — legacy TCs that never migrated still surface something.
+        // If the caller pinned a version, validate it exists on the TC — otherwise the /steps call
+        // just returns an empty array for an unknown id and the user sees "no steps" for a typo.
+        if (versionId) {
+            const known = (tc.versions ?? []).some((v) => v.id === versionId);
+            if (!known)
+                throw new Error(`version ${versionId} not found on test case ${id}`);
+        }
+        let rows = [];
         try {
-            const rows = await this.fetchStepsCollection(id, raw);
-            if (rows.length > 0)
-                return applyCollectionSteps(tc, rows);
+            rows = await this.fetchStepsCollection(id, raw, versionId);
         }
-        catch {
-            // ignore — inline steps stay
+        catch { /* fall through — inline steps stay */ }
+        const withSteps = rows.length > 0 ? applyCollectionSteps(tc, rows) : tc;
+        // Overlay currentVersionId to the resolved one and flip isCurrent flags on versions[]. Apply
+        // even when rows are empty — a caller who pinned versionId still expects the header + versions[]
+        // to reflect that choice (a legitimately-empty version shouldn't fall back to the TC's default).
+        const resolvedVer = versionId ?? tc.currentVersionId;
+        const patched = { ...withSteps, ...(resolvedVer ? { currentVersionId: resolvedVer } : {}) };
+        if (resolvedVer && patched.versions?.length) {
+            patched.versions = patched.versions.map((v) => ({ ...v, isCurrent: v.id === resolvedVer }));
         }
-        return tc;
+        if (rows.length > 0) {
+            await Promise.all([
+                this.hydrateFunctionNames(patched),
+                this.hydrateObjectNames(patched),
+            ]);
+        }
+        return patched;
     }
     async fetchRawTestcase(id) {
         const raw = await this.http.getJson(`/tm/testcase/getById/${numericId(id)}`);
@@ -217,16 +497,21 @@ export class SimplifyQaAdapter {
             doc = doc.length > 0 ? doc[0] : {};
         return doc && typeof doc === 'object' ? doc : {};
     }
-    async fetchStepsCollection(tcId, rawTc) {
+    async fetchStepsCollection(tcId, rawTc, versionOverride) {
         const projectId = this.requireProjectId();
         const tcNum = numericId(tcId);
-        // versionId lives under a few different keys depending on the read model — Java tries all four.
-        let versionId = str(rawTc, 'versionId', 'selectedVersionId') ??
-            (rawTc?.versionsDetails && typeof rawTc.versionsDetails === 'object'
-                ? str(rawTc.versionsDetails, 'id', '_id', 'versionId')
-                : undefined);
-        if (!versionId && Array.isArray(rawTc?.versions) && rawTc.versions.length > 0) {
-            versionId = str(rawTc.versions[0], 'id', '_id');
+        // Resolution order: explicit override → TC's currently-selected version (any of 4 field
+        // names, depending on the read model — Java tries all four) → first entry in versions[].
+        let versionId = versionOverride;
+        if (!versionId) {
+            versionId =
+                str(rawTc, 'versionId', 'selectedVersionId') ??
+                    (rawTc?.versionsDetails && typeof rawTc.versionsDetails === 'object'
+                        ? str(rawTc.versionsDetails, 'id', '_id', 'versionId')
+                        : undefined);
+            if (!versionId && Array.isArray(rawTc?.versions) && rawTc.versions.length > 0) {
+                versionId = str(rawTc.versions[0], 'id', '_id');
+            }
         }
         if (!versionId)
             return [];
@@ -239,6 +524,93 @@ export class SimplifyQaAdapter {
         const rows = Array.isArray(body) ? body : Array.isArray(body?.data) ? body.data : [];
         return rows;
     }
+    /** For every FUNCTION step, resolve the referenced function's code + name via /tm/function search
+     *  (batched by distinct functionId). Mutates `tc.steps[i].functionCall` in place with
+     *  `testCaseCode`/`testCaseName`. Non-fatal on failure — the raw id still renders. Mirrors the
+     *  Excel export builder in tcfn.service.js:2696-2703. */
+    async hydrateFunctionNames(tc) {
+        const ids = new Set();
+        for (const s of tc.steps) {
+            if (s.stepType === 'function' && s.functionCall?.testCaseId) {
+                ids.add(s.functionCall.testCaseId);
+            }
+        }
+        if (!ids.size)
+            return;
+        try {
+            const projectId = this.requireProjectId();
+            const body = this.searchBody([
+                { column: 'deleted', value: false },
+                { column: 'projectId', value: projectId },
+                { column: 'id', value: [...ids].map((x) => Number.parseInt(x, 10)).filter(Number.isFinite), regEx: false },
+            ]);
+            const raw = await this.http.postJson('/tm/function/search', body);
+            const rows = pickArray(raw, 'data', 'content', 'functions');
+            const byId = new Map();
+            for (const r of rows) {
+                const rid = str(r, 'id', '_id', 'functionId');
+                if (!rid)
+                    continue;
+                byId.set(rid, { code: str(r, 'code'), name: str(r, 'name', 'title') ?? '' });
+            }
+            for (const s of tc.steps) {
+                if (s.stepType !== 'function' || !s.functionCall)
+                    continue;
+                const hit = byId.get(s.functionCall.testCaseId);
+                if (!hit)
+                    continue;
+                if (hit.code)
+                    s.functionCall.testCaseCode = hit.code;
+                if (hit.name)
+                    s.functionCall.testCaseName = hit.name;
+            }
+        }
+        catch {
+            // Non-fatal: fall back to bare id in the render.
+        }
+    }
+    /** 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. */
+    async hydrateObjectNames(tc) {
+        const ids = new Set();
+        for (const s of tc.steps) {
+            if (s.objectRef?.id && !s.objectRef.name)
+                ids.add(s.objectRef.id);
+        }
+        if (!ids.size)
+            return;
+        try {
+            const projectId = this.requireProjectId();
+            const body = this.searchBody([
+                { column: 'deleted', value: false },
+                { column: 'projectId', value: projectId },
+                { column: 'id', value: [...ids].map((x) => Number.parseInt(x, 10)).filter(Number.isFinite), regEx: false },
+            ]);
+            const raw = await this.http.postJson('/tm/object/search', body);
+            const rows = pickArray(raw, 'data', 'content', 'objects');
+            const byId = new Map();
+            for (const r of rows) {
+                const rid = str(r, 'id', '_id');
+                if (!rid)
+                    continue;
+                const name = str(r, 'disname', 'description', 'placeholder');
+                if (name)
+                    byId.set(rid, name);
+            }
+            for (const s of tc.steps) {
+                if (!s.objectRef?.id || s.objectRef.name)
+                    continue;
+                const name = byId.get(s.objectRef.id);
+                if (name)
+                    s.objectRef.name = name;
+            }
+        }
+        catch {
+            // Non-fatal: fall back to bare id in the render.
+        }
+    }
     // ---------------------------------------------------------------------- Suites (read)
     async listSuites() {
         const projectId = this.requireProjectId();
@@ -248,7 +620,7 @@ export class SimplifyQaAdapter {
         ]);
         const raw = await this.http.postJson('/tm/suites/search', body);
         const rows = pickArray(raw, 'data', 'content', 'suites');
-        return rows.map(toSuiteSummary);
+        return withTotal(rows.map(toSuiteSummary), raw);
     }
     async getSuite(id) {
         const raw = await this.http.getJson(`/tm/suites/${numericId(id)}`);
@@ -271,10 +643,21 @@ export class SimplifyQaAdapter {
             fields.push({ column: 'iterationId', value: Number.parseInt(q.sprintId, 10) });
         if (q.releaseId)
             fields.push({ column: 'releaseId', value: Number.parseInt(q.releaseId, 10) });
+        const createdBy = this.resolveUserFilter(q.createdBy);
+        if (createdBy != null)
+            fields.push({ column: 'createdBy', value: createdBy });
+        const updatedBy = this.resolveUserFilter(q.updatedBy);
+        if (updatedBy != null)
+            fields.push({ column: 'updatedBy', value: updatedBy });
+        const ownerId = this.resolveUserFilter(q.ownerId);
+        if (ownerId != null)
+            fields.push({ column: 'ownerId', value: ownerId });
+        if (q.filters?.length)
+            fields.push(...q.filters);
         const body = this.searchBody(fields, { limit: q.limit ?? 50 });
         const raw = await this.http.postJson('/pm/userstory/search', body);
         const rows = pickArray(raw, 'data', 'content', 'userStories', 'stories');
-        return rows.map(toStorySummary);
+        return withTotal(rows.map(toStorySummary), raw);
     }
     async getStory(id) {
         const resolvedId = await this.resolveStoryNumericId(id);
@@ -298,16 +681,314 @@ export class SimplifyQaAdapter {
             throw new Error(`Story not found for business key: ${ref}`);
         return str(rows[0], 'id', '_id', 'userstoryId') ?? ref;
     }
+    // ---------------------------------------------------------------------- Defects (read)
+    /** `POST /pm/defect/search` — same searchFields protocol as userstory/testcase search. */
+    async listDefects(q) {
+        const projectId = this.requireProjectId();
+        const fields = [
+            { column: 'deleted', value: false },
+            { column: 'projectId', value: projectId },
+        ];
+        if (q.search)
+            fields.push({ column: 'name', value: q.search, regEx: true });
+        if (q.tcId)
+            fields.push({ column: 'selectedTestCase.testcaseId', value: [Number.parseInt(numericId(q.tcId), 10)] });
+        if (q.storyId)
+            fields.push({ column: 'userstoryId', value: Number.parseInt(numericId(q.storyId), 10) });
+        if (q.state)
+            fields.push({ column: 'state', value: q.state });
+        // ownerId is an array field — match with Mongo $in, not bare equality.
+        const assignedTo = this.resolveUserFilter(q.assignedTo);
+        if (assignedTo != null)
+            fields.push({ column: 'ownerId', value: { $in: [assignedTo] } });
+        const createdBy = this.resolveUserFilter(q.createdBy);
+        if (createdBy != null)
+            fields.push({ column: 'createdBy', value: createdBy });
+        if (q.filters?.length)
+            fields.push(...q.filters);
+        const body = this.searchBody(fields, { limit: q.limit ?? 50, startIndex: q.offset ?? 0 });
+        const raw = await this.http.postJson('/pm/defect/search', body);
+        const rows = pickArray(raw, 'data', 'content', 'defects');
+        return withTotal(rows.map(toDefectSummary), raw);
+    }
+    // ---------------------------------------------------------------------- Tasks (read)
+    /** `POST /pm/task/search` — same searchFields protocol as defect/userstory search. */
+    async listTasks(q) {
+        const projectId = this.requireProjectId();
+        const fields = [
+            { column: 'deleted', value: false },
+            { column: 'projectId', value: projectId },
+        ];
+        if (q.search)
+            fields.push({ column: 'name', value: q.search, regEx: true });
+        if (q.storyId)
+            fields.push({ column: 'userstoryId', value: Number.parseInt(numericId(q.storyId), 10) });
+        if (q.state)
+            fields.push({ column: 'state', value: q.state });
+        const assignedTo = this.resolveUserFilter(q.assignedTo);
+        if (assignedTo != null)
+            fields.push({ column: 'ownerId', value: { $in: [assignedTo] } });
+        const createdBy = this.resolveUserFilter(q.createdBy);
+        if (createdBy != null)
+            fields.push({ column: 'createdBy', value: createdBy });
+        if (q.filters?.length)
+            fields.push(...q.filters);
+        const body = this.searchBody(fields, { limit: q.limit ?? 50, startIndex: q.offset ?? 0 });
+        const raw = await this.http.postJson('/pm/task/search', body);
+        const rows = pickArray(raw, 'data', 'content', 'tasks');
+        return withTotal(rows.map(toTaskSummary), raw);
+    }
+    // ---------------------------------------------------------------------- Stories (write)
+    async createStory(input) {
+        const body = {
+            ...input,
+            // SQA userstory expects a singular numeric projectId; fill from the connected project when omitted.
+            projectId: input.projectId ?? this.requireProjectId(),
+        };
+        const raw = await this.http.postJson('/pm/userstory', body);
+        return toSavedRef(raw, true);
+    }
+    async updateStory(id, patch) {
+        const resolvedId = await this.resolveStoryNumericId(id);
+        const raw = await this.http.putJson(`/pm/userstory/${resolvedId}`, patch);
+        return toSavedRef(raw ?? { id: resolvedId }, false);
+    }
+    // ---------------------------------------------------------------------- Epics
+    async listEpics(q) {
+        const projectId = this.requireProjectId();
+        const fields = [
+            { column: 'deleted', value: false },
+            // Epic is multi-project in SQA — filter for members of the current project via $in.
+            { column: 'projectIds', value: projectId },
+        ];
+        if (q.search)
+            fields.push({ column: 'name', value: q.search, regEx: true });
+        if (q.state)
+            fields.push({ column: 'state', value: q.state });
+        const createdBy = this.resolveUserFilter(q.createdBy);
+        if (createdBy != null)
+            fields.push({ column: 'createdBy', value: createdBy });
+        const updatedBy = this.resolveUserFilter(q.updatedBy);
+        if (updatedBy != null)
+            fields.push({ column: 'updatedBy', value: updatedBy });
+        const ownerId = this.resolveUserFilter(q.ownerId);
+        if (ownerId != null)
+            fields.push({ column: 'ownerId', value: ownerId });
+        const body = this.searchBody(fields, {
+            startIndex: q.offset ?? 0,
+            limit: q.limit ?? 50,
+        });
+        const raw = await this.http.postJson('/pm/epic/search', body);
+        const rows = pickArray(raw, 'data', 'content', 'epics');
+        return withTotal(rows.map(toEpicSummary), raw);
+    }
+    async getEpic(id) {
+        const resolvedId = await this.resolveEpicNumericId(id);
+        const raw = await this.http.getJson(`/pm/epic/${resolvedId}`);
+        const doc = Array.isArray(raw)
+            ? (raw.length > 0 ? raw[0] : {})
+            : (raw?.data && typeof raw.data === 'object' ? raw.data : raw);
+        return toEpic(doc && typeof doc === 'object' ? doc : {});
+    }
+    async createEpic(input) {
+        const body = {
+            ...input,
+            projectIds: input.projectIds ?? [this.requireProjectId()],
+        };
+        const raw = await this.http.postJson('/pm/epic', body);
+        return toSavedRef(raw, true);
+    }
+    async updateEpic(id, patch) {
+        const resolvedId = await this.resolveEpicNumericId(id);
+        const raw = await this.http.putJson(`/pm/epic/${resolvedId}`, patch);
+        return toSavedRef(raw ?? { id: resolvedId }, false);
+    }
+    /** EP_XXX business key → numeric epic id via `/pm/epic/search`. Numeric passes through. */
+    async resolveEpicNumericId(ref) {
+        if (!ref)
+            return ref;
+        if (/^\d+$/.test(ref))
+            return ref;
+        const body = this.searchBody([{ column: 'code', value: ref }], { startIndex: 0, limit: 1 });
+        const raw = await this.http.postJson('/pm/epic/search', body);
+        const rows = pickArray(raw, 'data', 'content', 'epics');
+        if (rows.length === 0)
+            throw new Error(`Epic not found for business key: ${ref}`);
+        return str(rows[0], 'id', '_id', 'epicId') ?? ref;
+    }
+    // ---------------------------------------------------------------------- Features
+    async listFeatures(q) {
+        const projectId = this.requireProjectId();
+        const fields = [
+            { column: 'deleted', value: false },
+            { column: 'projectIds', value: projectId },
+        ];
+        if (q.search)
+            fields.push({ column: 'name', value: q.search, regEx: true });
+        if (q.state)
+            fields.push({ column: 'state', value: q.state });
+        if (q.epicId)
+            fields.push({ column: 'epicId', value: Number.parseInt(q.epicId, 10) });
+        const createdBy = this.resolveUserFilter(q.createdBy);
+        if (createdBy != null)
+            fields.push({ column: 'createdBy', value: createdBy });
+        const updatedBy = this.resolveUserFilter(q.updatedBy);
+        if (updatedBy != null)
+            fields.push({ column: 'updatedBy', value: updatedBy });
+        const ownerId = this.resolveUserFilter(q.ownerId);
+        if (ownerId != null)
+            fields.push({ column: 'ownerId', value: ownerId });
+        const body = this.searchBody(fields, {
+            startIndex: q.offset ?? 0,
+            limit: q.limit ?? 50,
+        });
+        const raw = await this.http.postJson('/pm/feature/search', body);
+        const rows = pickArray(raw, 'data', 'content', 'features');
+        return withTotal(rows.map(toFeatureSummary), raw);
+    }
+    async getFeature(id) {
+        const resolvedId = await this.resolveFeatureNumericId(id);
+        const raw = await this.http.getJson(`/pm/feature/${resolvedId}`);
+        const doc = Array.isArray(raw)
+            ? (raw.length > 0 ? raw[0] : {})
+            : (raw?.data && typeof raw.data === 'object' ? raw.data : raw);
+        return toFeature(doc && typeof doc === 'object' ? doc : {});
+    }
+    async createFeature(input) {
+        const body = {
+            ...input,
+            projectIds: input.projectIds ?? [this.requireProjectId()],
+        };
+        const raw = await this.http.postJson('/pm/feature', body);
+        return toSavedRef(raw, true);
+    }
+    async updateFeature(id, patch) {
+        const resolvedId = await this.resolveFeatureNumericId(id);
+        const raw = await this.http.putJson(`/pm/feature/${resolvedId}`, patch);
+        return toSavedRef(raw ?? { id: resolvedId }, false);
+    }
+    /** FT_XXX business key → numeric feature id via `/pm/feature/search`. Numeric passes through. */
+    async resolveFeatureNumericId(ref) {
+        if (!ref)
+            return ref;
+        if (/^\d+$/.test(ref))
+            return ref;
+        const body = this.searchBody([{ column: 'code', value: ref }], { startIndex: 0, limit: 1 });
+        const raw = await this.http.postJson('/pm/feature/search', body);
+        const rows = pickArray(raw, 'data', 'content', 'features');
+        if (rows.length === 0)
+            throw new Error(`Feature not found for business key: ${ref}`);
+        return str(rows[0], 'id', '_id', 'featureId') ?? ref;
+    }
     // ---------------------------------------------------------------------- Modules, releases, sprints
     async listModules() {
         const projectId = this.requireProjectId();
         const body = this.searchBody([
             { column: 'projectId', value: projectId },
             { column: 'deleted', value: false },
-        ], { selectFields: ['id', 'code', 'name', 'parentId'], limit: 10000 });
+        ], { selectFields: ['id', 'code', 'name', 'parentId'] });
         const raw = await this.http.postJson('/pm/module/search', body);
         const rows = pickArray(raw, 'data', 'content', 'modules');
-        return rows.map(toModuleSummary);
+        return withTotal(rows.map(toModuleSummary), raw);
+    }
+    /** GET /pm/module/:id — server returns an array; empty array → NotFound. */
+    async getModule(id) {
+        const raw = await this.http.getJson(`/pm/module/${numericId(id)}`);
+        const rows = Array.isArray(raw) ? raw : pickArray(raw, 'data', 'content');
+        const doc = rows[0];
+        if (!doc)
+            throw new Error(`Module ${id} not found.`);
+        const summary = toModuleSummary(doc);
+        const code = str(doc, 'code');
+        const description = str(doc, 'description');
+        const projectId = doc?.projectId != null ? String(doc.projectId) : undefined;
+        const childIds = Array.isArray(doc?.childIds)
+            ? doc.childIds.filter((n) => Number.isFinite(n))
+            : undefined;
+        const isRoot = typeof doc?.isRoot === 'boolean' ? doc.isRoot : undefined;
+        return {
+            ...summary,
+            ...(code ? { code } : {}),
+            ...(description ? { description } : {}),
+            ...(childIds ? { childIds } : {}),
+            ...(projectId ? { projectId } : {}),
+            ...(isRoot !== undefined ? { isRoot } : {}),
+        };
+    }
+    /** POST /pm/module — server validates: name+isRoot+projectId required; parentId ignored when
+     *  isRoot:true. Duplicate name per project is rejected server-side. */
+    async createModule(input) {
+        const payload = {
+            name: input.name,
+            isRoot: input.isRoot,
+            projectId: Number.parseInt(input.projectId, 10),
+        };
+        if (input.description)
+            payload['description'] = input.description;
+        if (!input.isRoot && input.parentId)
+            payload['parentId'] = Number.parseInt(input.parentId, 10);
+        const raw = await this.http.postJson('/pm/module', payload);
+        return toSavedRef(raw, true);
+    }
+    /** 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`
+     *  triggers the actual delete: server drops only ids with EMPTY dependencies; ids with references are
+     *  silently skipped — we still return that list so the caller can act on it.
+     *  ponytail: one method, `confirm` flag; mirrors the backend's two-call contract. */
+    async deleteModule(input) {
+        const numIds = input.ids.map((id) => Number.parseInt(numericId(id), 10));
+        const projectId = Number.parseInt(input.projectId, 10);
+        const isDelete = input.confirm === true;
+        const raw = await this.http.patchJson('/pm/module', { ids: numIds, projectId, isDelete });
+        const arr = Array.isArray(raw) ? raw : pickArray(raw, 'data', 'content');
+        const dependencies = arr
+            .filter((r) => r && typeof r === 'object')
+            .map((r) => ({
+            id: Number(r.id),
+            tcArr: Array.isArray(r.tcArr) ? r.tcArr : [],
+            fnArr: Array.isArray(r.fnArr) ? r.fnArr : [],
+            parameterArr: Array.isArray(r.parameterArr) ? r.parameterArr : [],
+            objArr: Array.isArray(r.objArr) ? r.objArr : [],
+            defectArr: Array.isArray(r.defectArr) ? r.defectArr : [],
+            usArr: Array.isArray(r.usArr) ? r.usArr : [],
+        }));
+        return { dryRun: !isDelete, dependencies };
+    }
+    /** PUT /tm/tcfnversion/delete — soft-delete ONE version of a TC or FN. Two-phase per
+     *  tcfnversion.service.js:30 — `isDelete:false` (or `isDelete:true` with non-empty deps) →
+     *  returns the dependency array unchanged; `isDelete:true` with EMPTY deps → soft-deletes the
+     *  tcfn_version row + its steps + testdata + testdata iterations.
+     *
+     *  ponytail: one method, `confirm` flag. Response shape decides `deleted`: if every dep row is
+     *  fully empty (all `*Arr` are `{}` maps), the server actually deleted; otherwise it refused
+     *  and just handed back the deps. We do not assume — we inspect. */
+    async deleteVersion(input) {
+        const projectId = this.requireProjectId();
+        const parentType = input.kind === 'tc' ? 'TC' : 'FN';
+        const isDelete = input.confirm === true;
+        const body = {
+            id: input.versionId,
+            parentId: Number.parseInt(numericId(input.parentId), 10),
+            parentType,
+            projectId,
+            name: input.versionName,
+            isDelete,
+        };
+        const raw = await this.http.putJson('/tm/tcfnversion/delete', body);
+        const data = raw?.data ?? raw;
+        // Distinguish "dep array" from "delete result": the service returns an ARRAY of dep rows for
+        // the dry-run + refused-delete branches, and a single mongo doc (findOneAndUpdate result) for
+        // the successful delete branch. Array → parse deps; single doc → deleted.
+        if (Array.isArray(data)) {
+            const dependencies = data
+                .filter((r) => r && typeof r === 'object')
+                .map((r) => normalizeVersionDep(r, parentType));
+            const hasBlockers = dependencies.some((d) => !versionDepIsEmpty(d));
+            return { dryRun: !isDelete, deleted: false, dependencies, hasBlockers };
+        }
+        // Single doc → successful delete (or upsert-echo when nothing matched, but the service only
+        // reaches that branch after emptyIds.push).
+        return { dryRun: false, deleted: true, dependencies: [], hasBlockers: false };
     }
     async listReleases(q) {
         const fields = [{ column: 'deleted', value: false }];
@@ -316,7 +997,7 @@ export class SimplifyQaAdapter {
         const body = this.searchBody(fields);
         const raw = await this.http.postJson('/pm/release/search', body);
         const rows = pickArray(raw, 'data', 'content', 'releases');
-        return rows.map(toReleaseSummary);
+        return withTotal(rows.map(toReleaseSummary), raw);
     }
     async listSprints(q) {
         const fields = [{ column: 'deleted', value: false }];
@@ -325,7 +1006,41 @@ export class SimplifyQaAdapter {
         const body = this.searchBody(fields);
         const raw = await this.http.postJson('/pm/sprint/search', body);
         const rows = pickArray(raw, 'data', 'content', 'sprints');
-        return rows.map(toSprintSummary);
+        return withTotal(rows.map(toSprintSummary), raw);
+    }
+    /** POST /pm/users/search — the customer's users (router mounted at `/pm/users`, plural — see
+     *  project-management/express-app.js:181). Backend auto-scopes non-admin callers to users in
+     *  their assigned projects. Optional `projectId` narrows to that project's members; optional
+     *  `search` is a case-insensitive regex over `name`. */
+    async listUsers(q) {
+        const fields = [
+            { column: 'deleted', value: false },
+        ];
+        if (q.search)
+            fields.push({ column: 'name', value: q.search, regEx: true });
+        if (q.projectId)
+            fields.push({ column: 'projectIds', value: Number.parseInt(q.projectId, 10) });
+        const body = this.searchBody(fields, {
+            startIndex: q.offset ?? 0,
+            limit: q.limit ?? 100,
+            selectFields: ['id', 'name', 'email', 'username', 'status'],
+        });
+        const raw = await this.http.postJson('/pm/users/search', body);
+        const rows = pickArray(raw, 'data', 'content', 'users');
+        const users = rows.map((n) => {
+            const name = str(n, 'name');
+            const email = str(n, 'email');
+            const username = str(n, 'username');
+            const status = str(n, 'status');
+            return {
+                id: str(n, 'id', '_id', 'userId') ?? '',
+                ...(name ? { name } : {}),
+                ...(email ? { email } : {}),
+                ...(username ? { username } : {}),
+                ...(status ? { status } : {}),
+            };
+        });
+        return withTotal(users, raw);
     }
     // ---------------------------------------------------------------------- Objects (read)
     async getObject(id) {
@@ -373,48 +1088,908 @@ export class SimplifyQaAdapter {
     }
     // ---------------------------------------------------------------------- Test cases (write)  [Step 4]
     /** Two-step create: (1) resolve every `${name}` token in the steps to a project-scoped parameter id
-     *  (get-or-create), (2) POST /tm/testcase multipart with the assembled `testcaseObj`. */
+     *  (get-or-create) plus, for AUTOMATION, each step's actionId + objectId, (2) POST /tm/testcase
+     *  multipart with the assembled `testcaseObj`. */
     async createTestCase(tc) {
         const projectId = this.requireProjectId();
         const moduleId = Number.parseInt(String(tc.folderOrModule ?? '0'), 10) || 0;
         const userstoryId = tc.storyRef ? await this.resolveStoryNumericIdOrNull(tc.storyRef) : undefined;
         const paramIdByName = await this.resolveParamIds(projectId, moduleId, tc);
+        const stepResolutions = tc.category === 'automated'
+            ? await this.resolveAutomationSteps(projectId, moduleId, tc)
+            : undefined;
         const payload = buildTestcasePayload({
             projectId, moduleId,
             ...(userstoryId != null ? { userstoryId } : {}),
             tc,
             paramIdByName,
-            operation: 'CREATE',
+            ...(stepResolutions ? { stepResolutions } : {}),
         });
         const raw = await this.http.postMultipart('/tm/testcase', 'testcaseObj', payload);
         return toSavedRef(raw, true);
     }
-    /** Same shape as create, but with `tcfnObj.id` set and operation:'UPDATE'. */
+    /** Same shape as create, but with `tcfnObj.id` set. */
     async updateTestCase(id, tc) {
         const projectId = this.requireProjectId();
         const moduleId = Number.parseInt(String(tc.folderOrModule ?? '0'), 10) || 0;
         const userstoryId = tc.storyRef ? await this.resolveStoryNumericIdOrNull(tc.storyRef) : undefined;
         const paramIdByName = await this.resolveParamIds(projectId, moduleId, tc);
+        const stepResolutions = tc.category === 'automated'
+            ? await this.resolveAutomationSteps(projectId, moduleId, tc)
+            : undefined;
         const payload = buildTestcasePayload({
             projectId, moduleId,
             ...(userstoryId != null ? { userstoryId } : {}),
             existingId: numericId(id),
             tc,
             paramIdByName,
-            operation: 'UPDATE',
+            ...(stepResolutions ? { stepResolutions } : {}),
         });
         // `!` — putMultipart is optional on QaHttp (walnut's wrapper opts out); makeClient always provides it.
         const raw = await this.http.putMultipart('/tm/testcase', 'testcaseObj', payload);
         return toSavedRef(raw, false);
     }
-    /** Soft-delete (recoverable via recycle bin). `isDelete:true` = delete; `false` = restore. */
+    /** Snapshot the CURRENT server state of a testcase under a NEW version name — same TC id,
+     *  new `tcfn_version` row with cloned steps. Backed by `PUT /tm/testcase` with
+     *  `operation:"SAVENEWVERSION"` (see tcfn.service.js:115/242/355 for the branches). The steps
+     *  we fetch from the collection are re-POSTed with their `id` stripped so the backend inserts
+     *  fresh rows attached to the new version. When `tdCopy` is true, the source version's
+     *  testdata iterations are cloned across environments via `verData.selVersionId`.
+     *
+     *  Not a mapper roundtrip: we resend the raw tcfnObj/steps we just fetched, so any fields the
+     *  neutral `TestCase` type doesn't carry (custom fields, mailers, exec platform, ...) are
+     *  preserved verbatim — the point of a version is "freeze what's there now". */
+    async saveAsNewVersion(id, opts) {
+        assertBusinessKeyKind(id, 'TC');
+        const projectId = this.requireProjectId();
+        const versionName = opts.versionName?.trim();
+        if (!versionName)
+            throw new Error('versionName is required.');
+        const rawTc = await this.fetchRawTestcase(id);
+        if (!rawTc || Object.keys(rawTc).length === 0) {
+            throw new Error(`test case ${id} not found`);
+        }
+        // Resolve source version: caller override → current versionId on the TC → versionsDetails.id
+        // → first entry in versions[]. Falls through to '' (empty) if none — backend then skips tdCopy.
+        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');
+            }
+        }
+        const rawSteps = await this.fetchStepsCollection(id, rawTc);
+        const automationSteps = [];
+        const manualSteps = [];
+        for (const s of rawSteps) {
+            // Project down to the step joi allow-list (testcaseValidator.js:244-306 + :307-367). Backend
+            // re-assigns id/versionId/parentId under the new version row, so drop those regardless.
+            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);
+        }
+        // Project down to the tcfnObj joi allow-list (testcaseValidator.js:189-227). Anything else on
+        // the raw doc (code, createdBy, updatedBy, stepCount, etc.) trips "is not allowed".
+        const tcfnObj = pick(rawTc, TCFNOBJ_ALLOWED_KEYS);
+        tcfnObj['deleted'] = false;
+        tcfnObj['projectId'] = typeof tcfnObj['projectId'] === 'number' ? tcfnObj['projectId'] : projectId;
+        // Required-but-boolean fields on the update schema. Coerce so the presence is guaranteed.
+        if (typeof tcfnObj['obsolete'] !== 'boolean')
+            tcfnObj['obsolete'] = false;
+        // Version stub: empty `id` tells the backend to create a fresh row. SYNCOFF normalised to
+        // '' matches the FE (testcase.component.ts:1399) — it's a client-side "don't inherit"
+        // marker, not a server value.
+        const prevSync = rawTc?.versionsDetails && typeof rawTc.versionsDetails === 'object'
+            ? str(rawTc.versionsDetails, 'syncONOFF')
+            : undefined;
+        const versionsDetails = {
+            name: versionName,
+            id: '',
+            syncONOFF: prevSync === 'SYNCOFF' ? '' : (prevSync ?? ''),
+            deleted: false,
+            executionType: str(rawTc, 'executionType') ?? 'AUTOMATION',
+            functionProjectIds: [projectId],
+            reviewApproveStatus: '',
+        };
+        const verData = {
+            tdCopy: !!opts.tdCopy,
+            ...(sourceVersionId ? { selVersionId: sourceVersionId } : {}),
+        };
+        const payload = {
+            tcfnObj,
+            steps: { automationSteps, manualSteps },
+            versionsDetails,
+            operation: 'SAVENEWVERSION',
+            type: 'TC',
+            verData,
+        };
+        const raw = await this.http.putMultipart('/tm/testcase', 'testcaseObj', payload);
+        const flat = raw?.data ?? raw ?? {};
+        const savedId = str(flat, 'id', '_id', 'testcaseId') ?? numericId(id);
+        const newVersionId = str(flat, 'versionId') ??
+            (flat?.versionsDetails && typeof flat.versionsDetails === 'object'
+                ? str(flat.versionsDetails, 'id')
+                : undefined);
+        return {
+            id: savedId,
+            created: false,
+            productUrl: this.productUrlFor({ kind: 'testcase', id: savedId }),
+            ...(newVersionId ? { artifacts: [`versionId=${newVersionId}`] } : {}),
+        };
+    }
+    /** STEPSTOFN — mirrors the FE "Save as function" flow (create-new-fn-modal.component.ts:88-197):
+     *  pick a subset of the TC's steps, retype to FN, POST /tm/function multipart with the
+     *  `functionObj` payload. Backend re-assigns step ids/versionId under the newly created FN version.
+     *
+     *  ponytail: file attachments (STEP_ATTACMENTS / STEP_COMAPAREFILES multipart entries) are NOT
+     *  forwarded — MCP callers don't ship blobs. Add if a real caller needs them.
+     *  ponytail: sub-step flattening (FE lines 124-127) is skipped — `/tm/testcase/steps` returns
+     *  flat top-level rows; nested FN expansions aren't in that read. Handle if that changes. */
+    async saveStepsAsFunction(tcId, opts) {
+        const projectId = this.requireProjectId();
+        const name = opts.name?.trim();
+        if (!name)
+            throw new Error('name is required.');
+        if (!opts.moduleId)
+            throw new Error('moduleId is required.');
+        const seqSet = new Set(opts.stepSeqs);
+        if (seqSet.size === 0)
+            throw new Error('stepSeqs is required.');
+        const rawTc = await this.fetchRawTestcase(tcId);
+        if (!rawTc || Object.keys(rawTc).length === 0) {
+            throw new Error(`test case ${tcId} not found`);
+        }
+        const sourceVersionId = opts.versionId ||
+            (str(rawTc, 'versionId', 'selectedVersionId') ??
+                (rawTc?.versionsDetails && typeof rawTc.versionsDetails === 'object'
+                    ? str(rawTc.versionsDetails, 'id', '_id', 'versionId')
+                    : undefined) ??
+                (Array.isArray(rawTc?.versions) && rawTc.versions.length > 0
+                    ? str(rawTc.versions[0], 'id', '_id')
+                    : undefined));
+        const rawSteps = await this.fetchStepsCollection(tcId, rawTc, opts.versionId);
+        const picked = rawSteps
+            .filter((s) => seqSet.has(Number(s.seq)))
+            .sort((a, b) => Number(a.seq) - Number(b.seq));
+        if (picked.length === 0) {
+            throw new Error(`no steps on ${tcId} match stepSeqs [${opts.stepSeqs.join(',')}]`);
+        }
+        const automationSteps = [];
+        const manualSteps = [];
+        let newSeq = 0;
+        for (const s of picked) {
+            const step = { ...s };
+            // Server-assigned refs stripped so backend re-creates them under the new FN version.
+            delete step.id;
+            delete step._id;
+            delete step.versionId;
+            delete step.parentId;
+            delete step.subSteps;
+            delete step.deleted;
+            delete step.isFunctionEdit;
+            delete step.sharedFNsteps;
+            delete step.sharedFnProjectId;
+            step.type = 'FN';
+            step.moduleId = opts.moduleId;
+            step.seq = ++newSeq;
+            // FE mirror (line 129-134): TM only accepts numeric parameterIds.
+            if (Array.isArray(step.parameterIds)) {
+                step.parameterIds = step.parameterIds.filter((p) => typeof p === 'number');
+            }
+            // FE mirror (line 136-150): shed conditional-step UI expansion.
+            if (step.conditions?.children?.length) {
+                for (const c of step.conditions.children) {
+                    delete c.groupedActions;
+                    delete c.stepActions;
+                    delete c.objectOfparameters;
+                    if (Array.isArray(c.parameterIds)) {
+                        c.parameterIds = c.parameterIds.filter((p) => typeof p === 'number');
+                    }
+                }
+            }
+            const forced = opts.executionType;
+            const bucket = forced
+                ?? (String(step.executionType ?? '').toUpperCase() === 'MANUAL' ? 'MANUAL' : 'AUTOMATION');
+            if (bucket === 'MANUAL')
+                manualSteps.push(step);
+            else
+                automationSteps.push(step);
+        }
+        // FE mirror (line 192): DUO iff both buckets populated.
+        const execType = automationSteps.length && manualSteps.length
+            ? 'DUO'
+            : manualSteps.length ? 'MANUAL' : 'AUTOMATION';
+        // FE mirror (line 271-276): all steps share technologyType → use that, else fall back to TC's.
+        const techs = new Set(picked.map((s) => str(s, 'technologyType')).filter(Boolean));
+        const fnType = techs.size === 1
+            ? [...techs][0]
+            : (str(rawTc, 'tcType') ?? 'WEB');
+        const tcfnObj = {
+            name,
+            projectId,
+            moduleId: opts.moduleId,
+            executionType: execType,
+            fnType,
+            reviewApproveStatus: '',
+        };
+        // FE default (function.model.ts:68) — backend requires versionsDetails.name.
+        const versionsDetails = { name: 'v1.0', id: '', syncONOFF: '' };
+        // testcaseId MUST be numeric here — tcfn.service.js:1124 uses it in a Mongo query
+        // against `testdata_iteration.testcaseId` (stored as a Number). A string "42" won't
+        // match `42`, so tdCopy silently returns zero source iterations. FE sends a number
+        // (create-new-fn-modal.component.ts:31 `@Input('tcfnId') _tcfnId: number`).
+        const verData = {
+            tdCopy: !!opts.copyTestData,
+            testcaseId: Number.parseInt(numericId(tcId), 10),
+            fromParent: 'TC',
+            ...(sourceVersionId ? { selVersionId: sourceVersionId } : {}),
+        };
+        const payload = {
+            tcfnObj,
+            steps: { automationSteps, manualSteps },
+            versionsDetails,
+            operation: 'STEPSTOFN',
+            type: 'FN',
+            verData,
+        };
+        const raw = await this.http.postMultipart('/tm/function', 'functionObj', payload);
+        return toSavedRef(raw, true);
+    }
+    /** Look up the freshly-created FN's version id — STEPSTOFN's response inlines the FN but not its
+     *  version, and the replace-in-TC step needs `fnVersionId`. Mirrors the FE
+     *  (`create-new-fn-modal.component.ts:getFnVersion`): search `tcfnversion` by parentType=FN
+     *  ordered by createdAt asc, take the first. */
+    async fetchFnVersionId(fnId) {
+        const projectId = this.requireProjectId();
+        const body = {
+            searchFields: [
+                { column: 'createdAt', sort: 'asc' },
+                { column: 'deleted', value: false, regEx: false },
+                { column: 'projectId', value: projectId, regEx: false },
+                { column: 'parentType', value: 'FN', regEx: false },
+                { column: 'parentId', value: Number.parseInt(numericId(fnId), 10), regEx: false },
+            ],
+            startIndex: 0,
+            limit: 10000,
+        };
+        const raw = await this.http.postJson('/tm/tcfnversion/search', body);
+        const rows = pickArray(raw, 'data', 'content');
+        const versionId = rows.length > 0 ? str(rows[0], 'id', '_id') : undefined;
+        if (!versionId)
+            throw new Error(`could not resolve fnVersionId for function ${fnId}`);
+        return versionId;
+    }
+    /** Second half of extract-to-function-and-replace-in-source (FE
+     *  `testcase.component.ts:createNewFns → onSave`): after the FN exists, PUT the source TC with the
+     *  extracted step rows marked `deleted:true` and a synthetic FUNCTION + FUNCTION_END pair inserted
+     *  at the first extracted position. The backend automatically:
+     *   - drops testdata columns for params only the deleted steps referenced (allParameters skips
+     *     `step.deleted:true` at tcfn.service.js:411)
+     *   - injects a per-env FN cell into every TC iteration row using the FN's default iteration
+     *     (tcfn.service.js:1032-1085) — so testdata rewiring is free.
+     *
+     *  ponytail: refuses DUO / SYNCON test cases and picks that span control-flow or nested FN
+     *  brackets. Those cases (v2) need parallel mirroring into the other execution-type array and
+     *  bracket-aware validation — out of scope for the first pass. */
+    async replaceStepsWithFunctionCall(tcId, opts) {
+        const projectId = this.requireProjectId();
+        const seqSet = new Set(opts.extractedSeqs);
+        if (seqSet.size === 0)
+            throw new Error('extractedSeqs is required.');
+        const sortedSeqs = [...seqSet].sort((a, b) => a - b);
+        // FE `checkStepsContinueOrNot`: picks must be a contiguous seq range or the resulting FN would
+        // be non-executable and the TC layout would fracture.
+        for (let i = 1; i < sortedSeqs.length; i++) {
+            if (sortedSeqs[i] !== sortedSeqs[i - 1] + 1) {
+                throw new Error(`extractedSeqs must be contiguous — got [${sortedSeqs.join(',')}]`);
+            }
+        }
+        const rawTc = await this.fetchRawTestcase(tcId);
+        if (!rawTc || Object.keys(rawTc).length === 0)
+            throw new Error(`test case ${tcId} not found`);
+        // `versionsDetailsRaw` reflects the TC's CURRENTLY-SELECTED version's inline details — only
+        // trustworthy when opts.versionId targets that same version (the common case). When targeting a
+        // DIFFERENT version, prefer that version's own row from rawTc.versions[] for name/executionType/
+        // reviewApproveStatus below; syncONOFF isn't carried per-version there, so it falls back to ''.
+        const versionsDetailsRaw = rawTc?.versionsDetails && typeof rawTc.versionsDetails === 'object' ? rawTc.versionsDetails : {};
+        const currentVersionId = str(rawTc, 'versionId', 'selectedVersionId') ?? str(versionsDetailsRaw, 'id', '_id', 'versionId');
+        const targetsCurrentVersion = !opts.versionId || opts.versionId === currentVersionId;
+        const versionMatch = Array.isArray(rawTc?.versions)
+            ? rawTc.versions.find((v) => str(v, 'id', '_id') === opts.versionId)
+            : undefined;
+        const execType = String((targetsCurrentVersion ? str(rawTc, 'executionType') : str(versionMatch, 'executionType')) ?? '').toUpperCase();
+        if (execType === 'DUO') {
+            throw new Error('DUO test cases are not yet supported for replaceInSource — split the extraction into AUTOMATION-only or MANUAL-only first.');
+        }
+        const syncOnOff = targetsCurrentVersion ? str(versionsDetailsRaw, 'syncONOFF') : undefined;
+        if (syncOnOff === 'SYNCON') {
+            throw new Error('SYNCON (mirrored automation/manual) test cases are not yet supported for replaceInSource.');
+        }
+        const sourceVersionId = opts.versionId ||
+            currentVersionId ||
+            (Array.isArray(rawTc?.versions) && rawTc.versions.length > 0
+                ? str(rawTc.versions[0], 'id', '_id')
+                : undefined);
+        if (!sourceVersionId)
+            throw new Error(`test case ${tcId} has no versionId — cannot save`);
+        const rawSteps = await this.fetchStepsCollection(tcId, rawTc, opts.versionId);
+        // Refuse picks that would break brackets. FUNCTION/FUNCTION_END pairs must not be half-picked;
+        // control-flow starts (IF/WHILE_START/FOR_START/…) must not span the range partially.
+        const CONTROL_TYPES = new Set([
+            'FUNCTION', 'FUNCTION_END', 'IF', 'ELSE_IF', 'ELSE', 'IF_END',
+            'FOR_START', 'FOR_END', 'WHILE_START', 'WHILE_END', 'DO', 'DO_WHILE_END',
+            'ITERATOR_START', 'ITERATOR_END', 'LOOP_ITERATION_START', 'LOOP_ITERATION_END',
+        ]);
+        for (const s of rawSteps) {
+            if (!seqSet.has(Number(s.seq)))
+                continue;
+            const t = String(s.stepType ?? '').toUpperCase();
+            if (CONTROL_TYPES.has(t)) {
+                throw new Error(`step seq ${s.seq} is a control-flow/FN bracket step (${t}) — extract a plain step range`);
+            }
+        }
+        const insertAt = sortedSeqs[0];
+        // Build the FUNCTION + FUNCTION_END pair. FE parent (testcase.component.ts:1953+1988-1994)
+        // overrides `type` from 'FN' to 'TC' before splicing — the FN-call lives inside a TC, so it's
+        // typed accordingly. `id`/`versionId` omitted so backend creates fresh rows.
+        const stepLevelActions = {
+            skip: false, captureScreenshot: false, continueOnFailure: false, skippedReport: false,
+        };
+        const fnCallStep = {
+            seq: insertAt,
+            stepType: 'FUNCTION',
+            type: 'TC',
+            functionId: Number.parseInt(numericId(opts.functionId), 10),
+            fnVersionId: opts.fnVersionId,
+            description: '',
+            projectId,
+            moduleId: opts.fnModuleId,
+            executionType: execType || 'AUTOMATION',
+            technologyType: opts.technologyType,
+            stepLevelActions,
+        };
+        const fnEndStep = {
+            seq: insertAt + 1,
+            stepType: 'FUNCTION_END',
+            type: 'TC',
+            projectId,
+            moduleId: opts.fnModuleId,
+            executionType: execType || 'AUTOMATION',
+            technologyType: opts.technologyType,
+            stepLevelActions,
+        };
+        // Kept steps: preserve id/versionId/parentId (this is an update, not a fresh save) and pass
+        // through as-is. Extracted steps: same, plus `deleted:true` — the backend's param collector
+        // (tcfn.service.js:411) skips deleted rows, so their paramIds automatically drop from the TC's
+        // rebuilt testdata columns. Do NOT strip parameterIds / objectParameterIds / parameterizedParamIds
+        // from the deleted rows — those are what `allParameters` compares against to know what to prune.
+        const kept = [];
+        const deleted = [];
+        for (const s of rawSteps) {
+            const step = { ...s };
+            delete step.subSteps; // transient — flat-only per the STEPSTOFN comment
+            if (seqSet.has(Number(step.seq))) {
+                step.deleted = true;
+                delete step.objectOfparameters; // FE mirror (testcase.component.ts:1272)
+                deleted.push(step);
+            }
+            else {
+                kept.push(step);
+            }
+        }
+        kept.sort((a, b) => Number(a.seq) - Number(b.seq));
+        // Splice fn-call pair at the insert position. seqs 1..N are re-assigned at the end so nothing
+        // downstream can misalign.
+        const afterInsert = kept.filter((k) => Number(k.seq) > sortedSeqs[sortedSeqs.length - 1]);
+        const beforeInsert = kept.filter((k) => Number(k.seq) < insertAt);
+        const orderedLive = [...beforeInsert, fnCallStep, fnEndStep, ...afterInsert];
+        let seq = 1;
+        for (const s of orderedLive) {
+            s.seq = seq++;
+        }
+        // Backend expects both automationSteps and manualSteps buckets. Live steps route by their
+        // executionType; deleted steps come along in their own bucket (FE mirror lines 1268-1284).
+        const automationSteps = [];
+        const manualSteps = [];
+        const bucketFor = (s) => {
+            const et = String(s?.executionType ?? '').toUpperCase();
+            return et === 'MANUAL' ? 'MANUAL' : 'AUTOMATION';
+        };
+        for (const s of orderedLive)
+            (bucketFor(s) === 'MANUAL' ? manualSteps : automationSteps).push(s);
+        for (const s of deleted)
+            (bucketFor(s) === 'MANUAL' ? manualSteps : automationSteps).push(s);
+        // tcfnObj: strict allow-list — extras trip the joi validator. Backend mirrors the FE's normal
+        // update PUT (testcase.component.ts:1376+1495): `operation:"TC"`, `type:"TC"`, same versionsDetails.
+        const tcfnObj = pick(rawTc, TCFNOBJ_ALLOWED_KEYS);
+        tcfnObj['deleted'] = false;
+        tcfnObj['id'] = Number.parseInt(numericId(tcId), 10);
+        tcfnObj['projectId'] = typeof tcfnObj['projectId'] === 'number' ? tcfnObj['projectId'] : projectId;
+        if (typeof tcfnObj['obsolete'] !== 'boolean')
+            tcfnObj['obsolete'] = false;
+        // Backend joi validator refuses an empty versionsDetails.name (BADREQUEST from /tm/testcase).
+        // `versionsDetailsRaw` only describes the CURRENT version — when targeting a different one,
+        // its name/reviewApproveStatus belong to the wrong version, so prefer `versionMatch` instead.
+        // Fall back to 'v1.0' (the SQA default set by project.service.js) if nothing resolves.
+        const versionName = (targetsCurrentVersion ? str(versionsDetailsRaw, 'name') : undefined) ??
+            str(versionMatch, 'name') ??
+            'v1.0';
+        const reviewApproveStatus = (targetsCurrentVersion ? str(versionsDetailsRaw, 'reviewApproveStatus') : undefined) ??
+            str(versionMatch, 'reviewApproveStatus') ??
+            '';
+        const versionsDetails = {
+            name: versionName,
+            id: sourceVersionId,
+            deleted: false,
+            syncONOFF: syncOnOff ?? '',
+            executionType: execType || 'AUTOMATION',
+            functionProjectIds: [projectId],
+            reviewApproveStatus,
+        };
+        const payload = {
+            tcfnObj,
+            steps: { automationSteps, manualSteps },
+            versionsDetails,
+            operation: 'TC',
+            type: 'TC',
+        };
+        const raw = await this.http.putMultipart('/tm/testcase', 'testcaseObj', payload);
+        const flat = raw?.data ?? raw ?? {};
+        const savedId = str(flat, 'id', '_id', 'testcaseId') ?? numericId(tcId);
+        return {
+            id: savedId,
+            created: false,
+            productUrl: this.productUrlFor({ kind: 'testcase', id: savedId }),
+        };
+    }
+    /** One-shot extract-to-function-and-replace. Chains STEPSTOFN → fetch fn version id → replace in
+     *  source TC. If step 2 or 3 fails after step 1 succeeded, the caller sees the fn id in the error
+     *  so they can retry or clean up the phantom function. */
+    async extractStepsAsFunctionAndReplace(tcId, opts) {
+        const fnRef = await this.saveStepsAsFunction(tcId, opts);
+        let fnVersionId;
+        try {
+            fnVersionId = await this.fetchFnVersionId(fnRef.id);
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            throw new Error(`Function ${fnRef.id} was created but its version lookup failed — the source TC was NOT modified. ${msg}`);
+        }
+        // Reuse tech detection from saveStepsAsFunction (same rule: single tech across picks → that
+        // tech, else fall back to the source TC's tcType).
+        const rawTc = await this.fetchRawTestcase(tcId);
+        const rawSteps = await this.fetchStepsCollection(tcId, rawTc, opts.versionId);
+        const picked = rawSteps.filter((s) => opts.stepSeqs.includes(Number(s.seq)));
+        const techs = new Set(picked.map((s) => str(s, 'technologyType')).filter(Boolean));
+        const technologyType = techs.size === 1 ? [...techs][0] : (str(rawTc, 'tcType') ?? 'WEB');
+        try {
+            const tcRef = await this.replaceStepsWithFunctionCall(tcId, {
+                extractedSeqs: opts.stepSeqs,
+                functionId: fnRef.id,
+                fnVersionId,
+                fnModuleId: opts.moduleId,
+                technologyType,
+                versionId: opts.versionId,
+            });
+            return { ...tcRef, fnId: fnRef.id, fnVersionId };
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            throw new Error(`Function ${fnRef.id} (version ${fnVersionId}) was created but replacing steps in ${tcId} failed — clean up the function or retry with tc_replace_steps_with_function. ${msg}`);
+        }
+    }
+    /** Soft-delete. `/tm/testcase/delete` returns HTTP 200 either way — its `data` is `true` on real
+     *  delete, or an array of dependency records when the TC is still referenced by a defect, suite,
+     *  execution plan, scenario, workflow, pipeline, or scheduler (nothing was deleted). Inspect the
+     *  shape and throw so the tool surfaces it as a failure instead of a fake success. */
     async deleteTestCase(id) {
         const projectId = this.requireProjectId();
-        await this.http.postJson('/tm/testcase/delete', {
+        const raw = await this.http.postJson('/tm/testcase/delete', {
             ids: [Number.parseInt(numericId(id), 10)],
             projectId,
             isDelete: true,
         });
+        const data = raw?.data;
+        if (data === true)
+            return;
+        const deps = Array.isArray(data) ? data[0] : undefined;
+        const list = (m) => m && typeof m === 'object' ? Object.values(m).flat().map(String) : [];
+        const refs = [];
+        const groups = [
+            ['defectArr', 'defects'], ['suiteArr', 'suites'], ['epArr', 'execution plans'],
+            ['scenarioArr', 'scenarios'], ['wfArr', 'workflows'], ['pipelineArr', 'pipelines'],
+            ['schedulerArr', 'schedulers'],
+        ];
+        for (const [key, label] of groups) {
+            const ids = list(deps?.[key]);
+            if (ids.length)
+                refs.push(`${label} (${ids.join(', ')})`);
+        }
+        throw new Error(refs.length
+            ? `Not deleted — test case is still referenced by ${refs.join('; ')}. Remove those references first.`
+            : 'Not deleted — the backend reported blocking dependencies.');
+    }
+    /** 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) {
+        assertBusinessKeyKind(id, 'TC');
+        const projectId = this.requireProjectId();
+        const src = await this.fetchRawTestcase(id);
+        if (!src || Object.keys(src).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();
+        }
+        return {
+            id: String(newIdNum),
+            created: true,
+            productUrl: this.productUrlFor({ kind: 'testcase', id: String(newIdNum) }),
+        };
+    }
+    // ---------------------------------------------------------------------- Functions (reusable)
+    // Same tcfnObj collection as testcases — type='FN' instead of 'TC'. Search / getById / delete /
+    // steps all mirror the testcase endpoints one-to-one.
+    async listFunctions(q) {
+        const projectId = this.requireProjectId();
+        const fields = [
+            { column: 'deleted', value: false },
+            { column: 'projectId', value: projectId },
+        ];
+        if (q.search)
+            fields.push({ column: 'name', value: q.search, regEx: true });
+        if (q.fnType)
+            fields.push({ column: 'fnType', value: q.fnType });
+        if (q.executionType)
+            fields.push({ column: 'executionType', value: q.executionType });
+        if (q.moduleId)
+            fields.push({ column: 'moduleId', value: Number.parseInt(numericId(q.moduleId), 10) });
+        const createdBy = this.resolveUserFilter(q.createdBy);
+        if (createdBy != null)
+            fields.push({ column: 'createdBy', value: createdBy });
+        const updatedBy = this.resolveUserFilter(q.updatedBy);
+        if (updatedBy != null)
+            fields.push({ column: 'updatedBy', value: updatedBy });
+        const body = this.searchBody(fields, {
+            startIndex: q.offset ?? 0,
+            limit: q.limit ?? 100,
+            selectFields: ['id', 'code', 'name', 'description', 'fnType', 'executionType',
+                'reviewApproveStatus', 'stepCount'],
+        });
+        const raw = await this.http.postJson('/tm/function/search', body);
+        const rows = pickArray(raw, 'data', 'content', 'functions');
+        return withTotal(rows.map(toFunctionSummary), raw);
+    }
+    async getFunction(id) {
+        const projectId = this.requireProjectId();
+        const fnNum = numericId(id);
+        const raw = await this.http.getJson(`/tm/function/${fnNum}/${projectId}`);
+        let doc = raw?.data ?? raw;
+        if (Array.isArray(doc))
+            doc = doc.length > 0 ? doc[0] : {};
+        if (!doc || typeof doc !== 'object' || Object.keys(doc).length === 0) {
+            throw new Error(`function ${id} not found`);
+        }
+        const fn = toFunction(doc);
+        // Fetch version rows ONCE — reused to (a) pick the newest for the steps call and (b) hydrate
+        // `fn.versions` for the caller. The FN doc from `/tm/function/:id/:pid` has NO inline versions[]
+        // (unlike TC's getById), so this sibling endpoint is the only source. Non-fatal on failure.
+        let versionRows = [];
+        try {
+            versionRows = await this.fetchFunctionVersionRows(fnNum);
+        }
+        catch { /* leave empty */ }
+        const currentVersionId = versionRows.length
+            ? str(versionRows[0], 'id', '_id', 'versionId')
+            : undefined;
+        if (versionRows.length)
+            fn.versions = toVersionEntries(versionRows, currentVersionId);
+        if (currentVersionId) {
+            try {
+                const rows = await this.fetchFunctionStepsForVersion(fnNum, currentVersionId);
+                if (rows.length > 0)
+                    fn.steps = rows.map((s, i) => fromSqaStep(s, i + 1));
+            }
+            catch { /* leave steps empty */ }
+        }
+        return fn;
+    }
+    /** Steps for one FN version. Unlike TC docs, the FN doc from `/tm/function/:id/:projectId`
+     *  doesn't carry a versionId inline — callers resolve the target versionId (usually the newest,
+     *  from `fetchFunctionVersionRows`) and pass it here. */
+    async fetchFunctionStepsForVersion(fnNum, versionId) {
+        const projectId = this.requireProjectId();
+        const path = '/tm/function/steps' +
+            `?projectId=${projectId}` +
+            `&tcfnId=${fnNum}` +
+            `&versionId=${encodeURIComponent(versionId)}` +
+            '&type=FN';
+        const body = await this.http.getJson(path);
+        return Array.isArray(body) ? body : Array.isArray(body?.data) ? body.data : [];
+    }
+    /** The function's version rows, newest-first. */
+    async fetchFunctionVersionRows(fnNum) {
+        const projectId = this.requireProjectId();
+        const raw = await this.http.getJson(`/tm/function/version/${fnNum}/${projectId}`);
+        const rows = pickArray(raw, 'data', 'content', 'versions');
+        if (!rows.length)
+            return [];
+        return [...rows].sort((a, b) => Number(b?.versionNumber ?? 0) - Number(a?.versionNumber ?? 0));
+    }
+    /** Soft-delete a function. `/tm/function/delete` returns HTTP 200 either way — its `data` is
+     *  `true` on real delete, or an array of dependency records when the FN is still referenced by a
+     *  TC / FN / workflow (nothing was deleted). Inspect the shape and throw so the tool surfaces it
+     *  as a failure instead of a fake success. */
+    async deleteFunction(id) {
+        const projectId = this.requireProjectId();
+        const raw = await this.http.postJson('/tm/function/delete', {
+            ids: [Number.parseInt(numericId(id), 10)],
+            projectId,
+            isDelete: true,
+        });
+        const data = raw?.data;
+        if (data === true)
+            return;
+        const deps = Array.isArray(data) ? data[0] : undefined;
+        const list = (m) => m && typeof m === 'object' ? Object.values(m).flat().map(String) : [];
+        const tcs = list(deps?.tcArr);
+        const fns = list(deps?.fnArr);
+        const wfs = list(deps?.wfArr);
+        const refs = [];
+        if (tcs.length)
+            refs.push(`test cases (${tcs.join(', ')})`);
+        if (fns.length)
+            refs.push(`functions (${fns.join(', ')})`);
+        if (wfs.length)
+            refs.push(`workflows (${wfs.join(', ')})`);
+        throw new Error(refs.length
+            ? `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) {
+        assertBusinessKeyKind(id, 'FN');
+        const projectId = this.requireProjectId();
+        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) {
+            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();
+        }
+        return {
+            id: String(newIdNum),
+            created: true,
+            productUrl: this.productUrlFor({ kind: 'function', id: String(newIdNum) }),
+        };
+    }
+    /** Snapshot the CURRENT server state of a function under a NEW version name — same FN id, new
+     *  `tcfn_version` row with cloned steps. Mirrors `saveAsNewVersion` (see there for the shape
+     *  rationale) with `type:'FN'` and the multipart route `PUT /tm/function` / key `functionObj`.
+     *  Source-version resolution goes through the FN's `/tm/function/version/:id/:pid` list — the
+     *  FN doc has no inline versionId. */
+    async saveAsNewFunctionVersion(id, opts) {
+        assertBusinessKeyKind(id, 'FN');
+        const projectId = this.requireProjectId();
+        const versionName = opts.versionName?.trim();
+        if (!versionName)
+            throw new Error('versionName is required.');
+        const fnNum = numericId(id);
+        const rawFn = await this.http.getJson(`/tm/function/${fnNum}/${projectId}`);
+        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`);
+        }
+        // FN doc has no inline versionId — resolve from the version list. Caller override wins.
+        let sourceVersionId = opts.sourceVersionId;
+        if (!sourceVersionId) {
+            const versionRows = await this.fetchFunctionVersionRows(fnNum);
+            if (versionRows.length > 0)
+                sourceVersionId = str(versionRows[0], 'id', '_id', 'versionId');
+        }
+        // Fetch steps under the resolved (or newest) version.
+        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;
+        // FN update joi REQUIRES `fnType` and REJECTS `obsolete`. Guarantee fnType from the raw doc
+        // (falls through to legacy `tcType` if a pre-migration FN row is missing fnType); never set
+        // obsolete.
+        if (typeof tcfnObj['fnType'] !== 'string' || !tcfnObj['fnType']) {
+            const fallback = str(rawTc, 'fnType', 'tcType') ?? 'WEB';
+            tcfnObj['fnType'] = fallback;
+        }
+        // Version stub mirrors function.component.ts:900-907 — empty id tells the backend to create a
+        // fresh row; SYNCOFF is normalised to '' the same way as the TC path. FN update joi REJECTS
+        // `functionProjectIds` (allowed on TC's versionsDetails but not FN's — see functionValidator.js
+        // updateFnBodyValidation.versionsDetails), so don't include it.
+        const prevSync = rawTc?.versionsDetails && typeof rawTc.versionsDetails === 'object'
+            ? str(rawTc.versionsDetails, 'syncONOFF')
+            : undefined;
+        const versionsDetails = {
+            name: versionName,
+            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: 'SAVENEWVERSION',
+            type: 'FN',
+            verData,
+        };
+        const raw = await this.http.putMultipart('/tm/function', 'functionObj', payload);
+        const flat = raw?.data ?? raw ?? {};
+        const savedId = str(flat, 'id', '_id', 'functionId', 'testcaseId') ?? fnNum;
+        const newVersionId = str(flat, 'versionId') ??
+            (flat?.versionsDetails && typeof flat.versionsDetails === 'object'
+                ? str(flat.versionsDetails, 'id')
+                : undefined);
+        return {
+            id: savedId,
+            created: false,
+            productUrl: this.productUrlFor({ kind: 'function', id: savedId }),
+            ...(newVersionId ? { artifacts: [`versionId=${newVersionId}`] } : {}),
+        };
     }
     /** Never throw on unresolvable storyRef — the Java code logs and moves on so the save still lands. */
     async resolveStoryNumericIdOrNull(storyRef) {
@@ -427,24 +2002,142 @@ export class SimplifyQaAdapter {
             return undefined;
         }
     }
-    /** Resolve every `${name}` token across every step to a SQA parameter id via get-or-create.
-     *  Name-uniqueness is project-wide on the backend; get-or-create means every TC using
-     *  `${appUrl}` links to the same parameter row. */
+    /** Resolve every param name referenced by the TC to a SQA parameter id via get-or-create.
+     *  Sources: (a) `${name}` tokens in every step's description (manual + automation), and
+     *  (b) keys of every automation step's `recordedParam` (action-argument names like
+     *  "packageName", "activity", "keys"). Name-uniqueness is project-wide on the backend, so
+     *  get-or-create means every TC using `${appUrl}` (or the same "packageName" recorded param)
+     *  links to the same parameter row. */
     async resolveParamIds(projectId, moduleId, tc) {
         const paramIdByName = new Map();
         const steps = Array.isArray(tc.steps) ? tc.steps : [];
         for (const s of steps) {
-            const names = extractParamNames(s.description);
-            for (const name of names) {
+            for (const name of extractParamNames(s.description)) {
                 if (paramIdByName.has(name))
                     continue;
                 const defaultValue = paramDefault(name, tc.data, s.value);
                 const id = await this.getOrCreateParameter(projectId, moduleId, name, defaultValue);
                 paramIdByName.set(name, id);
             }
+            if (s.recordedParam) {
+                for (const [name, value] of Object.entries(s.recordedParam)) {
+                    if (paramIdByName.has(name))
+                        continue;
+                    const id = await this.getOrCreateParameter(projectId, moduleId, name, String(value ?? ''));
+                    paramIdByName.set(name, id);
+                }
+            }
         }
         return paramIdByName;
     }
+    actionCatalog() {
+        if (this.actionCatalogCache)
+            return this.actionCatalogCache;
+        const projectId = this.requireProjectId();
+        this.actionCatalogCache = (async () => {
+            // `projectId in [0, projectId]` — 0 is the customer-wide default catalog, projectId is the
+            // per-project overrides layered on top. Same filter the SQA UI uses (steps.model.ts:59).
+            const body = {
+                searchFields: [
+                    { column: 'deleted', value: false },
+                    { column: 'projectId', value: { $in: [0, projectId] } },
+                ],
+                startIndex: 0,
+                limit: 100000,
+                selectFields: ['id', 'name', 'technology', 'objectTemplate', 'objectRequired'],
+            };
+            const raw = await this.http.postJson('/tm/action/search', body);
+            const rows = pickArray(raw, 'data', 'content', 'actions');
+            const map = new Map();
+            for (const row of rows) {
+                const idStr = str(row, 'id', '_id', 'actionId');
+                const name = str(row, 'name');
+                const tech = str(row, 'technology');
+                if (!idStr || !name || !tech)
+                    continue;
+                const id = Number.parseInt(idStr, 10);
+                if (!Number.isFinite(id))
+                    continue;
+                const objectRequired = row?.objectRequired === true;
+                const otRaw = row?.objectTemplate;
+                const objectTemplate = typeof otRaw === 'number' ? otRaw
+                    : typeof otRaw === 'string' && /^\d+$/.test(otRaw) ? Number.parseInt(otRaw, 10)
+                        : undefined;
+                // Prefer the higher-priority project override when the same (tech, name) has both a
+                // default and a project row: last write wins if we sort defaults first. Backend returns
+                // whichever ordering; we resolve determinism by preferring a non-zero projectId row.
+                const key = `${tech.toUpperCase()}::${name.toLowerCase()}`;
+                const prev = map.get(key);
+                const isProjectOverride = typeof row?.projectId === 'number' && row.projectId !== 0;
+                if (!prev || isProjectOverride)
+                    map.set(key, { id, objectRequired, objectTemplate });
+            }
+            return map;
+        })().catch((e) => { this.actionCatalogCache = null; throw e; });
+        return this.actionCatalogCache;
+    }
+    /** POST /tm/object/createObjectSeq — get-or-create the shared object row by locator match. The
+     *  backend does the dedup (`object.controller.js:268-370`) — same-locators reuses, same-disname-
+     *  different-locators creates a suffixed one. Returns the numeric object id.
+     *
+     *  ponytail: minimum body — no thumbnail_url / pageScreenShot_url / parameterId. The recording
+     *  path enriches these; the tc_save path doesn't have screenshots to attach, and the object
+     *  works for execution without them. */
+    async resolveObjectId(objectRef, projectId, moduleId, technology, objectTemplateId) {
+        const attributes = (objectRef.locators ?? []).map((l) => ({
+            name: l.name,
+            value: l.value,
+            ...(l.unique === true ? { unique: true } : {}),
+        }));
+        const body = {
+            projectId,
+            moduleId,
+            objecttemplateId: objectTemplateId,
+            technology,
+            disname: objectRef.name ?? '',
+            attributes,
+            parameterId: [],
+            description: '',
+        };
+        const raw = await this.http.postJson('/tm/object/createObjectSeq', body);
+        const flat = raw?.data ?? raw;
+        const id = str(flat, 'id', '_id', 'objectId');
+        if (!id)
+            throw new Error(`createObjectSeq returned no id for object "${objectRef.name}": ${JSON.stringify(raw)}`);
+        return Number.parseInt(id, 10);
+    }
+    /** For every automation step, resolve `actionId` (from action name + technology) and
+     *  `objectId` (via createObjectSeq get-or-create) so the mapper can emit a valid step. Runs
+     *  once per save, aligned by step index. */
+    async resolveAutomationSteps(projectId, moduleId, tc) {
+        const catalog = await this.actionCatalog();
+        const steps = Array.isArray(tc.steps) ? tc.steps : [];
+        const out = [];
+        for (let i = 0; i < steps.length; i++) {
+            const s = steps[i];
+            const tech = (TECH_BY_STEPTYPE[s.stepType] ?? deriveTcType(tc)).toUpperCase();
+            const name = (s.actionType ?? '').trim();
+            if (!name) {
+                throw new Error(`Automation step ${i + 1} ("${s.description}"): missing actionType — the neutral Step.actionType must name an SQA action (e.g. "Click", "Type Text", "Launch Application").`);
+            }
+            const meta = catalog.get(`${tech}::${name.toLowerCase()}`);
+            if (!meta) {
+                throw new Error(`Automation step ${i + 1}: no SQA action named "${name}" for technology ${tech}. Check the action catalog in the SQA UI.`);
+            }
+            let objectId = null;
+            if (meta.objectRequired) {
+                if (!s.objectRef || !s.objectRef.name || !(s.objectRef.locators?.length)) {
+                    throw new Error(`Automation step ${i + 1} ("${name}"): action requires an object but Step.objectRef is missing name/locators. Provide objectRef:{name, locators:[{name, value}]}.`);
+                }
+                if (meta.objectTemplate == null) {
+                    throw new Error(`Automation step ${i + 1} ("${name}"): action ${meta.id} has no objectTemplate — cannot create/reuse an object without knowing which template it belongs to.`);
+                }
+                objectId = await this.resolveObjectId(s.objectRef, projectId, moduleId, tech, meta.objectTemplate);
+            }
+            out.push({ actionId: meta.id, objectId });
+        }
+        return out;
+    }
     /** Case-insensitive project-scoped exact-name lookup. Backend duplicate-name check uses Mongo
      *  collation strength:2, so a case-sensitive search here misses params stored under different
      *  casing — the next POST then trips "Duplicate Name Error". Returns null when not found. */
@@ -617,10 +2310,178 @@ export class SimplifyQaAdapter {
             executionPlatform: { LOCAL: {}, REMOTE: {}, CLOUD: {} },
         };
     }
-    // ---------------------------------------------------------------------- Object search + write  [Step 4]
-    // No exposed common-mcp tool calls these on ProviderAdapter today for SQA — leave on hop.
-    async searchObjects(q) { return this.requireHop('search_objects').searchObjects(q); }
-    async createObject(o) { return this.requireHop('create_object').createObject(o); }
+    async resolveObjectTemplateId(technology) {
+        if (!this.objectTemplateCache) {
+            this.objectTemplateCache = (async () => {
+                const body = this.searchBody([{ column: 'deleted', value: false }], { limit: 1000 });
+                const raw = await this.http.postJson('/tm/objectTemplate/search', body);
+                const rows = pickArray(raw, 'data', 'content', 'objectTemplates');
+                const map = new Map();
+                for (const r of rows) {
+                    const name = str(r, 'name');
+                    const id = str(r, 'id', '_id');
+                    if (name && id)
+                        map.set(name.toUpperCase(), Number.parseInt(id, 10));
+                }
+                return map;
+            })().catch((e) => {
+                this.objectTemplateCache = null; // failure isn't memoised — a retry actually retries
+                throw e;
+            });
+        }
+        const map = await this.objectTemplateCache;
+        const id = map.get(technology.toUpperCase());
+        if (id == null) {
+            throw new Error(`Unknown object type/technology "${technology}"` +
+                (map.size ? ` — known: ${[...map.keys()].join(', ')}.` : ' — no object templates found in this project.'));
+        }
+        return id;
+    }
+    /** `POST /tm/object/search` — objects visible in the current project. `q.query` free-text searches
+     *  `disname` — the UI's "Name" column (confirmed against the real sqa-ui Object Repository grid;
+     *  `description` is a separate, optional field and is NOT what users mean by an object's name). */
+    async searchObjects(q) {
+        const projectId = this.requireProjectId();
+        const fields = [
+            { column: 'deleted', value: false },
+            { column: 'projectId', value: projectId },
+        ];
+        if (q.query)
+            fields.push({ column: 'disname', value: q.query, regEx: true });
+        const body = this.searchBody(fields, { startIndex: q.offset ?? 0, limit: q.limit ?? 100 });
+        const raw = await this.http.postJson('/tm/object/search', body);
+        const rows = pickArray(raw, 'data', 'content', 'objects');
+        return rows.map(toObject);
+    }
+    /**
+     * Create a new object — `POST /tm/object`, plain JSON (NOT multipart, unlike testcase/suite writes;
+     * confirmed against the real sqa-ui ObjectService.saveNewObject). `o.objectType` is REQUIRED: it
+     * resolves to the object's `objecttemplateId` — structural, and (per updateObject's contract) not
+     * editable after creation. `moduleId` auto-resolves to the project's "Default Module" (matching the
+     * real UI's `object.component.ts` `openForm()`, which pre-selects it for every new object) — best
+     * effort, never blocks creation if no such module exists or the lookup fails.
+     */
+    async createObject(o) {
+        if (!o.objectType) {
+            throw new Error('createObject: objectType is required (e.g. "WEB", "ANDROID") — it selects the object template ' +
+                'and cannot be changed after the object is created.');
+        }
+        const projectId = this.requireProjectId();
+        const objecttemplateId = await this.resolveObjectTemplateId(o.objectType);
+        const moduleId = await this.resolveDefaultModuleId();
+        const body = {
+            disname: o.name,
+            objecttemplateId,
+            parameterId: [],
+            projectId,
+            technology: o.objectType,
+            ...(moduleId != null ? { moduleId } : {}),
+            attributes: o.locators.map((l) => ({ name: l.name, value: l.value, ...(l.unique ? { unique: true } : {}) })),
+        };
+        const raw = await this.http.postJson('/tm/object', body);
+        const doc = (raw?.data && typeof raw.data === 'object' ? raw.data : raw) ?? {};
+        return toObject(doc);
+    }
+    /** The current project's module literally named "Default Module" (case-insensitive) — mirrors the
+     *  real sqa-ui `object.component.ts` `openForm()` auto-selection. Best-effort: returns undefined
+     *  (never throws) when no such module exists or the lookup fails, so object creation still proceeds
+     *  without a module rather than being blocked by this convenience. */
+    async resolveDefaultModuleId() {
+        try {
+            const modules = await this.listModules();
+            const found = modules.find((m) => m.name?.toLowerCase() === 'default module');
+            return found ? Number.parseInt(found.id, 10) : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * Soft-delete — `PATCH /tm/object` (NOT POST .../delete like testcase/suite; confirmed against the
+     * real sqa-ui ObjectService.deleteObject), body `{ids, projectId, isDelete:true}`.
+     *
+     * DEPENDENCY-CHECKED first: the SAME route with `isDelete:false` is a DRY RUN that returns, per
+     * object, which test cases / functions / workflows still reference it (`tcArr`/`fnArr`/`wfArr`, each
+     * keyed by projectId → an array of referencing ids — mirrors the real UI's
+     * deleteDependencyForObject flow, object.component.html/.ts). If anything still references it, the
+     * delete is refused rather than silently breaking those test cases; only a dependency-free object
+     * gets the real `isDelete:true` call.
+     */
+    async deleteObject(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);
+        if (tcCount || fnCount || wfCount) {
+            const parts = [];
+            if (tcCount)
+                parts.push(`${tcCount} test case${tcCount === 1 ? '' : 's'}`);
+            if (fnCount)
+                parts.push(`${fnCount} function${fnCount === 1 ? '' : 's'}`);
+            if (wfCount)
+                parts.push(`${wfCount} workflow${wfCount === 1 ? '' : 's'}`);
+            throw new Error(`Cannot delete object ${id} — still used by ${parts.join(', ')}. Remove those references first ` +
+                '(or review/delete them in the SimplifyQA UI, which shows exactly which ones).');
+        }
+        await this.http.patchJson('/tm/object', { ids: [numId], projectId, isDelete: true });
+    }
+    /**
+     * Update an object — `PUT /tm/object/:id`, plain JSON (NOT multipart, unlike testcase/suite writes;
+     * confirmed against the real sqa-ui ObjectService.update). The backend expects the FULL document
+     * back, so this reads the current one first and echoes every field it doesn't touch
+     * (disname/description/objecttemplateId/parameterId/moduleId/technology/updateVersion — the
+     * optimistic-concurrency token the real form also round-trips).
+     *
+     * `changes.locators` UPSERTS by locator name into the existing attribute list — an entry with a
+     * matching name gets its value/unique updated in place, everything else on the object is left alone,
+     * and a name with no existing match is appended as a new locator.
+     *
+     * `technology` (object type) and `objecttemplateId` are DELIBERATELY never taken from `changes` —
+     * they are always echoed back from the existing doc. Both are structural (they determine which
+     * attribute set is even valid for this object), so editing them here — outside the create flow — is
+     * out of scope; changing them means creating a new object, not "updating" this one.
+     */
+    async updateObject(id, changes) {
+        const numId = numericId(id);
+        const raw = await this.http.getJson(`/tm/object/${numId}`);
+        const doc = (raw?.data && typeof raw.data === 'object' ? raw.data : raw) ?? {};
+        if (!doc || typeof doc !== 'object' || Object.keys(doc).length === 0) {
+            throw new Error(`object ${id} not found`);
+        }
+        const attributes = Array.isArray(doc.attributes)
+            ? doc.attributes.map((a) => ({
+                name: String(a?.name ?? ''),
+                value: String(a?.value ?? ''),
+                ...(a?.unique === true ? { unique: true } : {}),
+            }))
+            : [];
+        for (const loc of changes.locators ?? []) {
+            const idx = attributes.findIndex((a) => a.name === loc.name);
+            const merged = { name: loc.name, value: loc.value, ...(loc.unique !== undefined ? { unique: loc.unique } : {}) };
+            if (idx >= 0)
+                attributes[idx] = { ...attributes[idx], ...merged };
+            else
+                attributes.push(merged);
+        }
+        const body = {
+            disname: changes.name ?? doc.disname,
+            description: doc.description,
+            objecttemplateId: doc.objecttemplateId,
+            parameterId: doc.parameterId ?? [],
+            moduleId: doc.moduleId,
+            technology: doc.technology,
+            attributes,
+            projectId: this.requireProjectId(),
+            updateVersion: doc.updateVersion ?? 0,
+        };
+        const res = await this.http.putJson(`/tm/object/${numId}`, body);
+        const updated = (res?.data && typeof res.data === 'object' ? res.data : res) ?? doc;
+        return toObject(updated);
+    }
     // ---------------------------------------------------------------------- Actions catalog
     async actionsCatalog(platform) {
         return this.requireHop('actions_catalog').actionsCatalog(platform);
@@ -668,11 +2529,13 @@ export class SimplifyQaAdapter {
                 const pid = Number.parseInt(key, 10);
                 if (!Number.isFinite(pid))
                     continue;
-                const seed = String(value?.value ?? '');
-                const name = await this.fetchParameterName(pid);
-                if (!name)
+                // Protected params get masked below — never assign this raw value to `seed` unmasked.
+                const rawValue = String(value?.value ?? '');
+                const meta = await this.fetchParameterMeta(pid);
+                if (!meta)
                     continue; // parameter deleted — skip
-                parameters.push({ paramId: pid, name, seed });
+                const seed = meta.protected ? (rawValue ? '*****' : '(empty)') : rawValue;
+                parameters.push({ paramId: pid, name: meta.name, seed, ...(meta.protected ? { protected: true } : {}) });
             }
         }
         return { tcId: q.tcId, versionId: versionId, environmentType: env, parameters };
@@ -760,9 +2623,8 @@ export class SimplifyQaAdapter {
         catch { /* fall through */ }
         return 'general';
     }
-    /** Parameter name lookup for paramId → name enrichment. Null when the parameter is deleted or
-     *  belongs to a different project. */
-    async fetchParameterName(paramId) {
+    /** Parameter name + protected-flag lookup. Null when the parameter is deleted or cross-project. */
+    async fetchParameterMeta(paramId) {
         let raw;
         try {
             raw = await this.http.getJson(`/tm/parameter/${paramId}`);
@@ -775,7 +2637,10 @@ export class SimplifyQaAdapter {
             n = n.length > 0 ? n[0] : null;
         if (!n || typeof n !== 'object')
             return null;
-        return str(n, 'name') ?? null;
+        const name = str(n, 'name');
+        if (!name)
+            return null;
+        return { name, protected: n?.protected === true };
     }
     // ---------------------------------------------------------------------- Formulas  [Step 3b]
     /** List every formula the current project can use — DEFAULT (customer-wide prefabs) unioned with
@@ -902,6 +2767,20 @@ export class SimplifyQaAdapter {
             reportUrl: `${base}/reports/execution/${runId}`,
         };
     }
+    /** 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. */
+    async lookupProjectName(projectId) {
+        try {
+            const body = this.searchBody([{ column: 'id', value: projectId }, { column: 'deleted', value: false }], { selectFields: ['id', 'name'], limit: 1 });
+            const raw = await this.http.postJson('/pm/project/search', body);
+            const rows = pickArray(raw, 'data', 'content', 'projects');
+            return str(rows[0], 'name', 'projectName') ?? '';
+        }
+        catch {
+            return '';
+        }
+    }
     // --- Run dispatch (direct REST) --------------------------------------------
     // Trigger, stop, and local-agent roster all speak the SQA gateway directly.
     // The desktop agent still runs the actual TC — backend RPUSHes to Redis and the
@@ -927,8 +2806,20 @@ export class SimplifyQaAdapter {
             throw new Error(`startRun: test case ${tcId} not found.`);
         }
         // Version resolution — same fallback chain buildTestcasePayload/getDefaultIteration use.
-        let versionName = str(rawTc, 'versionName', 'selectedVersionName');
-        let versionId = str(rawTc, 'versionId', 'selectedVersionId');
+        // 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.
+        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');
+            }
+        }
+        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'));
@@ -940,7 +2831,14 @@ export class SimplifyQaAdapter {
         }
         versionName ?? (versionName = 'v1.0');
         versionId ?? (versionId = '');
-        const info = await this.info();
+        // 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.
+        const projectName = await this.lookupProjectName(projectId);
+        if (!projectName) {
+            throw new Error(`startRun: could not resolve project name for projectId=${projectId}. ` +
+                `The token may not have read access to this project.`);
+        }
         const env = await this.resolveEnvironment(projectId, opts.environment);
         const tcType = String(str(rawTc, 'tcType') ?? 'WEB').toUpperCase();
         const executionType = String(str(rawTc, 'executionType') ?? 'AUTOMATION').toUpperCase();
@@ -951,14 +2849,16 @@ export class SimplifyQaAdapter {
         const moduleIdNum = typeof rawTc?.moduleId === 'number' ? rawTc.moduleId : 0;
         const userstoryIdNum = typeof rawTc?.userstoryId === 'number' ? rawTc.userstoryId : 0;
         const tags = Array.isArray(rawTc?.tags) ? rawTc.tags : [];
-        // Best-effort module name — backend doesn't validate it functionally; one /pm/module/search
-        // covers every id, so the extra call is cheap. Story name deliberately left empty; adds a
-        // per-run round-trip for a cosmetic field. ponytail: enrich if a caller ever complains.
+        // Best-effort module name — targeted id lookup (not a full listModules scan, which now caps
+        // at the default 100). Story name deliberately left empty; adds a per-run round-trip for a
+        // cosmetic field. ponytail: enrich if a caller ever complains.
         let moduleName = '';
         if (moduleIdNum > 0) {
             try {
-                const modules = await this.listModules();
-                moduleName = modules.find((m) => m.id === String(moduleIdNum))?.name ?? '';
+                const body = this.searchBody([{ column: 'id', value: moduleIdNum }, { column: 'deleted', value: false }], { selectFields: ['id', 'name'], limit: 1 });
+                const raw = await this.http.postJson('/pm/module/search', body);
+                const rows = pickArray(raw, 'data', 'content', 'modules');
+                moduleName = str(rows[0], 'name') ?? '';
             }
             catch { /* leave empty */ }
         }
@@ -979,8 +2879,8 @@ export class SimplifyQaAdapter {
             cloudType: mode === 'CLOUD' ? 'VM' : 'NONE',
             mode,
             executionCategory: 'EXECUTION',
-            releaseId: 0,
-            iterationId: 0,
+            releaseId: opts.releaseId ? Number.parseInt(opts.releaseId, 10) || 0 : 0,
+            iterationId: opts.sprintId ? Number.parseInt(opts.sprintId, 10) || 0 : 0,
             executionTime: '',
             status: 'INPROGRESS',
             iterationsSelected: [],
@@ -1003,7 +2903,7 @@ export class SimplifyQaAdapter {
                     type: 'TC',
                     platform,
                     projectId,
-                    projectName: info.projectName,
+                    projectName,
                     configuration: {},
                     iterationsSelected: [],
                     moduleId: moduleIdNum,
@@ -1035,27 +2935,61 @@ export class SimplifyQaAdapter {
             killType: 'STOP_EXECUTION',
         });
     }
-    // Cloud runner roster is not yet ported — plan doc only covers LOCAL trigger + stop + agents.
-    async listCloudRunners() { return this.requireHop('list_cloud_runners').listCloudRunners(); }
+    async listCloudRunners() {
+        const projectId = this.requireProjectId();
+        const body = this.searchBody([{ column: 'projectId', value: projectId }], { limit: 1000 });
+        const raw = await this.http.postJson('/pm/machineResources/search', body);
+        const rows = pickArray(raw, 'data', 'content');
+        return rows.map((n) => {
+            const id = str(n, 'id', '_id') ?? '';
+            const status = str(n, 'status') ?? '';
+            const parentId = str(n, 'parentId');
+            const type = str(n, 'type');
+            const os = [parentId ? `CM-${parentId}` : null, type].filter(Boolean).join(' · ') || undefined;
+            return {
+                id,
+                name: str(n, 'displayName', 'name') ?? id,
+                online: status === 'IDLE',
+                ...(status ? { status } : {}),
+                ...(os ? { os } : {}),
+            };
+        });
+    }
     async listLocalAgents() {
+        // ponytail: no projectId filter — machine_registration.projectId is never written by
+        // test-management/services/machine_registration.service.js (create only stamps
+        // machineName/systemName/macAddress/ipAddress/platform/customerId). Filtering by projectId
+        // strips every legacy row. customerId scoping is still applied server-side from the JWT.
         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;
         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 host = str(n, 'macAddress', 'hostAddress');
-            // `active` is the real Redis-heartbeat flag on machineRegistration — the executor only picks
-            // up runs whose agent is currently polling. A stale registration with `active: false` will
-            // sit in Redis until TTL and never execute, so surface the real state to the caller.
-            const active = typeof n?.active === 'boolean' ? n.active : false;
+            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);
             return {
                 id,
                 ...(agentName ? { name: agentName } : {}),
-                online: active,
+                online: dbActive || isMyBox,
                 ...(owner ? { owner } : {}),
-                ...(host ? { host } : {}),
+                ...(hostAddr ? { host: hostAddr } : {}),
             };
         });
     }
@@ -1087,8 +3021,10 @@ export class SimplifyQaAdapter {
             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.');
         }
-        const host = os.hostname().toLowerCase();
-        const mine = active.filter((a) => (a.name ?? '').toLowerCase().includes(host));
+        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');
@@ -1109,6 +3045,10 @@ export class SimplifyQaAdapter {
     buildRunPlatform(tcType, mode, browser, deviceId) {
         const t = tcType.toUpperCase();
         if (t === 'WEB') {
+            if (mode === 'CLOUD') {
+                const key = `${(browser ?? 'CHROME').toUpperCase()}_HEADLESS`;
+                return [{ name: key, id: key, technologyType: 'WEB', type: 'NONE' }];
+            }
             const b = (browser ?? 'CHROME').toUpperCase();
             return [{ name: b, id: b, technologyType: 'WEB', type: 'NONE' }];
         }
@@ -1130,10 +3070,26 @@ export class SimplifyQaAdapter {
         }
         return [{ name: t, id: t, technologyType: t, type: 'NONE' }];
     }
-    // --- Environments + datasets ------------------------------------------- (fine to hop for now)
+    // --- Environments + datasets -------------------------------------------
+    /** Direct REST — same endpoint `resolveEnvironment` uses. Works without an agent hop.
+     *  `key` is what testdata iterations store as `environmentType`; `id` is the uuid used by run dispatch. */
     async listEnvironments() {
-        const h = this.hop();
-        return h ? h.listEnvironments() : [];
+        const projectId = this.requireProjectId();
+        // Let fetch failures propagate rather than reading as "zero environments".
+        const raw = await this.http.getJson(`/pm/fields/8?projectId=${projectId}&fieldType=environment`);
+        const arr = Array.isArray(raw) ? raw : Array.isArray(raw?.data) ? raw.data : [];
+        const out = [];
+        for (const e of arr) {
+            if (!e || typeof e !== 'object' || e.deleted)
+                continue;
+            const key = str(e, 'key', 'value') ?? '';
+            const name = str(e, 'name', 'label') ?? key;
+            const id = str(e, 'id', '_id') ?? key;
+            if (!key && !name)
+                continue;
+            out.push({ id, name, key, ...(key === 'general' ? { isDefault: true } : {}) });
+        }
+        return out;
     }
     async listDatasets(tcId) {
         const h = this.hop();