@nanobpm/nano-workforce 0.82.0 → 0.82.1

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+## [0.82.1](https://github.com/nanobpm/nano-workforce/compare/v0.82.0...v0.82.1) (2026-08-17)
+
+
+### Bug Fixes
+
+* **plan-fanout:** make the wave-merge barrier level-triggered ([#262](https://github.com/nanobpm/nano-workforce/issues/262)) ([#264](https://github.com/nanobpm/nano-workforce/issues/264)) ([ae939d8](https://github.com/nanobpm/nano-workforce/commit/ae939d8e96f136f820fcae9149c120806ddc6f1b))
+
 # [0.82.0](https://github.com/nanobpm/nano-workforce/compare/v0.81.0...v0.82.0) (2026-08-17)
 
 

package/SPEC.md

@@ -565,11 +565,14 @@ the loop runs one parallel `implement` MI fan-out per wave:
   `dependsOn`), and advances `currentWave`.
 - **Wave-merge barrier** (`wait-wave-merged`): when a wave has a successor,
   `record-wave` sets `plans.gate_wave` to that wave's index and the process parks at
-  the `wait-wave-merged` catch event. The poller's `pollWaveGates` pass publishes the
-  `wave-merged` message (correlated on `planKey`) once **every opened PR in that wave
-  has merged** (`app/waves.ts` `waveMergeTargets` selects the PRs to wait on;
-  `blocked`/`skipped`/keyless tasks clear vacuously), then clears `gate_wave`
-  single-shot. So a `dependsOn` means the dependent wave is not **implemented** until
+  the `wait-wave-merged` catch event. The poller's `pollWaveGatesImpl` pass is
+  **level-triggered**: it publishes the `wave-merged` message (correlated on `planKey`)
+  once **every opened PR in that wave has merged** (`app/waves.ts` `waveMergeTargets`
+  selects the PRs to wait on; `blocked`/`skipped`/keyless tasks clear vacuously) **and**
+  it observes an OPEN `wait-wave-merged` subscription for the plan — so a merge that
+  lands while the token is still upstream can't drop the signal. The poller **never**
+  clears `gate_wave`; `record-wave` owns the marker's lifecycle (re-arming it to the next
+  wave, or clearing it to NULL on the final wave). So a `dependsOn` means the dependent wave is not **implemented** until
   its prerequisites have **landed on the base branch** — not merely opened. This lets
   a blocking prerequisite (e.g. app scaffolding) fully converge and merge before the
   next wave builds on it. `gate_wave` lives in `db/migrations/007_wave_gate.sql`.

package/app/service.test.ts

@@ -7,7 +7,7 @@
 // GitHub transport forced off so it is hermetic.
 import { test } from "node:test";
 import { assertEquals } from "#test-assert";
