fix(serenity): job-status polling follows the chain to its effective terminal hop (LLMO-7418 external-review Finding 8)

The runner marks the ORIGINAL AsyncJob COMPLETED on any non-throwing handler
return, including a self-requeue ({ requeuedJobId }, workspace not yet
settled) or a chain hand-off ({ provisioningStatus: 'ready', chainedJobId },
the chained market-create/activate work not yet started). getPromptsJobStatus
(the same handler serving the generic /serenity/jobs/:jobId polling alias)
just echoed that first hop's status/result verbatim, so a client polling
during a chain saw a premature "COMPLETED" the moment the FIRST hop merely
handed off, with no market created and no way to tell the difference from a
genuinely finished request. The frontend consumers built against this
contract this session all resolve on the first COMPLETED with no chain
awareness.

Fix is entirely backend-scoped, so no frontend change is needed: when the
polled job is COMPLETED and its result carries chainedJobId or
requeuedJobId, follow that pointer (recursively, capped at 10 hops against a
corrupt/cyclic chain) and report the EFFECTIVE terminal hop's status/result/
error instead. jobId/jobType in the response still reflect the ORIGINALLY-
requested job, so a caller polling a fixed URL never needs to learn
intermediate hop ids. Updated the two OpenAPI descriptions that previously
overclaimed "result is the same body a synchronous 2xx would have
returned" without qualifying that this only became true once the whole
chain, not just the first hop, had run.

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

Author: Iris Alexandrescu

docs/openapi/serenity-api.yaml

@@ -597,10 +597,13 @@ v2-serenity-markets:
           sub-workspace-mode brand only). The sub-workspace-ready check and the
           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 — on COMPLETED,
