@intentius/chant 0.58.0 → 0.60.0

package/src/op/local-executor.ts

@@ -26,6 +26,7 @@ import type { ReceiptReadResult } from "./receipt-store";
 import { isStepOutputRef } from "./step-output-ref";
 import { parseDuration } from "./duration";
 import { evaluateGate, gitGateLedgerPort, type GateLedgerPort } from "./gate";
+import { gateName } from "./gate-name";
 import type { PendingGateRecord } from "../lifecycle/gate-ledger";
 import { appendRunRecord, buildRunRecord } from "../lifecycle/run-ledger";
 import type { OpRunRecord } from "./runtime";
@@ -342,7 +343,7 @@ function pushRecord(sink: StepRecord[], ctx: GateContext, ...recs: StepRecord[])
 
 /** The record name a gate step lands under, so a reader (and a JSON consumer) can pick it out of `records`. */
 function gateFn(step: GateStep): string {
-  return `gate:${step.signalName}`;
+  return `gate:${gateName(step)}`;
 }
 
 /**
@@ -359,7 +360,7 @@ async function runGateStep(
   const start = Date.now();
   const check = await evaluateGate(gates.port, {
     op: gates.op,
-    gate: step.signalName,
+    gate: gateName(step),
     ...(step.description ? { description: step.description } : {}),
     ...(step.timeout ? { timeout: step.timeout } : {}),
     ...(gates.runId ? { runId: gates.runId } : {}),
@@ -376,7 +377,7 @@ async function runGateStep(
         status: "ok",
         durationMs: Date.now() - start,
         approval: {
-          gate: step.signalName,
+          gate: gateName(step),
           resolvedBy: resolution.resolvedBy,
           timestamp: resolution.timestamp,
           ...(resolution.url ? { url: resolution.url } : {}),

package/src/op/op-ir.test.ts

@@ -126,7 +126,7 @@ describe("op.json IR", () => {
     expect(build.steps[0]).toMatchObject({ kind: "activity", fn: "shellCmd", profile: "fastIdempotent" });
     expect(approve.steps[0]).toMatchObject({
       kind: "gate",
-      signalName: "approve-deploy",
+      gate: "approve-deploy",
       timeout: "24h",
       description: "Release manager sign-off",
     });
@@ -141,6 +141,17 @@ describe("op.json IR", () => {
     expect(ir.onFailure[0].name).toBe("Rollback");
   });
 
+  // #2202: whichever key an authored gate step used, the IR writes `gate`, so
+  // a foreign consumer of op.json never sees the deprecated spelling.
+  it("normalizes a gate step's deprecated `signalName` key onto `gate`", () => {
+    const config = representativeOp();
+    const approve = config.phases.find((p) => p.name === "Approve")!;
+    approve.steps[0] = { kind: "gate", signalName: "approve-deploy", timeout: "24h" };
+    const ir = buildOpIR(config);
+    expect(ir.phases[1].steps[0]).toMatchObject({ kind: "gate", gate: "approve-deploy", timeout: "24h" });
+    expect(serializeOpIR(config)).not.toContain("signalName");
+  });
+
   it("contracts are the injected registry's: empty until a caller supplies one", () => {
     const bare = buildOpIR(representativeOp());
     expect(bare.activityContracts).toEqual({});

package/src/op/op-ir.ts

@@ -95,6 +95,7 @@ import type {
 import type { EffectReceiptRef } from "./receipt-store";
 import type { ActivityContract } from "./activity-contract";
 import { ACTIVITY_PROFILES, type ActivityProfile } from "./activity-profiles";
+import { gateName } from "./gate-name";
 
 /**
  * The op.json IR schema version. Bumped on a breaking change to this
@@ -131,7 +132,8 @@ export interface OpIRActivityStep {
 
 export interface OpIRGateStep {
   kind: "gate";
-  signalName: string;
+  /** The gate's name — `GateStep.gate`, or its deprecated `signalName` spelling (#2202). */
+  gate: string;
   /** Resolved to its effective value — `GateStep.timeout ?? "48h"`. */
   timeout: string;
   description?: string;
