@intentius/chant 0.58.0 → 0.59.0

package/src/op/activities/reconcile.ts

@@ -1,10 +1,19 @@
 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.
+ */
+export type ReconcileMode = "pull-request" | "issue" | "report" | "comment";
 
 /** A change-set entry that triggered reconciliation. */
 export interface ReconcileEntry {
@@ -35,6 +44,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 +78,10 @@ export interface ReconcileResult {
   prUrl?: string;
   /** Opened issue URL (issue mode). */
   issueUrl?: string;
+  /** The posted or updated PR comment's URL (comment mode). */
+  commentUrl?: string;
+  /** The pull request the comment landed on, `owner/repo#number` (comment mode). */
+  pullRequest?: string;
   /** The markdown summary used as the PR/issue body. */
   summary: string;
   /** The entries that triggered the reconcile. */
@@ -101,6 +122,136 @@ 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. */
+export function noPullRequestContextMessage(): string {
+  return (
+    'reconcilePr mode "comment" posts the finding on the pull request that triggered the run, and this run ' +
+    "has none. 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`). " +
+    "GitHub Actions sets those on a pull_request event and on nothing else. Trigger this Op from a " +
+    'pull_request workflow, 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();
+}
+
 /**
  * Map a `chant lifecycle plan --json` ChangeSet to reconcile entries, dropping
  * `noop` entries (nothing to reconcile). Pure — exported for testing.
@@ -133,6 +284,12 @@ 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). Needs a pull-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.
  * - `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 +321,16 @@ 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 ctx = await resolvePullRequestContext();
+    const marker = args.marker ?? commentMarker(args.env);
+    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);
+  });
+});

package/src/op/change-signal.ts

@@ -0,0 +1,169 @@
+/**
+ * The wake gate between a substrate's change signal and `chant operator`'s
+ * sleep (#1981, epic #1487).
+ *
+ * A lexicon that implements `subscribeChanges` (`../lexicon.ts`) can say
+ * "something moved". This module is everything the loop does with that: it
+ * shortens the current sleep, at most once per floor. It is deliberately the
+ * only place a signal touches, so the rule that a signal is a trigger and
+ * never a fact is a property of the code rather than a convention. Nothing
+ * here has a parameter, a return value or a field that could carry what
+ * changed.
+ *
+ * ## Backpressure: the floor
+ *
+ * A watch on a busy namespace is not a trickle. A rollout, a Job sweep or a
+ * controller resyncing its whole world produces hundreds of events in a
+ * second, and each one is a truthful "something moved". Waking a tick per
+ * event would turn a convergence loop into a load generator pointed at the
+ * cluster it is meant to be watching.
+ *
+ * So the gate coalesces. Signals are collapsed into a single pending flag, and
+ * a pending flag wakes the sleep no earlier than {@link
+ * ChangeSignalGateOptions.floorMs} after the last round *started*. A storm of
+ * a thousand signals inside one floor window costs exactly one early wake, and
+ * a substrate that never stops sending settles into ticking on the floor
+ * rather than on the interval, which is the fastest the loop is ever allowed
+ * to run.
+ *
+ * The floor is measured from the start of the last round, not from the last
+ * signal, so a steady stream can never push the wake further out (that would
+ * be a debounce, and a debounce starves: the busier the cluster, the later the
+ * tick). Measuring from the round start makes the guarantee a rate limit,
+ * never more than one signal-driven tick per floor, which is the property the
+ * loop actually needs.
+ */
+
+/**
+ * The shortest gap between two rounds a change signal may produce. Signals
+ * arriving inside this window of the last round's start are coalesced into one
+ * wake at the end of it.
+ *
+ * Five seconds: long enough that a rollout's event storm costs one tick rather
+ * than dozens, short enough that "wakes within a second or so of a change"
+ * holds for the quiet case a signal exists for. The timer
+ * (`DEFAULT_OPERATOR_INTERVAL_MS`, 60s) is unchanged and remains the ceiling.
+ */
+export const DEFAULT_SIGNAL_FLOOR_MS = 5_000;
+
+/** Why {@link ChangeSignalGate.wait} returned. */
+export type WakeReason =
+  /** The full interval elapsed. An ordinary timer-driven round. */
+  | "timer"
+  /** A substrate signalled and the floor had passed. An early round. */
+  | "signal"
+  /** The operator is stopping. */
+  | "aborted";
+
+export interface ChangeSignalGateOptions {
+  /** @default DEFAULT_SIGNAL_FLOOR_MS */
+  floorMs?: number;
+  /** Injectable clock, for tests. @default Date.now */
+  now?: () => number;
+}
+
+/**
+ * One operator loop's wake gate. Not reusable across loops: it carries the
+ * time the current loop last started a round, which is what the floor is
+ * measured from.
+ */
+export interface ChangeSignalGate {
+  /**
+   * A substrate said something moved. Takes nothing and returns nothing, and
+   * that is the enforcement of "a trigger, never a fact": there is no
+   * argument for a watch event to ride in on.
+   *
+   * Safe to call at any time, including while no `wait` is in flight (the flag
+   * is remembered and honoured by the next one) and after the loop has
+   * stopped (it does nothing).
+   */
+  signal(): void;
+  /** The loop is starting a round now. Resets the pending flag and the floor. */
+  roundStarted(): void;
+  /**
+   * Sleep up to `intervalMs`, resolving early when a signal has passed the
+   * floor. Resolves rather than throws on abort, like the timer-only sleep it
+   * replaces, so Ctrl-C never surfaces as a loop failure.
+   */
+  wait(intervalMs: number, abortSignal?: AbortSignal): Promise<WakeReason>;
+  /** How many signals have arrived, coalesced or not. Diagnostics and tests. */
+  readonly signalCount: number;
+  /** How many of those actually shortened a sleep. Diagnostics and tests. */
+  readonly wakeCount: number;
+}
+
+export function createChangeSignalGate(options: ChangeSignalGateOptions = {}): ChangeSignalGate {
+  const floorMs = options.floorMs ?? DEFAULT_SIGNAL_FLOOR_MS;
+  const now = options.now ?? (() => Date.now());
+
+  let pending = false;
+  let lastRoundAt = now();
+  let signalCount = 0;
+  let wakeCount = 0;
+  /** Set only while a `wait` is in flight. */
+  let arm: (() => void) | undefined;
+
+  return {
+    get signalCount() {
+      return signalCount;
+    },
+    get wakeCount() {
+      return wakeCount;
+    },
+
+    signal() {
+      signalCount++;
+      pending = true;
+      arm?.();
+    },
+
+    roundStarted() {
+      lastRoundAt = now();
+      pending = false;
+    },
+
+    wait(intervalMs: number, abortSignal?: AbortSignal): Promise<WakeReason> {
+      return new Promise<WakeReason>((resolve) => {
+        if (abortSignal?.aborted) return resolve("aborted");
+
+        let settled = false;
+        let floorTimer: ReturnType<typeof setTimeout> | undefined;
+
+        const finish = (reason: WakeReason) => {
+          if (settled) return;
+          settled = true;
+          clearTimeout(intervalTimer);
+          if (floorTimer) clearTimeout(floorTimer);
+          abortSignal?.removeEventListener("abort", onAbort);
+          arm = undefined;
+          if (reason === "signal") wakeCount++;
+          resolve(reason);
+        };
+
+        const intervalTimer = setTimeout(() => finish("timer"), intervalMs);
+        const onAbort = () => finish("aborted");
+        abortSignal?.addEventListener("abort", onAbort, { once: true });
+
+        // A pending signal wakes the sleep the moment the floor has passed,
+        // and not one moment earlier. `remaining` is measured from the last
+        // round's start, so repeated signals inside the window collapse onto
+        // the same deadline instead of pushing it out.
+        const consider = () => {
+          if (settled || !pending) return;
+          const remaining = lastRoundAt + floorMs - now();
+          if (remaining <= 0) return finish("signal");
+          if (floorTimer) return; // already waiting out this window
+          floorTimer = setTimeout(() => {
+            floorTimer = undefined;
+            consider();
+          }, remaining);
+        };
+
+        arm = consider;
+        // A signal that arrived between rounds, while nothing was sleeping,
+        // is honoured here rather than lost.
+        consider();
+      });
+    },
+  };
+}

package/src/op/composites/apply-op.ts

@@ -30,7 +30,7 @@
  *   env: "prod",
  *   target: "kubectl",
  *   delete: "gated",
- *   gate: { signalName: "approve-apply", description: "Approve prod apply with deletes" },
+ *   gate: { gate: "approve-apply", description: "Approve prod apply with deletes" },
  * });
  * ```
  *
@@ -38,6 +38,7 @@
  */
 
 import { Op, phase, activity, gate } from "../builders";
+import { gateName } from "../gate-name";
 import type { OpResource } from "../resource";
 import { defaultOutput, hasNativeRollback, type ApplyTarget, type DeleteMode } from "../activities/apply";
 
@@ -69,11 +70,20 @@ export interface ApplyOpConfig {
   effects?: "gated";
   /**
    * Approval gate before the apply. Implied when `delete: "gated"`; may also be
-   * set explicitly. Omit `signalName` to default to `approve-<name>`. The gate
+   * set explicitly. Omit `gate` to default to `approve-<name>`. The gate
    * is resolved by `chant approve` on the ledger (#2119), which the next run
    * reads; nothing waits in the meantime.
+   *
+   * `signalName` is the key `gate` carried through 0.58.0 (#2202): still read,
+   * removed in 0.60.0.
    */
-  gate?: { signalName?: string; timeout?: string; description?: string };
+  gate?: {
+    gate?: string;
+    /** @deprecated Renamed to `gate` in #2202. Accepted through 0.59.0, removed in 0.60.0. */
+    signalName?: string;
+    timeout?: string;
+    description?: string;
+  };
   /**
    * Saga-style rollback on partial apply failure, run as an `onFailure` phase.
    *
@@ -129,7 +139,7 @@ export function ApplyOp(config: ApplyOpConfig): ApplyOpResources {
   if (gated) {
     phases.push(
       phase("Approve", [
-        gate(config.gate?.signalName ?? `approve-${config.name}`, {
+        gate(gateName(config.gate ?? {}) || `approve-${config.name}`, {
           ...(config.gate?.timeout ? { timeout: config.gate.timeout } : {}),
           description:
             config.gate?.description ??

package/src/op/composites/composites.test.ts

@@ -165,21 +165,34 @@ describe("ApplyOp: gating + deletes", () => {
     expect(phases.map((p) => p.name)).toEqual(["Build", "Plan", "Approve", "Apply"]);
     const gateStep = (phases[2].steps as Array<Record<string, unknown>>)[0];
     expect(gateStep.kind).toBe("gate");
-    expect(gateStep.signalName).toBe("approve-p");
+    expect(gateStep.gate).toBe("approve-p");
   });
 
   test("explicit gate config is honored", () => {
     const { op } = ApplyOp({
       name: "p",
       env: "prod",
-      gate: { signalName: "go", description: "ship it" },
+      gate: { gate: "go", description: "ship it" },
     });
     const phases = getProps(op).phases as Array<Record<string, unknown>>;
     const gateStep = (phases[2].steps as Array<Record<string, unknown>>)[0];
-    expect(gateStep.signalName).toBe("go");
+    expect(gateStep.gate).toBe("go");
     expect(gateStep.description).toBe("ship it");
   });
 
+  // #2202: the gate config's key is `gate`; `signalName` is read through 0.59.0.
+  test("the deprecated `signalName` key on the gate config still names the gate", () => {
+    const { op } = ApplyOp({
+      name: "p",
+      env: "prod",
+      gate: { signalName: "go", description: "ship it" },
+    });
+    const phases = getProps(op).phases as Array<Record<string, unknown>>;
+    const gateStep = (phases[2].steps as Array<Record<string, unknown>>)[0];
+    expect(gateStep.gate).toBe("go");
+    expect(gateStep.signalName).toBeUndefined();
+  });
+
   test("deleteMode flows into the nativeApply step", () => {
     const { op } = ApplyOp({ name: "p", env: "prod", delete: "owned-only" });
     const phases = getProps(op).phases as Array<Record<string, unknown>>;
@@ -301,7 +314,7 @@ describe("ApplyOp: effects gated (#1834, #1703 decision 6)", () => {
     expect(phases.map((p) => p.name)).toEqual(["Build", "Plan", "Approve", "Apply"]);
     const gateStep = (phases[2].steps as Array<Record<string, unknown>>)[0];
     expect(gateStep.kind).toBe("gate");
-    expect(gateStep.signalName).toBe("approve-p");
+    expect(gateStep.gate).toBe("approve-p");
     expect(gateStep.description).toBe("Approve apply to prod (delete mode: never, effects: gated)");
   });
 

package/src/op/composites/reconcile-op.ts

@@ -60,15 +60,18 @@ export function ReconcileOp(config: ReconcileOpConfig): ReconcileOpResources {
   const onDrift = config.onDrift ?? "pull-request";
   const owned = config.scope?.owned ?? false;
 
-  // The reconcile's headline output is the opened PR (or issue) URL. Expose it as
-  // an outcome attribute so it prints in `chant run` and lands on the ledger.
-  // `report` mode opens nothing, so it has no URL outcome.
+  // The reconcile's headline output is the opened PR (or issue, or the comment
+  // it posted on the triggering pull request) URL. Expose it as an outcome
+  // attribute so it prints in `chant run` and lands on the ledger. `report`
+  // mode opens nothing, so it has no URL outcome.
   const reconcileOutcome =
     onDrift === "pull-request"
       ? { name: "PR", from: "prUrl" }
       : onDrift === "issue"
         ? { name: "Issue", from: "issueUrl" }
-        : undefined;
+        : onDrift === "comment"
+          ? { name: "Comment", from: "commentUrl" }
+          : undefined;
 
   const op = Op({
     name: config.name,

package/src/op/effect-step.test.ts

@@ -58,7 +58,7 @@ describe("effect() builder", () => {
       inputs: { file: "seed.sql", version: 3 },
     });
     expect(s.expectation).toBe(receiptExpectation(seeded));
-    expect(s.steps.map((n) => (n.kind === "activity" ? n.fn : n.signalName))).toEqual(["shellCmd"]);
+    expect(s.steps.map((n) => (n.kind === "activity" ? n.fn : n.gate))).toEqual(["shellCmd"]);
   });
 
   test("existence receipts always get the constant expectation, reference inputs or not", () => {
@@ -83,7 +83,7 @@ describe("effect() builder", () => {
 
   test("preserves authored order and nested gates", () => {
     const s = effect(seeded, [
-      { kind: "gate", signalName: "approve-seed" },
+      { kind: "gate", gate: "approve-seed" },
       step("shellCmd", { cmd: "seed" }),
     ]);
     expect(s.steps.map((n) => n.kind)).toEqual(["gate", "activity"]);
@@ -288,7 +288,7 @@ describe("runOpLocally — effect steps", () => {
       name: "gated",
       overview: "",
       phases: [
-        phase("Seed", [effect(seeded, [{ kind: "gate", signalName: "approve-seed" }, step("runSeed")])]),
+        phase("Seed", [effect(seeded, [{ kind: "gate", gate: "approve-seed" }, step("runSeed")])]),
       ],
     };
     const { store } = memStore();