@aifabrix/builder 2.60.0 → 2.62.0

package/lib/parameters/rsa-secret-values.js

@@ -0,0 +1,165 @@
+/**
+ * @fileoverview Generate linked catalog RSA secrets without rotating existing identities.
+ */
+const crypto = require('crypto');
+const { decryptSecret, isEncrypted } = require('../utils/secrets-encryption');
+
+/** @param {*} value @returns {boolean} Whether a stored value is populated. */
+function populated(value) {
+  return value !== undefined && value !== null && String(value).trim() !== '';
+}
+
+/**
+ * Read a stored key without exposing crypto errors or key material.
+ * @param {string} value
+ * @param {string} encryptionKey
+ * @param {string} pairId
+ * @returns {import('crypto').KeyObject}
+ */
+function readPrivateKey(value, encryptionKey, pairId) {
+  try {
+    const pem = isEncrypted(value) ? decryptSecret(value, encryptionKey) : value;
+    const key = crypto.createPrivateKey(pem);
+    if (key.asymmetricKeyType !== 'rsa') throw new Error('Not RSA');
+    return key;
+  } catch {
+    throw new Error(`Cannot generate RSA pair "${pairId}": existing private key cannot be read as RSA. Restore a valid private key before retrying.`);
+  }
+}
+
+/**
+ * Pairs whose private half belongs to Mori, not to an installation.
+ *
+ * Builder must never mint these. Licence trust is a two-signature chain, and both links
+ * exist so that substituting a key fails rather than silently succeeding:
+ *
+ * 1. Mori signs the licence. The installation verifies it against the public key held on
+ *    disk, so a licence from anywhere else does not verify.
+ * 2. That on-disk material is itself validated against a key in Key Vault. The Key Vault is
+ *    provisioned by the Marketplace deployment and readable only by Miso's managed
+ *    identity — nobody can change it, including us — so swapping the on-disk public key for
+ *    one whose private half an attacker holds fails at the second check.
+ *
+ * The second link is an **Azure** guarantee. A Docker installation has no Key Vault and no
+ * managed identity, so locally the chain is the pinned public key alone. Closing that is
+ * online validation against Mori, which is a known gap deferred on purpose: the delivery
+ * target is Azure, and Docker exists to validate the shape of that stack.
+ *
+ * It does not soften this rule. The one environment lacking the second check is the last
+ * one that should mint its own keys, and a locally generated pair would make local
+ * behaviour diverge from the Azure stack it exists to mirror.
+ *
+ * Generating the pair locally breaks both links at once: the installation would hold the
+ * private half of the key it verifies against, so it could sign a licence it then accepts,
+ * and the material would no longer correspond to what Key Vault validates. 227.1 pinned
+ * this key "precisely because a key travelling inside the token it verifies proves
+ * nothing"; a self-generated key proves exactly as little.
+ *
+ * The public half reaches an installation through the `moriLicensePublicKey` deployment
+ * parameter, which the installation contract already classifies as registration-supplied.
+ * An installation with neither half stays unpinned and refuses every licence, which is the
+ * documented and correct failure.
+ */
+const ISSUER_SUPPLIED_PAIR_IDS = Object.freeze(['mori-license-signing', 'mori-policy-signing']);
+
+/**
+ * @param {Object} entry - Catalog entry
+ * @returns {boolean} True when the pair is supplied by Mori rather than generated here
+ */
+function isIssuerSuppliedPair(entry) {
+  return ISSUER_SUPPLIED_PAIR_IDS.includes(entry?.generator?.pairId);
+}
+
+/**
+ * Generate missing parts for one catalog pair, preserving existing key material.
+ * @param {Object[]} entries
+ * @param {Object} existing
+ * @param {string} encryptionKey
+ * @returns {Object} Missing values, including the linked counterpart when declared.
+ */
+function generatePair(entries, existing, encryptionKey) {
+  const pairId = entries[0].generator.pairId;
+  const privateEntry = entries.find(e => e.generator.part === 'private');
+  const publicEntries = entries.filter(e => e.generator.part === 'public');
+  if (!privateEntry) throw new Error(`Cannot generate RSA pair "${pairId}": catalog has no private key entry.`);
+  const storedPrivate = existing[privateEntry.key];
+  const hasPublic = publicEntries.some(e => populated(existing[e.key]));
+  if (!populated(storedPrivate) && hasPublic) {
+    throw new Error(`Cannot generate RSA pair "${pairId}": public key exists but private key is missing. Restore the matching private key before retrying.`);
+  }
+  const privateKey = populated(storedPrivate)
+    ? readPrivateKey(storedPrivate, encryptionKey, pairId)
+    : crypto.generateKeyPairSync('rsa', { modulusLength: 2048 }).privateKey;
+  const publicKey = crypto.createPublicKey(privateKey).export({ type: 'spki', format: 'pem' });
+  const values = {};
+  if (!populated(storedPrivate)) {
+    values[privateEntry.key] = privateKey.export({ type: 'pkcs8', format: 'pem' });
+  }
+  for (const entry of publicEntries) {
+    if (!populated(existing[entry.key])) values[entry.key] = publicKey;
+  }
+  return values;
+}
+
+/**
+ * Prepare linked RSA values for a single write operation; never cache identities globally.
+ * @param {string[]} keys - Missing keys requested by the caller
+ * @param {Object} [existing] - Existing or explicitly supplied values (plain or encrypted)
+ * @param {string} [encryptionKey] - Local encryption key
+ * @returns {Object} Newly generated values only
+ */
+function generateRsaSecretValues(keys, existing = {}, encryptionKey) {
+  let catalog;
+  try {
+    catalog = require('./infra-parameter-catalog').getInfraParameterCatalog();
+  } catch {
+    return {}; // Ordinary generation retains its existing catalog-unavailable handling.
+  }
+  const values = {};
+  for (const key of keys) {
+    if (populated(existing[key]) || populated(values[key])) continue;
+    const entry = catalog.findEntryForKey(key);
+    if (entry?.generator?.type !== 'rsaKeyPair') continue;
+    // Supplied by Mori at deployment and validated against Key Vault. Generating it here
+    // would hand the installation the private half of the key it verifies licences against.
+    if (isIssuerSuppliedPair(entry)) continue;
+    const entries = catalog.data.parameters.filter(e => e.key &&
+      e.generator?.type === 'rsaKeyPair' && e.generator.pairId === entry.generator.pairId);
+    Object.assign(values, generatePair(entries, { ...existing, ...values }, encryptionKey));
+  }
+  return values;
+}
+
+/**
+ * The rsaKeyPair branch, which is the only one that can refuse.
+ *
+ * Builder never mints a pair whose private half belongs to the issuer: an installation
+ * holding it could sign a licence it would then accept. Miso's catalog has since changed
+ * these three entries to `emptyAllowed`, so this is now a guard against the declaration
+ * coming back rather than a branch the shipped catalog reaches.
+ *
+ * @param {string} key - Secret key
+ * @param {Object} catalogEntry - Catalog entry
+ * @returns {string|undefined}
+ * @throws {Error} When the pair is issuer-supplied
+ */
+function generateRsaValueFromCatalog(key, catalogEntry) {
+  if (isIssuerSuppliedPair(catalogEntry)) {
+    throw new Error(
+      `Secret "${key}" is supplied by Mori and is never generated here. Licence trust is a ` +
+      'two-signature chain: Mori signs the licence, which is verified against the on-disk ' +
+      'public key, and that material is validated against a Key Vault key readable only by ' +
+      'Miso\'s managed identity. The public half reaches an installation through the ' +
+      'moriLicensePublicKey deployment parameter. An installation with neither stays ' +
+      'unpinned and refuses every licence, which is the intended failure.'
+    );
+  }
+  return generateRsaSecretValues([key])[key];
+}
+
+module.exports = {
+  generateRsaSecretValues,
+  generateRsaValueFromCatalog,
+  isIssuerSuppliedPair,
+  ISSUER_SUPPLIED_PAIR_IDS
+};