-import { parsePr, pollIncidentsImpl, repoEnvelopeVars, startMerge, submitPr } from "./service.ts";
+import { parsePr, pollIncidentsImpl, pollWaveGatesImpl, repoEnvelopeVars, startMerge, submitPr } from "./service.ts";
 
 function memTable(rows: any[], key: string) {
   return {
@@ -502,3 +502,190 @@ test("parsePr still resolves a well-formed prKey and PR URL", () => {
   assertEquals(parsePr("  owner/repo#42  ")?.number, 42);
   assertEquals(parsePr("https://github.com/owner/repo/pull/7")?.repo, "owner/repo");
 });
+
+// Red/green regression for the level-triggered wave-merge barrier (issue #262). The barrier is
+// armed (`plans.gate_wave = W`) at wave handoff, long BEFORE the token traverses the slow
+// `trial-merge` agent job and finally opens the `wait-wave-merged` subscription. The old
+// `pollWaveGates` was edge-triggered: the first pass that saw wave W's PRs merged cleared
+// `gate_wave` and published `wave-merged` EXACTLY ONCE. If that happened while the token was still
+// upstream (no open subscription), the message was dropped and — with `gate_wave` now null — never
+// republished, so the epic wedged forever once the token arrived. The fix reconciles the merged
+// state against the engine's OPEN-subscription state every pass, publishing only into an open
+// subscription and never clearing `gate_wave` optimistically.
+//
+// Stubs `/message-subscriptions/search` (keyed by processInstanceKey) so the subscription can be
+// toggled open between passes, and forces the GitHub transport off — the wave's PRs are tracked
+// `merged` rows, so `isDepMerged` resolves them from the DB with no network.
+function subscriptionFetch(open: Set<string>) {
+  return (url: string | URL | Request, init?: RequestInit): Promise<Response> => {
+    const u = typeof url === "string" ? url : url.toString();
+    if (!u.endsWith("/message-subscriptions/search")) {
+      throw new Error(`unexpected fetch: ${u}`);
+    }
+    const body = JSON.parse(String(init?.body ?? "{}")) as {
+      filter?: { processInstanceKey?: string };
+    };
+    const pik = body.filter?.processInstanceKey ?? "";
+    const items = open.has(pik)
+      ? [{ messageName: "wave-merged", correlationKey: "owner/repo#67", messageSubscriptionState: "CREATED" }]
+      : [];
+    return Promise.resolve(
+      new Response(JSON.stringify({ items }), { status: 200, headers: { "content-type": "application/json" } }),
+    );
+  };
+}
+
+test("pollWaveGatesImpl is level-triggered: PRs merged before the token arrives never lose the wave-merged signal (#262)", async () => {
+  await withGithubOff(async () => {
+    const PLAN_KEY = "owner/repo#67";
+    const PI = "PI-13794";
+    // Wave 1 opened two PRs; both are already MERGED (tracked rows → isDepMerged resolves from DB).
+    const plan = {
+      plan_key: PLAN_KEY,
+      process_key: PI,
+      gate_wave: 1 as number | null,
+      updated_at: "t0",
+    };
+    const stores: Record<string, { rows: unknown[]; key: string }> = {
+      plans: { rows: [plan], key: "plan_key" },
+      plan_tasks: {
+        rows: [
+          { id: "owner/repo#67:a", plan_key: PLAN_KEY, wave: 1, status: "opened", pr_key: "owner/repo#68" },
+          { id: "owner/repo#67:b", plan_key: PLAN_KEY, wave: 1, status: "opened", pr_key: "owner/repo#69" },
+        ],
+        key: "id",
+      },
+      pull_requests: {
+        rows: [
+          { pr_key: "owner/repo#68", status: "merged" },
+          { pr_key: "owner/repo#69", status: "merged" },
+        ],
+        key: "pr_key",
+      },
+    };
+    const data = {
+      table: (name: string, key: string) => memTable(stores[name]?.rows ?? [], stores[name]?.key ?? key),
+    } as any;
+
+    const published: { name: string; correlationKey?: string }[] = [];
+    const engine = {
+      publishMessage: (input: { name: string; correlationKey?: string }) => {
+        published.push(input);
+        return Promise.resolve();
+      },
+    } as any;
+    const headers = { "content-type": "application/json" };
+
+    const openSubs = new Set<string>(); // token still upstream of wait-wave-merged → NO open subscription
+    const prevFetch = globalThis.fetch;
+
+    // Pass 1 — the losing ordering: wave 1's PRs are all merged, but the token is parked upstream on
+    // the slow `trial-merge` job, so there is no open `wait-wave-merged` subscription yet. The old
+    // single-shot barrier would publish-into-the-void and CLEAR `gate_wave`, stranding the epic.
+    globalThis.fetch = subscriptionFetch(openSubs) as typeof fetch;
+    try {
+      await pollWaveGatesImpl(data, engine, "", "http://engine/v2", headers);
+    } finally {
+      globalThis.fetch = prevFetch;
+    }
+    // The signal must NOT have been fired into the void, and the gate must remain armed (not stranded).
+    assertEquals(published.length, 0, "must not publish wave-merged with no open subscription");
+    assertEquals(plan.gate_wave, 1, "gate_wave must stay armed until the barrier is actually released");
+
+    // Pass 2 — the token has now advanced to `wait-wave-merged`, opening the subscription. The
+    // level-triggered barrier re-publishes and correlates, releasing the token into wave 2.
+    openSubs.add(PI);
+    globalThis.fetch = subscriptionFetch(openSubs) as typeof fetch;
+    try {
+      await pollWaveGatesImpl(data, engine, "", "http://engine/v2", headers);
+    } finally {
+      globalThis.fetch = prevFetch;
+    }
+    assertEquals(published.length, 1, "must publish wave-merged once the subscription is open");
+    assertEquals(published[0]?.name, "wave-merged");
+    assertEquals(published[0]?.correlationKey, PLAN_KEY);
+  });
+});
+
+// Guards the false-positive failure class flagged in review: `waveMergedSubscriptionOpen` must treat
+// a search item with a missing/null/mismatched `messageName`, `correlationKey`, or
+// `messageSubscriptionState` as NOT-open. Defaulting an unverifiable field to its expected value
+// would publish `wave-merged` into a subscription we never confirmed open — buffering a message that
+// trips a LATER wave's barrier, i.e. re-introducing the exact #262 wedge this change prevents. A
+// false negative only costs a retry next pass; a false positive is a wedge, so unknown ⇒ don't match.
+function ambiguousSubscriptionFetch(items: unknown[]) {
+  return (url: string | URL | Request, _init?: RequestInit): Promise<Response> => {
+    const u = typeof url === "string" ? url : url.toString();
+    if (!u.endsWith("/message-subscriptions/search")) {
+      throw new Error(`unexpected fetch: ${u}`);
+    }
+    return Promise.resolve(
+      new Response(JSON.stringify({ items }), { status: 200, headers: { "content-type": "application/json" } }),
+    );
+  };
+}
+
+test("pollWaveGatesImpl never releases the barrier on an unverifiable subscription item (missing/null/mismatched fields)", async () => {
+  await withGithubOff(async () => {
+    const PLAN_KEY = "owner/repo#67";
+    const PI = "PI-13794";
+    const plan = {
+      plan_key: PLAN_KEY,
+      process_key: PI,
+      gate_wave: 1 as number | null,
+      updated_at: "t0",
+    };
+    const stores: Record<string, { rows: unknown[]; key: string }> = {
+      plans: { rows: [plan], key: "plan_key" },
+      plan_tasks: {
+        rows: [
+          { id: "owner/repo#67:a", plan_key: PLAN_KEY, wave: 1, status: "opened", pr_key: "owner/repo#68" },
+          { id: "owner/repo#67:b", plan_key: PLAN_KEY, wave: 1, status: "opened", pr_key: "owner/repo#69" },
+        ],
+        key: "id",
+      },
+      pull_requests: {
+        rows: [
+          { pr_key: "owner/repo#68", status: "merged" },
+          { pr_key: "owner/repo#69", status: "merged" },
+        ],
+        key: "pr_key",
+      },
+    };
+    const data = {
+      table: (name: string, key: string) => memTable(stores[name]?.rows ?? [], stores[name]?.key ?? key),
+    } as any;
+
+    const published: { name: string; correlationKey?: string }[] = [];
+    const engine = {
+      publishMessage: (input: { name: string; correlationKey?: string }) => {
+        published.push(input);
+        return Promise.resolve();
+      },
+    } as any;
+    const headers = { "content-type": "application/json" };
+    const prevFetch = globalThis.fetch;
+
+    // Each of these items is ambiguous — it omits or mismatches a field the barrier requires. None
+    // may be treated as an OPEN subscription for THIS plan, so none may release wave 1's gate.
+    const ambiguousItems: unknown[][] = [
+      [{}], // empty item — no fields at all
+      [{ messageName: "wave-merged", correlationKey: PLAN_KEY }], // missing state
+      [{ messageName: "wave-merged", correlationKey: PLAN_KEY, messageSubscriptionState: null }], // null state
+      [{ correlationKey: PLAN_KEY, messageSubscriptionState: "CREATED" }], // missing messageName
+      [{ messageName: "some-other-message", correlationKey: PLAN_KEY, messageSubscriptionState: "CREATED" }],
+      [{ messageName: "wave-merged", messageSubscriptionState: "CREATED" }], // missing correlationKey
+      [{ messageName: "wave-merged", correlationKey: "owner/repo#999", messageSubscriptionState: "CREATED" }],
+    ];
+    for (const items of ambiguousItems) {
+      globalThis.fetch = ambiguousSubscriptionFetch(items) as typeof fetch;
+      try {
+        await pollWaveGatesImpl(data, engine, "", "http://engine/v2", headers);
+      } finally {
+        globalThis.fetch = prevFetch;
+      }
+    }
+    assertEquals(published.length, 0, "must not publish wave-merged on an unverifiable subscription item");
+    assertEquals(plan.gate_wave, 1, "gate_wave must stay armed while no OPEN subscription is confirmed");
+  });
+});

package/app/service.ts

@@ -1141,17 +1141,104 @@ export async function pollIncidentsImpl(
   }
 }
 
-/** Wave-merge barrier poll pass. After `record-wave` hands off a wave that has a successor, the
- * plan-fanout instance parks at the `wait-wave-merged` catch event and `plans.gate_wave` records
- * that wave's index. Here we check whether every OPENED PR in that wave has MERGED and, if so,
- * publish `wave-merged` (correlated on the plan key) to release the next wave's implementation.
+/** The `wave-merged` message name (`resources/processes/plan-fanout.bpmn`): the `wait-wave-merged`
+ * catch event opens a subscription for it (correlated on `=planKey`) once the token arrives, and
+ * the poller publishes it to release the next wave. Single source of truth for the string shared by
+ * the publish and the subscription probe. */
+const WAVE_MERGED_MESSAGE = "wave-merged";
+
+/** The subset of a Camunda-8 `/v2/message-subscriptions/search` result item this app reads to tell
+ * whether the plan-fanout instance is *currently parked* at `wait-wave-merged`. `messageName` is the
+ * awaited message; `correlationKey` is the plan key the catch event binds; `messageSubscriptionState`
+ * is `CREATED` while the subscription is open (waiting) and `CORRELATED`/`DELETED` once consumed. */
+interface MessageSubscriptionSearchItem {
+  messageName?: string;
+  correlationKey?: string | null;
+  messageSubscriptionState?: string;
+}
+
+/** Is the plan-fanout instance `processKey` right now parked at `wait-wave-merged` with an OPEN
+ * (`CREATED`) subscription correlated on `planKey`? Reads the engine's Camunda-8
+ * `/v2/message-subscriptions/search` (the same raw-REST search surface `pollIncidents`/
+ * `pollJobActivation` use). Returns `true` (open — safe to release), `false` (no open subscription —
+ * the token is either upstream of the wait or has already passed through it), or `null` (transport
+ * unhappy / unparseable body — "unknown", so the caller neither publishes nor acts on a guess and
+ * simply retries next tick). This is the load-bearing check that makes the barrier level-triggered:
+ * we only ever publish `wave-merged` into a subscription we've observed OPEN, so a signal can never
+ * be dropped into the void (the #262 wedge) nor buffered to trip a *later* wave's barrier. */
+async function waveMergedSubscriptionOpen(
+  base: string,
+  headers: Record<string, string>,
+  processKey: string,
+  planKey: string,
+): Promise<boolean | null> {
+  try {
+    const res = await fetch(`${base}/message-subscriptions/search`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({
+        filter: {
+          processInstanceKey: processKey,
+          messageName: WAVE_MERGED_MESSAGE,
+          messageSubscriptionState: "CREATED",
+        },
+        page: { limit: 20 },
+      }),
+    });
+    if (!res.ok) return null; // engine unhappy → "unknown", retry next pass
+    // biome-ignore lint/plugin: runtime/framework contract boundary for external data shape
+    const body = (await res.json()) as { items?: MessageSubscriptionSearchItem[] };
+    // Re-filter defensively in case the engine ignores a filter field: an OPEN (`CREATED`)
+    // subscription for the `wave-merged` message, correlated on THIS plan key, is the barrier we may
+    // publish into. Every field must be PRESENT and match explicitly — we never default a
+    // missing/null `messageName`, `correlationKey`, or `messageSubscriptionState` to its expected
+    // value. Doing so would treat an unverifiable item as OPEN and re-introduce the exact #262
+    // failure class (publishing into a subscription we never confirmed open, buffering a message that
+    // trips a later wave's barrier). An item that omits a field is "unknown", so we simply don't
+    // match it: a false negative only costs a retry next pass, whereas a false positive is a wedge.
+    // State is compared case-insensitively so a future casing tweak can't silently drop the match.
+    return (body.items ?? []).some(
+      (it) =>
+        it.messageName === WAVE_MERGED_MESSAGE &&
+        it.correlationKey === planKey &&
+        typeof it.messageSubscriptionState === "string" &&
+        it.messageSubscriptionState.toUpperCase() === "CREATED",
+    );
+  } catch (err) {
+    console.error(`[poller] wave-merged subscription ${planKey}: ${err}`);
+    return null; // transport threw → "unknown", retry next pass
+  }
+}
+
+/** Wave-merge barrier poll pass (issue #262). After `record-wave` hands off a wave that has a
+ * successor, the plan-fanout instance eventually parks at the `wait-wave-merged` catch event and
+ * `plans.gate_wave` records that wave's index. Here we reconcile, on EVERY pass and idempotently,
+ * the external GitHub fact "every OPENED PR in that wave has MERGED" against the engine fact "is
+ * there an OPEN `wait-wave-merged` subscription for this plan right now?", publishing `wave-merged`
+ * (correlated on the plan key) to release the next wave's implementation whenever BOTH hold.
  *
- * `gate_wave` is cleared single-shot BEFORE publishing (and restored if the publish fails —
- * mirroring `flipToMergingThenPublish`) so a slow pass can't double-signal and a later wave's
- * barrier can't be tripped by a stale message reusing the same plan-key correlation. A wave whose
- * tasks all ended `blocked`/`skipped` (no opened PR to wait on) clears vacuously — there is
- * nothing to merge, and that failure has already cascaded to dependents in `select-wave`. */
-async function pollWaveGates(data: DataLayer, engine: EngineClient, token: string) {
+ * This is deliberately LEVEL-triggered, not the old single-shot edge trigger. The gate is armed at
+ * wave handoff — long before the token traverses `select-wave → trial-merge (a slow agent job) →
+ * … → wait-wave-merged` and opens the subscription. If the wave's PRs merged while the token was
+ * still upstream, the old code published its one `wave-merged` into NO open subscription (dropped)
+ * AND cleared `gate_wave`, so it never republished and the epic wedged forever once the token
+ * finally arrived (#262). We fix the class:
+ *   • We publish ONLY when {@link waveMergedSubscriptionOpen} confirms the token is parked at the
+ *     wait — never into the void — so a merged-before-arrival wave simply waits, and a later pass
+ *     (once the token arrives) republishes and correlates.
+ *   • We NEVER clear `gate_wave` here. `record-wave` owns its lifecycle (it re-arms it to the next
+ *     wave, or clears it to `null` on the final wave), so a signal published into the void can't
+ *     strand the gate, and double-advance is guarded by the open-subscription check — which, by the
+ *     handoff ordering, always matches the wave whose wait is currently open — not by a premature
+ *     clear. A wave whose tasks all ended `blocked`/`skipped` (no opened PR to wait on) has an empty
+ *     merge-target set and so is treated as merged; `record-wave` advances it on the next pass. */
+export async function pollWaveGatesImpl(
+  data: DataLayer,
+  engine: EngineClient,
+  token: string,
+  base: string,
+  headers: Record<string, string>,
+) {
   for (const plan of await plans(data).all()) {
     const gateWave = plan.gate_wave;
     if (gateWave == null) continue;
@@ -1165,18 +1252,14 @@ async function pollWaveGates(data: DataLayer, engine: EngineClient, token: strin
           break;
         }
       }
-      if (!allMerged) continue;
-      await plans(data).update(planKey, { gate_wave: null, updated_at: now() });
-      try {
-        await engine.publishMessage({ name: "wave-merged", correlationKey: planKey, variables: {} });
-      } catch (err) {
-        try {
-          await plans(data).update(planKey, { gate_wave: gateWave, updated_at: now() });
-        } catch (revertErr) {
-          console.error(`[poller] revert wave-gate ${planKey} -> ${gateWave} failed: ${revertErr}`);
-        }
-        throw err;
-      }
+      if (!allMerged) continue; // wave not landed yet → leave the gate armed, retry next pass
+      // The wave has landed on GitHub. Release the barrier ONLY if the token is actually parked at
+      // `wait-wave-merged` (an OPEN subscription for this plan): otherwise publishing would be a
+      // silent no-op that the old code paired with a gate clear — the edge-triggered wedge (#262).
+      if (!plan.process_key) continue; // no instance key to correlate against yet
+      const open = await waveMergedSubscriptionOpen(base, headers, plan.process_key, planKey);
+      if (open !== true) continue; // not parked here yet / already released / unknown → NEVER clear the gate; retry next pass
+      await engine.publishMessage({ name: WAVE_MERGED_MESSAGE, correlationKey: planKey, variables: {} });
       console.log(`[poller] wave ${gateWave} merged -> ${planKey}`);
     } catch (err) {
       console.error(`[poller] wave-gate ${planKey}: ${err}`);
@@ -1559,7 +1642,11 @@ export async function pollUserTasks(data: DataLayer, engine: EngineClient) {
 
 /** One full poll pass: advance the review stage, the merge stage, the wave-merge barrier, and
  * (when the engine REST endpoint is supplied) the job-activation visibility pass and the
- * technical-incident surfacing pass. Called on the self-scheduling loop in `main.ts`. */
+ * technical-incident surfacing pass. Called on the self-scheduling loop in `main.ts`.
+ *
+ * The wave-merge barrier is now level-triggered and probes the engine's message-subscription state
+ * over the same raw-REST search surface, so it runs only when `engineRest` is supplied (as in
+ * production — `main.ts` always passes it). */
 export async function pollOnce(
   data: DataLayer,
   engine: EngineClient,
@@ -1568,7 +1655,6 @@ export async function pollOnce(
 ) {
   await pollReviews(data, engine, token);
   await pollMerges(data, engine, token);
-  await pollWaveGates(data, engine, token);
   await pollDelivery(data);
   await pollFeatureDelivery(data);
   await pollLineage(data);
@@ -1576,6 +1662,10 @@ export async function pollOnce(
   await pollFeatureBlocked(data, engine);
   await pollUserTasks(data, engine);
   if (engineRest) {
+    const base = engineRest.restAddress.replace(/\/+$/, "");
+    const headers: Record<string, string> = { "content-type": "application/json" };
+    if (engineRest.token) headers.authorization = `Bearer ${engineRest.token}`;
+    await pollWaveGatesImpl(data, engine, token, base, headers);
     await pollJobActivation(data, engineRest.restAddress, engineRest.token);
     await pollIncidents(data, engineRest.restAddress, engineRest.token);
   }

package/db/migrations/007_wave_gate.sql

@@ -10,7 +10,10 @@
 --
 -- `plans.gate_wave` is the durable marker for the barrier: when `record-wave` hands
 -- off a wave that has a successor, it records that wave's index here and the process
--- parks at the `wait-wave-merged` catch event. The poller (`pollWaveGates`) clears it
--- and publishes `wave-merged` once every opened PR in that wave has merged. NULL means
--- the plan is not currently parked at the wave barrier.
+-- parks at the `wait-wave-merged` catch event. The poller (`pollWaveGatesImpl`) is
+-- level-triggered: it publishes `wave-merged` once every opened PR in that wave has
+-- merged AND it observes an OPEN `wait-wave-merged` subscription for the plan, and it
+-- NEVER clears `gate_wave` — `record-wave` owns the marker's lifecycle (re-arming it to
+-- the next wave, or clearing it to NULL on the final wave). NULL means the plan is not
+-- currently parked at the wave barrier.
 ALTER TABLE plans ADD COLUMN gate_wave INTEGER;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.82.0",
+  "version": "0.82.1",
   "description": "Nano Workforce — an Agent Graph Orchestration application for Agentic SDLC: durable BPMN processes that coordinate a graph of AI agents across the software delivery lifecycle.",
   "type": "module",
   "main": "main.ts",

package/workers/record-wave/worker.ts

@@ -293,9 +293,11 @@ const handler: AppJobHandler<In, Out> = async (job, app) => {
 
   // Wave-merge barrier: when another wave follows, park the plan-fanout instance at the
   // `wait-wave-merged` catch event until THIS wave's opened PRs have MERGED (not merely opened).
-  // `gate_wave` is that durable marker; the poller (`pollWaveGates`) clears it and publishes
-  // `wave-merged` once the wave has landed. Clear it on the final wave so a re-planned issue can't
-  // inherit a stale gate. Best-effort: a failed marker write must not fail the wave (the poller
+  // `gate_wave` is that durable marker; the level-triggered poller (`pollWaveGatesImpl`) publishes
+  // `wave-merged` once the wave has landed AND it observes an OPEN subscription, but NEVER clears
+  // `gate_wave` — record-wave owns the marker's lifecycle. Re-arm it to the next wave here, or
+  // clear it on the final wave so a re-planned issue can't inherit a stale gate. Best-effort: a
+  // failed marker write must not fail the wave (the poller
   // reconciles from `plan_tasks`/`pull_requests`), but the loop still relies on it to know which
   // wave to watch, so we log a failure loudly.
   try {