feat(serenity): opt-in async provisioning for the 3 remaining skip-mode call sites (LLMO-7352/LLMO-7418 Phase 4)

Extends the opt-in `async: true` contract (PR-C, #3246) to the last 3
ensureSubworkspace call sites that were still fully synchronous:
createBrandForOrg's bare-create (no semrushMarket) branch, and activate's
pending->active and bare-reactivation branches.

These 3 sites use ensureSubworkspace's `createReadiness: 'skip'` mode
(persist the workspace pointer immediately after a single create call,
without polling for settle) rather than 'poll' mode, so they never had the
in-request settle-poll latency/timeout problem PR-A/PR-B/PR-C fixed for the
other 2 sites. This is deliberate hardening for consistency and defense
against a slow/hanging single Semrush create call, not a fix for a
still-open incident — the original LLMO-7352 symptom is already closed by
PR-A alone, since any workspace pointer's first real use (e.g. adding a
market) always runs the now-fail-fast pollUntilCreated first.

- createBrandForOrg's bare-create branch mirrors its sibling hasSemrushMarket
  branch exactly: async:true persists the row first, then hands off to
  provision-workspace-job with no chained job (no project to create).
- activate's two skip-mode branches each mint a provisioning attempt and
  chain to a new activate-brand-workspace-job, which does the one piece of
  business logic the generic worker doesn't: flipping (or re-affirming) the
  brand's status to active once the workspace is confirmed ready. One job
  handler covers both branches; `wasPending` in its metadata distinguishes a
  real pending->active transition (502 on save failure) from a no-op
  reactivation re-affirm (207).
- Existing guardAgainstConcurrentProvisioning calls on the sync branches are
  unchanged (still needed to protect a sync caller against a concurrent
  async attempt from another endpoint).