package/lib/programmatic/builder-help-enterprise-sync-fabrix.js

@@ -10,7 +10,7 @@ const fs = require('fs');
 const path = require('path');
 const { buildHelpEnvelope } = require('./builder-help-envelope');
 
-const HELP_MD_DIR = path.join(__dirname, 'help-content');
+const HELP_MD_DIR = path.join(__dirname, '..', '..', 'docs', 'builder-help', 'content');
 
 /** @type {ReadonlyArray<string>} */
 const REPAIR_COMMANDS = Object.freeze([

package/lib/programmatic/builder-help-governance.js

@@ -15,7 +15,7 @@ const { listPlatformRoles } = require('./platform-rbac-catalog');
 const { CHANNEL_TARGET_KEYS, CHANNEL_TARGETS } = require('../channels/channel-targets');
 
 const BUILDER_HELP_DIR = path.join(__dirname, '..', '..', 'docs', 'builder-help');
-const HELP_MD_DIR = path.join(__dirname, 'help-content');
+const HELP_MD_DIR = path.join(BUILDER_HELP_DIR, 'content');
 
 /**
  * @param {string} fileName

package/lib/programmatic/builder-help.js

@@ -65,7 +65,7 @@ const PROSE_TOPIC_FILES = Object.freeze({
   enterpriseSyncFabrix: 'enterprise-sync-fabrix.md'
 });
 
-const HELP_MD_DIR = path.join(__dirname, 'help-content');
+const HELP_MD_DIR = path.join(__dirname, '..', '..', 'docs', 'builder-help', 'content');
 
 /**
  * @param {string} message

package/lib/programmatic/run-channel-install-artifacts.js

@@ -45,6 +45,30 @@ function listChannelArtifacts(ctx) {
   return { artifacts };
 }
 
+/**
+ * Locate the rendered setup document.
+ *
+ * `dist/channels/<target>/` is build output and is gitignored, so anything served only from
+ * there disappears on a clean, a rebuild, or in a fresh workspace — which is what made the
+ * portal report "Setup document not available" after an install that had succeeded. The
+ * durable copy lives beside the channel's other committed files under
+ * `integration/<systemKey>/`, so that is preferred and `dist/` is only a fallback for a
+ * package built but not yet persisted.
+ *
+ * @param {import('./workspace-context').WorkspaceContext} ctx - Workspace context
+ * @param {string} root - User root
+ * @param {string} target - Channel target / system key
+ * @returns {string} Absolute path, or '' when no copy exists
+ */
+function resolveInstallGuidePath(ctx, root, target) {
+  const candidates = [];
+  if (typeof ctx.getIntegrationPath === 'function') {
+    candidates.push(path.join(ctx.getIntegrationPath(), 'INSTALL.md'));
+  }
+  candidates.push(path.join(path.dirname(getArtifactOutputPath(root, target)), 'INSTALL.md'));
+  return candidates.find(candidate => fs.existsSync(candidate)) || '';
+}
+
 /**
  * @param {import('./workspace-context').WorkspaceContext} ctx
  * @param {string} artifactId
@@ -68,8 +92,8 @@ function resolveArtifactFile(ctx, artifactId) {
     }
   }
   if (id === 'installMd') {
-    const absPath = path.join(path.dirname(getArtifactOutputPath(root, target)), 'INSTALL.md');
-    if (fs.existsSync(absPath)) {
+    const absPath = resolveInstallGuidePath(ctx, root, target);
+    if (absPath) {
       return { absPath, contentType: 'text/markdown; charset=utf-8', fileName: 'INSTALL.md' };
     }
   }
@@ -131,6 +155,8 @@ async function handleChannelCallback(ctx, provider, query, body, deps = {}) {
 
 module.exports = {
   listChannelArtifacts,
+  resolveArtifactFile,
+  resolveInstallGuidePath,
   getChannelArtifact,
   handleChannelCallback,
   storeChannelCallbackCredential

package/lib/programmatic/run-channel-package.js

@@ -119,7 +119,9 @@ function generatePackageArtifact(ctx, body, channelTarget, branding, dataplaneUr
     projectRoot: ctx.getUserRoot(),
     channelTarget,
     runtimeValues,
-    dryRun: body.dryRun === true
+    dryRun: body.dryRun === true,
+    // Persist the setup document beside the channel's committed files; dist/ is disposable.
+    durableDir: workspaceSystemDir(ctx)
   });
 }
 

package/lib/programmatic/workspace-context.js

@@ -27,6 +27,38 @@ const WORKSPACE_INTEGRATION_FORMAT = 'json';
  * @property {string} bearerToken
  */
 
+/**
+ * The root a given environment's work lives under.
+ *
+ * `tst` and `pro` get a path segment of their own so an environment's work is separable and
+ * can be deleted on its own; `dev` keeps the existing layout, so no in-flight workspace moves
+ * and nothing that already holds a path stops resolving.
+ *
+ * Because `dev` is unprefixed, a user id equal to a promotion-only environment name would
+ * make `<root>/pro` mean two things — that environment, or that user's dev work. `userId`
+ * comes from a token and only has to avoid traversal to pass validation, so the collision is
+ * refused here rather than assumed away.
+ *
+ * @param {string} workspaceRoot - Resolved WORKSPACE_ROOT
+ * @param {string} userId - Validated user id
+ * @param {string} [environment] - Environment key
+ * @returns {string} Root for this environment
+ * @throws {Error} When the user id would collide with an environment segment
+ */
+function resolveEnvironmentWorkspaceRoot(workspaceRoot, userId, environment) {
+  const { isPromotionOnlyEnvironment } = require('../core/environment-mode-policy');
+  if (isPromotionOnlyEnvironment(userId)) {
+    throw new Error(
+      `userId "${userId}" collides with an environment workspace segment; it cannot be an ` +
+      'environment name'
+    );
+  }
+  if (!isPromotionOnlyEnvironment(environment)) {
+    return workspaceRoot;
+  }
+  return path.join(workspaceRoot, String(environment).trim().toLowerCase());
+}
+
 /**
  * @param {string} segment
  * @returns {string}
@@ -63,7 +95,9 @@ function createWorkspaceContext(params) {
   }
 
   const workspaceRoot = resolveWorkspaceRoot(params.workspaceRoot);
-  const userRoot = path.join(workspaceRoot, userId);
+  const environment = params.environment || process.env.DEFAULT_ENVIRONMENT || 'dev';
+  const environmentRoot = resolveEnvironmentWorkspaceRoot(workspaceRoot, userId, environment);
+  const userRoot = path.join(environmentRoot, userId);
   const integrationRoot = path.join(userRoot, 'integration');
   const useExplicitIntegration = Boolean(params.integrationPath);
   const integrationPath = useExplicitIntegration
@@ -82,7 +116,7 @@ function createWorkspaceContext(params) {
     userId,
     workspaceRoot,
     systemKey,
-    environment: params.environment || process.env.DEFAULT_ENVIRONMENT || 'dev',
+    environment,
     controllerUrl:
       params.controllerUrl ||
       process.env.MISO_CONTROLLER_URL ||
@@ -149,5 +183,6 @@ module.exports = {
   runWithWorkspaceContext,
   ensureIntegrationDirectory,
   resolveWorkspaceRoot,
+  resolveEnvironmentWorkspaceRoot,
   assertPathContained
 };

package/lib/role-assistant/test-runner-workhub-answers.js

@@ -5,6 +5,8 @@
 
 'use strict';
 
+const { coversMissingFields } = require('./test-runner-workhub-missing-fields');
+
 const {
   resolveTargetSystemKey,
   shouldStampSuiteBid,
@@ -409,7 +411,8 @@ function resolveRespondValue(testCase, wait, statusRow, objective) {
   if (fromCase !== undefined) {
     return fromCase;
   }
-  return synthesizeWaitAnswer(wait, statusRow, objective, testCase);
+  const synthesized = synthesizeWaitAnswer(wait, statusRow, objective, testCase);
+  return coversMissingFields(wait, synthesized) ? synthesized : undefined;
 }
 
 function waitRespondFingerprint(wait) {

package/lib/role-assistant/test-runner-workhub-missing-fields.js

@@ -0,0 +1,42 @@
+/**
+ * @fileoverview Missing-field coverage for synthesized Work Hub answers.
+ */
+
+'use strict';
+
+function asPlainObject(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return {};
+  }
+  return value;
+}
+
+/**
+ * Fields the runtime named as missing (missingRequestBody waits). A synthesized
+ * answer that lacks any of them only makes the runtime ask the same question
+ * again, so it must not be sent.
+ * @param {Object} wait
+ * @returns {string[]}
+ */
+function waitMissingFields(wait) {
+  const raw = wait?.objectRef && typeof wait.objectRef === 'object' ? wait.objectRef.missingFields : null;
+  const list = Array.isArray(raw) ? raw : String(raw || '').split(',');
+  return list.map((row) => String(row || '').trim()).filter(Boolean);
+}
+
+function coversMissingFields(wait, value) {
+  if (value === undefined) {
+    return false;
+  }
+  const missing = waitMissingFields(wait);
+  if (missing.length === 0) {
+    return true;
+  }
+  const obj = asPlainObject(value);
+  if (!obj) {
+    return false;
+  }
+  return missing.every((field) => obj[field] !== undefined && obj[field] !== null && obj[field] !== '');
+}
+
+module.exports = { coversMissingFields, waitMissingFields };

package/lib/role-assistant/test-runner-workhub-wait-stop.js

@@ -0,0 +1,94 @@
+/**
+ * @fileoverview Work Hub poll stop rules for waits the runner cannot resolve.
+ *
+ * A wait with no matching case answer, a question the runtime re-issues
+ * unchanged after our answer, or a failed respond call never resolves by
+ * polling. Stopping at once keeps a stalled case at seconds, not the 180 s
+ * poll timeout (dev01 sales ladder, 2026-09-26: six cases, 18 min waiting).
+ */
+
+'use strict';
+
+const UNANSWERED_WAIT_TYPES = new Set(['respond-skipped', 'respond-repeated', 'respond-error']);
+
+/**
+ * The runtime asked the same question again after our answer: the answer did
+ * not resolve it, and repeating it cannot. Record once so the poll can stop.
+ */
+function recordRepeatedResponse(interactions, peId, fingerprint, wait) {
+  const already = interactions.some(
+    (row) => row && row.type === 'respond-repeated' && row.fingerprint === fingerprint
+  );
+  if (already) {
+    return;
+  }
+  interactions.push({
+    type: 'respond-repeated',
+    processExecutionId: peId,
+    fingerprint,
+    questionKey: wait.questionKey || wait.requestKey || null,
+    objectRefKind: wait.objectRef?.kind || null,
+    reason: 'same-question-after-answer'
+  });
+}
+
+function recordRespondError(interactions, peId, error) {
+  interactions.push({
+    type: 'respond-error',
+    processExecutionId: peId,
+    error: (error && error.message) || String(error)
+  });
+}
+
+/**
+ * A wait we could not answer (no matching case answer, the runtime re-asked
+ * after our answer, or respond failed) will not change by polling: stop now
+ * instead of waiting for the poll timeout.
+ * @param {Array<Object>} interactions
+ * @returns {string|null} stop reason or null to keep polling
+ */
+function unansweredWaitStopReason(interactions) {
+  const last = interactions.length > 0 ? interactions[interactions.length - 1] : null;
+  if (!last || !UNANSWERED_WAIT_TYPES.has(last.type)) {
+    return null;
+  }
+  return last.type === 'respond-error' ? 'respondFailed' : 'unansweredQuestion';
+}
+
+function recordSkippedResponse(interactions, peId, fingerprint, wait) {
+  interactions.push({
+    type: 'respond-skipped',
+    processExecutionId: peId,
+    fingerprint,
+    questionKey: wait.questionKey || wait.requestKey || null,
+    objectRefKind: wait.objectRef?.kind || null,
+    reason: 'no-matching-answer-or-synthesis'
+  });
+}
+
+const ALREADY_TERMINAL_RE = /already terminal/i;
+
+/**
+ * work.respond resumes the Decision Engine inline; by the time work.continue
+ * lands the execution may already be terminal. That is a finished run, not a
+ * failed answer.
+ */
+async function continueAfterRespond(dataplaneUrl, authConfig, peId) {
+  const { continueWorkExecution } = require('../api/work.api');
+  try {
+    await continueWorkExecution(dataplaneUrl, authConfig, peId, {});
+  } catch (err) {
+    if (!ALREADY_TERMINAL_RE.test((err && err.message) || String(err))) {
+      throw err;
+    }
+  }
+}
+
+module.exports = {
+  continueAfterRespond,
+  UNANSWERED_WAIT_TYPES,
+  recordSkippedResponse,
+  recordRepeatedResponse,
+  recordRespondError,
+  unansweredWaitStopReason
+};

package/lib/role-assistant/test-runner-workhub.js

@@ -13,8 +13,7 @@ const {
   getWorkTask,
   approveWorkTask,
   getWorkExecutionStatus,
-  respondWorkExecution,
-  continueWorkExecution
+  respondWorkExecution
 } = require('../api/work.api');
 const {
   synthesizeWaitAnswer,
@@ -29,6 +28,13 @@ const {
   persistCaseOpenApiViaBuilderApi
 } = require('./test-runner-bid-apply');
 const { resolveTargetSystemKey } = require('./test-runner-bid-document');
+const {
+  recordSkippedResponse,
+  recordRepeatedResponse,
+  recordRespondError,
+  unansweredWaitStopReason,
+  continueAfterRespond
+} = require('./test-runner-workhub-wait-stop');
 const {
   TERMINAL_TASK,
   delayMs,
@@ -178,17 +184,6 @@ async function maybeApproveTask(dataplaneUrl, authConfig, taskId, ctx) {
   await _attemptApproveTask(dataplaneUrl, authConfig, taskId, ctx);
 }
 
-function recordSkippedResponse(interactions, peId, fingerprint, wait) {
-  interactions.push({
-    type: 'respond-skipped',
-    processExecutionId: peId,
-    fingerprint,
-    questionKey: wait.questionKey || wait.requestKey || null,
-    objectRefKind: wait.objectRef?.kind || null,
-    reason: 'no-matching-answer-or-synthesis'
-  });
-}
-
 function recordBidEmit(testCase, interactions, peId) {
   const { loadCaseBidDocument } = require('./test-runner-workhub-answers');
   const emittedBid = loadCaseBidDocument(testCase);
@@ -237,6 +232,7 @@ async function respondToWaitingExecution(
   const wait = statusRow.wait && typeof statusRow.wait === 'object' ? statusRow.wait : {};
   const fingerprint = waitRespondFingerprint(wait);
   if (alreadyResponded(interactions, fingerprint)) {
+    recordRepeatedResponse(interactions, peId, fingerprint, wait);
     return;
   }
   const payload = buildRespondPayload(
@@ -260,7 +256,7 @@ async function respondToWaitingExecution(
     }
   }
   await respondWorkExecution(dataplaneUrl, authConfig, peId, payload);
-  await continueWorkExecution(dataplaneUrl, authConfig, peId, {});
+  await continueAfterRespond(dataplaneUrl, authConfig, peId);
   interactions.push({ type: 'respond', processExecutionId: peId, fingerprint });
   if (shouldApplyBidAfterWait(testCase, wait)) {
     recordBidEmit(testCase, interactions, peId);
@@ -291,8 +287,9 @@ async function maybeRespondWaiting(dataplaneUrl, authConfig, taskRow, testCase,
       interactions,
       statusRow
     );
-  } catch (_err) {
-    // Soft: continue polling task.
+  } catch (err) {
+    // A failed respond/continue never resolves itself; record it so the poll stops.
+    recordRespondError(interactions, peId, err);
   }
 }
 
@@ -301,7 +298,13 @@ function assertTerminalWorkHubTask(last, taskId, timeoutMs, options = {}) {
     throw new Error(`Work Hub task ${taskId} produced no status rows.`);
   }
   const finalStatusToken = String(last?.status || last?.taskStatus || '').trim().toLowerCase();
-  if (!TERMINAL_TASK.has(finalStatusToken) && options.recordTimeout === true) {
+  if (TERMINAL_TASK.has(finalStatusToken)) {
+    return last;
+  }
+  if (options.stoppedReason) {
+    return { ...last, pollStopped: options.stoppedReason, lastStatus: finalStatusToken || 'unknown' };
+  }
+  if (options.recordTimeout === true) {
     last = {
       ...last,
       pollTimedOut: true,
@@ -353,14 +356,18 @@ async function pollWorkHubTask(dataplaneUrl, authConfig, taskId, testCase, optio
     applyWorkHubPollStatus(ctx, last, status);
     await maybeApproveTask(dataplaneUrl, authConfig, taskId, ctx);
     await maybeRespondWaiting(dataplaneUrl, authConfig, last, testCase, ctx.interactions);
-    if (shouldStopPendingApprovalPoll(status, ctx)) {
+    ctx.stoppedReason = unansweredWaitStopReason(ctx.interactions);
+    if (ctx.stoppedReason || shouldStopPendingApprovalPoll(status, ctx)) {
       break;
     }
     await delayMs(intervalMs);
   }
 
   return {
-    finalTask: assertTerminalWorkHubTask(last, taskId, timeoutMs, { recordTimeout: true }),
+    finalTask: assertTerminalWorkHubTask(last, taskId, timeoutMs, {
+      recordTimeout: !ctx.stoppedReason,
+      stoppedReason: ctx.stoppedReason || null
+    }),
     timeline,
     interactions: ctx.interactions
   };
@@ -478,6 +485,8 @@ async function runWorkHubCaseLifecycle(roleKey, testCase, runtimeContext, option
 module.exports = {
   wantsWorkHubPath,
   runWorkHubCaseLifecycle,
+  pollWorkHubTask,
+  unansweredWaitStopReason,
   planAlreadyActivated,
   isPlanLostError,
   extractPeFromTask,

package/lib/schema/application-schema.json

@@ -7,12 +7,12 @@
     "key": "application-schema",
     "name": "Application Configuration Schema",
     "description": "JSON schema for validating AI Fabrix application configuration files",
-    "version": "1.9.0",
+    "version": "1.10.0",
     "type": "schema",
     "category": "infrastructure",
     "author": "AI Fabrix Team",
     "createdAt": "2024-01-01T00:00:00Z",
-    "updatedAt": "2026-09-23T00:00:00Z",
+    "updatedAt": "2026-09-25T00:00:00Z",
     "compatibility": {
       "minVersion": "1.0.0",
       "maxVersion": "2.0.0",
@@ -30,6 +30,14 @@
       "external-datasource.schema.json"
     ],
     "changelog": [
+      {
+        "version": "1.10.0",
+        "date": "2026-09-25T00:00:00Z",
+        "changes": [
+          "Added optional top-level webSocketsEnabled: request Azure App Service WebSocket support for applications whose manifest opts in. Absent or false preserves existing deployment behavior."
+        ],
+        "breaking": false
+      },
       {
         "version": "1.9.0",
         "date": "2026-09-23T00:00:00Z",
@@ -231,6 +239,10 @@
       "type": "boolean",
       "description": "Whether application requires storage.Physical storage is mapped to /mnt/data/. Blob storage is mapped to SMB File share /data/{app-key}/."
     },
+    "webSocketsEnabled": {
+      "type": "boolean",
+      "description": "Whether the hosting provider must enable WebSocket upgrades for this application. Optional and false by default."
+    },
     "platforms": {
       "type": "array",
       "description": "Platform resolution: the target Azure resource group is matched against these entries, yielding {platform} and {platform.name}. Optional and independent of environments.",