mandrel 1.94.0 → 2.1.0

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

@@ -1,378 +0,0 @@
-// .agents/scripts/lib/orchestration/lifecycle/listeners/index.js
-/**
- * Default listener-chain builder for the standalone `lifecycle-emit`
- * CLI surface (Story #2510, Epic #2501).
- *
- * This is the SOLE production wiring path for the close-tail listener
- * roster. (The in-process `epic-runner/factory.js` that previously
- * mirrored this roster for an in-session runner was deleted with the
- * dead epic-runner stratum in Story #3908; the host-LLM-drives-CLIs
- * model reaches every close-tail listener through the `lifecycle-emit.js`
- * CLI shells in `/deliver`'s Phase 6 / 7.5 / 8 markdown invocations,
- * which call this builder.)
- *
- * Canonical roster (registration order):
- *   1. LedgerWriter            (privileged hooks via `register(bus)`)
- *   2. AcceptanceReconciler    (epic.close.end → acceptance.reconcile.*)
- *   3. Finalizer               (acceptance.reconcile.{ok,waived} → pr.created)
- *   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. 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
- * executes, so a crash mid-chain leaves a recoverable trail.
- *
- * Listeners whose constructors require collaborators that are not
- * available outside the runner (e.g. AutomergePredicate's `provider`,
- * BranchCleaner's `checkpointer`) are SKIPPED with a debug log rather
- * than constructed. This matches the factory's defensive guard pattern
- * — registration is best-effort; the chain still wires every listener
- * whose dependencies are satisfiable.
- *
- * Signature: `buildDefaultListenerChain({ bus, ledgerPath, repoRoot })`.
- * The Tech Spec for Epic #2501 (§ Story 4) fixes the public shape at
- * those three keys. `ledgerPath` is decomposed into `tempRoot` and
- * `epicId` so the listener constructors receive what they need;
- * `repoRoot` threads through as `cwd` for listeners that shell out
- * (`Finalizer`, `AutomergeArmer`).
- *
- * Maintainability exemption (refs #3685): this module is listed under
- * `delivery.quality.gates.maintainability.ignoreGlobs` in `.agentrc.json`.
- * Its sole content is a linear, low-branching listener-registration
- * sequence; the maintainability index mis-gauges that shape (the same
- * reason the declarative `config-settings-schema*` files are exempt).
- * Splitting the sequence across sibling builder modules purely to clear
- * the floor would add indirection without making the wiring easier to
- * read, so the debt is carried explicitly here rather than hidden behind
- * a blanket low floor.
- */
-
-import path from 'node:path';
-
-import { createLedgerWriter } from '../ledger-writer.js';
-import { AcceptanceReconciler } from './acceptance-reconciler.js';
-import { AutomergeArmer } from './automerge-armer.js';
-import { AutomergePredicate } from './automerge-predicate.js';
-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';
-
-/**
- * Parse `temp/epic-<id>/lifecycle.ndjson` into `{ tempRoot, epicId }`.
- *
- * Throws when the input does not match the canonical layout. The
- * standalone `lifecycle-emit` CLI is the sole production caller and it
- * always feeds the canonical `epicLedgerPath(eid)` value, so a mismatch
- * here is a programmer error — surface it loudly.
- *
- * @param {string} ledgerPath
- * @returns {{ tempRoot: string, epicId: number }}
- */
-export function parseLedgerPath(ledgerPath) {
-  if (typeof ledgerPath !== 'string' || ledgerPath.length === 0) {
-    throw new TypeError(
-      'buildDefaultListenerChain: ledgerPath must be a non-empty string',
-    );
-  }
-  const epicDir = path.dirname(ledgerPath);
-  const tempRoot = path.dirname(epicDir);
-  const epicDirName = path.basename(epicDir);
-  const m = /^epic-(\d+)$/.exec(epicDirName);
-  if (!m) {
-    throw new Error(
-      `buildDefaultListenerChain: ledgerPath does not match temp/epic-<id>/lifecycle.ndjson layout (got ${ledgerPath})`,
-    );
-  }
-  const epicId = Number.parseInt(m[1], 10);
-  if (!Number.isInteger(epicId) || epicId < 1) {
-    throw new Error(
-      `buildDefaultListenerChain: parsed epicId from ledgerPath is not a positive integer (got ${m[1]})`,
-    );
-  }
-  return { tempRoot, epicId };
-}
-
-/**
- * Build and subscribe the canonical default listener chain onto the
- * supplied bus.
- *
- * @param {object} opts
- * @param {object} opts.bus Lifecycle bus instance (must expose `on`,
- *   `emit`, and the privileged `onEmitted` / `onCompleted` / `onFailed`
- *   hook seam).
- * @param {string} opts.ledgerPath Absolute or repo-relative path to the
- *   Epic's `lifecycle.ndjson`. Decomposed into `{ tempRoot, epicId }`
- *   for downstream constructors.
- * @param {string} opts.repoRoot Absolute path used as `cwd` for
- *   listeners that shell out (Finalizer, AutomergeArmer, BranchCleaner).
- * @param {object} [opts.provider] Ticketing provider. When omitted,
- *   AutomergePredicate is skipped (the listener constructor throws on
- *   a missing provider).
- * @param {object} [opts.config] Resolved agent config. Forwarded to the
- *   AcceptanceReconciler.
- * @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,
- *   acceptanceReconciler: object,
- *   finalizer: object,
- *   automergeArmer: object,
- *   automergePredicate: object|null,
- *   branchCleaner: object|null,
- *   cleaner: object,
- *   checkpointPointerWriter: object,
- *   order: string[]
- * }>}
- */
-export async function buildDefaultListenerChain(opts = {}) {
-  const {
-    bus,
-    ledgerPath,
-    repoRoot,
-    provider = null,
-    config = null,
-    checkpointer = null,
-    logger = console,
-    headless = false,
-  } = opts;
-  if (
-    !bus ||
-    typeof bus.on !== 'function' ||
-    typeof bus.emit !== 'function' ||
-    typeof bus.onEmitted !== 'function'
-  ) {
-    throw new TypeError(
-      'buildDefaultListenerChain: bus must expose on/emit and the privileged onEmitted/onCompleted/onFailed seam',
-    );
-  }
-  if (typeof repoRoot !== 'string' || repoRoot.length === 0) {
-    throw new TypeError(
-      'buildDefaultListenerChain: repoRoot must be a non-empty string',
-    );
-  }
-  const { tempRoot, epicId } = parseLedgerPath(ledgerPath);
-
-  const order = [];
-
-  // 1. LedgerWriter — MUST be first. Uses the privileged hook seam, so
-  // its registration call is `register(bus)` rather than a regular
-  // `bus.on()` subscription. The bus contract guarantees `emitted`
-  // lands on disk before any listener body executes.
-  const ledgerWriter = createLedgerWriter({ epicId, tempRoot });
-  ledgerWriter.register(bus);
-  order.push('LedgerWriter');
-
-  // 2. AcceptanceReconciler — gates Finalize on close-time AC coverage.
-  const acceptanceReconciler = new AcceptanceReconciler({
-    bus,
-    epicId,
-    cwd: repoRoot,
-    provider,
-    config,
-    logger,
-  });
-  acceptanceReconciler.register();
-  order.push('AcceptanceReconciler');
-
-  // 3. Finalizer — opens the PR on acceptance.reconcile.ok or .waived
-  //    (Story #2893 split waiver out of .skipped) via the bus-owned
-  //    default (`composeBusOwnedFinalize`, Story #2894), which chains
-  //    openOrLocatePr → postHandoffComment and
-  //    emits `epic.merge.ready` on success. The legacy
-  //    `d1-default-no-op` blocker is gone; the listener constructed
-  //    with no `runFinalizeFn` override always runs the real flow.
-  //    The code-review / audit-results graduator steps (Stories
-  //    #2555 / #2615) remain best-effort and are silently skipped
-  //    when `provider` / `currentRepo` are not wired in. `currentRepo`
-  //    is resolved from `config.github.{owner,repo}`; `frameworkRepo`
-  //    from `config.github.frameworkRepo` when distinct, otherwise omitted.
-  const currentRepo =
-    config?.github?.owner && config?.github?.repo
-      ? { owner: config.github.owner, repo: config.github.repo }
-      : null;
-  const frameworkRepo =
-    config?.github?.frameworkRepo?.owner && config?.github?.frameworkRepo?.repo
-      ? {
-          owner: config.github.frameworkRepo.owner,
-          repo: config.github.frameworkRepo.repo,
-        }
-      : null;
-  const finalizer = new Finalizer({
-    bus,
-    epicId,
-    cwd: repoRoot,
-    provider,
-    config,
-    currentRepo,
-    frameworkRepo,
-    logger,
-  });
-  finalizer.register();
-  order.push('Finalizer');
-
-  // 4. AutomergeArmer — arms `gh pr merge --auto --squash --delete-branch`
-  //    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();
-  order.push('AutomergeArmer');
-
-  // 5. AutomergePredicate — emits epic.merge.{ready,blocked} based on
-  //    the runtime predicate evaluation. Requires a truthy `provider`;
-  //    skip cleanly when the caller omitted one (lifecycle-emit CLI
-  //    has no provider wired in by default). `config` selects the
-  //    `delivery.ci.autoMerge` posture (trust-ci default vs strict) and
-  //    `cwd` (repoRoot) is where the live `gh pr checks --required`
-  //    probe shells out (Story #4361).
-  let automergePredicate = null;
-  if (provider) {
-    automergePredicate = new AutomergePredicate({
-      bus,
-      epicId,
-      provider,
-      config,
-      cwd: repoRoot,
-      headless,
-      logger,
-    });
-    automergePredicate.register();
-    order.push('AutomergePredicate');
-  } else {
-    logger?.debug?.(
-      '[lifecycle] buildDefaultListenerChain: skipping AutomergePredicate (no provider)',
-    );
-  }
-
-  // 6. BranchCleaner — reaps story/epic branches on epic.cleanup.start.
-  //    Requires a checkpointer exposing `read()`; skip cleanly when
-  //    the caller omitted one.
-  let branchCleaner = null;
-  if (checkpointer && typeof checkpointer.read === 'function') {
-    branchCleaner = new BranchCleaner({
-      bus,
-      epicId,
-      checkpointer,
-      cwd: repoRoot,
-      logger,
-    });
-    branchCleaner.register();
-    order.push('BranchCleaner');
-  } else {
-    logger?.debug?.(
-      '[lifecycle] buildDefaultListenerChain: skipping BranchCleaner (no checkpointer)',
-    );
-  }
-
-  // 7. MergeWatcher (Story #2896, Epic #2880) — polls `gh pr view`
-  //    after `epic.merge.armed` until the PR's mergeCommit is
-  //    non-null, then emits `epic.merge.confirmed`. Cleaner now
-  //    waits on the confirmed event rather than the armed event so
-  //    the Epic only transitions to its terminal state after the
-  //    merge is actually observed on GitHub. Reads `intervalSeconds`
-  //    and `maxBudgetSeconds` from `config.delivery.mergeWatch.*`
-  //    when supplied; otherwise uses the listener's framework
-  //    defaults (30s / 3600s).
-  const mergeWatchConfig = config?.delivery?.mergeWatch ?? {};
-  const mergeWatcher = new MergeWatcher({
-    bus,
-    epicId,
-    tempRoot,
-    cwd: repoRoot,
-    intervalSeconds: mergeWatchConfig.intervalSeconds,
-    maxBudgetSeconds: mergeWatchConfig.maxBudgetSeconds,
-    headless,
-    logger,
-  });
-  mergeWatcher.register();
-  order.push('MergeWatcher');
-
-  // 8. Cleaner — archives temp/epic-<id>/ and emits the terminal
-  //    epic.cleanup.start → .end → epic.complete sequence. Story
-  //    #2896 rebound this listener from `epic.merge.armed` to
-  //    `epic.merge.confirmed`.
-  const cleaner = new Cleaner({
-    bus,
-    epicId,
-    tempRoot,
-    logger,
-  });
-  cleaner.register();
-  order.push('Cleaner');
-
-  // 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,
-    epicId,
-    tempRoot,
-    logger,
-  });
-  checkpointPointerWriter.register();
-  order.push('CheckpointPointerWriter');
-
-  logger?.debug?.(
-    `[lifecycle] buildDefaultListenerChain registered listeners: ${order.join(' → ')}`,
-  );
-
-  return {
-    ledgerWriter,
-    acceptanceReconciler,
-    finalizer,
-    automergeArmer,
-    automergePredicate,
-    branchCleaner,
-    mergeWatcher,
-    cleaner,
-    labelTransitioner,
-    checkpointPointerWriter,
-    order,
-  };
-}