@@ -227,7 +229,7 @@ function irActivityStep(step: ActivityStep, contracts: ReadonlyMap<string, Activ
 function irGateStep(step: GateStep): OpIRGateStep {
   return {
     kind: "gate",
-    signalName: step.signalName,
+    gate: gateName(step),
     timeout: step.timeout ?? "48h",
     ...(step.description ? { description: step.description } : {}),
   };
@@ -375,7 +377,7 @@ function opStepFromIR(step: OpIRStep): StepDefinition {
   if (step.kind === "gate") {
     return {
       kind: "gate",
-      signalName: step.signalName,
+      gate: step.gate,
       timeout: step.timeout,
       ...(step.description ? { description: step.description } : {}),
     };

package/src/op/op-verb-class.test.ts

@@ -106,7 +106,7 @@ describe("isGated", () => {
     expect(
       isGated(
         cfg([
-          { name: "Approve", steps: [{ kind: "gate", signalName: "approve-x" }] },
+          { name: "Approve", steps: [{ kind: "gate", gate: "approve-x" }] },
           { name: "Apply", steps: [{ kind: "activity", fn: "nativeApply", args: {} }] },
         ]),
       ),
@@ -118,7 +118,7 @@ describe("isGated", () => {
       isGated(
         cfg(
           [{ name: "Apply", steps: [{ kind: "activity", fn: "nativeApply", args: {} }] }],
-          [{ name: "Rollback", steps: [{ kind: "gate", signalName: "approve-rollback" }] }],
+          [{ name: "Rollback", steps: [{ kind: "gate", gate: "approve-rollback" }] }],
         ),
       ),
     ).toBe(true);

package/src/op/op.test.ts

@@ -131,10 +131,10 @@ describe("activity()", () => {
 // ── gate() ────────────────────────────────────────────────────────────────────
 
 describe("gate()", () => {
-  it("returns GateStep with kind 'gate' and signalName", () => {
+  it("returns GateStep with kind 'gate' and the gate name", () => {
     const g = gate("dns-delegation");
     expect(g.kind).toBe("gate");
-    expect(g.signalName).toBe("dns-delegation");
+    expect(g.gate).toBe("dns-delegation");
   });
 
   it("includes timeout when provided", () => {

package/src/op/operator.test.ts

@@ -9,7 +9,11 @@ import {
   runOperatorRound,
   runOperatorForever,
   formatRoundLine,
+  formatSignalLine,
   DEFAULT_OPERATOR_INTERVAL_MS,
+  type ChangeSubscriber,
+  type OperatorSignalEvent,
+  type OperatorTickEvent,
 } from "./operator";
 import { readLease } from "../lifecycle/lease";
 import { appendConvergeRecord, readConvergeLedger } from "../lifecycle/converge-ledger";
@@ -513,3 +517,367 @@ describe("formatRoundLine", () => {
       .toContain("not-due:*/10 * * * *");
   });
 });
+
+describe("runOperatorForever: a substrate change signal wakes a tick (#1981)", () => {
+  async function waitFor(predicate: () => boolean, maxWaitMs = 5_000): Promise<void> {
+    const deadline = Date.now() + maxWaitMs;
+    while (!predicate() && Date.now() < deadline) {
+      await new Promise((r) => setTimeout(r, 5));
+    }
+  }
+
+  /**
+   * A stub `subscribeChanges` seam. Hands the loop's `onChange`/`onError` back
+   * to the test so it can fabricate signals and kill the subscription, with no
+   * substrate anywhere near it, which is the whole point of the seam being a
+   * plain callback pair.
+   */
+  function stubSubscriber(lexicon = "stub") {
+    const handle = {
+      lexicon,
+      subscribes: 0,
+      closes: 0,
+      onChange: undefined as undefined | (() => void),
+      onError: undefined as undefined | ((message: string) => void),
+      signal: undefined as undefined | AbortSignal,
+      failNextSubscribe: undefined as undefined | string,
+    };
+    const subscriber: ChangeSubscriber = {
+      lexicon,
+      async subscribe(ctx) {
+        handle.subscribes++;
+        if (handle.failNextSubscribe) {
+          const message = handle.failNextSubscribe;
+          handle.failNextSubscribe = undefined;
+          throw new Error(message);
+        }
+        handle.onChange = ctx.onChange;
+        handle.onError = ctx.onError;
+        handle.signal = ctx.signal;
+        return {
+          async close() {
+            handle.closes++;
+          },
+        };
+      },
+    };
+    return { handle, subscriber };
+  }
+
+  test("a signal wakes the next round early, well inside the interval", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      writeFixtureConvergeOp(dir, "staging-converge", "staging");
+      const activities = fakeTickActivities(dir, "staging", "staging-converge");
+      const { handle, subscriber } = stubSubscriber("k8s");
+
+      const controller = new AbortController();
+      const rounds: number[] = [];
+      const signalEvents: OperatorSignalEvent[] = [];
+      const loop = runOperatorForever({
+        cwd: dir,
+        holder: "op-a",
+        intervalMs: 60_000, // a full minute: nothing but a signal can produce a second round
+        signalFloorMs: 0,
+        activities,
+        profiles: PROFILES,
+        signal: controller.signal,
+        subscribers: [subscriber],
+        onRound: () => rounds.push(Date.now()),
+        onSignalEvent: (e) => signalEvents.push(e),
+      });
+
+      await waitFor(() => handle.onChange !== undefined);
+      expect(rounds.length).toBe(1);
+      handle.onChange!();
+      await waitFor(() => rounds.length >= 2);
+      expect(rounds.length).toBeGreaterThanOrEqual(2);
+
+      controller.abort();
+      await loop;
+      expect(signalEvents.some((e) => e.kind === "subscribed" && e.lexicon === "k8s")).toBe(true);
+      expect(signalEvents.some((e) => e.kind === "woken")).toBe(true);
+    });
+  }, 15_000);
+
+  test("a fabricated signal cannot change what the tick reports, only when it runs", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      writeFixtureConvergeOp(dir, "staging-converge", "staging");
+
+      /** One round's events, run to completion on a timer alone. */
+      async function roundsWithoutSignal(): Promise<string> {
+        const controller = new AbortController();
+        const seen: OperatorTickEvent[][] = [];
+        const loop = runOperatorForever({
+          cwd: dir,
+          holder: "op-a",
+          intervalMs: 60_000,
+          activities: fakeTickActivities(dir, "staging", "staging-converge"),
+          profiles: PROFILES,
+          signal: controller.signal,
+          onRound: (events) => {
+            seen.push(events);
+            controller.abort();
+          },
+        });
+        await loop;
+        return JSON.stringify(seen[0].map((e) => ({ kind: e.kind, op: e.op, env: e.env })));
+      }
+
+      /** The same, woken by a signal carrying a fabricated payload. */
+      async function roundsWithFabricatedSignal(): Promise<string> {
+        const { handle, subscriber } = stubSubscriber("liar");
+        const controller = new AbortController();
+        const seen: OperatorTickEvent[][] = [];
+        const loop = runOperatorForever({
+          cwd: dir,
+          holder: "op-a",
+          intervalMs: 60_000,
+          signalFloorMs: 0,
+          activities: fakeTickActivities(dir, "staging", "staging-converge"),
+          profiles: PROFILES,
+          signal: controller.signal,
+          subscribers: [subscriber],
+          onRound: (events) => {
+            seen.push(events);
+            if (seen.length >= 2) controller.abort();
+          },
+        });
+        await waitFor(() => handle.onChange !== undefined);
+        // `onChange` takes no arguments; a caller that fabricates a resource
+        // has nowhere to put it, and the extra arguments go nowhere.
+        (handle.onChange as unknown as (...args: unknown[]) => void)(
+          { kind: "Deployment", name: "ghost", status: "Drifted" },
+          "fabricated",
+        );
+        await waitFor(() => seen.length >= 2);
+        controller.abort();
+        await loop;
+        return JSON.stringify(seen[1].map((e) => ({ kind: e.kind, op: e.op, env: e.env })));
+      }
+
+      const timerOnly = await roundsWithoutSignal();
+      const signalled = await roundsWithFabricatedSignal();
+      // Byte for byte the same verdict: the signal moved the clock, nothing else.
+      expect(signalled).toBe(timerOnly);
+      // And the seam itself carries no payload channel to begin with.
+      const { handle } = stubSubscriber();
+      expect(handle.onChange?.length ?? 0).toBe(0);
+    });
+  }, 20_000);
+
+  test("a storm of signals wakes at most one round per floor", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      writeFixtureConvergeOp(dir, "staging-converge", "staging");
+      const { handle, subscriber } = stubSubscriber();
+
+      const controller = new AbortController();
+      const rounds: number[] = [];
+      const loop = runOperatorForever({
+        cwd: dir,
+        holder: "op-a",
+        intervalMs: 60_000,
+        signalFloorMs: 400,
+        activities: fakeTickActivities(dir, "staging", "staging-converge"),
+        profiles: PROFILES,
+        signal: controller.signal,
+        subscribers: [subscriber],
+        onRound: () => rounds.push(Date.now()),
+      });
+
+      await waitFor(() => handle.onChange !== undefined);
+      const before = rounds.length;
+      for (let i = 0; i < 300; i++) handle.onChange!();
+      // Well past a floor, but nowhere near the 60s interval: at most one
+      // extra round may have happened, and a per-signal wake would have
+      // produced hundreds.
+      await waitFor(() => rounds.length > before, 2_000);
+      expect(rounds.length - before).toBeLessThanOrEqual(1);
+
+      controller.abort();
+      await loop;
+    });
+  }, 15_000);
+
+  test("a killed subscription is reported once, the loop keeps ticking, and the next round re-subscribes", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      writeFixtureConvergeOp(dir, "staging-converge", "staging");
+      const { handle, subscriber } = stubSubscriber("k8s");
+
+      const controller = new AbortController();
+      const rounds: number[] = [];
+      const signalEvents: OperatorSignalEvent[] = [];
+      const loop = runOperatorForever({
+        cwd: dir,
+        holder: "op-a",
+        intervalMs: 60,
+        signalFloorMs: 0,
+        activities: fakeTickActivities(dir, "staging", "staging-converge"),
+        profiles: PROFILES,
+        signal: controller.signal,
+        subscribers: [subscriber],
+        onRound: () => rounds.push(Date.now()),
+        onSignalEvent: (e) => signalEvents.push(e),
+      });
+
+      await waitFor(() => handle.onError !== undefined);
+      const subscribesBefore = handle.subscribes;
+      // The watch dies. Twice, because a dead subscription reports once.
+      handle.onError!("connection reset by peer");
+      handle.onError!("connection reset by peer");
+
+      await waitFor(() => handle.subscribes > subscribesBefore);
+      const roundsAtDeath = rounds.length;
+      await waitFor(() => rounds.length > roundsAtDeath + 1);
+
+      controller.abort();
+      await loop;
+
+      const lost = signalEvents.filter((e) => e.kind === "subscription-lost");
+      expect(lost).toHaveLength(1);
+      expect(formatSignalLine(lost[0])).toContain("polling on the timer");
+      // The loop kept ticking on the timer, and re-subscribed.
+      expect(rounds.length).toBeGreaterThan(roundsAtDeath + 1);
+      expect(handle.subscribes).toBeGreaterThan(subscribesBefore);
+    });
+  }, 15_000);
+
+  test("a subscription that cannot be established degrades to polling with one line, never a crash", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      writeFixtureConvergeOp(dir, "staging-converge", "staging");
+      const failing: ChangeSubscriber = {
+        lexicon: "k8s",
+        async subscribe() {
+          throw new Error("no cluster binding for env staging");
+        },
+      };
+
+      const controller = new AbortController();
+      const rounds: number[] = [];
+      const signalEvents: OperatorSignalEvent[] = [];
+      const loop = runOperatorForever({
+        cwd: dir,
+        holder: "op-a",
+        intervalMs: 40,
+        activities: fakeTickActivities(dir, "staging", "staging-converge"),
+        profiles: PROFILES,
+        signal: controller.signal,
+        subscribers: [failing],
+        onRound: () => rounds.push(Date.now()),
+        onSignalEvent: (e) => signalEvents.push(e),
+      });
+
+      await waitFor(() => rounds.length >= 3);
+      controller.abort();
+      await loop; // resolves: a failing subscription never rejects the loop
+
+      const failed = signalEvents.filter((e) => e.kind === "subscribe-failed");
+      expect(failed.length).toBeGreaterThanOrEqual(1);
+      expect(formatSignalLine(failed[0])).toContain("no cluster binding for env staging");
+      expect(rounds.length).toBeGreaterThanOrEqual(3);
+    });
+  }, 15_000);
+
+  test("stopping the operator closes every subscription and aborts its signal", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      writeFixtureConvergeOp(dir, "staging-converge", "staging");
+      const a = stubSubscriber("k8s");
+      const b = stubSubscriber("docker");
+
+      const controller = new AbortController();
+      const loop = runOperatorForever({
+        cwd: dir,
+        holder: "op-a",
+        intervalMs: 60_000,
+        activities: fakeTickActivities(dir, "staging", "staging-converge"),
+        profiles: PROFILES,
+        signal: controller.signal,
+        subscribers: [a.subscriber, b.subscriber],
+      });
+
+      await waitFor(() => a.handle.onChange !== undefined && b.handle.onChange !== undefined);
+      expect(a.handle.signal!.aborted).toBe(false);
+
+      controller.abort();
+      await loop;
+
+      expect(a.handle.closes).toBe(1);
+      expect(b.handle.closes).toBe(1);
+      expect(a.handle.signal!.aborted).toBe(true);
+      expect(b.handle.signal!.aborted).toBe(true);
+    });
+  }, 15_000);
+
+  test("a close() that throws still unwinds the loop cleanly", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      writeFixtureConvergeOp(dir, "staging-converge", "staging");
+      let subscribed = false;
+      const hostile: ChangeSubscriber = {
+        lexicon: "k8s",
+        async subscribe() {
+          subscribed = true;
+          return { close: async () => { throw new Error("close blew up"); } };
+        },
+      };
+
+      const controller = new AbortController();
+      const loop = runOperatorForever({
+        cwd: dir,
+        holder: "op-a",
+        intervalMs: 60_000,
+        activities: fakeTickActivities(dir, "staging", "staging-converge"),
+        profiles: PROFILES,
+        signal: controller.signal,
+        subscribers: [hostile],
+      });
+
+      await waitFor(() => subscribed);
+      controller.abort();
+      await expect(loop).resolves.toBeUndefined();
+    });
+  }, 15_000);
+
+  test("no subscribers: the loop is exactly the timer it always was", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      writeFixtureConvergeOp(dir, "staging-converge", "staging");
+      const controller = new AbortController();
+      const rounds: number[] = [];
+      const signalEvents: OperatorSignalEvent[] = [];
+      const loop = runOperatorForever({
+        cwd: dir,
+        holder: "op-a",
+        intervalMs: 40,
+        activities: fakeTickActivities(dir, "staging", "staging-converge"),
+        profiles: PROFILES,
+        signal: controller.signal,
+        subscribers: [], // a project whose lexicons implement no signal seam
+        onRound: () => rounds.push(Date.now()),
+        onSignalEvent: (e) => signalEvents.push(e),
+      });
+
+      await waitFor(() => rounds.length >= 3);
+      controller.abort();
+      await loop;
+      expect(rounds.length).toBeGreaterThanOrEqual(3);
+      expect(signalEvents).toEqual([]);
+    });
+  }, 15_000);
+});
+
+describe("formatSignalLine", () => {
+  test("renders each signal event kind as one line, none of them an observation", () => {
+    expect(formatSignalLine({ kind: "subscribed", lexicon: "k8s" })).toContain("the timer still runs");
+    expect(formatSignalLine({ kind: "subscribe-failed", lexicon: "k8s", error: "no binding" }))
+      .toContain("polling on the timer");
+    expect(formatSignalLine({ kind: "subscription-lost", lexicon: "k8s", error: "410 Gone" }))
+      .toContain("re-subscribes");
+    expect(formatSignalLine({ kind: "woken", afterMs: 120 })).toContain("running an ordinary round");
+  });
+});

