tinybeeai 0.0.0-stage → 0.16.1

package/dist/deploy-wait.js

@@ -0,0 +1,701 @@
+// Waiting for the deploy of a merge before its post-merge run (KAT-368). A merge reaches the QA environment a few minutes after it
+// lands, and a run that starts at once tests the build from before the merge. A dot with `waitForDeploySec` above 0 and a
+// `deployEnvironment` holds the post_merge job of a merge into the default branch until GitHub shows a successful deployment of
+// the merge commit, or of a later commit that contains it, to that environment. Then the run tests. When the time is up the run
+// tests anyway and says so in a step.
+//
+// The wait holds no queue slot. A gate (queue.ts onBeforeJob, like the model cap) looks for the deployment each time the queue claims
+// the job; when there is none yet it sends the job back with `runAfter` and a run that shows the wait, and the slot is free again. The
+// job is looked at again
+//   - every 30 s for a dot that polls GitHub, since nothing tells it a deploy finished (the poll cadence of the server),
+//   - at once when a deployment_status success for that repository and environment arrives, for a dot on webhooks, and
+//   - every 5 min as well on webhooks, since a delivery the server missed (a restart, a lost hook) would otherwise be waited out.
+// Each look reads what webhooks said (the deployments the server heard of) and then GitHub (GET /repos/{o}/{r}/deployments?sha=&environment=
+// and the statuses of each deployment). A deployment counts when it holds the merge commit and is on the default branch: a feature
+// branch built on the merge is not a deploy of the merge. A newer merge into the same branch that waits for its own deploy replaces a
+// job that waits. Newer means later in the branch, which GitHub's compare of the two commits says, and not the order the two events
+// came in.
+//
+// Per repo (KAT-395): an app repo may set its own `deployEnvironment` and `waitForDeploySec`; the dot's two fields are the default for
+// a repo that sets none. A repo with a wait of 0 does not wait while the dot waits for the others. A merge waits on its own repo's
+// settings, and the deployments it looks at are those of that repo's merge commit in that repo's environment.
+//
+// All the deployments of one commit in one environment are one set: a push may deploy several services, each as its own deployment.
+// The merge counts as deployed when the newest attempt of every service succeeded, and the wait ends with no test run when the newest
+// attempt of one of them ended in `failure` or `error`: the build that would be tested does not hold the merge. A failed deployment that
+// was retried is not a failed service: the retry is the newest attempt. Attempts of one service are told apart by the service the
+// deployment names in a field made for it (payload or task). A name read from the description is a guess, since parallel jobs of one
+// pipeline share it, so it and a deployment that names none go by order: a deployment of the same commit and environment made after
+// the failure was written replaces it, and one made before it (a service deployed in parallel) does not. A failure of the
+// merge commit's own deploy is final only after the later commits that contain the merge were looked at: one of them that deployed is
+// the deploy of the merge. A plain step says so, the check on the commit closes, and no defect is drafted.
+//
+// The target of the tests is the Base URL unless a deployment of the set gave the address of the site: its `environment_url` is used
+// only when its origin is the Base URL's origin, or the host or origin the repo names in `deployUrlMatch`, and only when it is the root
+// of the site (https://web.qa.example.com, never https://api.qa.example.com/health). With no Base URL and no `deployUrlMatch`, the
+// address is used when every deployment of the set that gives one gives the same origin.
+//
+// The run is interrupted with the reason `deploy_wait` while the job waits, so a restart loses nothing and the dot's health does not
+// change. It carries one step with the environment and the time waited, rewritten on each look. When the wait ends the same run goes
+// on (src/agent/runs.ts startRun finds it by the job).
+import { log } from './config.js';
+import { get, list, update } from './db.js';
+import { addStep, closeDeployRun, holdRunForDeploy, startRun } from './agent/runs.js';
+import { docsOnlyChange, mergeShaOf, testSavings } from './flows/testSavings.js';
+import { closeUnrun, noteDeployWait, noteSupersededWait, scopeOf } from './flows/checkStatus.js';
+import { eventOf, getDiff, repoTarget } from './flows/common.js';
+import { testRepoSwitches, testReposFor } from './flows/testRepo.js';
+import { githubFor, onDeploymentEnd } from './integrations/github.js';
+import { wantsGithubPoll } from './monitor/pollers.js';
+import { onBeforeJob, withJobContext } from './queue.js';
+import { repoForEvent, targetRepo, testsOffRepo } from './repos.js';
+import { cleanDeployEnvironment, cleanDeploySec } from './runner/command.js';
+import { hostOf, matchesDeployUrl, originOf, targetUrlOf, uiBaseOf } from './target-url.js';
+/** Seconds between two looks at GitHub for a dot that polls. */
+export const DEPLOY_POLL_SEC = 30;
+/** Seconds between two looks for a dot on webhooks, which a deployment_status delivery also wakes. */
+export const DEPLOY_NUDGE_SEC = 300;
+/** The label of the step a merge run carries when the time is up: the wording the pilot team reads on the run page. */
+export const DEPLOY_TIMEOUT_LABEL = 'Tested before the QA deploy finished; the build may be older than this merge';
+/** A deployment of a later commit counts only when GitHub wrote it after the job began, less this slack for the clocks of two machines. */
+const LATER_SLACK_MS = 5 * 60_000;
+/** Deployments heard on webhooks are kept for this long and this many for each repository and environment. */
+const HEARD_MS = 24 * 3600_000;
+const HEARD_MAX = 20;
+/**
+ * The deploy wait of a merge, or null when it is off: no seconds, or no environment to wait on. The repo's own fields come first and
+ * the dot's are the default for a field the repo leaves out (KAT-395). A repo with 0 seconds does not wait, whatever the dot says.
+ */
+export function deployWaitOf(w, repo) {
+    const sec = cleanDeploySec(repo?.waitForDeploySec !== undefined && repo?.waitForDeploySec !== null ? repo.waitForDeploySec : w.waitForDeploySec);
+    const environment = cleanDeployEnvironment(repo?.deployEnvironment) ?? cleanDeployEnvironment(w.deployEnvironment);
+    return sec && environment ? { sec, environment } : null;
+}
+/** The environment as a person writes it in a sentence: qa is QA, any other name stays as it was typed. */
+export function environmentWords(environment) {
+    return environment.trim().toLowerCase() === 'qa' ? 'QA' : environment.trim();
+}
+export { targetUrlOf };
+/** True when the host of `url` is the host of `base` or a subdomain of it. */
+export function withinSiteOf(base, url) {
+    const b = hostOf(base);
+    const h = hostOf(url);
+    return !!b && !!h && (h === b || h.endsWith(`.${b}`));
+}
+/** True when a test login of the dot (runner.passEnv, a file runner.copyFiles copies in, a Tests repo's passEnv, or an AI-Vision credential variable) would go with a run. */
+function carriesTestLogin(w, ev) {
+    const ai = w.runner.aivision;
+    return (!!w.runner.passEnv?.length ||
+        !!w.runner.copyFiles?.length ||
+        testReposFor(w, ev, 'post_merge').some((r) => !!r.test?.passEnv?.length) ||
+        !!(ai && (ai.passEnv?.length || ai.tokenEnv || ai.cookieEnv || ai.userEnv || ai.passwordEnv)));
+}
+/**
+ * The address a merge's tests run against after the deploy (KAT-395): the environment URL of the deployment. GitHub gives that
+ * address, and anyone who can write a deployment status in the environment chooses it, so a dot that carries a test login uses it only
+ * when it is on the Base URL's own site (the same host or a subdomain of it). Any other address is left out, and the tests run against
+ * the Base URL as before. `ignored` is the host that was left out.
+ */
+export function deployTargetFor(w, ev, url) {
+    if (!url)
+        return {};
+    if (!carriesTestLogin(w, ev) || withinSiteOf(w.baseUrl, url))
+        return { url };
+    return { ignored: hostOf(url) ?? url };
+}
+const lc = (s) => s.toLowerCase();
+const sameSha = (a, b) => !!a && !!b && (a === b || a.startsWith(b) || b.startsWith(a));
+const repoKey = (r) => lc(`${r.owner}/${r.name}`);
+/** "2 min 30 s", "45 s", "1 h 5 min": the time of a step. */
+export function durationText(ms) {
+    const s = Math.max(0, Math.round(ms / 1000));
+    if (s < 60)
+        return `${s} s`;
+    const m = Math.floor(s / 60);
+    if (m < 60)
+        return s % 60 ? `${m} min ${s % 60} s` : `${m} min`;
+    return m % 60 ? `${Math.floor(m / 60)} h ${m % 60} min` : `${Math.floor(m / 60)} h`;
+}
+const heard = new Map();
+const heardKey = (repo, environment) => `${repoKey(repo)}@${lc(environment)}`;
+/** Ids for deliveries that carry none, rising so a later delivery is a later deployment. Far from any id GitHub gives. */
+let heardSeq = Number.MIN_SAFE_INTEGER;
+const HEARD_DEPLOYMENTS_MAX = 30;
+function hear(d, now = Date.now()) {
+    if (!d.environment || !d.sha)
+        return;
+    const key = heardKey(d.repo, d.environment);
+    const live = (heard.get(key) ?? []).filter((h) => now - h.at < HEARD_MS);
+    const before = live.find((h) => h.sha === d.sha);
+    const kept = live.filter((h) => h.sha !== d.sha);
+    const deployments = [...(before?.deployments ?? [])];
+    const at = deployments.findIndex((x) => d.id !== undefined && x.id === d.id);
+    const prior = at >= 0 ? deployments[at] : undefined;
+    const row = {
+        id: d.id ?? ++heardSeq,
+        sha: d.sha,
+        environment: d.environment,
+        state: d.state,
+        // A deployment that succeeded at any time was deployed, like a status list of GitHub reads.
+        succeeded: d.state === 'success' || !!prior?.succeeded,
+        ...((d.at ?? prior?.at) ? { at: (d.at ?? prior?.at) } : {}),
+        ...((d.createdAt ?? prior?.createdAt) ? { createdAt: (d.createdAt ?? prior?.createdAt) } : {}),
+        ...((d.service ?? prior?.service) ? { service: (d.service ?? prior?.service) } : {}),
+        ...((d.service ? d.serviceGuessed : prior?.serviceGuessed) ? { serviceGuessed: true } : {}),
+    };
+    if (at >= 0)
+        deployments[at] = row;
+    else
+        deployments.push(row);
+    const set = deployments.slice(-HEARD_DEPLOYMENTS_MAX);
+    const verdict = judgeSet(set);
+    const failed = verdict.state === 'failed' ? (verdict.failed.state === 'error' ? 'error' : 'failure') : undefined;
+    heard.set(key, [{ sha: d.sha, at: now, ok: set.some((x) => x.succeeded), ...(failed ? { failed } : {}), deployments: set }, ...kept].slice(0, HEARD_MAX));
+}
+/** True when a deployment succeeded in this repository and environment after `since` (ms): a delivery that arrived while a look was under way. */
+function heardSince(repo, environment, since) {
+    return (heard.get(heardKey(repo, environment)) ?? []).some((h) => h.at > since);
+}
+/** Forgets every deployment heard. Used by tests. */
+export function resetHeardDeployments() {
+    heard.clear();
+}
+/** True when the newest status of the deployment is a failure or an error and none was a success. */
+const failedDeployment = (d) => !d.succeeded && (d.state === 'failure' || d.state === 'error');
+const timeOf = (iso) => {
+    const t = iso ? Date.parse(iso) : NaN;
+    return Number.isFinite(t) ? t : undefined;
+};
+/**
+ * True when both deployments name the same service in a field made for it (payload, task). A name read from the description is a guess:
+ * parallel jobs of one pipeline share it once their numbers are cut, so it never makes the higher id a retry on its own (KAT-403).
+ */
+const sameNamedService = (a, b) => !!a.service && a.service === b.service && !a.serviceGuessed && !b.serviceGuessed;
+/**
+ * True when `later` is a newer attempt at what `earlier` deployed. Both name a service: the same one, whatever the order of the times
+ * (a retry made while the first attempt still ran is older than the failure that attempt wrote later). Otherwise (one or both name
+ * none) it is a deployment of the same commit and environment that GitHub made after the failure of `earlier` was written. A
+ * deployment made before that (a service deployed in parallel, whose own deploy finished first) is another deployment, not a retry.
+ * With times unknown a keyless pair is two deployments.
+ */
+function newerAttempt(later, earlier) {
+    if (later === earlier || later.id <= earlier.id)
+        return false;
+    if (!!later.service && !!earlier.service && later.service !== earlier.service)
+        return false;
+    // The same named service: the higher id is the newer attempt, whenever GitHub wrote the failure of the older one. A retry is often made
+    // while the first attempt is still running, so the failure of that attempt is written after the retry was created (KAT-403).
+    if (sameNamedService(later, earlier))
+        return true;
+    const made = timeOf(later.createdAt);
+    const was = timeOf(earlier.at);
+    if (made !== undefined && was !== undefined)
+        return made >= was;
+    return false;
+}
+/**
+ * The address a set of deployments gives for the tests, or undefined (keep the Base URL). Only a successful deployment gives one, and
+ * only the root of a site (uiBaseOf). It is used when it is on the origin of the Base URL, or on the host or origin the repo names;
+ * a repo's own name comes first. With neither a Base URL nor a name, an address counts only when the deployments agree on one origin.
+ */
+export function pickTargetUrl(set, rule = {}) {
+    const urls = set.filter((d) => d.succeeded).flatMap((d) => uiBaseOf(d.url, rule.baseUrl) ?? []);
+    if (rule.match) {
+        const named = urls.find((u) => matchesDeployUrl(rule.match, u));
+        if (named)
+            return named;
+    }
+    const base = originOf(rule.baseUrl);
+    if (base)
+        return urls.find((u) => originOf(u) === base);
+    if (rule.match)
+        return undefined;
+    const origins = new Set(urls.map((u) => originOf(u)));
+    return origins.size === 1 ? urls[0] : undefined;
+}
+/**
+ * The deployments of a commit in an environment as one set (KAT-395, KAT-388). One push may deploy several services, each as its own
+ * deployment, so the commit is deployed only when the newest attempt of every service succeeded, and a failure of the newest attempt
+ * of any one is a failed deploy. An attempt that a retry replaced (newerAttempt) is left out: a keyless failure is replaced by a
+ * deployment made after it, a failure of a named service by a newer deployment of that service. A deployment that GitHub marked
+ * inactive without a success was replaced before it finished and is left out. `none` for a commit with no deployment, `pending` while
+ * at least one is still on its way.
+ */
+export function judgeSet(set, rule = {}) {
+    const live = set.filter((d) => d.succeeded || d.state !== 'inactive');
+    if (!live.length)
+        return { state: 'none' };
+    const current = live.filter((d) => !live.some((y) => newerAttempt(y, d) && (sameNamedService(y, d) || failedDeployment(d))));
+    const failed = current.find(failedDeployment);
+    if (failed)
+        return { state: 'failed', failed };
+    if (current.every((d) => d.succeeded)) {
+        const url = pickTargetUrl(current, rule);
+        return { state: 'deployed', ...(url ? { url } : {}) };
+    }
+    return { state: 'pending' };
+}
+/** True when `deploySha` contains `mergeSha`: the compare of the merge commit against the deploy says it is behind it, or the same. */
+async function contains(gh, deploySha, mergeSha) {
+    try {
+        const rel = await gh.compareStatus(deploySha, mergeSha);
+        return rel === 'behind' || rel === 'identical';
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * True when `sha` is on the branch: the branch head is that commit or holds it. A commit of a feature branch built on the merge holds
+ * the merge commit too, with code that is not merged, so a deploy of it is not the deploy of the merge. A GitHub error is no.
+ */
+async function onBranch(gh, branch, sha) {
+    if (!branch)
+        return true;
+    try {
+        const rel = await gh.compareStatus(branch, sha);
+        return rel === 'behind' || rel === 'identical';
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Is the merge commit deployed to the environment? GitHub first: the deployments of the merge commit itself are one set (judgeSet),
+ * and when that set has none or is not finished, the newest few of the environment, which may hold a later commit. A later commit
+ * counts when GitHub says it contains the merge commit and that it is on the branch, and its own deployments are judged as a set the
+ * same way. A deployment that webhooks reported counts for itself only when GitHub lists no deployment of that commit, or cannot be read:
+ * a delivery says one deployment succeeded, and the set may hold more. A GitHub error is returned, not thrown: the job keeps waiting,
+ * and the timeout step names it.
+ */
+async function lookDeployed(o) {
+    const { gh, repo, branch, environment, sha } = o;
+    const rule = o.rule ?? {};
+    /** A later commit counts when it holds the merge commit and the branch holds it. */
+    const laterCounts = async (later) => (await contains(gh, later, sha)) && (await onBranch(gh, branch, later));
+    // What deliveries reported. GitHub's list outranks them when it can be read and has the commit; they stand when it has none or is unreadable.
+    const heardAll = heard.get(heardKey(repo, environment)) ?? [];
+    const heardHere = heardAll.filter((h) => h.ok && !h.failed);
+    const heardFailed = (commit) => heardAll.find((h) => sameSha(h.sha, commit) && h.failed);
+    const setOf = (commit) => gh.deployments({ environment, sha: commit, limit: 30 });
+    let error;
+    // The merge commit's own deploy failed. That is final only after the later commits that hold the merge were looked at, since one of
+    // them that deployed is the deploy of the merge (the failure was fixed by a later push, or by a new commit on the branch).
+    let ownFailure;
+    // True when the later commits could not be listed or judged on GitHub, so a rescue may be hidden.
+    let laterUnread = false;
+    const verdicts = new Map();
+    try {
+        if (gh.deployments) {
+            const own = judgeSet(await setOf(sha), rule);
+            verdicts.set(sha, own);
+            if (own.state === 'failed')
+                ownFailure = { sha: own.failed.sha || sha, later: false, state: own.failed.state, id: own.failed.id };
+            if (own.state === 'deployed')
+                return { found: { sha, later: false, ...(own.url ? { url: own.url } : {}) } };
+        }
+    }
+    catch (err) {
+        error = err instanceof Error ? err.message : String(err);
+    }
+    // GitHub lists nothing of this commit, or could not be read: what deliveries said stands. A failed deployment comes first, since a
+    // commit with one failed deployment is not deployed whatever else succeeded.
+    const blind = !!error || verdicts.get(sha)?.state === 'none' || !gh.deployments;
+    const own = verdicts.get(sha);
+    const ownFailed = heardFailed(sha);
+    if (ownFailed && blind)
+        ownFailure = { sha: ownFailed.sha, later: false, state: ownFailed.failed };
+    const same = heardHere.find((h) => sameSha(h.sha, sha));
+    if (same && blind && !ownFailure)
+        return { found: { sha: same.sha, later: false } };
+    // The deploys of the merge commit itself are still on their way: only a later commit that deployed stands in for them. A later commit
+    // that failed says nothing about them.
+    const ownPending = own?.state === 'pending';
+    // A later commit that contains the merge: the ones webhooks heard of, then the newest of the environment.
+    const candidates = [];
+    const add = (c) => {
+        if (c && !sameSha(c, sha) && !candidates.some((x) => sameSha(x, c)))
+            candidates.push(c);
+    };
+    for (const h of heardAll)
+        if (h.at >= o.jobAt - LATER_SLACK_MS && (h.ok || h.failed))
+            add(h.sha);
+    // A read of the merge commit's own deployments that failed does not stop the look at the later commits (KAT-403): the list of the
+    // environment may read fine, and a later commit that deployed is the deploy of the merge. `githubOut` is set by the first later read that fails.
+    const ownReadFailed = !!error;
+    let githubOut = false;
+    if (gh.deployments) {
+        try {
+            for (const d of await gh.deployments({ environment, limit: 5 })) {
+                if (d.at && Date.parse(d.at) < o.jobAt - LATER_SLACK_MS)
+                    continue;
+                add(d.sha);
+            }
+        }
+        catch (err) {
+            error = err instanceof Error ? err.message : String(err);
+            githubOut = true;
+            // GitHub could not be read at all (the own set failed too): a failure that deliveries reported stands, as it always did.
+            if (!ownReadFailed)
+                laterUnread = true;
+        }
+    }
+    // The newest commit that deployed settles it, whatever order the candidates came in: a failed later commit that holds the merge is
+    // only the answer when no other later commit deployed, so a failure is kept aside and the rest are looked at first.
+    let laterFailed;
+    for (const later of candidates) {
+        if (!(await laterCounts(later)))
+            continue;
+        let verdict = { state: 'none' };
+        if (gh.deployments && !githubOut) {
+            try {
+                verdict = judgeSet(await setOf(later), rule);
+            }
+            catch (err) {
+                error = err instanceof Error ? err.message : String(err);
+                githubOut = true;
+                laterUnread = true;
+            }
+        }
+        if (verdict.state === 'failed') {
+            laterFailed ??= { sha: verdict.failed.sha || later, later: true, state: verdict.failed.state, id: verdict.failed.id };
+            continue;
+        }
+        if (verdict.state === 'deployed')
+            return { found: { sha: later, later: true, ...(verdict.url ? { url: verdict.url } : {}) } };
+        // No deployment of that commit on GitHub, or it cannot be read: what webhooks heard stands.
+        if (verdict.state === 'none') {
+            if (heardHere.some((h) => sameSha(h.sha, later)))
+                return { found: { sha: later, later: true } };
+            const failedHere = heardFailed(later);
+            if (failedHere)
+                laterFailed ??= { sha: later, later: true, state: failedHere.failed };
+        }
+    }
+    // The merge commit's own deploy failed and no later commit that holds the merge deployed: the merge is not on the environment. When
+    // the later commits could not be read on GitHub one of them may have deployed, so the wait goes on and the next look decides.
+    if (ownFailure)
+        return laterUnread ? { error: error ?? 'GitHub could not be read' } : { failed: ownFailure };
+    // A failed later commit ends the wait only when the merge commit's own deploy is known not to be on its way: not while it is still
+    // running, and not while GitHub cannot be read, since it may be running then too.
+    if (laterFailed && !ownPending && !error)
+        return { failed: laterFailed };
+    return error ? { error } : {};
+}
+// ---------- the gate ----------
+/** What a merge job needs for a wait, or null when it has none: no wait set, a run a person asked for, or nothing to wait for. */
+async function waitFor(w, ev) {
+    const sha = mergeShaOf(ev);
+    const repo = targetRepo(w, ev);
+    // The repo's own wait first, the dot's as the default (KAT-395).
+    const cfg = deployWaitOf(w, repo);
+    if (!cfg || !sha || !repo || repo.role !== 'app' || ev.requestedBy)
+        return null;
+    // A repo with Run tests off runs no tests of its own, so there is nothing to time, unless its merge runs a Tests repo (KAT-86): that
+    // suite tests the deployed build, and it is the one that needs the wait.
+    if (testsOffRepo(w, ev) && !(testRepoSwitches(w).onMerge && testReposFor(w, ev, 'post_merge').length))
+        return null;
+    // The environment deploys the default branch. A merge into a release branch the dot also tests would wait for a deploy that never comes.
+    const merged = ev.push ? ev.push.ref.replace(/^refs\/heads\//, '') : ev.pr?.baseRef;
+    const branch = repoForEvent(w, ev)?.defaultBranch ?? repo.defaultBranch;
+    if (merged && merged !== branch)
+        return null;
+    const gh = githubFor(w, ev);
+    if (gh.mode === 'demo' || !gh.deployments)
+        return null;
+    return { cfg, sha, repo, branch, gh };
+}
+/** The first step of a wait run: the same step the run of a merge starts with, so the wait follows the merge it is for. */
+const MERGE_STEP = 'Merge detected';
+/** The step of a wait: what it waits for and how long it has waited. With `over` it is the last word of the wait, once the time is known. */
+function waitStep(env, short, waitedMs, maxSec, error, over = false) {
+    const label = `Waiting for the ${env} deploy`;
+    const of = `${durationText(waitedMs)} of ${durationText(maxSec * 1000)}`;
+    if (over)
+        return { label, detail: `Waited ${of} for a successful deploy of merge commit ${short} to ${env}.` };
+    return {
+        label,
+        detail: `Merge commit ${short} has no successful deploy to ${env} yet. Waited ${of} so far. The tests start when it deploys, or when the time is up.${error ? ` The last look at GitHub failed: ${error}` : ''}`,
+    };
+}
+/** Ends the wait of a job. The job runs on the next claim, or this one when the gate returns false. */
+function release(job, state, outcome) {
+    update('jobs', job.id, { heldBy: null, deployWait: { ...state, state: 'released', outcome } });
+    return false;
+}
+/**
+ * The dot was paused or archived under a job that waits: the held run is cancelled with the step that says why, and the job ends its wait.
+ * The handler then closes the job as it does for any paused dot. False, like release: the job is not held any more.
+ */
+function stopWaiting(job, state) {
+    if (state?.runId)
+        closeDeployRun(state.runId, { label: 'Stopped waiting for the deploy', detail: 'The dot is paused, so localdost did not run this check.', status: 'warn' }, 'dot paused');
+    return state ? release(job, state, 'stopped') : false;
+}
+/**
+ * Queue gate: true when the job waits for the deploy of its merge and goes back to the queue. False when it may run: no wait applies,
+ * the merge is deployed, or the time is up. The run that shows the wait is made on the first look.
+ */
+export async function holdForDeploy(job, now = new Date()) {
+    if (job.kind !== 'post_merge')
+        return false;
+    const prior = job.deployWait;
+    // A job that waited already, or was replaced, does not wait again: a retry of its run starts at once.
+    if (prior && prior.state !== 'waiting')
+        return false;
+    const w = get('watches', job.watchId);
+    if (!w)
+        return false;
+    const ev = eventOf(job);
+    // The dot was paused while the job waited: the run stops, and the handler closes the job as it does for any paused dot.
+    if (w.paused || w.archived)
+        return stopWaiting(job, prior);
+    const need = prior ? await waitFor(w, ev) : await firstWaitFor(w, ev);
+    if (!need) {
+        // The setting was turned off, or no longer applies, while the job waited: the run goes on now.
+        if (prior?.runId)
+            holdRunForDeploy(prior.runId, { environment: prior.environment, sha: prior.sha, since: prior.since, until: now.toISOString() }, { label: 'Stopped waiting for the deploy', detail: 'The deploy wait no longer applies to this merge, so the tests start now.' });
+        return prior ? release(job, prior, 'off') : false;
+    }
+    const { cfg, sha, repo, branch, gh } = need;
+    const env = cfg.environment;
+    const short = sha.slice(0, 7);
+    const since = prior?.since ?? now.toISOString();
+    const waitedMs = now.getTime() - Date.parse(since);
+    const deadline = Date.parse(since) + cfg.sec * 1000;
+    const state = { ...(prior ?? { since, sha, repo: repoKey(repo) }), state: 'waiting', environment: env };
+    const hold = { environment: env, sha, since, until: new Date(deadline).toISOString() };
+    if (!state.runId) {
+        // The run of this merge starts here, so the wait is on screen from the first look. It is held at once and the job keeps its id, so
+        // whatever happens next the job's own start finds it (src/agent/runs.ts startRun) and no run is left running with nobody to renew it.
+        state.runId = await withJobContext(job, async () => {
+            const run = startRun(w.id, 'post_merge', ev);
+            addStep(run.id, MERGE_STEP, ev.title);
+            holdRunForDeploy(run.id, hold, waitStep(env, short, 0, cfg.sec));
+            return run.id;
+        });
+        update('jobs', job.id, { deployWait: state });
+        void noteDeployWait(job, w, `Waiting for the ${env} deploy`, `${ev.title}\n\nlocaldost waits for merge commit ${short} to deploy to ${env}, up to ${durationText(cfg.sec * 1000)}, and tests after that.`);
+    }
+    // A merge that waits and is newer ends the wait of the older one. When this job is the older one, the newer one ends this job.
+    await settleOrder(job, w, ev, sha, gh);
+    if (replaced(job.id))
+        return true;
+    const lookStarted = Date.now();
+    const look = await lookDeployed({
+        gh,
+        repo,
+        branch,
+        environment: env,
+        sha,
+        jobAt: Date.parse(job.createdAt) || now.getTime(),
+        rule: { baseUrl: w.baseUrl, match: repo.deployUrlMatch },
+    });
+    // A newer merge may have replaced this job while the look was under way. The job stays as that merge left it.
+    if (replaced(job.id))
+        return true;
+    // The dot may have been paused or archived while the look was under way. releaseDeployWaits wakes only the jobs that sit in the queue,
+    // so this job, which was running, is the one that must notice: it ends its wait now and not with a deploy that nobody tests.
+    const now2 = get('watches', job.watchId);
+    if (!now2 || now2.paused || now2.archived)
+        return stopWaiting(job, state);
+    if (look.error)
+        state.lastError = look.error;
+    else
+        delete state.lastError;
+    // The run stays held until the handler starts it again, so each ending is a step on the held run.
+    if (look.failed) {
+        const d = look.failed;
+        const words = environmentWords(env);
+        const sentence = `The ${words} deploy of this merge failed, so the tests did not run.`;
+        holdRunForDeploy(state.runId, hold, {
+            label: `Waiting for the ${env} deploy`,
+            detail: `Waited ${durationText(waitedMs)} of ${durationText(cfg.sec * 1000)} for a successful deploy of merge commit ${short} to ${env}.`,
+        });
+        // The wait ends here and nothing tests: no test run, so no defect and no verdict about the product. The check on the commit says why.
+        closeDeployRun(state.runId, {
+            label: sentence,
+            detail: `${d.later ? `Commit ${d.sha.slice(0, 7)}, which contains the merge commit ${short},` : `Merge commit ${short}`} has a deployment to ${env} that ended in ${d.state}${d.id ? ` (deployment ${d.id})` : ''}. Waited ${durationText(waitedMs)}.`,
+            status: 'error',
+        }, 'the failed deploy');
+        update('jobs', job.id, {
+            status: 'done',
+            error: sentence,
+            finishedAt: new Date().toISOString(),
+            heldBy: null,
+            deployWait: { ...state, state: 'released', outcome: 'failed' },
+        });
+        void closeUnrun(job, w, `The ${words} deploy failed`, sentence);
+        log.info(`deploy wait: job ${job.id} for ${short} ends, the ${env} deploy ended in ${d.state}`);
+        return true;
+    }
+    if (look.found) {
+        const d = look.found;
+        const target = deployTargetFor(w, ev, d.url);
+        holdRunForDeploy(state.runId, hold, waitStep(env, short, waitedMs, cfg.sec, undefined, true));
+        holdRunForDeploy(state.runId, hold, {
+            label: `Deployed to ${env}`,
+            detail: `${d.later ? `Commit ${d.sha.slice(0, 7)}, which contains the merge commit ${short}, deployed to ${env}` : `Merge commit ${short} deployed to ${env}`}. Waited ${durationText(waitedMs)}. The tests start now${target.url ? `, against ${target.url}` : ''}.${target.ignored
+                ? ` The deploy gave the address ${target.ignored}, which is outside the site of the Base URL, so the tests run against the Base URL and keep the test login away from it.`
+                : ''}`,
+            status: target.ignored ? 'warn' : 'ok',
+        });
+        if (target.url)
+            state.url = target.url;
+        return release(job, state, 'deployed');
+    }
+    if (now.getTime() >= deadline) {
+        holdRunForDeploy(state.runId, hold, waitStep(env, short, waitedMs, cfg.sec, undefined, true));
+        holdRunForDeploy(state.runId, hold, {
+            label: DEPLOY_TIMEOUT_LABEL,
+            detail: `Waited ${durationText(cfg.sec * 1000)} for a successful deploy of ${short} to ${env}. The tests run on the ${env} build as it is.${state.lastError ? ` The last look at GitHub failed: ${state.lastError}` : ''}`,
+            status: 'warn',
+        });
+        return release(job, state, 'timeout');
+    }
+    // Not deployed yet. The run says how long it has waited, and the job goes back to the queue for the next look.
+    // A deployment_status that came in while this look was under way found the job running, so it woke nothing: look again at once.
+    const gapMs = heardSince(repo, env, lookStarted) ? 0 : (wantsGithubPoll(w) ? DEPLOY_POLL_SEC : DEPLOY_NUDGE_SEC) * 1000;
+    const next = Math.max(now.getTime() + 1000, Math.min(now.getTime() + gapMs, deadline));
+    holdRunForDeploy(state.runId, hold, waitStep(env, short, waitedMs, cfg.sec, state.lastError));
+    update('jobs', job.id, {
+        status: 'queued',
+        attempts: Math.max(0, job.attempts - 1),
+        runAfter: new Date(next).toISOString(),
+        error: null,
+        heldBy: 'deploy_wait',
+        deployWait: state,
+    });
+    return true;
+}
+/**
+ * The first look at a job: like waitFor, and a merge that changes only docs is left out when the dot skips the tests of such a
+ * change (the run would skip them after the wait, and the environment may not deploy docs). A diff GitHub cannot give keeps the wait.
+ */
+async function firstWaitFor(w, ev) {
+    const need = await waitFor(w, ev);
+    if (!need || !testSavings(w).docsOnlySkip)
+        return need;
+    try {
+        if (docsOnlyChange(await getDiff(w, ev)))
+            return null;
+    }
+    catch {
+        /* the wait goes on */
+    }
+    return need;
+}
+// ---------- a newer merge, and a deployment that arrives ----------
+/** True when a newer merge replaced the job: its wait is over, and nothing more is done for it. */
+function replaced(jobId) {
+    return get('jobs', jobId)?.deployWait?.state === 'superseded';
+}
+/**
+ * The jobs that wait for another merge into the same branch of the same repository, a job in the middle of its look included. Not
+ * this job, and not the same commit: one merge that arrives twice (a pull request event and a push event) is not a newer merge.
+ */
+function waitingForOthers(job, w, ev, sha) {
+    const scope = scopeOf('post_merge', ev, w, sha);
+    const repo = repoTarget(w, ev);
+    return list('jobs', { watchId: w.id, status: ['queued', 'running'] }).filter((j) => {
+        const st = j.deployWait;
+        if (j.id === job.id || j.kind !== 'post_merge' || !st || st.state !== 'waiting' || sameSha(st.sha, sha))
+            return false;
+        const other = eventOf(j);
+        return repoTarget(w, other) === repo && scopeOf('post_merge', other, w, st.sha) === scope;
+    });
+}
+/**
+ * Which merge is later in the branch: GitHub's compare of the two merge commits says which one holds the other. The order the two
+ * events came in says nothing, since each merge sends two events and a delivery can be late. `unknown` when GitHub cannot say.
+ */
+async function laterMerge(gh, mine, other) {
+    try {
+        // compareStatus(base, head) is `behind` when head is an ancestor of base: the other merge is behind this one.
+        const rel = await gh.compareStatus(mine, other);
+        return rel === 'behind' ? 'newer' : rel === 'ahead' ? 'older' : 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+/** Ends the wait of a job: its job is done, its run is cancelled with the step that says which merge tests instead, and its check is closed. */
+function endWait(j, w, by) {
+    const st = j.deployWait;
+    if (!st)
+        return;
+    const scope = scopeOf('post_merge', eventOf(j), w, st.sha);
+    const branch = scope.replace(/^branch:/, '');
+    update('jobs', j.id, {
+        status: 'done',
+        error: `Superseded by the newer merge ${by.slice(0, 7)}.`,
+        finishedAt: new Date().toISOString(),
+        heldBy: null,
+        deployWait: { ...st, state: 'superseded' },
+    });
+    if (st.runId)
+        closeDeployRun(st.runId, {
+            label: 'Superseded by a newer merge',
+            detail: `${by.slice(0, 7)} is a newer merge${scope.startsWith('branch:') ? ` into ${branch}` : ''}, so localdost tests that merge instead of waiting for the ${st.environment} deploy of ${st.sha.slice(0, 7)}.`,
+            status: 'warn',
+        }, 'a newer merge');
+    void noteSupersededWait(j, w, by);
+    log.info(`deploy wait: job ${j.id} for ${st.sha.slice(0, 7)} superseded by the newer merge ${by.slice(0, 7)}`);
+}
+/**
+ * Settles which merge waits when two merges into the same branch both wait. The later one in the branch replaces the other: when it
+ * is this job's merge, the other job ends; when it is not (the event of an older merge came in late), this job ends. When GitHub cannot
+ * say which is later, both keep waiting: a build tested twice costs less than a merge that nothing tests. Called by a job that waits,
+ * on each of its looks, so a pair left open once is settled on the next look.
+ */
+async function settleOrder(job, w, ev, sha, gh) {
+    for (const other of waitingForOthers(job, w, ev, sha)) {
+        const theirs = other.deployWait.sha;
+        const order = await laterMerge(gh, sha, theirs);
+        // The compare took time, and another look may have ended either job meanwhile: act on what is still so.
+        const mine = get('jobs', job.id);
+        if (mine?.deployWait?.state !== 'waiting')
+            return;
+        const there = get('jobs', other.id);
+        if (there?.deployWait?.state !== 'waiting')
+            continue;
+        if (order === 'newer')
+            endWait(there, w, sha);
+        else if (order === 'older') {
+            endWait(mine, w, theirs);
+            return;
+        }
+    }
+}
+/** Makes the jobs of a dot that wait look again now: the dot's deploy wait was changed in a save. Returns how many it woke. */
+export function releaseDeployWaits(w, now = new Date()) {
+    const waiting = list('jobs', { watchId: w.id, status: 'queued', heldBy: 'deploy_wait' });
+    for (const j of waiting)
+        update('jobs', j.id, { runAfter: now.toISOString() });
+    return waiting.length;
+}
+/** A deployment_status that ends a deployment arrived: remember a success, and wake the jobs that wait for that repository and environment. */
+function onDeployment(d, now = new Date()) {
+    hear(d, now.getTime());
+    let woken = 0;
+    for (const j of list('jobs', { status: 'queued', heldBy: 'deploy_wait' })) {
+        const st = j.deployWait;
+        if (!st || st.state !== 'waiting' || st.repo !== repoKey(d.repo) || lc(st.environment) !== lc(d.environment))
+            continue;
+        update('jobs', j.id, { runAfter: now.toISOString() });
+        woken++;
+    }
+    if (woken)
+        log.info(`deploy wait: ${d.repo.owner}/${d.repo.name} deployment of ${d.sha.slice(0, 7)} to ${d.environment} ended in ${d.state}, ${woken} job(s) look again`);
+    return woken;
+}
+let registered = false;
+/** Puts the gate and the deployment listener in place. Importing src/flows/index.ts does this once. */
+export function registerDeployWait() {
+    if (registered)
+        return;
+    registered = true;
+    onBeforeJob((job) => holdForDeploy(job));
+    onDeploymentEnd((d) => void onDeployment(d));
+}
+//# sourceMappingURL=deploy-wait.js.map