package/.agents/scripts/lib/orchestration/lifecycle/listeners/intervention-recorder.js

@@ -1,140 +0,0 @@
-// .agents/scripts/lib/orchestration/lifecycle/listeners/intervention-recorder.js
-/**
- * InterventionRecorder — lifecycle listener that persists out-of-band
- * manual interventions to the `epic-run-state` structured comment.
- *
- * Subscribes to (per Story #2410 / Task #2416):
- *   - `intervention.recorded` → calls `appendIntervention` on the
- *     `epic-run-state-store` so the `manualInterventions` array on the
- *     epic-run-state checkpoint comment grows by exactly one record.
- *
- * The lifecycle event is the canonical signal that the host LLM has
- * performed an out-of-band recovery (`AskUserQuestion`, manual
- * `git restore`, `--no-ff` recovery merge, `story-close --skipValidation`,
- * etc.). The auto-merge predicate reads the persisted array and only
- * fires when it is empty, so getting one record per emit is load-bearing.
- *
- * Idempotency contract (listeners/README.md): the listener keeps a
- * per-instance `Set<seqId>` of seqIds it has handled. A repeat
- * invocation with the same seqId short-circuits without calling the
- * store. (`epic-run-state-store.appendIntervention` is NOT idempotent
- * on its own — it always appends — so the seqId guard is the only
- * thing standing between a bus replay and a duplicated record.)
- *
- * Side-effect firewall (listeners/README.md):
- *   - MAY read/write the epic-run-state comment via the injected
- *     `provider` (through `epic-run-state-store`).
- *   - MUST NOT `bus.emit()` from inside the handler body — the bus is a
- *     sequential mediator and cannot re-enter safely.
- *   - MUST NOT import any module from
- *     `STATE_MUTATING_MODULES` in `check-lifecycle-lint.js`. The
- *     epic-run-state-store module is NOT on that blocklist; the lint
- *     rule treats it as a safe persistence boundary for listeners.
- */
-
-import { appendIntervention } from '../../epic-run-state-store.js';
-
-export const INTERVENTION_RECORDED_EVENT = 'intervention.recorded';
-
-export class InterventionRecorder {
-  /**
-   * @param {object} opts
-   * @param {object} opts.provider Ticketing provider threaded through to
-   *   `appendIntervention`.
-   * @param {number} opts.epicId Target ticket id (the Epic). Used both
-   *   to scope `appendIntervention` and to filter incoming emits — a
-   *   payload whose `epicId` does not match this listener's Epic is
-   *   ignored (defensive; production wiring only ever emits with the
-   *   listener's own epicId).
-   * @param {{ warn?: Function, debug?: Function }} [opts.logger]
-   * @param {Function} [opts.appendIntervention] Injected store fn —
-   *   defaults to the canonical import. Tests pass a spy.
-   */
-  constructor(opts = {}) {
-    if (!opts.provider) {
-      throw new TypeError('InterventionRecorder requires a provider');
-    }
-    if (!Number.isInteger(opts.epicId) || opts.epicId < 1) {
-      throw new TypeError('InterventionRecorder requires a numeric epicId');
-    }
-    this.provider = opts.provider;
-    this.epicId = opts.epicId;
-    this.logger = opts.logger ?? console;
-    this._appendIntervention =
-      typeof opts.appendIntervention === 'function'
-        ? opts.appendIntervention
-        : appendIntervention;
-    /** @type {Set<number>} seqIds we've already handled. */
-    this._seen = new Set();
-    this.events = Object.freeze([INTERVENTION_RECORDED_EVENT]);
-  }
-
-  /**
-   * Subscribe to `intervention.recorded`. Returns the unsubscribe
-   * handles so tests / teardown can detach without re-binding through
-   * the bus's private registry.
-   */
-  register(bus) {
-    if (!bus || typeof bus.on !== 'function') {
-      throw new TypeError(
-        'InterventionRecorder.register requires a bus with on()',
-      );
-    }
-    return this.events.map((event) =>
-      bus.on(event, async (ctx) => this.handle(ctx)),
-    );
-  }
-
-  /**
-   * Handle one `intervention.recorded` emit. Idempotent on seqId. The
-   * payload has already been schema-validated by the bus, so `reason`
-   * is guaranteed to be a non-empty string and `epicId` a positive
-   * integer.
-   *
-   * @param {{ event: string, seqId: number, payload: { epicId: number, reason: string, source?: string, ts?: string } }} ctx
-   */
-  async handle({ event, seqId, payload }) {
-    if (event !== INTERVENTION_RECORDED_EVENT) return;
-    if (this._seen.has(seqId)) {
-      this.logger.debug?.(
-        `[InterventionRecorder] skip duplicate seqId=${seqId} (idempotent)`,
-      );
-      return;
-    }
-    // Defensive epicId filter — a misrouted emit (e.g., a shared bus in
-    // tests) should not pollute a different Epic's state comment.
-    if (payload?.epicId !== this.epicId) {
-      this.logger.debug?.(
-        `[InterventionRecorder] skip payload.epicId=${payload?.epicId} (listener bound to #${this.epicId})`,
-      );
-      return;
-    }
-    this._seen.add(seqId);
-
-    const entry = {
-      reason: payload.reason,
-    };
-    if (typeof payload.source === 'string' && payload.source.length > 0) {
-      entry.source = payload.source;
-    }
-    if (typeof payload.ts === 'string' && payload.ts.length > 0) {
-      entry.ts = payload.ts;
-    }
-    try {
-      await this._appendIntervention({
-        provider: this.provider,
-        epicId: this.epicId,
-        entry,
-      });
-    } catch (err) {
-      this.logger.warn?.(
-        `[InterventionRecorder] appendIntervention failed for seqId=${seqId}: ${err?.message ?? err}`,
-      );
-      throw err;
-    }
-  }
-
-  resetSeen() {
-    this._seen.clear();
-  }
-}

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

@@ -1,144 +0,0 @@
-// .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();
-  }
-}