Stacked on PR-C (#3246). 30 new unit tests; 954 passing overall, 0
regressions.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Author: Iris Alexandrescu

docs/openapi/brands-v2-api.yaml

@@ -81,13 +81,14 @@ v2-brands-for-org:
               $ref: './schemas.yaml#/V2Brand'
       '202':
         description: |
-          PR-C (LLMO-7352/LLMO-7418): the request set `async: true` alongside
-          `semrushMarket`. The brand row is persisted immediately (visible,
+          The request set `async: true` (PR-C, LLMO-7352/LLMO-7418, alongside
+          `semrushMarket`; or Phase 4, same epic, on a bare create with no
+          market). The brand row is persisted immediately (visible,
           non-active — "Setting up", no workspace pointer yet); the
-          sub-workspace ready-check and the initial market's project create/
-          publish are enqueued to a background job chain instead of running
-          inline. Poll the returned `jobId` at `GET .../serenity/jobs/{jobId}`
-          for status + result.
+          sub-workspace ready-check — and, when `semrushMarket` was supplied,
+          the initial market's project create/publish — are enqueued to a
+          background job chain instead of running inline. Poll the returned
+          `jobId` at `GET .../serenity/jobs/{jobId}` for status + result.
         content:
           application/json:
             schema:
@@ -117,7 +118,7 @@ v2-brands-for-org:
             organization (`code: brand_site_org_mismatch`).
           - The brand's primary URL is already the primary URL (base site) of
             another brand in this organization.
-          - (PR-C, `async: true` only) a provisioning attempt is already in flight
+          - (`async: true` only) a provisioning attempt is already in flight
             for this brand (`error: semrushProvisioningInProgress`).
         headers:
           X-Error:

docs/openapi/serenity-api.yaml

@@ -1203,12 +1203,12 @@ v2-serenity-activate:
       intact; retry converges idempotently). An already-active brand re-supplying
       markets is never downgraded (a partial failure is reported as 207).
 
-      PR-C (LLMO-7352/LLMO-7418): when a primary URL/domain and markets are
-      present (the branch described above — NOT the sub-workspace-only pending
-      or bare-reactivation paths, which always stay synchronous), the caller may
-      set `async: true` to enqueue the whole batch to a background job chain
-      instead of running it inline; see the `202` response. Absent/false runs
-      synchronously as described above — this is opt-in only and not yet the
+      LLMO-7352/LLMO-7418: the caller may set `async: true` on ANY of the 3
+      branches — project activation (PR-C), the sub-workspace-only
+      pending→active flip, and bare reactivation (both Phase 4) — to enqueue
+      that branch's work to a background job chain instead of running it
+      inline; see the `202` response. Absent/false runs synchronously as
+      described above on every branch — this is opt-in only and not yet the
       default.
     operationId: activateSerenityBrand
     security:
@@ -1226,17 +1226,20 @@ v2-serenity-activate:
             schema: { $ref: './schemas.yaml#/SerenityActivateResponse' }
       '202':
         description: |
-          PR-C (LLMO-7352/LLMO-7418): the request set `async: true` on the
-          project-activation branch (primary URL + markets present). The whole
-          batch (sub-workspace ready-check, every market's project create/
-          publish, the site link, and the active flip) is enqueued to a
-          background job chain instead of running inline. Poll the returned
-          `jobId` at `GET .../serenity/jobs/{jobId}` for status + result — the
-          polling endpoint transparently follows the job chain to its
-          EFFECTIVE terminal hop, so `status` only reports `COMPLETED` once
-          the actual batch has run, not merely once the sub-workspace became
-          ready; on COMPLETED, `result` is the same body a synchronous
-          `200`/`207` would have returned.
+          The request set `async: true`. On the project-activation branch
+          (primary URL + markets present — PR-C), the whole batch
+          (sub-workspace ready-check, every market's project create/publish,
+          the site link, and the active flip) is enqueued to a background job
+          chain. On the sub-workspace-only pending→active or bare-reactivation
+          branches (Phase 4), only the sub-workspace ready-check + the status
+          flip are enqueued — there is no project/market work on those
+          branches. Either way, poll the returned `jobId` at
+          `GET .../serenity/jobs/{jobId}` for status + result — the polling
+          endpoint transparently follows the job chain to its EFFECTIVE
+          terminal hop, so `status` only reports `COMPLETED` once the actual
+          batch (or status flip) has run, not merely once the sub-workspace
+          became ready; on COMPLETED, `result` is the same body the branch's
+          own synchronous `200`/`207`/`502` would have returned.
         content:
           application/json:
             schema: { $ref: './schemas.yaml#/SerenityPromptsJobAccepted' }
@@ -1258,8 +1261,9 @@ v2-serenity-activate:
           outcomes — the operator must choose a different primary URL; (b)
           misconfiguration: the brand's sub-workspace equals the organization parent
           workspace (refused to avoid acting on the shared parent pool); or (c)
-          (PR-C, `async: true` only) a provisioning attempt is already in flight for
-          this brand (`error: semrush_provisioning_in_progress`) — retry shortly.
+          (`async: true` only, any branch) a provisioning attempt is already in
+          flight for this brand (`error: semrush_provisioning_in_progress`) —
+          retry shortly.
         content:
           application/json:
             schema:

src/controllers/brands.js

@@ -1729,6 +1729,12 @@ function BrandsController(ctx, log, env) {
     // hoisted so the catch can mark that persisted-but-not-yet-provisioning row visibly failed if
     // starting the attempt itself throws (see the catch's compensation).
     let asyncMarketProvisioning = null;
+    // Phase 4 (LLMO-7352/LLMO-7418): the bare-create (no semrushMarket) sibling of
+    // asyncMarketProvisioning above — same "non-null after the row is persisted means start an
+    // attempt" contract, just with no chained job (a bare sub-workspace has no project to create
+    // afterward). Mutually exclusive with asyncMarketProvisioning (they're set in sibling
+    // if/else branches of the same hasSemrushMarket check).
+    let asyncBareProvisioning = null;
 
     try {
       if (!hasText(spaceCatId)) {
@@ -1928,6 +1934,28 @@ function BrandsController(ctx, log, env) {
               languageCode: provisioned.languageCode,
             };
           }
+        } else if (validateAsync(brandData)) {
+          // B (LLMO-6405): sub-workspace-only active create — no market supplied, so
+          // no project is provisioned. Markets are added afterwards from the Markets
+          // tab. The brand is anchored by its primary site (baseSiteId, persisted by
+          // upsertBrand below) AND by its Semrush sub-workspace.
+          //
+          // Phase 4 (LLMO-7352/LLMO-7418): opt-in only (mirrors the hasSemrushMarket branch's own
+          // `async` flag above). Absent/false runs the EXACT bespoke synchronous
+          // provisionBrandSubworkspaceBare call this branch has always run. `async: true` persists
+          // the brand row FIRST (visible, active, no workspace pointer yet), then hands the bare
+          // sub-workspace provisioning off to provision-workspace-job — no chained job, since a
+          // bare create has no project to create once the workspace is ready.
+          //
+          // Resolved and validated HERE, before any write — same rationale as the
+          // hasSemrushMarket branch: a missing org workspace config must never leave a
+          // persisted, permanently-inert brand row behind.
+          const parentWorkspaceId = await resolveWorkspaceId(context, spaceCatId);
+          if (!parentWorkspaceId || !hasText(parentWorkspaceId)) {
+            return badRequest('Organization has no Semrush workspace configured');
+          }
+          provisionedBrandId = randomUUID();
+          asyncBareProvisioning = { parentWorkspaceId };
         } else {
           // B (LLMO-6405): sub-workspace-only active create — no market supplied, so
           // no project is provisioned. Markets are added afterwards from the Markets
@@ -2126,6 +2154,76 @@ function BrandsController(ctx, log, env) {
         }
       }
 
+      // Phase 4 (LLMO-7352/LLMO-7418): bare-create's async sibling of the block above — same
+      // shape, no chained job (no project to create once the workspace is ready).
+      if (asyncBareProvisioning) {
+        const asyncBrandId = /** @type {string} */ (provisionedBrandId);
+        const { parentWorkspaceId } = asyncBareProvisioning;
+        const attemptId = randomUUID();
+        let began;
+        try {
+          began = await beginProvisioningAttempt({
+            brandId: asyncBrandId,
+            attemptId,
+            postgrestClient,
+            updatedBy,
+          });
+        } catch (beginError) {
+          log.error('brands: failed to begin the provisioning attempt after brand row was persisted', {
+            brandId: asyncBrandId, error: beginError?.message,
+          });
+          await recordFreshBrandProvisioningStartFailure({
+            brandId: asyncBrandId,
+            error: 'Failed to start Semrush provisioning',
+            postgrestClient,
+          }).catch((failError) => {
+            log.error('brands: failed to record the provisioning-start failure itself', {
+              brandId: asyncBrandId, error: failError?.message,
+            });
+          });
+          throw beginError;
+        }
+        if (!began) {
+          return createResponse(
+            {
+              error: 'semrushProvisioningInProgress',
+              message: 'Unable to start Semrush provisioning for the new brand',
+            },
+            409,
+          );
+        }
+        try {
+          const job = await createAndEnqueueJob(context, {
+            jobType: PROVISION_WORKSPACE_JOB_TYPE,
+            metadata: {
+              brandId: asyncBrandId,
+              attemptId,
+              parentWorkspaceId,
+              title: brandData.name,
+            },
+          });
+          return createResponse(
+            { ...withSerenityState(created, serenityScopes), status: 'pending', jobId: job.getId() },
+            202,
+          );
+        } catch (enqueueError) {
+          log.error('brands: failed to start async Semrush provisioning after brand row was persisted', {
+            brandId: asyncBrandId, error: enqueueError?.message,
+          });
+          await promoteProvisioningFailed({
+            brandId: asyncBrandId,
+            attemptId,
+            error: 'Failed to start Semrush provisioning',
+            postgrestClient,
+          }).catch((failError) => {
+            log.error('brands: failed to record the provisioning-start failure itself', {
+              brandId: asyncBrandId, error: failError?.message,
+            });
+          });
+          throw enqueueError;
+        }
+      }
+
       return createResponse(withSerenityState(created, serenityScopes), 201);
     } catch (error) {
       if (error.code === 'brand_status_demotion_not_allowed') {

src/controllers/serenity.js

@@ -47,6 +47,7 @@ import { CLASSIFY_PROMPTS_JOB_TYPE } from '../support/serenity/handlers/classify
 import { PROVISION_WORKSPACE_JOB_TYPE } from '../support/serenity/handlers/provision-workspace-job.js';
 import { CREATE_MARKET_JOB_TYPE } from '../support/serenity/handlers/create-market-job.js';
 import { ACTIVATE_MARKETS_JOB_TYPE } from '../support/serenity/handlers/activate-markets-job.js';
+import { ACTIVATE_BRAND_WORKSPACE_JOB_TYPE } from '../support/serenity/handlers/activate-brand-workspace-job.js';
 import { ORIGIN_VALUE } from '../support/serenity/prompt-tags.js';
 import {
   BULK_TAGS_JOB_TYPE,
@@ -1617,6 +1618,41 @@ function SerenityController(context, log, env) {
         if (!existingSiteId) {
           throw new ErrorWithStatusCode(`Brand has no onboarded primary site: ${brandUuid}`, 400);
         }
+        // Phase 4 (LLMO-7352/LLMO-7418): opt-in only (mirrors this endpoint's own
+        // project-activation branch below, and createMarket's/createBrandForOrg's `async` flag).
+        // Absent/false runs the EXACT synchronous pending->active flip this branch has always
+        // run. `async: true` hands the sub-workspace-ensure + status flip off to the
+        // `provision-workspace-job` ->
+        // `serenity-activate-brand-workspace` job chain instead.
+        if (validateAsync(body)) {
+          const attemptId = randomUUID();
+          const began = await beginProvisioningAttempt({
+            brandId: brandUuid,
+            attemptId,
+            postgrestClient: ctx.dataAccess.services.postgrestClient,
+            updatedBy: 'serenity-activate',
+          });
+          if (!began) {
+            const err = new ErrorWithStatusCode(
+              'A Semrush sub-workspace provisioning attempt is already in progress for this '
+              + 'brand; please retry shortly.',
+              409,
+            );
+            err.code = 'semrush_provisioning_in_progress';
+            throw err;
+          }
+          const job = await createAndEnqueueJob(ctx, {
+            jobType: PROVISION_WORKSPACE_JOB_TYPE,
+            metadata: {
+              brandId: brandUuid,
+              attemptId,
+              parentWorkspaceId: auth.parentWorkspaceId ?? '',
+              chainedJobType: ACTIVATE_BRAND_WORKSPACE_JOB_TYPE,
+              chainedJobMetadata: { brandId: brandUuid, wasPending: true },
+            },
+          });
+          return accepted({ jobId: job.getId(), status: job.getStatus() });
+        }
         // PR-C guard (LLMO-7352/LLMO-7418): this branch stays synchronous, but a market-creating
         // endpoint may have an async provisioning attempt in flight for this SAME brand — without
         // this check, ensureSubworkspace below could independently create a second workspace.
@@ -1694,6 +1730,40 @@ function SerenityController(context, log, env) {
         if (generatePrompts) {
           throw new ErrorWithStatusCode('A primary URL is required to generate prompts', 400);
         }
+        // Phase 4 (LLMO-7352/LLMO-7418): opt-in only — see the wasPending branch above for the
+        // full rationale. `wasPending: false` in the chained metadata distinguishes this
+        // already-active no-op re-affirm from a real pending->active transition, so
+        // activate-brand-workspace-job.js's save-divergence handling matches this branch's own
+        // 207-not-502 contract.
+        if (validateAsync(body)) {
+          const attemptId = randomUUID();
+          const began = await beginProvisioningAttempt({
+            brandId: brandUuid,
+            attemptId,
+            postgrestClient: ctx.dataAccess.services.postgrestClient,
+            updatedBy: 'serenity-activate',
+          });
+          if (!began) {
+            const err = new ErrorWithStatusCode(
+              'A Semrush sub-workspace provisioning attempt is already in progress for this '
+              + 'brand; please retry shortly.',
+              409,
+            );
+            err.code = 'semrush_provisioning_in_progress';
+            throw err;
+          }
+          const job = await createAndEnqueueJob(ctx, {
+            jobType: PROVISION_WORKSPACE_JOB_TYPE,
+            metadata: {
+              brandId: brandUuid,
+              attemptId,
+              parentWorkspaceId: auth.parentWorkspaceId ?? '',
+              chainedJobType: ACTIVATE_BRAND_WORKSPACE_JOB_TYPE,
+              chainedJobMetadata: { brandId: brandUuid, wasPending: false },
+            },
+          });
+          return accepted({ jobId: job.getId(), status: job.getStatus() });
+        }
         // PR-C guard (LLMO-7352/LLMO-7418): see the wasPending branch above for rationale.
         await guardAgainstConcurrentProvisioning(
           brandUuid,

src/serenity-prompt-classification/index.js

@@ -47,6 +47,10 @@ import {
   activateMarketsJobHandler,
   ACTIVATE_MARKETS_JOB_TYPE,
 } from '../support/serenity/handlers/activate-markets-job.js';
+import {
+  activateBrandWorkspaceJobHandler,
+  ACTIVATE_BRAND_WORKSPACE_JOB_TYPE,
+} from '../support/serenity/handlers/activate-brand-workspace-job.js';
 import {
   isRateLimited,
   isSemrushTransportError,
@@ -119,7 +123,9 @@ export const vaultOpts = {
  * sub-workspace provisioning lives in `../support/serenity/handlers/provision-workspace-job.js`;
  * and PR-C's two chained market-creation phases (workspace ready -> create the market/run the
  * activate batch against it) live in `../support/serenity/handlers/create-market-job.js` and
- * `../support/serenity/handlers/activate-markets-job.js`. All five are registered below.
+ * `../support/serenity/handlers/activate-markets-job.js`; Phase 4's brand-status-flip half of
+ * `activate`'s two remaining "skip"-mode branches lives in
+ * `../support/serenity/handlers/activate-brand-workspace-job.js`. All six are registered below.
  *
  * @type {Record<string, (context: object, job: object,
  *   accessToken: string) => Promise<object>>}
@@ -130,6 +136,7 @@ const HANDLERS = {
   [PROVISION_WORKSPACE_JOB_TYPE]: provisionWorkspaceHandler,
   [CREATE_MARKET_JOB_TYPE]: createMarketJobHandler,
   [ACTIVATE_MARKETS_JOB_TYPE]: activateMarketsJobHandler,
+  [ACTIVATE_BRAND_WORKSPACE_JOB_TYPE]: activateBrandWorkspaceJobHandler,
 };
 
 const TRANSIENT_NETWORK_ERROR_CODES = new Set([