mandrel 1.88.0 → 1.90.0

package/.agents/scripts/lib/orchestration/lifecycle/listeners/automerge-predicate.js

@@ -66,9 +66,12 @@
 
 import { spawnSync } from 'node:child_process';
 
+import { hasSurvivingCritical } from '../../../audit-suite/findings.js';
 import { getCiDelivery } from '../../../config/ci.js';
+import { parsePrNumberFromUrl } from '../../../github-url.js';
 import * as epicRunStateStore from '../../epic-run-state-store.js';
 import { findStructuredComment } from '../../ticketing.js';
+import { emitMergeUnlanded } from '../emit-merge-unlanded.js';
 import { normalizeCheckState, RECOGNIZED_CHECK_STATES } from './watcher.js';
 
 /**
@@ -223,19 +226,51 @@ export function probeRequiredChecks({ prUrl, cwd, spawnFn = spawnSync }) {
  * stdout. We parse stdout first (it is populated even on the non-zero
  * exit) and classify from the outcomes.
  *
+ * Story #4472 — checks-less repos. In a repo with zero required checks
+ * (no branch protection, or protection that requires no status checks),
+ * `gh pr checks --required` writes NOTHING to stdout and reports
+ * `no checks reported on the <branch> branch` to stderr with a non-zero
+ * exit. That is the SAME empty-parsed-set condition the outcomes loop
+ * below already treats as green — there is simply nothing to gate on — so
+ * we must not conflate it with a genuine probe failure (auth, network, no
+ * PR). We detect the `no checks reported` stderr signature and return
+ * green, UNLESS the consumer opted into `delivery.ci.requireChecks`, in
+ * which case the absent CI gate is a deliberate hard block.
+ *
  * @param {{ status: number, stdout: string, stderr: string }} probe
+ * @param {{ requireChecks?: boolean }} [opts] When `requireChecks` is
+ *   true, a checks-less repo fails closed instead of arming.
  * @returns {{ ok: boolean, reason: string|null, outcomes: Record<string, string> }}
  */