-          `result` is the same body a synchronous `201` would have returned.
-          Absent/false runs synchronously as today; this is opt-in only and not
-          yet the default.
+          `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
+          market create/publish has run, not merely once the sub-workspace
+          became ready; on COMPLETED, `result` is the same body a synchronous
+          `201` would have returned. Absent/false runs synchronously as
+          today; this is opt-in only and not yet the default.
         content:
           application/json:
             schema: { $ref: './schemas.yaml#/SerenityPromptsJobAccepted' }
@@ -1228,9 +1231,12 @@ v2-serenity-activate:
           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 — on
-          COMPLETED, `result` is the same body a synchronous `200`/`207` would
-          have 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.
         content:
           application/json:
             schema: { $ref: './schemas.yaml#/SerenityPromptsJobAccepted' }

src/controllers/serenity.js

@@ -1978,7 +1978,7 @@ function SerenityController(context, log, env) {
       if (!AsyncJob || typeof AsyncJob.findById !== 'function') {
         return internalServerError('AsyncJob data-access not available');
       }
-      const job = await AsyncJob.findById(jobId);
+      let job = await AsyncJob.findById(jobId);
       // A job that does not exist AND a job that belongs to another brand answer
       // the same 404: whether the id is unknown or simply not yours is not the
       // caller's business (mirrors authorize's brand-not-found contract).
@@ -1987,6 +1987,31 @@ function SerenityController(context, log, env) {
         return notFound(`Job not found: ${jobId}`);
       }
       const metadata = job.getMetadata?.() ?? {};
+      // Follow a chain/requeue to its EFFECTIVE terminal hop (LLMO-7418 external-review
+      // Finding 8): the runner marks the ORIGINAL job COMPLETED on any non-throwing handler
+      // return, including a self-requeue (`{ requeuedJobId }`, workspace not yet settled) or a
+      // chain hand-off (`{ provisioningStatus: 'ready', chainedJobId }`, the chained market-
+      // create/activate work not yet started) — neither means the real work actually finished.
+      // Without this, a caller polling the FIRST hop's id sees a premature COMPLETED the moment
+      // the chain merely starts, not when it actually ends. `jobId`/`jobType` below still report
+      // the ORIGINALLY-requested job's identity — only status/result/error follow the chain, so a
+      // caller polling a fixed URL never needs to learn about intermediate hop ids. Bounded to
+      // guard against a corrupt/cyclic chain; a dangling pointer (an id the chain names but that
+      // no longer resolves) simply stops following and reports the last hop actually found.
+      const MAX_CHAIN_FOLLOW_HOPS = 10;
+      for (let hops = 0; job.getStatus() === 'COMPLETED' && hops < MAX_CHAIN_FOLLOW_HOPS; hops += 1) {
+        const hopResult = job.getResult?.();
+        const nextJobId = hopResult?.chainedJobId || hopResult?.requeuedJobId;
+        if (!nextJobId) {
+          break;
+        }
+        // eslint-disable-next-line no-await-in-loop
+        const nextJob = await AsyncJob.findById(nextJobId);
+        if (!nextJob) {
+          break;
+        }
+        job = nextJob;
+      }
       /** @type {'classifyPrompts' | 'bulkTags' | 'tagImpact'} */
       let publicJobType = 'classifyPrompts';
       if (metadata.jobType === BULK_TAGS_JOB_TYPE) {
@@ -2010,7 +2035,9 @@ function SerenityController(context, log, env) {
       const error = status === 'FAILED' ? publicJobError(job.getError?.()) : null;
       return createResponse(
         {
-          jobId: job.getId(),
+          // The ORIGINALLY-requested id, never a followed hop's — the caller polls a fixed URL
+          // and never needs to learn about intermediate chain/requeue job ids.
+          jobId,
           jobType: publicJobType,
           status,
           result,

test/controllers/serenity.test.js

@@ -3034,6 +3034,130 @@ describe('SerenityController', () => {
         );
         expect(response.status).to.equal(400);
       });
+
+      // LLMO-7418 external-review Finding 8: a self-requeue or chained hand-off marks the FIRST
+      // hop COMPLETED immediately, even though the real work hasn't run yet. These tests confirm
+      // the endpoint follows the chain to its effective terminal status instead.
+      describe('chain/requeue following (LLMO-7418 external-review Finding 8)', () => {
+        const CHAINED_JOB = 'aaaaaaaa-1111-2222-3333-444444444444';
+        const FINAL_JOB = 'bbbbbbbb-1111-2222-3333-444444444444';
+
+        function ctxWithChain(jobsById, { jobId = JOB } = {}) {
+          const ctx = fakeContext({ params: { jobId } });
+          ctx.dataAccess.AsyncJob = {
+            findById: sinon.stub().callsFake((id) => Promise.resolve(jobsById[id] ?? null)),
+          };
+          return ctx;
+        }
+
+        it('follows a chainedJobId to the market-create job\'s own terminal status, not the provisioning job\'s premature COMPLETED', async () => {
+          const controller = SerenityController({ env: {} }, fakeLog(), {});
+          const finalResult = { status: 201, body: { projectId: 'proj-1' } };
+          const ctx = ctxWithChain({
+            [JOB]: makeAsyncJob({
+              id: JOB,
+              status: 'COMPLETED',
+              result: { provisioningStatus: 'ready', chainedJobId: CHAINED_JOB },
+            }),
+            [CHAINED_JOB]: makeAsyncJob({
+              id: CHAINED_JOB, status: 'COMPLETED', result: finalResult,
+            }),
+          });
+
+          const response = await controller.getPromptsJobStatus(ctx);
+          const body = await readBody(response);
+
+          // The ORIGINALLY-requested id is echoed back, not the chained job's.
+          expect(body.jobId).to.equal(JOB);
+          expect(body.status).to.equal('COMPLETED');
+          expect(body.result).to.deep.equal(finalResult);
+        });
+
+        it('follows a requeuedJobId and reports IN_PROGRESS while the chain is still settling', async () => {
+          const controller = SerenityController({ env: {} }, fakeLog(), {});
+          const ctx = ctxWithChain({
+            [JOB]: makeAsyncJob({
+              id: JOB, status: 'COMPLETED', result: { requeuedJobId: CHAINED_JOB },
+            }),
+            [CHAINED_JOB]: makeAsyncJob({ id: CHAINED_JOB, status: 'IN_PROGRESS', result: null }),
+          });
+
+          const response = await controller.getPromptsJobStatus(ctx);
+          const body = await readBody(response);
+
+          expect(body.jobId).to.equal(JOB);
+          expect(body.status).to.equal('IN_PROGRESS');
+          expect(body.result).to.equal(null);
+        });
+
+        it('follows a multi-hop chain (requeue then chained job) to its final terminal status', async () => {
+          const controller = SerenityController({ env: {} }, fakeLog(), {});
+          const finalResult = { status: 201, body: {} };
+          const ctx = ctxWithChain({
+            [JOB]: makeAsyncJob({
+              id: JOB, status: 'COMPLETED', result: { requeuedJobId: CHAINED_JOB },
+            }),
+            [CHAINED_JOB]: makeAsyncJob({
+              id: CHAINED_JOB,
+              status: 'COMPLETED',
+              result: { provisioningStatus: 'ready', chainedJobId: FINAL_JOB },
+            }),
+            [FINAL_JOB]: makeAsyncJob({ id: FINAL_JOB, status: 'COMPLETED', result: finalResult }),
+          });
+
+          const response = await controller.getPromptsJobStatus(ctx);
+          const body = await readBody(response);
+
+          expect(body.status).to.equal('COMPLETED');
+          expect(body.result).to.deep.equal(finalResult);
+        });
+
+        it('reports the last hop actually found when the chain names a dangling job id', async () => {
+          const controller = SerenityController({ env: {} }, fakeLog(), {});
+          const ctx = ctxWithChain({
+            [JOB]: makeAsyncJob({
+              id: JOB, status: 'COMPLETED', result: { chainedJobId: 'does-not-exist' },
+            }),
+          });
+
+          const response = await controller.getPromptsJobStatus(ctx);
+          const body = await readBody(response);
+
+          expect(response.status).to.equal(200);
+          expect(body.jobId).to.equal(JOB);
+          expect(body.status).to.equal('COMPLETED');
+          expect(body.result).to.deep.equal({ chainedJobId: 'does-not-exist' });
+        });
+
+        it('does not follow a chain when the first hop is not COMPLETED', async () => {
+          const controller = SerenityController({ env: {} }, fakeLog(), {});
+          const ctx = ctxWithChain({
+            [JOB]: makeAsyncJob({ id: JOB, status: 'IN_PROGRESS', result: null }),
+            [CHAINED_JOB]: makeAsyncJob({ id: CHAINED_JOB, status: 'COMPLETED', result: {} }),
+          });
+
+          const response = await controller.getPromptsJobStatus(ctx);
+          const body = await readBody(response);
+
+          expect(body.status).to.equal('IN_PROGRESS');
+        });
+
+        it('stops following after the hop cap, never loops forever on a cyclic chain', async () => {
+          const controller = SerenityController({ env: {} }, fakeLog(), {});
+          const jobA = 'cccccccc-1111-2222-3333-444444444444';
+          const jobB = 'dddddddd-1111-2222-3333-444444444444';
+          const ctx = ctxWithChain({
+            [JOB]: makeAsyncJob({ id: JOB, status: 'COMPLETED', result: { chainedJobId: jobA } }),
+            [jobA]: makeAsyncJob({ id: jobA, status: 'COMPLETED', result: { chainedJobId: jobB } }),
+            [jobB]: makeAsyncJob({ id: jobB, status: 'COMPLETED', result: { chainedJobId: jobA } }),
+          });
+
+          const response = await controller.getPromptsJobStatus(ctx);
+
+          // Must resolve (not hang) and still answer 200 with SOME terminal status.
+          expect(response.status).to.equal(200);
+        });
+      });
     });
 
     it('builds a working type classifier from the brand name + aliases and passes it to the handler (serenity-docs#31)', async () => {