@intentius/chant 0.58.0 → 0.60.0

package/src/op/activities/reconcile.ts

@@ -1,10 +1,26 @@
 import { exec } from "node:child_process";
+import { readFile } from "node:fs/promises";
 import { promisify } from "node:util";
 
 const execAsync = promisify(exec);
 
-/** What the reconcile activity does with the regenerated source. */
-export type ReconcileMode = "pull-request" | "issue" | "report";
+/**
+ * What the reconcile activity does with the regenerated source.
+ *
+ * `comment` is the one mode that posts nothing new: it writes the body onto
+ * the pull request that triggered the run, updating the same comment on every
+ * re-run (chant #2231). It therefore needs a pull-request trigger, and
+ * {@link resolvePullRequestContext} fails the step by name when the run has
+ * none.
+ *
+ * On GitLab the same mode writes a merge-request note (chant #2256): the same
+ * marker, the same edit-in-place, a different API. Which forge a run is on is
+ * read off the run's own CI variables rather than configured — a
+ * `merge_request_event` pipeline sets `CI_MERGE_REQUEST_IID`, a GitHub
+ * `pull_request` event sets `GITHUB_REPOSITORY`, and no run sets both. See
+ * {@link mergeRequestContextFrom}.
+ */
+export type ReconcileMode = "pull-request" | "issue" | "report" | "comment";
 
 /** A change-set entry that triggered reconciliation. */
 export interface ReconcileEntry {
@@ -35,6 +51,14 @@ export interface ReconcilePrArgs {
   owned?: boolean;
   /** PR / issue title. Default derived from env. */
   title?: string;
+  /**
+   * Hidden marker identifying this Op's comment on the pull request (comment
+   * mode). The activity writes it as the comment's first line and finds the
+   * comment again by it on the next run, so a re-run edits one comment instead
+   * of stacking a new one. Default: {@link commentMarker} keyed on `env`, so
+   * two Ops over two roots get two comments and each updates in place.
+   */
+  marker?: string;
   /**
    * A finding body built by the caller, used verbatim as the issue/PR body in
    * place of {@link reconcileSummary} (chant #2087).
@@ -61,6 +85,12 @@ export interface ReconcileResult {
   prUrl?: string;
   /** Opened issue URL (issue mode). */
   issueUrl?: string;
+  /** The posted or updated PR comment / MR note URL (comment mode). */
+  commentUrl?: string;
+  /** The pull request the comment landed on, `owner/repo#number` (comment mode, GitHub). */
+  pullRequest?: string;
+  /** The merge request the note landed on, `group/project!iid` (comment mode, GitLab — #2256). */
+  mergeRequest?: string;
   /** The markdown summary used as the PR/issue body. */
   summary: string;
   /** The entries that triggered the reconcile. */
@@ -101,6 +131,359 @@ function shellQuote(s: string): string {
   return `'${s.replace(/'/g, "'\\''")}'`;
 }
 
+/** The pull request a `comment`-mode run posts onto. */
+export interface PullRequestContext {
+  /** `owner/repo`, from `GITHUB_REPOSITORY`. */
+  repo: string;
+  /** The pull request number. */
+  number: number;
+}
+
+/**
+ * The hidden marker that makes a `comment`-mode finding findable across
+ * re-runs: written as the comment's first line, matched with `startswith` on
+ * the next run. Keyed on `env` (slugified the same way {@link
+ * reconcileBranchName} slugifies it, which also keeps the value free of the
+ * quotes and backslashes it is interpolated next to), so two Ops over two
+ * environments own two comments and each updates in place.
+ */
+export function commentMarker(env: string): string {
+  return `<!-- chant-reconcile:${env.replace(/[^a-zA-Z0-9._-]+/g, "-")} -->`;
+}
+
+/** What a `comment`-mode step says when the run it is in has no pull request and no merge request. */
+export function noPullRequestContextMessage(): string {
+  return (
+    'reconcilePr mode "comment" posts the finding on the pull request or merge request that triggered the ' +
+    "run, and this run has none. On GitHub Actions it needs GITHUB_REPOSITORY plus a pull request number, " +
+    "read from the event payload at GITHUB_EVENT_PATH (`.number` / `.pull_request.number`) or from " +
+    "GITHUB_REF (`refs/pull/<n>/merge`), which a pull_request event sets and nothing else does. On GitLab " +
+    "CI it needs CI_MERGE_REQUEST_IID plus the project (CI_MERGE_REQUEST_PROJECT_ID or CI_PROJECT_ID) and " +
+    "the API base (CI_API_V4_URL, or CI_SERVER_URL to derive it), which a merge_request_event pipeline " +
+    "sets and nothing else does. Trigger this Op from a pull_request or merge_request pipeline, or give " +
+    'it findingMode "issue" or "report".'
+  );
+}
+
+/**
+ * Read the pull request number out of a parsed webhook event payload. Pure.
+ * A `pull_request` event carries it top-level as `number` and again under
+ * `pull_request.number`; both are accepted, neither is invented.
+ */
+function prNumberFromPayload(payload: unknown): number | undefined {
+  if (typeof payload !== "object" || payload === null) return undefined;
+  const p = payload as { number?: unknown; pull_request?: { number?: unknown } };
+  if (typeof p.number === "number") return p.number;
+  if (typeof p.pull_request?.number === "number") return p.pull_request.number;
+  return undefined;
+}
+
+/**
+ * Derive the triggering pull request from CI environment variables plus the
+ * already-parsed event payload. Pure — exported for testing; the IO (reading
+ * `GITHUB_EVENT_PATH`) is {@link resolvePullRequestContext}'s.
+ *
+ * Returns undefined rather than throwing, so the caller owns the message.
+ */
+export function pullRequestContextFrom(
+  env: Record<string, string | undefined>,
+  eventPayload?: unknown,
+): PullRequestContext | undefined {
+  const repo = env.GITHUB_REPOSITORY;
+  if (!repo) return undefined;
+  const fromRef = /^refs\/pull\/(\d+)\//.exec(env.GITHUB_REF ?? "")?.[1];
+  const number = prNumberFromPayload(eventPayload) ?? (fromRef ? Number(fromRef) : undefined);
+  if (number === undefined || !Number.isInteger(number) || number <= 0) return undefined;
+  return { repo, number };
+}
+
+/**
+ * Resolve the triggering pull request, reading and parsing the event payload
+ * `GITHUB_EVENT_PATH` names. Throws {@link noPullRequestContextMessage} when
+ * the run has no pull request, which is the whole point: a `comment` mode that
+ * quietly fell back to an issue would post the finding somewhere nobody asked
+ * for it.
+ */
+export async function resolvePullRequestContext(
+  env: Record<string, string | undefined> = process.env,
+): Promise<PullRequestContext> {
+  let payload: unknown;
+  const eventPath = env.GITHUB_EVENT_PATH;
+  if (eventPath) {
+    try {
+      payload = JSON.parse(await readFile(eventPath, "utf8"));
+    } catch {
+      // An unreadable or malformed payload is not fatal on its own: GITHUB_REF
+      // may still name the pull request. If it does not, the error below says so.
+      payload = undefined;
+    }
+  }
+  const ctx = pullRequestContextFrom(env, payload);
+  if (!ctx) throw new Error(noPullRequestContextMessage());
+  return ctx;
+}
+
+/**
+ * Post `body` as one comment on `ctx`'s pull request, or edit the comment this
+ * Op already owns there. The sticky-comment recipe the github lexicon's
+ * `PrPlanReport` uses, run from the activity instead of from generated YAML:
+ * find the comment whose body starts with `marker`, PATCH it when there is
+ * one, POST otherwise. `gh` ships on GitHub's hosted runners and is already
+ * this activity's dependency for the issue and pull-request modes, so the
+ * mode needs nothing new on the runner.
+ */
+async function postOrUpdateComment(
+  ctx: PullRequestContext,
+  marker: string,
+  body: string,
+  signal?: AbortSignal,
+): Promise<string> {
+  const listPath = `repos/${ctx.repo}/issues/${ctx.number}/comments`;
+  const jq = `map(select(.body | startswith("${marker}"))) | .[0].id // empty`;
+  const { stdout: found } = await execAsync(
+    `gh api ${shellQuote(listPath)} --paginate --jq ${shellQuote(jq)}`,
+    { signal },
+  );
+  // `--paginate` prints one `--jq` result per page, so take the first line
+  // that is an id and ignore the empty ones the other pages produce.
+  const existing = found.split("\n").map((l) => l.trim()).find((l) => /^\d+$/.test(l));
+  const field = `body=${marker}\n\n${body}`;
+
+  if (existing) {
+    const { stdout } = await execAsync(
+      `gh api --method PATCH ${shellQuote(`repos/${ctx.repo}/issues/comments/${existing}`)} ` +
+        `-f ${shellQuote(field)} --jq .html_url`,
+      { signal },
+    );
+    return stdout.trim();
+  }
+  const { stdout } = await execAsync(
+    `gh api --method POST ${shellQuote(listPath)} -f ${shellQuote(field)} --jq .html_url`,
+    { signal },
+  );
+  return stdout.trim();
+}
+
+// ── The GitLab merge-request note (#2256) ───────────────────────────────────
+
+/**
+ * The merge request a `comment`-mode run posts its note onto (#2256), as a
+ * GitLab CI job knows it. The GitLab counterpart of {@link
+ * PullRequestContext}.
+ */
+export interface MergeRequestContext {
+  /** REST v4 base, from `CI_API_V4_URL` or derived from `CI_SERVER_URL`. */
+  api: string;
+  /** The project holding the merge request — its numeric id, or a `group/project` path. */
+  project: string;
+  /** The merge request's `iid` (its per-project number, which is what the API path takes). */
+  iid: number;
+  /** `group/project`, for the human-readable `group/project!iid` on the result. */
+  path?: string;
+  /** The project's web URL, used to build the note's own URL. */
+  webUrl?: string;
+}
+
+/**
+ * Derive the triggering merge request from a GitLab job's CI variables. Pure
+ * — exported for testing, and the whole forge detection: nothing but a
+ * `merge_request_event` pipeline sets `CI_MERGE_REQUEST_IID`, so a run that
+ * has it is on GitLab and has a merge request, and a run that does not is
+ * neither.
+ *
+ * The project is the merge request's own (`CI_MERGE_REQUEST_PROJECT_ID`) in
+ * preference to the pipeline's (`CI_PROJECT_ID`): a merge request opened from
+ * a fork runs its pipeline in the fork, and the note belongs on the target
+ * project's merge request rather than on an iid that means something else in
+ * the fork.
+ *
+ * Returns undefined rather than throwing, so the caller owns the message.
+ */
+export function mergeRequestContextFrom(
+  env: Record<string, string | undefined>,
+): MergeRequestContext | undefined {
+  const rawIid = env.CI_MERGE_REQUEST_IID?.trim();
+  if (!rawIid) return undefined;
+  const iid = Number(rawIid);
+  if (!Number.isInteger(iid) || iid <= 0) return undefined;
+
+  const server = env.CI_SERVER_URL?.trim().replace(/\/+$/, "");
+  const api = env.CI_API_V4_URL?.trim().replace(/\/+$/, "") || (server ? `${server}/api/v4` : "");
+  if (!api) return undefined;
+
+  const project =
+    env.CI_MERGE_REQUEST_PROJECT_ID?.trim() ||
+    env.CI_PROJECT_ID?.trim() ||
+    env.CI_MERGE_REQUEST_PROJECT_PATH?.trim() ||
+    env.CI_PROJECT_PATH?.trim() ||
+    "";
+  if (!project) return undefined;
+
+  const path = env.CI_MERGE_REQUEST_PROJECT_PATH?.trim() || env.CI_PROJECT_PATH?.trim();
+  const webUrl = env.CI_MERGE_REQUEST_PROJECT_URL?.trim() || env.CI_PROJECT_URL?.trim();
+  return {
+    api,
+    project,
+    iid,
+    ...(path ? { path } : {}),
+    ...(webUrl ? { webUrl } : {}),
+  };
+}
+
+/** The credential a merge-request note is written with, and the header GitLab reads it from. */
+export interface GitlabNoteToken {
+  /** `PRIVATE-TOKEN` for a personal/project/group access token, `JOB-TOKEN` for `CI_JOB_TOKEN`. */
+  header: "PRIVATE-TOKEN" | "JOB-TOKEN";
+  value: string;
+  /** The variable it came from, so a refusal or a log line can name it. */
+  source: string;
+}
+
+/**
+ * Resolve the token a merge-request note is written with, most specific
+ * first. Pure — exported for testing.
+ *
+ * Two headers, not one, because GitLab reads two different credentials from
+ * two different headers: an access token goes in `PRIVATE-TOKEN`, and the
+ * pipeline's own ephemeral `CI_JOB_TOKEN` goes in `JOB-TOKEN`. Sending one in
+ * the other's header is a 401, not a fallback.
+ *
+ * The access token is preferred because it is the one that reliably works:
+ * `CI_JOB_TOKEN` reaches only the endpoints GitLab's job-token allowlist
+ * names, and the notes API is not among them on current GitLab, so a project
+ * that has not widened that allowlist needs a token with `api` scope. It is
+ * still accepted last rather than refused, so a project on an instance whose
+ * allowlist does cover notes needs no long-lived credential at all.
+ */
+export function gitlabNoteTokenFrom(
+  env: Record<string, string | undefined>,
+): GitlabNoteToken | undefined {
+  for (const source of ["CHANT_GITLAB_TOKEN", "GITLAB_TOKEN"]) {
+    const value = env[source]?.trim();
+    if (value) return { header: "PRIVATE-TOKEN", value, source };
+  }
+  const jobToken = env.CI_JOB_TOKEN?.trim();
+  if (jobToken) return { header: "JOB-TOKEN", value: jobToken, source: "CI_JOB_TOKEN" };
+  return undefined;
+}
+
+/** What a `comment`-mode step says on a merge request it has no credential for. */
+export function noGitlabNoteTokenMessage(iid: number): string {
+  return (
+    `reconcilePr mode "comment" has merge request !${iid} to post its finding on and no token to post it ` +
+    "with. Set a GITLAB_TOKEN CI/CD variable (masked, scope: api) on the project — a project access token " +
+    "is enough — or, on an instance whose job-token allowlist covers the notes API, make CI_JOB_TOKEN " +
+    "available to the job. CHANT_GITLAB_TOKEN is read first where the two must differ."
+  );
+}
+
+/** One page of merge-request notes, as much of each as this activity reads. */
+interface GitlabNote {
+  id: number;
+  body?: string;
+  /** GitLab's own generated notes ("changed the description"), never ours. */
+  system?: boolean;
+}
+
+/** GitLab's REST paths take a URL-encoded project id or `group%2Fproject` path. */
+function notesEndpoint(ctx: MergeRequestContext): string {
+  return `${ctx.api}/projects/${encodeURIComponent(ctx.project)}/merge_requests/${ctx.iid}/notes`;
+}
+
+/** One GitLab REST call, with the failure spelled out rather than swallowed into a parse error. */
+async function gitlabRequest(
+  url: string,
+  token: GitlabNoteToken,
+  init: RequestInit,
+  signal?: AbortSignal,
+): Promise<Response> {
+  const res = await fetch(url, {
+    ...init,
+    ...(signal ? { signal } : {}),
+    headers: { [token.header]: token.value, "content-type": "application/json" },
+  });
+  if (!res.ok) {
+    const detail = (await res.text().catch(() => "")).slice(0, 500);
+    throw new Error(
+      `GitLab API ${init.method ?? "GET"} ${url} answered ${res.status}${detail ? `: ${detail}` : ""} ` +
+        `(token from ${token.source}, sent as ${token.header}).`,
+    );
+  }
+  return res;
+}
+
+/**
+ * Find the note this Op already owns on `ctx`'s merge request, by the same
+ * hidden marker `postOrUpdateComment` looks a GitHub comment up by: the
+ * marker is the body's first line and the match is a prefix.
+ *
+ * Pages the way GitLab pages, following the `x-next-page` response header
+ * rather than guessing a page count — an active merge request runs past one
+ * page of notes routinely, and a lookup that read page one alone would post
+ * a second comment instead of editing the first.
+ *
+ * GitLab's own system notes are skipped: they are the activity feed
+ * ("changed the description"), they are never ours, and they are the bulk of
+ * what fills those pages.
+ */
+async function findOwnedNote(
+  ctx: MergeRequestContext,
+  token: GitlabNoteToken,
+  marker: string,
+  signal?: AbortSignal,
+): Promise<number | undefined> {
+  const endpoint = notesEndpoint(ctx);
+  // A merge request with more notes than this has something other than a
+  // stale plan comment wrong with it; the bound is what stops a broken
+  // `x-next-page` header from looping forever.
+  const MAX_PAGES = 50;
+  for (let page = 1; page <= MAX_PAGES; page++) {
+    const res = await gitlabRequest(`${endpoint}?per_page=100&page=${page}`, token, { method: "GET" }, signal);
+    const notes = (await res.json()) as GitlabNote[];
+    const owned = notes.find((note) => !note.system && (note.body ?? "").startsWith(marker));
+    if (owned) return owned.id;
+    const next = res.headers.get("x-next-page")?.trim();
+    if (!next) return undefined;
+  }
+  return undefined;
+}
+
+/**
+ * Post `body` as one note on `ctx`'s merge request, or edit the note this Op
+ * already owns there — {@link postOrUpdateComment}'s GitLab half, and the
+ * same recipe: find by marker, PUT when there is one, POST when there is not,
+ * so a merge request pushed to five times carries one note holding the
+ * current finding rather than five stale ones.
+ *
+ * Over `fetch` rather than a CLI. `gh` is on GitHub's hosted runners and is
+ * already this activity's dependency for the issue and pull-request modes;
+ * `glab` is on no GitLab runner by default, and a job whose finding step
+ * depended on it would fail on the ordinary `node:22-slim` image the
+ * generator emits.
+ */
+async function postOrUpdateNote(
+  ctx: MergeRequestContext,
+  token: GitlabNoteToken,
+  marker: string,
+  body: string,
+  signal?: AbortSignal,
+): Promise<string> {
+  const endpoint = notesEndpoint(ctx);
+  const existing = await findOwnedNote(ctx, token, marker, signal);
+  const payload = JSON.stringify({ body: `${marker}\n\n${body}` });
+  const res = existing
+    ? await gitlabRequest(`${endpoint}/${existing}`, token, { method: "PUT", body: payload }, signal)
+    : await gitlabRequest(endpoint, token, { method: "POST", body: payload }, signal);
+  const note = (await res.json()) as GitlabNote;
+  // GitLab's note payload carries no web URL, unlike GitHub's comment. The
+  // anchor is how the UI itself addresses a note, so it is built rather than
+  // read; with no project web URL to build it from, the API path is at least
+  // a resolvable address for the thing that was written.
+  return ctx.webUrl
+    ? `${ctx.webUrl}/-/merge_requests/${ctx.iid}#note_${note.id}`
+    : `${endpoint}/${note.id}`;
+}
+
 /**
  * Map a `chant lifecycle plan --json` ChangeSet to reconcile entries, dropping
  * `noop` entries (nothing to reconcile). Pure — exported for testing.
@@ -133,6 +516,15 @@ async function derivePlanEntries(
  *
  * - `report` — return the summary only; no git, no network.
  * - `issue` — open a GitHub issue describing the drift (no code change).
+ * - `comment` — post the body as one comment on the pull request that
+ *   triggered the run, editing that same comment on every re-run rather than
+ *   stacking a new one (#2231), or, on a GitLab `merge_request_event`
+ *   pipeline, as one note on that merge request by the same recipe (#2256).
+ *   Needs a pull-request- or merge-request-triggered run; fails by name when
+ *   there is none. No code change, and the `pull-requests: write` the
+ *   generated workflow already grants on that trigger is the whole scope it
+ *   spends on GitHub; on GitLab the scope is whatever the token it is given
+ *   carries.
  * - `pull-request` — create a branch, regenerate source via
  *   `chant import --from <env>`, commit, push, and open a PR whose diff is the
  *   regenerated TypeScript. Never commits to the main branch.
@@ -164,6 +556,35 @@ export async function reconcilePr(args: ReconcilePrArgs, signal?: AbortSignal):
     return { mode, summary, entries, issueUrl: stdout.trim() };
   }
 
+  if (mode === "comment") {
+    // The trigger context is read here rather than passed in: a step's args
+    // are serialized at build time, and the pull request is not known until
+    // the run. Missing context is fatal — see `noPullRequestContextMessage`.
+    const marker = args.marker ?? commentMarker(args.env);
+
+    // GitLab first, because its check is the narrow one: only a
+    // `merge_request_event` pipeline sets `CI_MERGE_REQUEST_IID` (#2256), so
+    // a run that has it is unambiguously the GitLab case, and a GitHub run
+    // never reaches this branch.
+    const mr = mergeRequestContextFrom(process.env);
+    if (mr) {
+      const token = gitlabNoteTokenFrom(process.env);
+      if (!token) throw new Error(noGitlabNoteTokenMessage(mr.iid));
+      const commentUrl = await postOrUpdateNote(mr, token, marker, summary, signal);
+      return {
+        mode,
+        summary,
+        entries,
+        commentUrl,
+        mergeRequest: `${mr.path ?? mr.project}!${mr.iid}`,
+      };
+    }
+
+    const ctx = await resolvePullRequestContext();
+    const commentUrl = await postOrUpdateComment(ctx, marker, summary, signal);
+    return { mode, summary, entries, commentUrl, pullRequest: `${ctx.repo}#${ctx.number}` };
+  }
+
   // pull-request
   const branch = args.branch ?? reconcileBranchName(args.env);
   const output = args.output ?? "./infra";

package/src/op/builders.ts

@@ -105,16 +105,16 @@ export function activity(
 /**
  * Insert a human gate. A gate is a fact on the gate ledger, not a wait: a run
  * that reaches this step with no resolution newer than its pending fact
- * records the pending fact and ends `gated`. `chant approve <op> <signalName>`
+ * records the pending fact and ends `gated`. `chant approve <op> <gate>`
  * writes the resolution, and the next run walks through carrying the approver.
  */
 export function gate(
-  signalName: string,
+  name: string,
   opts?: { timeout?: string; description?: string },
 ): GateStep {
   return {
     kind: "gate",
-    signalName,
+    gate: name,
     ...(opts?.timeout ? { timeout: opts.timeout } : {}),
     ...(opts?.description ? { description: opts.description } : {}),
   };

package/src/op/change-signal.test.ts

@@ -0,0 +1,117 @@
+/**
+ * The wake gate (#1981): coalescing, the floor, and abort.
+ *
+ * Real timers with small floors rather than fake ones: the gate is nothing but
+ * two `setTimeout`s racing, and a fake-timer test of that asserts the mock
+ * rather than the behaviour.
+ */
+import { describe, test, expect } from "vitest";
+import { createChangeSignalGate, DEFAULT_SIGNAL_FLOOR_MS } from "./change-signal";
+
+describe("createChangeSignalGate", () => {
+  test("no signal: the wait runs the full interval and reports the timer", async () => {
+    const gate = createChangeSignalGate({ floorMs: 10 });
+    gate.roundStarted();
+    const started = Date.now();
+    expect(await gate.wait(60)).toBe("timer");
+    expect(Date.now() - started).toBeGreaterThanOrEqual(45);
+    expect(gate.wakeCount).toBe(0);
+  });
+
+  test("a signal past the floor wakes the sleep early", async () => {
+    const gate = createChangeSignalGate({ floorMs: 0 });
+    gate.roundStarted();
+    const started = Date.now();
+    const waiting = gate.wait(5_000);
+    setTimeout(() => gate.signal(), 10);
+    expect(await waiting).toBe("signal");
+    expect(Date.now() - started).toBeLessThan(2_000);
+    expect(gate.wakeCount).toBe(1);
+  });
+
+  test("a signal inside the floor waits the floor out rather than waking at once", async () => {
+    const gate = createChangeSignalGate({ floorMs: 120 });
+    gate.roundStarted();
+    const started = Date.now();
+    const waiting = gate.wait(5_000);
+    gate.signal();
+    expect(await waiting).toBe("signal");
+    // Woken by the signal, but not before the floor had passed.
+    expect(Date.now() - started).toBeGreaterThanOrEqual(100);
+  });
+
+  test("a storm of signals inside one floor window costs exactly one wake", async () => {
+    const gate = createChangeSignalGate({ floorMs: 60 });
+    gate.roundStarted();
+    const waiting = gate.wait(5_000);
+    for (let i = 0; i < 500; i++) gate.signal();
+    expect(await waiting).toBe("signal");
+    expect(gate.signalCount).toBe(500);
+    expect(gate.wakeCount).toBe(1);
+  });
+
+  test("the floor is measured from the round, so a steady stream cannot starve the tick", async () => {
+    const gate = createChangeSignalGate({ floorMs: 80 });
+    gate.roundStarted();
+    const started = Date.now();
+    const waiting = gate.wait(5_000);
+    // A signal every 10ms. A debounce would push the deadline out forever.
+    const drip = setInterval(() => gate.signal(), 10);
+    const reason = await waiting;
+    clearInterval(drip);
+    expect(reason).toBe("signal");
+    expect(Date.now() - started).toBeLessThan(1_000);
+  });
+
+  test("a signal arriving between rounds is honoured by the next wait, not lost", async () => {
+    const gate = createChangeSignalGate({ floorMs: 0 });
+    gate.roundStarted();
+    gate.signal(); // nothing is sleeping yet
+    expect(await gate.wait(5_000)).toBe("signal");
+  });
+
+  test("roundStarted clears the pending flag, so one signal never wakes two rounds", async () => {
+    const gate = createChangeSignalGate({ floorMs: 0 });
+    gate.roundStarted();
+    gate.signal();
+    expect(await gate.wait(5_000)).toBe("signal");
+    gate.roundStarted();
+    expect(await gate.wait(40)).toBe("timer");
+    expect(gate.wakeCount).toBe(1);
+  });
+
+  test("abort resolves rather than throwing, before and during a wait", async () => {
+    const gate = createChangeSignalGate({ floorMs: 0 });
+    const already = new AbortController();
+    already.abort();
+    expect(await gate.wait(5_000, already.signal)).toBe("aborted");
+
+    const controller = new AbortController();
+    const waiting = gate.wait(5_000, controller.signal);
+    setTimeout(() => controller.abort(), 10);
+    expect(await waiting).toBe("aborted");
+  });
+
+  test("a signal after abort does nothing", async () => {
+    const gate = createChangeSignalGate({ floorMs: 0 });
+    const controller = new AbortController();
+    const waiting = gate.wait(5_000, controller.signal);
+    controller.abort();
+    expect(await waiting).toBe("aborted");
+    gate.signal();
+    expect(gate.wakeCount).toBe(0);
+  });
+
+  test("signal() carries no payload: the type has no argument and the call ignores one", () => {
+    const gate = createChangeSignalGate();
+    expect(gate.signal.length).toBe(0);
+    // A caller that fabricates an event has nowhere to put it: the extra
+    // argument is dropped, and the gate's only state is a boolean.
+    (gate.signal as (...args: unknown[]) => void)({ kind: "Deployment", name: "fabricated" });
+    expect(gate.signalCount).toBe(1);
+  });
+
+  test("the documented floor is a real, positive default", () => {
+    expect(DEFAULT_SIGNAL_FLOOR_MS).toBe(5_000);
+  });
+});