-export function classifyRequiredChecksProbe(probe) {
+export function classifyRequiredChecksProbe(
+  probe,
+  { requireChecks = false } = {},
+) {
   const stdout = String(probe?.stdout ?? '').trim();
-  // Empty stdout with a non-zero status → probe genuinely failed (auth,
-  // network, no PR). Fail closed.
+  const stderr = String(probe?.stderr ?? '').trim();
+  // Empty stdout: either a checks-less repo (green, nothing to gate on) or
+  // a genuine probe failure. The `no checks reported` stderr signature
+  // distinguishes them.
   if (stdout.length === 0) {
+    const noChecksReported = /no checks reported/i.test(stderr);
+    if (noChecksReported && !requireChecks) {
+      // Zero required checks configured — matches the empty-parsed-set
+      // "treated as green" branch below. Nothing to gate on.
+      return { ok: true, reason: null, outcomes: {} };
+    }
+    if (noChecksReported && requireChecks) {
+      return {
+        ok: false,
+        reason:
+          'no required checks reported and delivery.ci.requireChecks is set — failing closed per policy',
+        outcomes: {},
+      };
+    }
     return {
       ok: false,
       reason:
         `live required-check probe failed (status=${probe?.status ?? 'unknown'})` +
-        (probe?.stderr ? `: ${String(probe.stderr).trim().slice(0, 200)}` : ''),
+        (stderr ? `: ${stderr.slice(0, 200)}` : ''),
       outcomes: {},
     };
   }
@@ -441,7 +476,11 @@ function evaluateCodeReviewSignals(codeReview, reasons) {
   if (codeReviewUnparseable) {
     return { codeReviewFound, codeReviewUnparseable, severity };
   }
-  if (severity.critical > 0) {
+  // Route the halt-on-critical decision through the single halting rule of
+  // the unified verification-results contract (Story #4411) rather than a
+  // re-derived `critical > 0` expression. The unparseable branch above has
+  // already returned, so `severity.critical` is a concrete number here.
+  if (hasSurvivingCritical(severity)) {
     pushReason(
       reasons,
       REASON_CATEGORY.CRITICAL_REVIEW,
@@ -648,7 +687,11 @@ export async function evaluateAutoMergePredicate({
   // only IO, but the rule is directory-scoped; sequencing here is a
   // cheap concession for living inside the listener tree.
   const state = await readRunStateFn({ provider, epicId });
-  const codeReview = await findCommentFn(provider, epicId, 'code-review');
+  const codeReview = await findCommentFn(
+    provider,
+    epicId,
+    'verification-results',
+  );
   let retro = await findCommentFn(provider, epicId, 'retro');
   if (!retro) {
     retro = await findCommentFn(provider, epicId, 'retro-partial');
@@ -669,8 +712,13 @@ export class AutomergePredicate {
    *   evaluator). Required for the read of run-state + structured
    *   comments.
    * @param {object} [opts.config] Resolved agent config. Read for the
-   *   `delivery.ci.autoMerge` policy via `getCiDelivery`. Defaults to the
-   *   framework default (`trust-ci`) when omitted.
+   *   `delivery.ci.autoMerge` policy and the `delivery.ci.requireChecks`
+   *   fail-closed-without-checks policy via `getCiDelivery`. Defaults to the
+   *   framework defaults (`trust-ci` / `requireChecks: false`) when omitted.
+   * @param {boolean} [opts.headless] When true (a `/deliver --yes` run), a
+   *   predicate refusal escalates to an explicit `merge.unlanded` +
+   *   `epic.blocked` terminal instead of silently parking on the
+   *   operator-merges path (Story #4472). Defaults to `false` (attended).
    * @param {string} [opts.cwd] Working directory for the live
    *   `gh pr checks --required` probe. Defaults to `process.cwd()`.
    * @param {Function} [opts.evaluatePredicateFn] override of
@@ -699,13 +747,20 @@ export class AutomergePredicate {
     this.epicId = opts.epicId;
     this.provider = opts.provider;
     this.cwd = opts.cwd ?? process.cwd();
-    // Resolve the merge posture once at construction. `getCiDelivery`
-    // applies the framework default (`trust-ci`) for any omitted field.
-    this.policy = getCiDelivery(opts.config ?? null).autoMerge;
+    // Resolve the merge posture + fail-closed policy once at construction.
+    // `getCiDelivery` applies the framework defaults (`trust-ci` /
+    // `requireChecks: false`) for any omitted field.
+    const ci = getCiDelivery(opts.config ?? null);
+    this.policy = ci.autoMerge;
+    this.requireChecks = ci.requireChecks;
+    this.headless = opts.headless === true;
     this.evaluatePredicateFn =
       opts.evaluatePredicateFn ?? evaluateAutoMergePredicate;
     this.probeRequiredChecksFn =
       opts.probeRequiredChecksFn ?? probeRequiredChecks;
+    // Injected for tests so the headless terminal escalation can be
+    // observed without touching disk.
+    this.emitMergeUnlandedFn = opts.emitMergeUnlandedFn ?? emitMergeUnlanded;
     this.logger = opts.logger ?? console;
     /** @type {Set<string>} `${event}:${seqId}` idempotency cache. */
     this._seen = new Set();
@@ -777,7 +832,9 @@ export class AutomergePredicate {
       let probeVerdict;
       try {
         const probe = this.probeRequiredChecksFn({ prUrl, cwd: this.cwd });
-        probeVerdict = classifyRequiredChecksProbe(probe);
+        probeVerdict = classifyRequiredChecksProbe(probe, {
+          requireChecks: this.requireChecks,
+        });
       } catch (err) {
         probeVerdict = {
           ok: false,
@@ -869,6 +926,17 @@ export class AutomergePredicate {
    * Emit `epic.merge.blocked`. Helper carved out so the blocking paths
    * (CI failure / predicate dirty / evaluator throw) share the same emit
    * shape.
+   *
+   * Story #4472 — must-land coverage of predicate refusal. In a headless
+   * (`/deliver --yes`) run there is no operator to act on a bare
+   * `epic.merge.blocked` (nothing in the listener chain consumes it), so
+   * the run would silently park on the operator-merges path. When
+   * `this.headless`, we additionally attribute the refusal to the
+   * lifecycle ledger via `merge.unlanded` (blockClass `predicate-refused`)
+   * and drive the explicit `epic.blocked` terminal — the same
+   * escalation the MergeWatcher performs on post-arm budget exhaustion —
+   * so the Epic transitions to `agent::blocked` with an operator-visible
+   * reason instead of stalling.
    */
   async _emitBlocked(prUrl, reason) {
     try {
@@ -878,6 +946,35 @@ export class AutomergePredicate {
         `[AutomergePredicate] epic.merge.blocked emit failed (swallowed): ${err?.message ?? err}`,
       );
     }
+    if (!this.headless) return;
+    // Ledger attribution — best-effort; a failed append must NOT mask the
+    // epic.blocked transition below.
+    try {
+      const prNumber = parsePrNumberFromUrl(prUrl);
+      if (Number.isInteger(prNumber) && prNumber > 0) {
+        this.emitMergeUnlandedFn({
+          scope: 'epic',
+          ticketId: this.epicId,
+          prNumber,
+          blockClass: 'predicate-refused',
+          reason,
+          elapsedSeconds: 0,
+        });
+      }
+    } catch (err) {
+      this.logger.warn?.(
+        `[AutomergePredicate] emitMergeUnlanded failed (swallowed): ${err?.message ?? err}`,
+      );
+    }
+    try {
+      await this.bus.emit('epic.blocked', {
+        reason: `merge-predicate:refused`,
+      });
+    } catch (err) {
+      this.logger.warn?.(
+        `[AutomergePredicate] epic.blocked emit on predicate refusal failed (swallowed): ${err?.message ?? err}`,
+      );
+    }
   }
 
   reset() {

package/.agents/scripts/lib/orchestration/lifecycle/listeners/finalizer.js

@@ -16,8 +16,15 @@
  *
  * Side effects executed inside `handle()`:
  *   1. Emit `epic.finalize.start`.
- *   2. Auto-graduate non-blocking code-review / audit-results findings
- *      (best-effort; never throws).
+ *   2. Auto-graduate non-blocking findings in a SINGLE pass over the
+ *      unified `verification-results` comment (best-effort; never throws).
+ *      Story #4411 folded the former code-review + audit-results
+ *      structured-comment contracts into one comment; the lens-aware
+ *      audit-results graduator is the single canonical reader (its
+ *      🟢→`suggestion` severity vocabulary matches `findings-renderer.js`).
+ *      Running a second code-review pass over the same comment would file
+ *      every non-blocking finding twice, so only the audit-results
+ *      graduation runs here.
  *   3. Idempotency probe — `gh pr list --head epic/<id>` returns any
  *      existing PR URL. If one exists, short-circuit to `pr.created`
  *      + `epic.finalize.end` carrying the existing URL.
@@ -69,7 +76,6 @@ import {
   graduateAuditResults as defaultGraduateAuditResults,
   isAutoFileEnabled as isAuditResultsAutoFileEnabled,
 } from '../../../feedback-loop/audit-results-graduator.js';
-import { graduateFindings as defaultGraduateFindings } from '../../../feedback-loop/code-review-graduator.js';
 import { parsePrNumberFromUrl } from '../../../github-url.js';
 import {
   markPrReady as defaultMarkPrReady,
@@ -235,17 +241,39 @@ export function extractPrUrl(stdout) {
   return match ? match[0] : null;
 }
 
+/**
+ * Default bounded timeout for the finalize idempotency probe. Story #4415
+ * (Epic #4406) — a hung `gh pr list` spawn previously blocked finalize
+ * forever; the probe now SIGKILLs the child at this bound so a stalled
+ * `gh` cannot park the merge gate.
+ */
+export const GH_PR_LIST_TIMEOUT_MS = 30000;
+
 /**
  * Default `gh` spawn used by the listener's idempotency probe.
  * Mirrors the `shell: false` contract `openOrLocatePr` and the other
  * listener helpers use so a future Windows audit doesn't have to grep
- * across two modules. Exported so tests can stub.
+ * across two modules. Bounded by `timeoutMs` (default
+ * {@link GH_PR_LIST_TIMEOUT_MS}) + `killSignal: 'SIGKILL'` so a hung `gh`
+ * spawn cannot block finalize indefinitely (Story #4415). Exported so
+ * tests can stub.
  */
-export function ghPrListHead({ epicBranch, cwd, spawnFn = spawnSync }) {
+export function ghPrListHead({
+  epicBranch,
+  cwd,
+  spawnFn = spawnSync,
+  timeoutMs = GH_PR_LIST_TIMEOUT_MS,
+}) {
   const result = spawnFn(
     'gh',
     ['pr', 'list', '--head', epicBranch, '--json', 'url', '--jq', '.[0].url'],
-    { cwd, encoding: 'utf-8', shell: false },
+    {
+      cwd,
+      encoding: 'utf-8',
+      shell: false,
+      timeout: timeoutMs,
+      killSignal: 'SIGKILL',
+    },
   );
   return {
     status: result.status ?? 1,
@@ -276,7 +304,6 @@ export class Finalizer {
    *   the graduators.
    * @param {{owner:string,repo:string}} [opts.currentRepo]
    * @param {{owner:string,repo:string}} [opts.frameworkRepo]
-   * @param {Function} [opts.graduateFindingsFn]
    * @param {Function} [opts.graduateAuditResultsFn]
    * @param {{ info?: Function, warn?: Function, debug?: Function }} [opts.logger]
    */
@@ -314,8 +341,6 @@ export class Finalizer {
     this.config = opts.config ?? null;
     this.currentRepo = opts.currentRepo ?? null;
     this.frameworkRepo = opts.frameworkRepo ?? null;
-    this.graduateFindingsFn =
-      opts.graduateFindingsFn ?? defaultGraduateFindings;
     this.graduateAuditResultsFn =
       opts.graduateAuditResultsFn ?? defaultGraduateAuditResults;
     this.logger = opts.logger ?? console;
@@ -373,10 +398,11 @@ export class Finalizer {
       return;
     }
 
-    // 1b. Auto-graduate non-blocking code-review findings (Story #2555).
-    await this._runCodeReviewGraduation();
-
-    // 1c. Auto-graduate non-blocking audit-results findings (Story #2615).
+    // 1b. Auto-graduate non-blocking findings in a SINGLE pass over the
+    //     unified `verification-results` comment (Story #2615; unified in
+    //     Story #4411). The lens-aware audit-results graduator is the sole
+    //     canonical reader — a second code-review pass over the same comment
+    //     would file every non-blocking finding twice.
     await this._runAuditResultsGraduation();
 
     // 2. Idempotency probe — does a PR already exist on the head
@@ -498,54 +524,14 @@ export class Finalizer {
   }
 
   /**
-   * Invoke the code-review graduator best-effort. Wired into finalize so
-   * that surviving non-blocking findings get auto-filed as routed
-   * follow-up issues (Story #2555 / Epic #2547). All failures are
-   * captured and logged at warn level; the finalize pipeline continues
-   * regardless — the toggle `delivery.feedbackLoop.codeReviewAutoFile`
-   * is the only operator-facing kill switch.
-   */
-  async _runCodeReviewGraduation() {
-    if (!this.provider || !this.currentRepo) {
-      this.logger.debug?.(
-        '[Finalizer] code-review graduation skipped: provider or currentRepo not wired',
-      );
-      return;
-    }
-    try {
-      const summary = await this.graduateFindingsFn({
-        epicId: this.epicId,
-        provider: this.provider,
-        config: this.config,
-        currentRepo: this.currentRepo,
-        frameworkRepo: this.frameworkRepo,
-        cwd: this.cwd,
-        logger: this.logger,
-      });
-      const filed = Array.isArray(summary?.filed) ? summary.filed.length : 0;
-      const skipped = Array.isArray(summary?.skipped)
-        ? summary.skipped.length
-        : 0;
-      const errors = Array.isArray(summary?.errors) ? summary.errors.length : 0;
-      this.logger.info?.(
-        `[Finalizer] code-review graduation: filed=${filed} skipped=${skipped} errors=${errors}`,
-      );
-      if (errors > 0) {
-        this.logger.warn?.(
-          `[Finalizer] code-review graduator errors: ${summary.errors.join('; ')}`,
-        );
-      }
-    } catch (err) {
-      this.logger.warn?.(
-        `[Finalizer] code-review graduator threw (swallowed): ${err?.message ?? err}`,
-      );
-    }
-  }
-
-  /**
-   * Invoke the audit-results graduator best-effort. Wired into finalize
-   * so that non-blocking audit findings (high/medium/low/suggestion) get
-   * auto-filed as routed follow-up issues — Story #2615 / Epic #2586.
+   * Invoke the audit-results graduator best-effort — the SINGLE canonical
+   * graduation pass over the unified `verification-results` comment. Wired
+   * into finalize so that non-blocking findings (high/medium/low/suggestion)
+   * get auto-filed as routed follow-up issues — Story #2615 / Epic #2586,
+   * unified into one pass in Story #4411 / Epic #4405. The lens-aware
+   * audit-results graduator is canonical because its 🟢→`suggestion`
+   * severity vocabulary matches `findings-renderer.js`; running a parallel
+   * code-review pass over the same comment would double-file every finding.
    */
   async _runAuditResultsGraduation() {
     if (!this.provider || !this.currentRepo) {

package/.agents/scripts/lib/orchestration/lifecycle/listeners/index.js

@@ -18,8 +18,10 @@
  *   4. AutomergeArmer          (epic.merge.ready → epic.merge.armed)
  *   5. AutomergePredicate      (epic.watch.end → epic.merge.{ready,blocked})
  *   6. BranchCleaner           (epic.cleanup.start → branch reap)
- *   7. Cleaner                 (epic.merge.armed → epic.cleanup.* / epic.complete)
- *   8. CheckpointPointerWriter (every *.end → checkpoint.json)
+ *   7. MergeWatcher            (epic.merge.armed → epic.merge.confirmed)
+ *   8. Cleaner                 (epic.merge.confirmed → epic.cleanup.* / epic.complete)
+ *   9. LabelTransitioner       (epic.complete → Epic ticket flips to agent::done)
+ *  10. CheckpointPointerWriter (every *.end → checkpoint.json)
  *
  * The bus contract requires LedgerWriter first: its `onEmitted` hook
  * lands the `emitted` ledger record on disk BEFORE any listener body
@@ -60,6 +62,7 @@ import { BranchCleaner } from './branch-cleaner.js';
 import { CheckpointPointerWriter } from './checkpoint-pointer-writer.js';
 import { Cleaner } from './cleaner.js';
 import { Finalizer } from './finalizer.js';
+import { LabelTransitioner } from './label-transitioner.js';
 import { MergeWatcher } from './merge-watcher.js';
 
 /**
@@ -118,6 +121,11 @@ export function parseLedgerPath(ledgerPath) {
  * @param {object} [opts.checkpointer] Epic-run-state checkpoint reader.
  *   When omitted, BranchCleaner is skipped.
  * @param {object} [opts.logger] Logger surface (`debug`/`warn`/`error`).
+ * @param {boolean} [opts.headless] Explicit must-land signal (Story
+ *   #4427), threaded straight through to `MergeWatcher`. Defaults to
+ *   `false` (attended-mode behavior unchanged). `lifecycle-emit.js`
+ *   resolves this from its own `--headless` runtime flag — an explicit
+ *   input, never an ambient global.
  *
  * @returns {Promise<{
  *   ledgerWriter: object,
@@ -140,6 +148,7 @@ export async function buildDefaultListenerChain(opts = {}) {
     config = null,
     checkpointer = null,
     logger = console,
+    headless = false,
   } = opts;
   if (
     !bus ||
@@ -217,10 +226,15 @@ export async function buildDefaultListenerChain(opts = {}) {
   order.push('Finalizer');
 
   // 4. AutomergeArmer — arms `gh pr merge --auto --squash --delete-branch`
-  //    on epic.merge.ready.
+  //    on epic.merge.ready. Story #4472: `headless` gates the direct-merge
+  //    fallback's terminal escalation (a genuine arm failure emits
+  //    `merge.unlanded` + `epic.blocked` in a `--yes` run instead of
+  //    returning silently); `epicId` scopes the `merge.unlanded` ledger row.
   const automergeArmer = new AutomergeArmer({
     bus,
+    epicId,
     cwd: repoRoot,
+    headless,
     logger,
   });
   automergeArmer.register();
@@ -241,6 +255,7 @@ export async function buildDefaultListenerChain(opts = {}) {
       provider,
       config,
       cwd: repoRoot,
+      headless,
       logger,
     });
     automergePredicate.register();
@@ -288,6 +303,7 @@ export async function buildDefaultListenerChain(opts = {}) {
     cwd: repoRoot,
     intervalSeconds: mergeWatchConfig.intervalSeconds,
     maxBudgetSeconds: mergeWatchConfig.maxBudgetSeconds,
+    headless,
     logger,
   });
   mergeWatcher.register();
@@ -306,7 +322,32 @@ export async function buildDefaultListenerChain(opts = {}) {
   cleaner.register();
   order.push('Cleaner');
 
-  // 8. CheckpointPointerWriter — persists `{ lastCompletedSeqId, phase }`
+  // 9. LabelTransitioner — flips the Epic ticket to `agent::done` (and
+  //    closes it as completed, idempotently) on the terminal
+  //    `epic.complete` event. Requires a truthy `provider`; skip
+  //    cleanly when the caller omitted one — the same guard pattern as
+  //    AutomergePredicate. Restores the contract the Cleaner /
+  //    BranchCleaner / MergeWatcher docstrings have referenced since
+  //    the original listener was deleted with the epic-runner stratum
+  //    (#3936): without this registration the flip had NO owner and
+  //    cleanly-merged Epics stranded at `agent::executing`.
+  let labelTransitioner = null;
+  if (provider) {
+    labelTransitioner = new LabelTransitioner({
+      bus,
+      epicId,
+      provider,
+      logger,
+    });
+    labelTransitioner.register();
+    order.push('LabelTransitioner');
+  } else {
+    logger?.debug?.(
+      '[lifecycle] buildDefaultListenerChain: skipping LabelTransitioner (no provider)',
+    );
+  }
+
+  // 10. CheckpointPointerWriter — persists `{ lastCompletedSeqId, phase }`
   //    on every `*.end` event.
   const checkpointPointerWriter = new CheckpointPointerWriter({
     bus,
@@ -330,6 +371,7 @@ export async function buildDefaultListenerChain(opts = {}) {
     branchCleaner,
     mergeWatcher,
     cleaner,
+    labelTransitioner,
     checkpointPointerWriter,
     order,
   };

package/.agents/scripts/lib/orchestration/lifecycle/listeners/label-transitioner.js

@@ -0,0 +1,144 @@
+// .agents/scripts/lib/orchestration/lifecycle/listeners/label-transitioner.js
+/**
+ * LabelTransitioner — lifecycle listener that owns the terminal Epic
+ * ticket-state flip: on `epic.complete` it transitions the Epic to
+ * `agent::done` via the canonical `transitionTicketState` API (which
+ * also closes the issue with `state_reason: completed` and mirrors the
+ * Projects-v2 status column).
+ *
+ * Subscribes to:
+ *   - `epic.complete` → and ONLY this event.
+ *
+ * Why this listener exists (regression history): the original
+ * LabelTransitioner lived in the in-process epic-runner stratum and was
+ * deleted with it (Story #3908 / #3936) — but the `lifecycle-emit`
+ * listener chain never re-registered a replacement, so the Epic
+ * `agent::done` flip silently had NO owner. Every docstring in
+ * `cleaner.js` / `branch-cleaner.js` / `merge-watcher.js` that says
+ * "LabelTransitioner flips the Epic ticket to `agent::done` on
+ * epic.complete" referenced a ghost. In practice the flip only happened
+ * when a driving session (or the operator) ran `update-ticket-state.js`
+ * by hand — observed live on 2026-07-11 when Epics #4405 / #4425 /
+ * #4429 merged cleanly (Cleaner archived, `epic.complete` on the
+ * ledger) yet stayed at `agent::executing`. This listener restores the
+ * documented contract on the SOLE production wiring path
+ * (`buildDefaultListenerChain`).
+ *
+ * Side effects executed inside `handle()`:
+ *   1. `transitionTicketState(provider, epicId, STATE_LABELS.DONE)` —
+ *      adds `agent::done`, removes every other `agent::*` label, closes
+ *      the issue as completed (idempotent when the GitHub Closes-#N
+ *      linkage already closed it), syncs the board column, and runs the
+ *      upward cascade (a no-op sweep here: story-close already flipped
+ *      every child Story).
+ *
+ * Failure posture: a failed transition THROWS (per
+ * `rules/orchestration-error-handling.md` — throw, never fatal). The
+ * bus's `onFailed` hook records the failure on the ledger and
+ * `lifecycle-emit`'s `collectOutcomes` → `emitBlockedSignal` path
+ * surfaces it loudly, so a provider outage cannot silently strand the
+ * Epic at `agent::executing` again — the exact failure mode this
+ * listener exists to close.
+ *
+ * Idempotency contract: per-instance `Set<string>` of
+ * `${event}:${seqId}` keys (the standard bus-replay defence). The
+ * transition itself is also idempotent at the provider layer (label
+ * add/remove and a close on an already-closed issue are no-ops), so a
+ * cross-process replay after a crash re-runs the flip harmlessly.
+ *
+ * Side-effect firewall: exactly one provider call per handled event. No
+ * filesystem writes, no follow-up bus emits, no `gh` shell-outs.
+ */
+
+import { STATE_LABELS } from '../../ticketing/reads.js';
+import { transitionTicketState } from '../../ticketing/transition.js';
+
+/**
+ * The single lifecycle event this listener subscribes to. `epic.complete`
+ * is the terminal event of a successful Epic run, emitted by Cleaner
+ * AFTER the MergeWatcher observed a non-null mergeCommit — so the flip
+ * can never fire for an Epic whose PR did not actually merge.
+ */
+export const SUBSCRIBED_EVENT = 'epic.complete';
+
+export class LabelTransitioner {
+  /**
+   * @param {object} opts
+   * @param {object} opts.bus Lifecycle bus exposing `on()`.
+   * @param {number} opts.epicId Epic ticket id.
+   * @param {import('../../../ITicketingProvider.js').ITicketingProvider} opts.provider
+   *   Ticketing provider. Required — the chain builder skips this
+   *   listener entirely when no provider is wired (parity with
+   *   AutomergePredicate's guard), so construction can demand one.
+   * @param {{ info?: Function, warn?: Function, debug?: Function }} [opts.logger]
+   */
+  constructor(opts = {}) {
+    if (!opts.bus || typeof opts.bus.on !== 'function') {
+      throw new TypeError('LabelTransitioner requires a bus with on()');
+    }
+    if (!Number.isInteger(opts.epicId) || opts.epicId < 1) {
+      throw new TypeError('LabelTransitioner requires a numeric epicId');
+    }
+    if (!opts.provider) {
+      // Truthiness-only, parity with AutomergePredicate: the chain
+      // builder's best-effort registration must not explode on a
+      // shape-minimal provider — a malformed one fails loudly at
+      // handle time instead, where the ledger records the outcome.
+      throw new TypeError('LabelTransitioner requires a provider');
+    }
+    this.bus = opts.bus;
+    this.epicId = opts.epicId;
+    this.provider = opts.provider;
+    this.logger = opts.logger ?? console;
+    /** @type {Set<string>} `${event}:${seqId}` idempotency cache. */
+    this._seen = new Set();
+    // Canonical subscription-set shape: the lifecycle doc-drift gate
+    // (`check-lifecycle-doc-drift.js#extractCodeEvents`) and the
+    // event-connectivity contract test both resolve this frozen array
+    // (constant references included) to derive the subscriber table.
+    this.events = Object.freeze([SUBSCRIBED_EVENT]);
+  }
+
+  /**
+   * Register the listener on `epic.complete`. Returns the array of
+   * unsubscribe callbacks the bus produced (parity with the sibling
+   * listeners).
+   */
+  register() {
+    return this.events.map((event) =>
+      this.bus.on(event, async (ctx) => this.handle(ctx)),
+    );
+  }
+
+  /**
+   * Bus listener body. Idempotent on `(event, seqId)`; flips the Epic
+   * to `agent::done` exactly once per observed `epic.complete`.
+   */
+  async handle({ event, seqId }) {
+    const key = `${event}:${seqId}`;
+    if (this._seen.has(key)) {
+      this.logger.debug?.(
+        `[LabelTransitioner] skip duplicate ${key} (idempotent)`,
+      );
+      return;
+    }
+    this._seen.add(key);
+
+    this.logger.info?.(
+      `[LabelTransitioner] epic.complete observed — transitioning Epic #${this.epicId} to ${STATE_LABELS.DONE}.`,
+    );
+    // Throws on failure by design: the ledger records the failed
+    // listener outcome and lifecycle-emit surfaces it (see the failure
+    // posture note in the module docstring). Swallowing here would
+    // recreate the silent agent::executing strand this listener fixes.
+    await transitionTicketState(this.provider, this.epicId, STATE_LABELS.DONE);
+  }
+
+  /**
+   * Test-only — clear the idempotency cache so a single instance can
+   * exercise replay scenarios without re-constructing the listener.
+   */
+  resetSeen() {
+    this._seen.clear();
+  }
+}