package/src/op/operator.ts

@@ -41,6 +41,8 @@ import { runOpLocally, OpRunFailure, type OpRunResult } from "./local-executor";
 import { acquireLease, stillHoldsLease, currentHolderId, DEFAULT_LEASE_TTL_MS, type LeaseRecord, type AcquireLeaseResult } from "../lifecycle/lease";
 import { StaleLockError } from "../lifecycle/git";
 import { cronMatches, cronDueBetween } from "./cron";
+import { createChangeSignalGate, DEFAULT_SIGNAL_FLOOR_MS, type WakeReason } from "./change-signal";
+import type { ChangeSubscription } from "../lexicon";
 
 /**
  * Poll interval between rounds — the operator's own cadence, and the fallback
@@ -211,11 +213,67 @@ function sleepAbortable(ms: number, signal?: AbortSignal): Promise<void> {
   });
 }
 
+/**
+ * One lexicon's change-signal seam, already bound to an environment (#1981).
+ *
+ * The loop never sees a `LexiconPlugin`: core's operator does not import
+ * plugins, and binding happens where plugins are already loaded
+ * (`collectChangeSubscribers` in `../cli/plugins.ts`), the same extract-then-
+ * thread shape `collectBuildRootContributors` uses for build roots.
+ */
+export interface ChangeSubscriber {
+  /** Which lexicon supplies the signal. Log lines only; never a fact. */
+  lexicon: string;
+  subscribe(ctx: {
+    onChange: () => void;
+    onError: (message: string) => void;
+    signal: AbortSignal;
+  }): Promise<ChangeSubscription>;
+}
+
+/**
+ * What the loop's change-signal machinery reports, alongside the per-op tick
+ * events. Separate from {@link OperatorTickEvent} on purpose: none of this is
+ * about an Op, and none of it is an observation.
+ */
+export type OperatorSignalEvent =
+  /** A lexicon's subscription is live and the loop may now wake early. */
+  | { kind: "subscribed"; lexicon: string }
+  /** Establishing it failed. The loop keeps its timer and retries next round. */
+  | { kind: "subscribe-failed"; lexicon: string; error: string }
+  /** A live subscription died. Reported once; the next round re-subscribes. */
+  | { kind: "subscription-lost"; lexicon: string; error: string }
+  /** A signal shortened the sleep. The round that follows is an ordinary round. */
+  | { kind: "woken"; afterMs: number };
+
+/** Render one signal event as `chant operator`'s log line shape. */
+export function formatSignalLine(event: OperatorSignalEvent): string {
+  switch (event.kind) {
+    case "subscribed":
+      return `operator: ${event.lexicon} change signal subscribed (the timer still runs)`;
+    case "subscribe-failed":
+      return `operator: ${event.lexicon} change signal unavailable, polling on the timer (${event.error})`;
+    case "subscription-lost":
+      return `operator: ${event.lexicon} change signal lost, polling on the timer until the next round re-subscribes (${event.error})`;
+    case "woken":
+      return `operator: woken by a change signal after ${event.afterMs}ms, running an ordinary round`;
+  }
+}
+
 export interface OperatorLoopOptions extends OperatorRoundOptions {
   /** @default DEFAULT_OPERATOR_INTERVAL_MS */
   intervalMs?: number;
   /** Called after every round completes — the CLI's one-line-per-tick log lives here, not inside the loop itself, so a test can drive rounds without capturing stdout. */
   onRound?: (events: OperatorTickEvent[]) => void;
+  /**
+   * Change-signal seams to keep subscribed for the life of the loop (#1981).
+   * Omitted, or empty, and the loop is exactly what it was: a timer.
+   */
+  subscribers?: readonly ChangeSubscriber[];
+  /** @default DEFAULT_SIGNAL_FLOOR_MS. The shortest gap a signal may force between two rounds. */
+  signalFloorMs?: number;
+  /** Called for every subscription and wake event. The CLI logs one line each. */
+  onSignalEvent?: (event: OperatorSignalEvent) => void;
 }
 
 /**
@@ -224,6 +282,12 @@ export interface OperatorLoopOptions extends OperatorRoundOptions {
  * (issue: "if it dies, nothing breaks and nothing is lost") — this function
  * is exactly `while (!aborted) { round(); sleep(); }`, nothing durable lives
  * in its own memory that a restart would need to recover.
+ *
+ * With `subscribers` (#1981) the sleep gains a second wake source, and only a
+ * wake source. A signal aborts the current sleep; the round that follows is
+ * the same round the timer would have run, deriving everything from a fresh
+ * observation. Nothing a subscription reports reaches a tick, because the
+ * seam has nowhere to put it: `onChange` takes no arguments.
  */
 export async function runOperatorForever(opts: OperatorLoopOptions): Promise<void> {
   const holder = opts.holder ?? currentHolderId();
@@ -232,11 +296,83 @@ export async function runOperatorForever(opts: OperatorLoopOptions): Promise<voi
   // lands on a firing minute — a fresh operator owes no catch-up for the ticks
   // it was not running for.
   const scheduleState = opts.scheduleState ?? new Map<string, Date>();
-  while (!opts.signal?.aborted) {
-    const events = await runOperatorRound({ ...opts, holder, scheduleState });
-    opts.onRound?.(events);
-    if (opts.signal?.aborted) break;
-    await sleepAbortable(opts.intervalMs ?? DEFAULT_OPERATOR_INTERVAL_MS, opts.signal);
+  const intervalMs = opts.intervalMs ?? DEFAULT_OPERATOR_INTERVAL_MS;
+  const subscribers = opts.subscribers ?? [];
+
+  // Nothing to subscribe to: the loop below is byte for byte the loop that
+  // shipped before #1981, and takes none of the machinery's cost.
+  if (subscribers.length === 0) {
+    while (!opts.signal?.aborted) {
+      const events = await runOperatorRound({ ...opts, holder, scheduleState });
+      opts.onRound?.(events);
+      if (opts.signal?.aborted) break;
+      await sleepAbortable(intervalMs, opts.signal);
+    }
+    return;
+  }
+
+  const gate = createChangeSignalGate({ floorMs: opts.signalFloorMs ?? DEFAULT_SIGNAL_FLOOR_MS });
+  // The subscriptions the loop currently holds, by lexicon. A lexicon absent
+  // from this map is one to (re-)subscribe on the next round, which is how a
+  // killed watch comes back without a special retry path.
+  const live = new Map<string, ChangeSubscription>();
+  // Stops every subscription at once when the loop ends, whatever ends it.
+  const subscriptionsAbort = new AbortController();
+
+  const closeAll = async (): Promise<void> => {
+    subscriptionsAbort.abort();
+    const open = [...live.values()];
+    live.clear();
+    // A close that throws must not mask why the loop is unwinding.
+    await Promise.allSettled(open.map((s) => s.close()));
+  };
+
+  const ensureSubscribed = async (): Promise<void> => {
+    for (const subscriber of subscribers) {
+      if (live.has(subscriber.lexicon) || subscriptionsAbort.signal.aborted) continue;
+      try {
+        const subscription = await subscriber.subscribe({
+          onChange: () => gate.signal(),
+          onError: (error) => {
+            // Reported once, then forgotten: dropping it from `live` is what
+            // makes the next round re-subscribe. The loop itself is untouched.
+            if (!live.delete(subscriber.lexicon)) return;
+            opts.onSignalEvent?.({ kind: "subscription-lost", lexicon: subscriber.lexicon, error });
+          },
+          signal: subscriptionsAbort.signal,
+        });
+        live.set(subscriber.lexicon, subscription);
+        opts.onSignalEvent?.({ kind: "subscribed", lexicon: subscriber.lexicon });
+      } catch (err) {
+        // A subscription that cannot be established is a slower loop, never a
+        // stopped one: report it and fall through to the timer.
+        opts.onSignalEvent?.({
+          kind: "subscribe-failed",
+          lexicon: subscriber.lexicon,
+          error: err instanceof Error ? err.message : String(err),
+        });
+      }
+    }
+  };
+
+  try {
+    while (!opts.signal?.aborted) {
+      gate.roundStarted();
+      const startedAt = Date.now();
+      const events = await runOperatorRound({ ...opts, holder, scheduleState });
+      opts.onRound?.(events);
+      if (opts.signal?.aborted) break;
+
+      await ensureSubscribed();
+      if (opts.signal?.aborted) break;
+
+      const reason: WakeReason = await gate.wait(intervalMs, opts.signal);
+      if (reason === "signal") {
+        opts.onSignalEvent?.({ kind: "woken", afterMs: Date.now() - startedAt });
+      }
+    }
+  } finally {
+    await closeAll();
   }
 }