@qawolf/ci-sdk 1.1.0 → 1.2.0

package/README.md

@@ -14,6 +14,7 @@ to determine the status of your CI/CD step/job/action.
 - [Notify Deployment](#notify-deployment)
 - [Notify Preview Deployment (Pull Request / Merge Request Testing)](#notify-preview)
 - [Poll for CI Greenlight Status](#ci-greenlight)
+- [Advanced: Poll with Custom Control (Iterator)](#ci-greenlight-iterator)
 - [Upload Run Input Artifacts](#upload-artifacts)
 - [Requirements](#requirements)
 - [Versioning](#versioning)
@@ -180,6 +181,127 @@ const { pollCiGreenlightStatus } = makeQaWolfSdk({
 })();
 ```
 
+<a id="ci-greenlight-iterator"></a>
+
+## Advanced: Poll with Custom Control (Iterator)
+
+For advanced use cases where you need fine-grained control over the polling lifecycle, use `makePollCiGreenlightStatusIterator`. This async generator gives you full control to implement custom logic such as:
+
+- Stop polling early based on time limits (e.g., "wait max 10 minutes in review then proceed")
+- Stop polling based on bug counts (e.g., "proceed if only 3 or fewer blocking bugs")
+- Implement custom logging or monitoring at each poll iteration
+- Access detailed bug data during the "under review" stage
+
+> ℹ️ [See the API documentation page for this endpoint](https://qawolf.notion.site/1b170576efea411fa785842a71e7c99e).
+
+### Example: Early Exit with Custom Logic
+
+> ⚠️ **Important**: When using the iterator, ensure you handle all run stages in your switch statement. The `default` case with `satisfies never` provides compile-time safety - if a new stage is added, TypeScript will error. This prevents silently passing your CI job while ignoring error conditions.
+
+```ts
+import { makeQaWolfSdk } from "@qawolf/ci-sdk";
+
+const { makePollCiGreenlightStatusIterator } = makeQaWolfSdk({
+  apiKey: "qawolf_xxxxx",
+});
+
+(async () => {
+  let underReviewStartTime: number | null = null;
+
+  const iterator = makePollCiGreenlightStatusIterator({
+    runId: "your-run-id",
+  });
+
+  for await (const iteration of iterator) {
+    // Check if the iterator yielded an abort result
+    if (iteration.isAborted) {
+      console.error(`Poll aborted: ${iteration.abortReason}`);
+      process.exit(1);
+    }
+
+    // Handle status iterations
+    const { status, stageChanged } = iteration;
+
+    switch (status.runStage) {
+      case "initializing":
+        console.log(`Run stage: ${status.runStage}`);
+        break;
+
+      case "underReview": {
+        // Track when we first enter underReview
+        if (stageChanged) {
+          underReviewStartTime = Date.now();
+          console.log(`Run stage: ${status.runStage}`);
+        }
+
+        const timeInUnderReview = underReviewStartTime
+          ? Date.now() - underReviewStartTime
+          : 0;
+
+        // Option 1: Stop after 10 minutes in review
+        if (timeInUnderReview > 10 * 60 * 1000) {
+          console.log("10 minutes in review, proceeding with deployment");
+          // Decide whether to fail CI based on your criteria
+          if (status.blockingBugsCount > 5) {
+            console.log("Too many blocking bugs, failing CI");
+            process.exit(1);
+          }
+          break;
+        }
+
+        // Option 2: Stop if bug count is acceptable
+        if (status.blockingBugsCount <= 3) {
+          console.log(
+            `Only ${status.blockingBugsCount} blocking bugs, acceptable to proceed`,
+          );
+          break;
+        }
+        break;
+      }
+
+      case "completed":
+        console.log(`Completed with greenlight: ${status.greenlight}`);
+        if (!status.greenlight) {
+          console.log("Run failed, blocking bugs found");
+          process.exit(1);
+        }
+        console.log("Run passed successfully");
+        return; // Exit the loop
+
+      case "canceled":
+        console.log("Run was canceled");
+        process.exit(1);
+
+      default:
+        // Exhaustive check - TypeScript will error if a case is missing
+        status.runStage satisfies never;
+        throw new Error(`Unexpected run stage: ${status.runStage}`);
+    }
+  }
+})();
+```
+
+### Yielded Iteration Object
+
+The iterator yields a discriminated union that can be either a status update or an abort notification:
+
+**Status Iteration** (`isAborted: false`):
+
+- `isAborted`: `false` - Indicates a normal status update
+- `status`: The current `CiGreenlightStatus` from the API
+- `previousStatus`: The status from the previous iteration (undefined on first iteration)
+- `stageChanged`: Boolean indicating if the run stage changed from the previous iteration
+- `elapsedMs`: Milliseconds elapsed since polling started
+
+**Aborted Iteration** (`isAborted: true`):
+
+- `isAborted`: `true` - Indicates the polling was aborted
+- `abortReason`: String indicating why polling was aborted (e.g., `"poll-timed-out"`, `"run-canceled"`, `"network-error"`, `"4XX-client-error"`, `"5XX-server-error"`)
+- `httpStatus`: HTTP status code if applicable, otherwise `undefined`
+- `elapsedMs`: Milliseconds elapsed since polling started
+
+**Important**: Always check `iteration.isAborted` to determine which type of result you received. When `isAborted === true`, you should handle the abort reason and exit appropriately.
+
 <a id="upload-artifacts"></a>
 
 ## Upload Run Input Artifacts
@@ -294,6 +416,10 @@ This package follows the [SemVer](https://semver.org/) versioning scheme. Additi
 
 # Changelog
 
+## v1.2.0
+
+- New `makePollCiGreenlightStatusIterator` async generator function for advanced polling control with custom early-exit logic
+
 ## v1.1.0
 
 - New `ephemeralEnvironment` parameter for `attemptNotifyDeploy`

package/dist/index.cjs

@@ -38,49 +38,7 @@ var defaultServiceBase = "https://app.qawolf.com/";
 
 // package.json
 var package_default = {
-  name: "@qawolf/ci-sdk",
-  version: "1.1.0",
-  private: false,
-  description: "A simple SDK for interacting with QAWolf in CI scripts.",
-  keywords: [],
-  license: "MIT",
-  author: "Jules Sam. Randolph<jules@qawolf.com>",
-  sideEffects: false,
-  type: "module",
-  exports: {
-    ".": {
-      types: "./dist/index.d.ts",
-      require: "./dist/index.cjs",
-      import: "./dist/index.js",
-      default: "./dist/index.js"
-    }
-  },
-  files: [
-    "/dist",
-    "/README.md"
-  ],
-  scripts: {
-    build: "tsup src/index.ts --format esm,cjs --dts --clean --splitting --treeshake --sourcemap --outDir dist --target es2022",
-    lint: "dpdm --exit-code circular:1 --no-tree --no-warning --transform --include='.*' --exclude='/(dist|node_modules)/' '**/*' && eslint . --ext cjs,cts,js,jsx,mjs,ts,tsx --quiet && prettier --check .",
-    "lint:fix": "eslint . --ext cjs,cts,js,jsx,mjs,ts,tsx --fix --quiet && prettier --log-level=warn --write .",
-    "lint:warnings": "eslint . --ext cjs,cts,js,jsx,mjs,ts,tsx",
-    prepublishOnly: "nx run ci-sdk:build",
-    test: 'NODE_OPTIONS="--experimental-vm-modules" NODE_NO_WARNINGS=1 jest',
-    "tsc:check": "tsc --noEmit"
-  },
-  dependencies: {
-    "@qawolf/ci-utils": "^1.0.0",
-    "@sinonjs/fake-timers": "^10.3.0",
-    slugify: "^1.6.6",
-    tslib: "^2.6.2"
-  },
-  devDependencies: {
-    tsup: "8.3.5"
-  },
-  engines: {
-    node: ">=20"
-  }
-};
+  version: "1.2.0"};
 
 // src/lib/sdk/defaults/userAgent.ts
 var defaultUserAgent = `ci-sdk/${package_default.version}`;
@@ -103,8 +61,8 @@ async function logFetchError({ log, methodName, response }) {
       };
     } catch {
       return {
-        eventId: undefined,
-        failureMessage: undefined
+        eventId: void 0,
+        failureMessage: void 0
       };
     }
   })();
@@ -151,7 +109,7 @@ async function attemptNotifyDeploy(deps, apiConfig, config) {
     log.error(`\u{1F6AB} Network error from deploy_success, aborting.`);
     return {
       abortReason: "network-error",
-      httpStatus: undefined,
+      httpStatus: void 0,
       outcome: "aborted"
     };
   }
@@ -160,7 +118,7 @@ __name(attemptNotifyDeploy, "attemptNotifyDeploy");
 async function handleErrorResponse(response, log) {
   const status = response.status;
   let abortReason;
-  if (status === undefined) abortReason = "network-error";
+  if (status === void 0) abortReason = "network-error";
   else if (status === 401) abortReason = "401-unauthorized";
   else if (status === 403) abortReason = "403-forbidden";
   else if (status >= 500) abortReason = "5XX-server-error";
@@ -190,10 +148,10 @@ async function handleSuccessResponse(data, log) {
       return {
         environmentId: environment.id,
         outcome: "success",
-        runId: undefined
+        runId: void 0
       };
     }
-    log.error(`\u{1F6AB} No trigger matched the request. Please contact support.`);
+    log.error(`\u{1F6AB} No trigger matched the request. Please make sure there is at least one active test in the QA Wolf environment, or contact support.`);
     return {
       failReason: "no-matched-trigger",
       outcome: "failed"
@@ -400,6 +358,29 @@ async function generateSignedUrlForTempTeamStorage(deps, apiConfig, config) {
 }
 __name(generateSignedUrlForTempTeamStorage, "generateSignedUrlForTempTeamStorage");
 
+// src/lib/sdk/domain/pollCiGreenlight/buildCompletedRunResult.ts
+function buildCompletedRunResult(status) {
+  if (status.greenlight) return {
+    greenlightStatus: status,
+    outcome: "success"
+  };
+  else return {
+    greenlightStatus: status,
+    outcome: "failed"
+  };
+}
+__name(buildCompletedRunResult, "buildCompletedRunResult");
+
+// src/lib/sdk/domain/pollCiGreenlight/consts.ts
+var pollCiGreenlightDefaults = {
+  abortOnSuperseded: false,
+  maxRetries: 10,
+  pollTimeout: 120 * 60 * 1e3,
+  retryInterval: 10 * 1e3,
+  runInProgressInterval: 30 * 1e3,
+  runUnderReviewInterval: 60 * 1e3
+};
+
 // src/lib/api/ci-greenlight.ts
 async function fetchCiGreenlightStatus({ apiKey, serviceBase, userAgent }, { runId }, { fetch: localFetch, log }) {
   try {
@@ -455,56 +436,61 @@ async function fetchCiGreenlightStatus({ apiKey, serviceBase, userAgent }, { run
 }
 __name(fetchCiGreenlightStatus, "fetchCiGreenlightStatus");
 
-// src/lib/sdk/domain/poll-ci-greenlight.ts
-var safeDefaults = {
-  abortOnSuperseded: false,
-  maxRetries: 10,
-  pollTimeout: 120 * 60 * 1e3,
-  retryInterval: 10 * 1e3,
-  runInProgressInterval: 30 * 1e3,
-  runUnderReviewInterval: 60 * 1e3
-};
-async function pollCiGreenlightStatus(deps, apiConfig, { onRunStageChanged = /* @__PURE__ */ __name(() => undefined, "onRunStageChanged"), runId, ...pollConfig }) {
-  let retries = 0;
+// src/lib/sdk/domain/pollCiGreenlight/iterator.ts
+async function* makePollCiGreenlightStatusIterator(deps, apiConfig, { runId, ...pollConfig }) {
   const { log } = deps;
-  const { abortOnSuperseded = safeDefaults.abortOnSuperseded, maxRetries = safeDefaults.maxRetries, pollTimeout = safeDefaults.pollTimeout, retryInterval = safeDefaults.retryInterval, runInProgressInterval = safeDefaults.runInProgressInterval, runUnderReviewInterval = safeDefaults.runUnderReviewInterval } = pollConfig;
-  let currentStatus = undefined;
+  const { maxRetries = pollCiGreenlightDefaults.maxRetries, pollTimeout = pollCiGreenlightDefaults.pollTimeout, retryInterval = pollCiGreenlightDefaults.retryInterval, runInProgressInterval = pollCiGreenlightDefaults.runInProgressInterval, runUnderReviewInterval = pollCiGreenlightDefaults.runUnderReviewInterval } = pollConfig;
+  let retries = 0;
+  let previousStatus = void 0;
   const startedAt = Date.now();
-  let hasTimedOut = false;
-  while (!(hasTimedOut = Date.now() - startedAt > pollTimeout)) {
+  while (Date.now() - startedAt <= pollTimeout) {
     const responseState = await fetchCiGreenlightStatus(apiConfig, {
       runId
     }, deps);
+    const elapsedMs = Date.now() - startedAt;
     if (!responseState.ok && !responseState.canRetry) {
-      log.error(`\u{1F6AB} Unrecoverable error (status ${responseState.httpStatus}) from CI greenlight, aborting.`);
-      return {
+      yield {
         abortReason: "4XX-client-error",
+        elapsedMs,
         httpStatus: responseState.httpStatus,
-        outcome: "aborted"
+        isAborted: true
       };
+      return;
     }
     if (!responseState.ok) {
       retries += 1;
+      const { errorType, httpStatus } = responseState;
       if (retries > maxRetries) {
-        log.error(`\u{1F6AB} Unrecoverable error${responseState.httpStatus ? ` (status ${responseState.httpStatus})` : ""} from CI greenlight, aborting after ${maxRetries} attempts.`);
-        if (responseState.errorType === "network") {
-          return {
-            abortReason: "network-error",
-            httpStatus: undefined,
-            outcome: "aborted"
-          };
+        switch (errorType) {
+          case "network":
+            yield {
+              abortReason: "network-error",
+              elapsedMs,
+              httpStatus: void 0,
+              isAborted: true
+            };
+            break;
+          case "not-found":
+            yield {
+              abortReason: "404-run-not-found",
+              elapsedMs,
+              httpStatus: httpStatus ?? 404,
+              isAborted: true
+            };
+            break;
+          case "server":
+            yield {
+              abortReason: "5XX-server-error",
+              elapsedMs,
+              httpStatus: httpStatus ?? 500,
+              isAborted: true
+            };
+            break;
+          default:
+            throw Error(`Unexpected error type: ${errorType}`);
         }
-        let abortReason = "XXX-other-http-code";
-        if (responseState.errorType === "not-found") abortReason = "404-run-not-found";
-        else if (responseState.errorType === "server") abortReason = "5XX-server-error";
-        else ;
-        return {
-          abortReason,
-          httpStatus: responseState.httpStatus,
-          outcome: "aborted"
-        };
+        return;
       }
-      const { errorType, httpStatus } = responseState;
       const retryLabel = `${httpStatus ? ` (status ${httpStatus})` : ""}, will try again... (${retries}/${maxRetries})`;
       if (errorType === "network") log.warn(`\u274C Network error${retryLabel}`);
       else if (errorType === "not-found") log.info(`\u23F3 Run not found${retryLabel}`);
@@ -514,89 +500,231 @@ async function pollCiGreenlightStatus(deps, apiConfig, { onRunStageChanged = /*
     }
     retries = 0;
     const { greenlightStatus } = responseState;
-    const previousStatus = currentStatus;
-    currentStatus = greenlightStatus;
-    if (!previousStatus || previousStatus.runStage !== greenlightStatus.runStage) {
-      try {
-        await onRunStageChanged(greenlightStatus, previousStatus);
-      } catch (e) {
-        log.error(`Error in onRunStageChanged callback`, e);
-      }
-    }
-    const urlInfo = `See ${greenlightStatus.relevantRunUrl}`;
-    const { greenlight, relevantRunId, relevantRunUrl, relevantRunWithBugsUrl, rootRunId, rootRunUrl, runStage } = greenlightStatus;
-    if (rootRunId !== relevantRunId) {
-      const supersedingDetails = `
-  - Root: ${rootRunUrl}
-  - Superseding: ${relevantRunUrl}`;
-      if (abortOnSuperseded) {
-        log.warn(`\u274C Aborting due to superseded run (option 'abortOnSuperseded' is enabled).${supersedingDetails}`);
-        return {
-          abortReason: "superseded-run",
-          httpStatus: undefined,
-          outcome: "aborted"
+    const stageChanged = !previousStatus || previousStatus.runStage !== greenlightStatus.runStage;
+    const isFailedTerminalStage = greenlightStatus.runStage === "canceled" || greenlightStatus.runStage === "completed" && greenlightStatus.greenlight === false;
+    yield {
+      elapsedMs,
+      isAborted: false,
+      isFailedTerminalStage,
+      previousStatus,
+      stageChanged,
+      status: greenlightStatus
+    };
+    previousStatus = greenlightStatus;
+    switch (greenlightStatus.runStage) {
+      case "canceled": {
+        yield {
+          abortReason: "run-canceled",
+          elapsedMs,
+          httpStatus: void 0,
+          isAborted: true
         };
+        return;
       }
-      log.info(`Root run was superseded:${supersedingDetails}`);
+      case "completed":
+        return;
+      case "initializing":
+        await sleep(runInProgressInterval);
+        break;
+      case "underReview":
+        await sleep(runUnderReviewInterval);
+        break;
+      default:
+        throw Error(`Unexpected run stage: ${greenlightStatus}`);
     }
-    if (runStage === "completed") {
-      const { blockingBugsCount, blockingBugUrls = [], nonBlockingBugsCount, nonBlockingBugUrls = [] } = greenlightStatus;
-      const blockingBugList = blockingBugUrls.map((url) => `
+  }
+  yield {
+    abortReason: "poll-timed-out",
+    elapsedMs: Date.now() - startedAt,
+    httpStatus: void 0,
+    isAborted: true
+  };
+  return;
+}
+__name(makePollCiGreenlightStatusIterator, "makePollCiGreenlightStatusIterator");
+
+// src/lib/sdk/domain/pollCiGreenlight/logging.ts
+function buildSuccessLogMessage(status) {
+  const { nonBlockingBugsCount, relevantRunUrl } = status;
+  const urlInfo = `See ${relevantRunUrl}`;
+  return `\u2705 Run passed and no blocking bugs found${nonBlockingBugsCount > 0 ? ` and ${nonBlockingBugsCount} non-blocking bug${pluralize(nonBlockingBugsCount)} found` : ""}.
+${urlInfo}`;
+}
+__name(buildSuccessLogMessage, "buildSuccessLogMessage");
+function buildFailedLogMessage(status) {
+  const { blockingBugsCount, blockingBugUrls = [], nonBlockingBugsCount, nonBlockingBugUrls = [], relevantRunWithBugsUrl } = status;
+  const blockingBugList = blockingBugUrls.map((url) => `
 \u2022 ${url}`).join("");
-      const nonBlockingBugList = nonBlockingBugUrls.map((url) => `
+  const nonBlockingBugList = nonBlockingBugUrls.map((url) => `
 \u2022 ${url}`).join("");
-      const bugsListInText = `${blockingBugUrls.length > 0 ? `
+  const bugsListInText = `${blockingBugUrls.length > 0 ? `
 BLOCKING BUGS:${blockingBugList}` : ""}${nonBlockingBugUrls.length > 0 ? `
 NON BLOCKING BUGS:${nonBlockingBugList}` : ""}`;
-      if (greenlight) {
-        log.info(`\u2705 Run passed and no blocking bugs found${nonBlockingBugsCount > 0 ? ` and ${nonBlockingBugsCount} non-blocking bug${pluralize(nonBlockingBugsCount)} found` : ""}.
-${urlInfo}`);
-        return {
-          greenlightStatus,
-          outcome: "success"
-        };
-      } else {
-        log.warn(`\u274C Run failed and ${blockingBugsCount} blocking bug${pluralize(blockingBugsCount)} found${nonBlockingBugsCount ? ` and ${nonBlockingBugsCount} non-blocking bug${pluralize(nonBlockingBugsCount)}` : ""}.
+  return `\u274C Run failed and ${blockingBugsCount} blocking bug${pluralize(blockingBugsCount)} found${nonBlockingBugsCount ? ` and ${nonBlockingBugsCount} non-blocking bug${pluralize(nonBlockingBugsCount)}` : ""}.
 See ${relevantRunWithBugsUrl}
 You may review the priority of certain bugs to mark these non-blocking and retry the job.
-` + bugsListInText);
-        return {
-          greenlightStatus,
-          outcome: "failed"
-        };
-      }
-    }
-    if (runStage === "canceled") {
-      log.info(`\u{1F6AB} Run was canceled. Aborting... Please contact support.
-${urlInfo}`);
+` + bugsListInText;
+}
+__name(buildFailedLogMessage, "buildFailedLogMessage");
+function buildSupersededAbortLogMessage(rootRunUrl, relevantRunUrl) {
+  const supersedingDetails = `
+  - Root: ${rootRunUrl}
+  - Superseding: ${relevantRunUrl}`;
+  return `\u274C Aborting due to superseded run (option 'abortOnSuperseded' is enabled).${supersedingDetails}`;
+}
+__name(buildSupersededAbortLogMessage, "buildSupersededAbortLogMessage");
+function buildSupersededContinueLogMessage(rootRunUrl, relevantRunUrl) {
+  const supersedingDetails = `
+  - Root: ${rootRunUrl}
+  - Superseding: ${relevantRunUrl}`;
+  return `Root run was superseded:${supersedingDetails}`;
+}
+__name(buildSupersededContinueLogMessage, "buildSupersededContinueLogMessage");
+function buildRunStageLogMessage(runStage, relevantRunUrl) {
+  const urlInfo = `See ${relevantRunUrl}`;
+  switch (runStage) {
+    case "canceled":
+      return `\u{1F6AB} Run was canceled. Aborting... Please contact support.
+${urlInfo}`;
+    case "initializing":
+      return `\u23F3 Run is in progress... ${urlInfo}`;
+    case "underReview":
+      return `\u{1F575}\uFE0F  Run is under review... ${urlInfo}`;
+    case "completed":
+      throw Error("buildRunStageLogMessage should not be called for completed stage");
+    default:
+      throw Error(`Unexpected run stage: ${runStage}`);
+  }
+}
+__name(buildRunStageLogMessage, "buildRunStageLogMessage");
+
+// src/lib/sdk/domain/pollCiGreenlight/mapIteratorAbortToGreenlightStatus.ts
+function mapIteratorAbortToGreenlightStatus(iteration, pollTimeout, deps) {
+  const { log } = deps;
+  const { abortReason, httpStatus } = iteration;
+  switch (abortReason) {
+    case "4XX-client-error":
+      log.error(`\u{1F6AB} Unrecoverable error (status ${httpStatus}) from CI greenlight, aborting.`);
+      return {
+        abortReason,
+        httpStatus,
+        outcome: "aborted"
+      };
+    case "5XX-server-error":
+      log.error(`\u{1F6AB} Unrecoverable error (status ${httpStatus}) from CI greenlight, aborting.`);
+      return {
+        abortReason,
+        httpStatus,
+        outcome: "aborted"
+      };
+    case "404-run-not-found":
+      log.error(`\u{1F6AB} Unrecoverable error (status ${httpStatus}) from CI greenlight, aborting.`);
+      return {
+        abortReason,
+        httpStatus,
+        outcome: "aborted"
+      };
+    case "network-error":
+      log.error(`\u{1F6AB} Unrecoverable network error from CI greenlight, aborting.`);
+      return {
+        abortReason,
+        httpStatus: void 0,
+        outcome: "aborted"
+      };
+    case "poll-timed-out":
+      log.warn(`\u274C Poll timed out after ${pollTimeout / 1e3}s`);
       return {
-        abortReason: "run-canceled",
-        httpStatus: undefined,
+        abortReason,
+        httpStatus: void 0,
         outcome: "aborted"
       };
+    case "run-canceled":
+      log.info(`Run was canceled`);
+      return {
+        abortReason,
+        httpStatus: void 0,
+        outcome: "aborted"
+      };
+    case "XXX-other-http-code":
+      log.error(`\u{1F6AB} Unrecoverable error (status ${httpStatus}) from CI greenlight, aborting.`);
+      return {
+        abortReason,
+        httpStatus,
+        outcome: "aborted"
+      };
+    default:
+      throw Error(`Unexpected abort reason: ${abortReason}`);
+  }
+}
+__name(mapIteratorAbortToGreenlightStatus, "mapIteratorAbortToGreenlightStatus");
+
+// src/lib/sdk/domain/pollCiGreenlight/index.ts
+async function pollCiGreenlightStatus(deps, apiConfig, { onRunStageChanged = /* @__PURE__ */ __name(() => void 0, "onRunStageChanged"), runId, ...pollConfig }) {
+  const { log } = deps;
+  const { abortOnSuperseded = pollCiGreenlightDefaults.abortOnSuperseded, pollTimeout = pollCiGreenlightDefaults.pollTimeout } = pollConfig;
+  const iterator = makePollCiGreenlightStatusIterator(deps, apiConfig, {
+    runId,
+    ...pollConfig
+  });
+  for await (const lastPoll of iterator) {
+    if (lastPoll.isAborted) return mapIteratorAbortToGreenlightStatus(lastPoll, pollTimeout, deps);
+    const { previousStatus, stageChanged, status } = lastPoll;
+    if (stageChanged) {
+      try {
+        await onRunStageChanged(status, previousStatus);
+      } catch (e) {
+        log.error(`Error in onRunStageChanged callback`, e);
+      }
     }
-    if (hasTimedOut) {
-      log.warn(`\u274C Poll timed out after ${pollTimeout / 1e3}s. Aborting...`);
+    const { relevantRunId, relevantRunUrl, rootRunId, rootRunUrl, runStage } = status;
+    const isSuperseded = rootRunId !== relevantRunId;
+    const shouldAbortOnSuperseded = isSuperseded && abortOnSuperseded;
+    if (shouldAbortOnSuperseded) {
+      const message = buildSupersededAbortLogMessage(rootRunUrl, relevantRunUrl);
+      log.warn(message);
       return {
-        abortReason: "poll-timed-out",
-        httpStatus: undefined,
+        abortReason: "superseded-run",
+        httpStatus: void 0,
         outcome: "aborted"
       };
     }
-    if (runStage === "initializing") {
-      log.info(`\u23F3 Run is in progress... ${urlInfo}`);
-      await sleep(runInProgressInterval);
-    } else if (runStage === "underReview") {
-      log.info(`\u{1F575}\uFE0F  Run is under review... ${urlInfo}`);
-      await sleep(runUnderReviewInterval);
-    } else throw Error(`Unexpected run stage: ${runStage}`);
+    if (isSuperseded) {
+      const message = buildSupersededContinueLogMessage(rootRunUrl, relevantRunUrl);
+      log.info(message);
+    }
+    switch (runStage) {
+      case "canceled":
+      case "initializing":
+      case "underReview": {
+        log.info(buildRunStageLogMessage(runStage, relevantRunUrl));
+        break;
+      }
+      case "completed": {
+        const result = buildCompletedRunResult(status);
+        switch (result.outcome) {
+          case "aborted": {
+            break;
+          }
+          case "failed": {
+            const message = buildFailedLogMessage(status);
+            log.warn(message);
+            break;
+          }
+          case "success": {
+            const message = buildSuccessLogMessage(status);
+            log.info(message);
+            break;
+          }
+          default:
+            throw Error(`Unexpected outcome: ${result}`);
+        }
+        return result;
+      }
+      default:
+        throw Error(`Unexpected run stage: ${runStage}`);
+    }
   }
-  log.warn(`\u274C Poll timed out after ${pollTimeout / 1e3}s. Aborting...`);
-  return {
-    abortReason: "poll-timed-out",
-    httpStatus: undefined,
-    outcome: "aborted"
-  };
+  throw Error("Iterator ended unexpectedly");
 }
 __name(pollCiGreenlightStatus, "pollCiGreenlightStatus");
 
@@ -622,6 +750,7 @@ We recommend 'undici' package for that purpose. See the Requirement section of o
     attemptNotifyDeploy: attemptNotifyDeploy.bind(null, deps, apiConfig),
     generateSignedUrlForRunInputsExecutablesStorage: generateSignedUrlForRunInputsExecutablesStorage.bind(null, deps, apiConfig),
     generateSignedUrlForTempTeamStorage: generateSignedUrlForTempTeamStorage.bind(null, deps, apiConfig),
+    makePollCiGreenlightStatusIterator: makePollCiGreenlightStatusIterator.bind(null, deps, apiConfig),
     pollCiGreenlightStatus: pollCiGreenlightStatus.bind(null, deps, apiConfig)
   };
 }