@qawolf/ci-sdk 3.1.0 → 3.3.0

package/README.md

@@ -13,6 +13,7 @@ to determine the status of your CI/CD step/job/action.
 
 - [API Keys and Workspaces](#api-keys)
 - [Report a Deployment](#report-deployment)
+- [Wait for a Verdict](#wait-for-verdict)
 - [Notify Deployment (deprecated)](#notify-deployment)
 - [Notify Preview Deployment (Pull Request / Merge Request Testing)](#notify-preview)
 - [Poll for CI Greenlight Status (deprecated)](#ci-greenlight)
@@ -249,7 +250,90 @@ The response carries the deployment only, not the resulting runs. Waiting for a
 
 `detectProviderDeploymentId()` composes the run, attempt and job, so two jobs in one workflow do not report into the same deployment. Compose the id yourself only if you would rather not call it, and include the job.
 
-Four things move: `deploymentType` becomes `environment.name`; `branch` / `sha` become `metadata`; `providerDeploymentId` is new and required (`deduplicationKey` is subsumed by it); `hostingService` disappears, since the code host comes from your integration. There is no `skipped` outcome: whether a trigger matched is not known at report time. `pollCiGreenlightStatus` takes a run id that only `attemptNotifyDeploy` returns, so a pipeline that waits for a verdict stays on the legacy pair until the successor to polling ships.
+Four things move: `deploymentType` becomes `environment.name`; `branch` / `sha` become `metadata`; `providerDeploymentId` is new and required (`deduplicationKey` is subsumed by it); `hostingService` disappears, since the code host comes from your integration. There is no `skipped` outcome: whether a trigger matched is not known at report time. `pollCiGreenlightStatus` takes a run id that only `attemptNotifyDeploy` returns; a pipeline that waits for a verdict moves to [`deployment.waitForVerdict`](#wait-for-verdict), which takes the deployment id this call returns.
+
+<a id="wait-for-verdict"></a>
+
+## Wait for a Verdict
+
+`deployment.waitForVerdict` blocks until QA Wolf can say whether a deployment's tests passed. Give it the deployment id [the report](#report-deployment) returned; working out which runs the deployment produced happens inside.
+
+> ⚠️ Set `timeout` below your CI job's own ceiling. When the job's ceiling fires first, the job is killed with no run link and no explanation. When ours fires first, you get `timed-out` with the stage, the elapsed time, and every run URL we know about.
+
+### Example
+
+```ts
+const { deployment } = makeQaWolfSdk({ apiKey: "qawolf_xxxxx" });
+
+const report = await deployment.reportStatus({ /* ... */ status: "success" });
+if (report.outcome !== "reported") process.exit(1);
+
+const verdict = await deployment.waitForVerdict({
+  deploymentId: report.deployment.id,
+  timeout: 45 * 60 * 1000,
+});
+
+process.exit(["passed", "not-tested"].includes(verdict.outcome) ? 0 : 1);
+```
+
+### Result
+
+Like every function here, it never throws. Branch on `outcome` alone:
+
+| `outcome`               | Meaning                                                                                                                                                                                                                                                                   |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `passed`                | Every run QA Wolf started passed. Carries `runs`.                                                                                                                                                                                                                         |
+| `failed`                | A run found a bug that is still open and serious enough to block. Carries `runs` and `blockingBugCount`.                                                                                                                                                                  |
+| `not-tested`            | Nothing tested this deployment. Carries `reason` and a `triggers` note per trigger saying why.                                                                                                                                                                            |
+| `run-canceled`          | A run was canceled, so there is no verdict. This is not a pass. Carries `runs`.                                                                                                                                                                                           |
+| `superseded`            | A newer deployment to the same branch and environment replaced this run before it finished, so there is no verdict for _this_ deployment. Not a pass. Carries `runs` and `supersededBy` with the replacement's id and URL. The replacement may be testing a later commit. |
+| `timed-out`             | The budget ran out. Carries `elapsedMs`, `lastStage` and any `runs` it had already looked up.                                                                                                                                                                             |
+| `canceled-by-caller`    | The `signal` you passed was aborted.                                                                                                                                                                                                                                      |
+| `unauthorized`          | The API key is unknown, or may not read this deployment. Carries `message`.                                                                                                                                                                                               |
+| `not-found`             | No such deployment. Carries `message`.                                                                                                                                                                                                                                    |
+| `server-error`          | QA Wolf kept failing after every retry. Carries `httpStatus`.                                                                                                                                                                                                             |
+| `unexpected-status`     | A status this SDK version does not map. Carries `httpStatus` and `message`.                                                                                                                                                                                               |
+| `network-error`         | The connection never came back within the retries.                                                                                                                                                                                                                        |
+| `invalid-response-body` | QA Wolf answered with a body the contract rejects.                                                                                                                                                                                                                        |
+
+`not-tested` is a separate answer from `passed` on purpose. A deployment that no trigger matched was not tested, which is a different fact from tests passing, and you decide what it is worth: exit 0 and keep the log line, or fail the build when you expect a run every time. `run-canceled` likewise means we cannot tell you.
+
+`superseded` is what a `cancel-in-progress` job looks like in your CI: the example above ends within one poll of the supersession, logs the replacement's URL and exits 1, and the later deployment's job carries the verdict. Reserve a distinct exit code for it when your CI should treat the job as skipped rather than failed, for example `continue-on-error` on GitHub Actions, `allow_failure: { exit_codes: [3] }` on GitLab or `soft_fail: [{ exit_status: 3 }]` on Buildkite:
+
+```ts
+if (verdict.outcome === "superseded") process.exit(3);
+process.exit(["passed", "not-tested"].includes(verdict.outcome) ? 0 : 1);
+```
+
+The wait never follows `supersededBy`, because the replacement is chosen by branch and environment, not by commit, and a pipeline promoting the artifact it just built must not promote it on tests of a later one. A release train that promotes whatever is on the environment can follow the pointer itself. The SDK has no run-keyed wait yet, so the follow step is your own poll of the public API's `run.get` with the replacement's id until its `status` is terminal. That answer is a run summary, with `status` and `supersededBy` rather than `outcome`, and the replacement can itself be superseded:
+
+```ts
+const verdict = await deployment.waitForVerdict({ deploymentId });
+let replacement =
+  verdict.outcome === "superseded" ? verdict.supersededBy : undefined;
+while (replacement) {
+  console.log(`superseded by ${replacement.url}, following`);
+  const run = await waitForRun(replacement.runId); // your poll of run.get until status is terminal
+  replacement = run.supersededBy;
+}
+```
+
+The shape is `deploymentVerdictSchema`, published in `@qawolf/api-contracts`, so the same answer parses the same way wherever you read it.
+
+### Options
+
+Every field below is optional and carries the default shown.
+
+| Option                 | Default | Meaning                                                                               |
+| ---------------------- | ------- | ------------------------------------------------------------------------------------- |
+| `timeout`              | `2h`    | Whole-operation budget. Set it below your CI job's ceiling.                           |
+| `runAppearanceTimeout` | `5min`  | Give up if no trigger has produced a run by then. Runs that did appear are waited on. |
+| `triggerPollInterval`  | `3s`    | Between polls while a trigger is still producing a run.                               |
+| `runPollInterval`      | `30s`   | Between polls while a run executes.                                                   |
+| `maxRetries`           | `10`    | Network and server-error retries before giving up.                                    |
+| `retryInterval`        | `10s`   | Between those retries.                                                                |
+| `onProgress`           | —       | Called on every stage change, for your build log.                                     |
+| `signal`               | —       | An `AbortSignal`. Aborting it yields `canceled-by-caller` instead of a rejection.     |
 
 <a id="notify-deployment"></a>
 
@@ -735,6 +819,14 @@ This package follows the [SemVer](https://semver.org/) versioning scheme. Additi
 
 # Changelog
 
+## v3.3.0
+
+- `deployment.waitForVerdict` answers `superseded` when a newer deployment to the same branch and environment replaced the run before it finished. It carries `runs` and `supersededBy` with the replacement's id and URL, is not a pass, and the wait stops there rather than follow the replacement, which may be testing a later commit. A caller switching exhaustively on `outcome` has one more case to handle; the recipe's `["passed", "not-tested"].includes(...)` check needs no change. `runs[].status` now uses the run summary's vocabulary, so it can read `superseded`, and `runs[]` carries `supersededBy` for such a run. See [Wait for a Verdict](#wait-for-verdict).
+
+## v3.2.0
+
+- New `deployment.waitForVerdict` function, which blocks until QA Wolf can say whether a deployment's tests passed. It takes the deployment id `deployment.reportStatus` returned and resolves that to runs internally, so no run id crosses the boundary. It answers `passed`, `failed`, `not-tested`, `run-canceled`, `timed-out`, `canceled-by-caller` or one of the transport outcomes, and never throws. `not-tested` is deliberately distinct from `passed`, and `run-canceled` means no verdict rather than a pass. The whole-operation budget stays at 2 hours, matching `pollCiGreenlightStatus`. See [Wait for a Verdict](#wait-for-verdict).
+
 ## v3.1.0
 
 - New `deployment.reportStatus` function, which reports a deployment through the public `deployment.reportStatus` API — the one your triggers watch. A deployment's first `success` report is what starts a run. Its parameters are the API's own input, taken from the `@qawolf/api-contracts` package, so the SDK cannot drift from the API, and it returns `{ outcome: "reported", deployment }` carrying the deployment's `id`, `status` and `url`. A refusal comes back as one named outcome you can branch on — `invalid-request`, `unauthorized`, `not-found`, `conflict`, `server-error`, `unexpected-status`, `network-error` or `invalid-response-body` — so `if (result.outcome !== "reported")` is the whole check a CI gate needs. See [Report a Deployment](#report-deployment).

package/dist/index.js

@@ -98,6 +98,9 @@ var buildFetchWithTimeout = /* @__PURE__ */ __name((fetch, defaultTimeoutMs) =>
   return fetch(args[0], { ...args[1], signal });
 }, "buildFetchWithTimeout");
 
+// src/lib/sdk/defaults/clock.ts
+var defaultClock = { now: /* @__PURE__ */ __name(() => Date.now(), "now"), sleep };
+
 // src/lib/sdk/defaults/fetch.ts
 var defaultFetch = globalThis.fetch;
 
@@ -120,7 +123,7 @@ var defaultServiceBase = "https://app.qawolf.com/";
 // package.json
 var package_default = {
   name: "@qawolf/ci-sdk",
-  version: "3.1.0",
+  version: "3.3.0",
   private: false,
   description: "A simple SDK for interacting with QAWolf in CI scripts.",
   keywords: [],
@@ -149,7 +152,7 @@ var package_default = {
     "tsc:check": "tsc --noEmit"
   },
   dependencies: {
-    "@qawolf/api-contracts": ">=0.68.0",
+    "@qawolf/api-contracts": ">=0.73.0",
     "@qawolf/ci-utils": "^2.0.0",
     "@sinonjs/fake-timers": "^10.3.0",
     tslib: "^2.6.2",
@@ -1273,7 +1276,7 @@ async function callPublicContract({ fetch: localFetch, log }, apiConfig, {
     if (!response.ok) return readHttpError(response, contract.name, log);
     bodyText = await response.text();
   } catch {
-    log.error(`\u{1F6AB} Network error from ${contract.name}, aborting.`);
+    log.error(`\u{1F6AB} Network error from ${contract.name}.`);
     return { outcome: "network-error" };
   }
   const parsed = contract.output.safeParse(
@@ -1316,12 +1319,441 @@ function mapFailure(result) {
 }
 __name(mapFailure, "mapFailure");
 
+// src/lib/sdk/domain/waitForVerdict/awaitRuns.ts
+import { publicContractsV1 as publicContractsV12 } from "@qawolf/api-contracts";
+
+// src/lib/sdk/domain/waitForVerdict/failures.ts
+function handleCallFailure(failure, deploymentId) {
+  if (failure.outcome === "network-error") {
+    return {
+      exhaustedVerdict: { deploymentId, outcome: "network-error" },
+      kind: "retry"
+    };
+  }
+  if (failure.outcome === "invalid-response-body") {
+    return {
+      kind: "stop",
+      verdict: { deploymentId, outcome: "invalid-response-body" }
+    };
+  }
+  const { httpStatus, message } = failure;
+  if (httpStatus >= 500) {
+    return {
+      exhaustedVerdict: { deploymentId, httpStatus, outcome: "server-error" },
+      kind: "retry"
+    };
+  }
+  if (httpStatus === 401 || httpStatus === 403) {
+    return {
+      kind: "stop",
+      verdict: { deploymentId, message, outcome: "unauthorized" }
+    };
+  }
+  if (httpStatus === 404) {
+    return {
+      kind: "stop",
+      verdict: { deploymentId, message, outcome: "not-found" }
+    };
+  }
+  return {
+    kind: "stop",
+    verdict: {
+      deploymentId,
+      httpStatus,
+      message,
+      outcome: "unexpected-status"
+    }
+  };
+}
+__name(handleCallFailure, "handleCallFailure");
+
+// src/lib/sdk/domain/waitForVerdict/poll.ts
+async function pollUntil(ctx, {
+  deadlineAt,
+  onData,
+  onDeadline,
+  request
+}) {
+  const { clock, log } = ctx.deps;
+  const { deploymentId } = ctx;
+  const { maxRetries, retryInterval, signal } = ctx.config;
+  let retries = 0;
+  const sleepWithinBudget = /* @__PURE__ */ __name((intervalMs) => clock.sleep(Math.max(0, Math.min(intervalMs, deadlineAt - clock.now()))), "sleepWithinBudget");
+  for (; ; ) {
+    if (signal?.aborted)
+      return { deploymentId, outcome: "canceled-by-caller" };
+    if (clock.now() >= deadlineAt) return onDeadline();
+    const result = await request();
+    if (result.outcome === "ok") {
+      retries = 0;
+      const step = await onData(result.data);
+      if (step.kind === "done") return step.result;
+      await sleepWithinBudget(step.intervalMs);
+      continue;
+    }
+    const handling = handleCallFailure(result, deploymentId);
+    if (handling.kind === "stop") return handling.verdict;
+    retries += 1;
+    if (retries > maxRetries) return handling.exhaustedVerdict;
+    log.warn(
+      `\u23F3 QA Wolf did not answer, trying again... (${retries}/${maxRetries})`
+    );
+    await sleepWithinBudget(retryInterval);
+  }
+}
+__name(pollUntil, "pollUntil");
+
+// src/lib/sdk/domain/waitForVerdict/progress.ts
+function describeStage(stage) {
+  switch (stage.stage) {
+    case "waiting-for-evaluation":
+      return "\u23F3 Waiting for QA Wolf to evaluate this deployment's triggers...";
+    case "waiting-for-run": {
+      const { matchedTriggerCount } = stage;
+      return `\u23F3 ${matchedTriggerCount} trigger${pluralize(matchedTriggerCount)} matched; waiting for a run to start...`;
+    }
+    case "waiting-for-verdict": {
+      const urls = stage.runs.map((run) => run.runUrl).join(" ");
+      return `\u23F3 ${stage.runs.length} run${pluralize(stage.runs.length)} executing... ${urls}`;
+    }
+    default:
+      throw Error(`Unexpected stage: ${stage}`);
+  }
+}
+__name(describeStage, "describeStage");
+async function reportStage(ctx, previousDescription, stage) {
+  const description = describeStage(stage);
+  if (description === previousDescription) return description;
+  ctx.deps.log.info(description);
+  try {
+    await ctx.config.onProgress?.(stage);
+  } catch (error) {
+    ctx.deps.log.error("The onProgress callback failed.", error);
+  }
+  return description;
+}
+__name(reportStage, "reportStage");
+
+// src/lib/sdk/domain/waitForVerdict/readEvaluations.ts
+var notConsideredMessages = {
+  "not-a-deployment-trigger": "The trigger has no deployment conditions, so no deployment can fire it.",
+  "trigger-paused": "The trigger was paused when the deployment was evaluated."
+};
+function readDidNotMatch(conditionSets) {
+  const reasons = conditionSets.flatMap(
+    (set) => set.conditions.flatMap(
+      (condition) => condition.outcome === "did-not-match" ? [condition.reason] : []
+    )
+  );
+  return reasons.length > 0 ? reasons.join(" ") : "The trigger's conditions did not match this deployment.";
+}
+__name(readDidNotMatch, "readDidNotMatch");
+function toTriggerNote(evaluation) {
+  const { triggerName, verdict } = evaluation;
+  if (verdict.outcome === "did-not-match")
+    return { message: readDidNotMatch(verdict.conditionSets), triggerName };
+  if (verdict.outcome === "not-considered") {
+    return {
+      message: notConsideredMessages[verdict.reason],
+      triggerName
+    };
+  }
+  if (verdict.run.status === "did-not-run") {
+    return {
+      message: verdict.run.message,
+      reason: verdict.run.reason,
+      triggerName
+    };
+  }
+  return void 0;
+}
+__name(toTriggerNote, "toTriggerNote");
+function toMatchedRun(evaluation) {
+  const { triggerName, verdict } = evaluation;
+  if (verdict.outcome !== "matched") return void 0;
+  if (verdict.run.status === "ran")
+    return { runId: verdict.run.runId, triggerName };
+  if (verdict.run.status === "did-not-run" && verdict.run.supersededByRunId)
+    return { runId: verdict.run.supersededByRunId, triggerName };
+  return void 0;
+}
+__name(toMatchedRun, "toMatchedRun");
+function isStillProducingARun(evaluation) {
+  const { verdict } = evaluation;
+  return verdict.outcome === "matched" && (verdict.run.status === "starting" || verdict.run.status === "unknown");
+}
+__name(isStillProducingARun, "isStillProducingARun");
+function readEvaluations(evaluations) {
+  if (evaluations.state === "not-evaluated") return { kind: "not-evaluated" };
+  const runs = evaluations.evaluations.flatMap((evaluation) => {
+    const run = toMatchedRun(evaluation);
+    return run ? [run] : [];
+  });
+  const matched = evaluations.evaluations.filter(
+    (evaluation) => evaluation.verdict.outcome === "matched"
+  );
+  if (evaluations.evaluations.some(isStillProducingARun))
+    return { kind: "awaiting-run", matchedTriggerCount: matched.length, runs };
+  if (runs.length > 0) return { kind: "runs", runs };
+  return {
+    kind: "not-tested",
+    reason: matched.length > 0 ? "no-run-created" : "no-trigger-matched",
+    triggers: evaluations.evaluations.flatMap((evaluation) => {
+      const note = toTriggerNote(evaluation);
+      return note ? [note] : [];
+    })
+  };
+}
+__name(readEvaluations, "readEvaluations");
+
+// src/lib/sdk/domain/waitForVerdict/awaitRuns.ts
+async function awaitRuns(ctx) {
+  const { clock } = ctx.deps;
+  const { deploymentId } = ctx;
+  const { runAppearanceTimeout, timeout, triggerPollInterval } = ctx.config;
+  const overallDeadlineAt = ctx.startedAt + timeout;
+  let knownRuns = [];
+  let lastStage = { stage: "waiting-for-evaluation" };
+  let lastDescription = void 0;
+  return pollUntil(ctx, {
+    deadlineAt: Math.min(
+      overallDeadlineAt,
+      ctx.startedAt + runAppearanceTimeout
+    ),
+    async onData(evaluations) {
+      const reading = readEvaluations(evaluations);
+      if (reading.kind === "runs")
+        return { kind: "done", result: { kind: "runs", runs: reading.runs } };
+      if (reading.kind === "not-tested") {
+        return {
+          kind: "done",
+          result: {
+            deploymentId,
+            outcome: "not-tested",
+            reason: reading.reason,
+            triggers: reading.triggers
+          }
+        };
+      }
+      knownRuns = reading.kind === "awaiting-run" ? reading.runs : knownRuns;
+      lastStage = reading.kind === "awaiting-run" ? {
+        matchedTriggerCount: reading.matchedTriggerCount,
+        stage: "waiting-for-run"
+      } : { stage: "waiting-for-evaluation" };
+      lastDescription = await reportStage(ctx, lastDescription, lastStage);
+      return { intervalMs: triggerPollInterval, kind: "continue" };
+    },
+    onDeadline() {
+      const now = clock.now();
+      if (knownRuns.length > 0 && now < overallDeadlineAt)
+        return { kind: "runs", runs: knownRuns };
+      return {
+        deploymentId,
+        elapsedMs: now - ctx.startedAt,
+        lastStage,
+        outcome: "timed-out",
+        runs: []
+      };
+    },
+    request: /* @__PURE__ */ __name(() => callPublicContract(ctx.deps, ctx.apiConfig, {
+      contract: publicContractsV12.deployment.listTriggerEvaluations,
+      input: { deploymentId }
+    }), "request")
+  });
+}
+__name(awaitRuns, "awaitRuns");
+
+// src/lib/sdk/domain/waitForVerdict/awaitVerdict.ts
+import { publicContractsV1 as publicContractsV13 } from "@qawolf/api-contracts";
+var settledStatuses = ["passed", "failed", "canceled", "superseded"];
+function isSettled(run) {
+  return settledStatuses.includes(run.status);
+}
+__name(isSettled, "isSettled");
+function aggregateRuns(deploymentId, runs) {
+  if (runs.some((run) => run.status === "failed" || run.blockingBugCount > 0)) {
+    return {
+      blockingBugCount: runs.reduce(
+        (total, run) => total + run.blockingBugCount,
+        0
+      ),
+      deploymentId,
+      outcome: "failed",
+      runs
+    };
+  }
+  const supersededBy = runs.find(
+    (run) => run.status === "superseded"
+  )?.supersededBy;
+  if (supersededBy)
+    return { deploymentId, outcome: "superseded", runs, supersededBy };
+  if (runs.some((run) => run.status === "canceled"))
+    return { deploymentId, outcome: "run-canceled", runs };
+  return { deploymentId, outcome: "passed", runs };
+}
+__name(aggregateRuns, "aggregateRuns");
+function keepOnePerRun(runs) {
+  return runs.filter(
+    (run, index) => runs.findIndex((other) => other.runId === run.runId) === index
+  );
+}
+__name(keepOnePerRun, "keepOnePerRun");
+async function requestRuns(ctx, matched) {
+  const answers = await Promise.all(
+    matched.map(async (run) => ({
+      result: await callPublicContract(ctx.deps, ctx.apiConfig, {
+        contract: publicContractsV13.run.get,
+        // A suite can hold hundreds of flows and the verdict reads none of
+        // them, so ask for the smallest list the contract allows.
+        input: { flowStatuses: ["failed"], runId: run.runId }
+      }),
+      triggerName: run.triggerName
+    }))
+  );
+  const failed = answers.find((answer) => answer.result.outcome !== "ok");
+  if (failed && failed.result.outcome !== "ok") return failed.result;
+  return {
+    data: keepOnePerRun(
+      answers.flatMap(
+        (answer) => answer.result.outcome === "ok" ? [
+          {
+            blockingBugCount: answer.result.data.blockingBugCount,
+            // Differs from the id asked for only when a deploy notification's
+            // pre-allocated id was folded into an earlier run of the same commit.
+            runId: answer.result.data.runId,
+            runUrl: answer.result.data.url,
+            status: answer.result.data.status,
+            supersededBy: answer.result.data.supersededBy,
+            triggerName: answer.triggerName
+          }
+        ] : []
+      )
+    ),
+    outcome: "ok"
+  };
+}
+__name(requestRuns, "requestRuns");
+async function awaitVerdict(ctx, matched) {
+  const { deploymentId } = ctx;
+  let lastRuns = [];
+  let lastDescription = void 0;
+  return pollUntil(ctx, {
+    deadlineAt: ctx.startedAt + ctx.config.timeout,
+    async onData(runs) {
+      lastRuns = runs;
+      if (runs.every(isSettled))
+        return { kind: "done", result: aggregateRuns(deploymentId, runs) };
+      lastDescription = await reportStage(ctx, lastDescription, {
+        runs,
+        stage: "waiting-for-verdict"
+      });
+      return { intervalMs: ctx.config.runPollInterval, kind: "continue" };
+    },
+    onDeadline: /* @__PURE__ */ __name(() => ({
+      deploymentId,
+      elapsedMs: ctx.deps.clock.now() - ctx.startedAt,
+      lastStage: { runs: lastRuns, stage: "waiting-for-verdict" },
+      outcome: "timed-out",
+      runs: lastRuns
+    }), "onDeadline"),
+    request: /* @__PURE__ */ __name(() => requestRuns(ctx, matched), "request")
+  });
+}
+__name(awaitVerdict, "awaitVerdict");
+
+// src/lib/sdk/domain/waitForVerdict/consts.ts
+var waitForVerdictDefaults = {
+  maxRetries: 10,
+  retryInterval: 10 * 1e3,
+  runAppearanceTimeout: 5 * 60 * 1e3,
+  runPollInterval: 30 * 1e3,
+  timeout: 120 * 60 * 1e3,
+  triggerPollInterval: 3 * 1e3
+};
+
+// src/lib/sdk/domain/waitForVerdict/logVerdict.ts
+function runUrls(runs) {
+  return runs.map((run) => run.runUrl).join(" ");
+}
+__name(runUrls, "runUrls");
+function logVerdict(log, verdict) {
+  switch (verdict.outcome) {
+    case "canceled-by-caller":
+      return log.warn("\u{1F6AB} The wait was canceled before QA Wolf answered.");
+    case "failed":
+      return log.error(
+        `\u274C QA Wolf found ${verdict.blockingBugCount} blocking bug${pluralize(verdict.blockingBugCount)}. ${runUrls(verdict.runs)}`
+      );
+    case "not-tested": {
+      log.info(
+        verdict.reason === "no-trigger-matched" ? "\u26A0\uFE0F QA Wolf: nothing to test for this deployment." : "\u26A0\uFE0F QA Wolf: a trigger matched this deployment but started no run."
+      );
+      for (const trigger of verdict.triggers)
+        log.info(`   ${trigger.triggerName}: ${trigger.message}`);
+      return;
+    }
+    case "passed":
+      return log.info(`\u2705 QA Wolf gate: passed. ${runUrls(verdict.runs)}`);
+    case "run-canceled":
+      return log.error(
+        `\u{1F6AB} The run was canceled, so QA Wolf reached no verdict. ${runUrls(verdict.runs)}`
+      );
+    case "superseded":
+      return log.error(
+        `\u{1F6AB} superseded \u2014 replaced by ${verdict.supersededBy.url}, so QA Wolf reached no verdict for this deployment. ${runUrls(verdict.runs)}`
+      );
+    case "timed-out":
+      return log.error(
+        `\u{1F6AB} Gave up after ${Math.round(verdict.elapsedMs / 1e3)}s waiting for QA Wolf. ${runUrls(verdict.runs)}`
+      );
+    default:
+      return void 0;
+  }
+}
+__name(logVerdict, "logVerdict");
+
+// src/lib/sdk/domain/waitForVerdict/index.ts
+async function waitForVerdict(deps, apiConfig, {
+  deploymentId,
+  maxRetries = waitForVerdictDefaults.maxRetries,
+  onProgress,
+  retryInterval = waitForVerdictDefaults.retryInterval,
+  runAppearanceTimeout = waitForVerdictDefaults.runAppearanceTimeout,
+  runPollInterval = waitForVerdictDefaults.runPollInterval,
+  signal,
+  timeout = waitForVerdictDefaults.timeout,
+  triggerPollInterval = waitForVerdictDefaults.triggerPollInterval
+}) {
+  const ctx = {
+    apiConfig,
+    config: {
+      maxRetries,
+      onProgress,
+      retryInterval,
+      runAppearanceTimeout,
+      runPollInterval,
+      signal,
+      timeout,
+      triggerPollInterval
+    },
+    deploymentId,
+    deps,
+    startedAt: deps.clock.now()
+  };
+  const phase = await awaitRuns(ctx);
+  const verdict = "kind" in phase ? await awaitVerdict(ctx, phase.runs) : phase;
+  logVerdict(deps.log, verdict);
+  return verdict;
+}
+__name(waitForVerdict, "waitForVerdict");
+
 // src/lib/sdk/index.ts
 function makeQaWolfSdk({
   apiKey,
   serviceBase = defaultServiceBase,
   userAgent = defaultUserAgent
 }, {
+  clock = defaultClock,
   fetch = defaultFetch,
   log = defaultLogDriver
 } = {}) {
@@ -1332,6 +1764,7 @@ We recommend 'undici' package for that purpose. See the Requirement section of o
     );
   }
   const deps = {
+    clock,
     // Versions of fetch may have different default timeouts. For consistency, we explicitly set it to 2 minutes here.
     // The increased timeout helps avoid edge cases where we need to search for a commit against multiple
     // code hosting service repositories as a fallback when not finding the repository based on organization/name.
@@ -1346,7 +1779,8 @@ We recommend 'undici' package for that purpose. See the Requirement section of o
      */
     attemptNotifyDeploy: attemptNotifyDeploy.bind(null, deps, apiConfig),
     deployment: {
-      reportStatus: reportDeployment.bind(null, deps, apiConfig)
+      reportStatus: reportDeployment.bind(null, deps, apiConfig),
+      waitForVerdict: waitForVerdict.bind(null, deps, apiConfig)
     },
     generateSignedUrlForRunInputsExecutablesStorage: generateSignedUrlForRunInputsExecutablesStorage.bind(
       null,