mandrel 1.94.0 → 2.1.0

package/.agents/scripts/lib/orchestration/lifecycle/emit-ledger-event.js

@@ -0,0 +1,142 @@
+/**
+ * emit-ledger-event.js — shared validate-and-append core for the
+ * merge-terminal lifecycle emitters (Story #4539).
+ *
+ * `emit-merge-unlanded.js` and `emit-merge-flip-failed.js` report the two
+ * terminal outcomes a landing attempt can reach without ending at
+ * `agent::done`. They share everything except their schema and their
+ * payload's meaning, so the Ajv compile/cache, the scope→ledger routing,
+ * and the NDJSON append live here once rather than being copy-pasted.
+ *
+ * Like its callers, this is a bare `appendFileSync` rather than a bus
+ * publish: these events fire from the `single-story-close` flow, which has
+ * no bus at all, so a direct append keeps the call site dependency-free.
+ */
+
+import { appendFileSync, mkdirSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import Ajv2020 from 'ajv/dist/2020.js';
+import addFormats from 'ajv-formats';
+
+import { storyLedgerPath } from '../../config/temp-paths.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const SCHEMA_DIR = path.resolve(
+  __dirname,
+  '..',
+  '..',
+  '..',
+  '..',
+  'schemas',
+  'lifecycle',
+);
+
+/**
+ * The scopes a merge-terminal event may be WRITTEN with. v2.0.0 removed the
+ * Epic tier, so `'story'` is the only emittable scope.
+ *
+ * Note the deliberate asymmetry with the `merge.unlanded` /
+ * `merge.flip-failed` schema enums, which still accept `'epic'`: archived
+ * ledger records carry `scope: 'epic'` and the schemas must keep validating
+ * them on read. The value stays READABLE; only the writer path is gone —
+ * the same split `merge-block-class.js` keeps for `predicate-refused`.
+ */
+const VALID_SCOPES = new Set(['story']);
+
+/** @type {Map<string, Function>} */
+const _validators = new Map();
+
+/**
+ * Compile (once) and return the validator for a lifecycle schema file.
+ *
+ * @param {string} schemaFile Basename under `.agents/schemas/lifecycle/`.
+ * @returns {Function}
+ */
+function getValidator(schemaFile) {
+  const cached = _validators.get(schemaFile);
+  if (cached) return cached;
+  const schema = JSON.parse(
+    readFileSync(path.resolve(SCHEMA_DIR, schemaFile), 'utf8'),
+  );
+  const ajv = new Ajv2020({ allErrors: true, strict: false });
+  addFormats(ajv);
+  const validator = ajv.compile(schema);
+  _validators.set(schemaFile, validator);
+  return validator;
+}
+
+/**
+ * Assert the fields every merge-terminal event shares. Throws with the
+ * caller's own emitter name so the message stays attributable.
+ *
+ * @param {string} emitter
+ * @param {{ scope: string, ticketId: number, prNumber: number, reason: string, elapsedSeconds: number }} fields
+ */
+export function assertMergeTerminalFields(
+  emitter,
+  { scope, ticketId, prNumber, reason, elapsedSeconds },
+) {
+  if (!VALID_SCOPES.has(scope)) {
+    throw new Error(
+      `${emitter}: scope "${scope}" must be one of: ${[...VALID_SCOPES].join(', ')}`,
+    );
+  }
+  if (!Number.isInteger(ticketId) || ticketId < 1) {
+    throw new Error(`${emitter}: ticketId must be a positive integer`);
+  }
+  if (!Number.isInteger(prNumber) || prNumber < 1) {
+    throw new Error(`${emitter}: prNumber must be a positive integer`);
+  }
+  if (typeof reason !== 'string' || reason.length === 0) {
+    throw new Error(`${emitter}: reason must be a non-empty string`);
+  }
+  if (typeof elapsedSeconds !== 'number' || elapsedSeconds < 0) {
+    throw new Error(`${emitter}: elapsedSeconds must be a non-negative number`);
+  }
+}
+
+/**
+ * Validate a payload against its lifecycle schema and append exactly one
+ * NDJSON record to the scope-resolved ledger.
+ *
+ * @param {object} args
+ * @param {string} args.emitter       Caller name, for error attribution.
+ * @param {string} args.schemaFile    Basename under `schemas/lifecycle/`.
+ * @param {object} args.payload       The event payload (already assembled).
+ * @param {number} args.ticketId
+ * @param {string} args.timestamp
+ * @param {object} [args.config]
+ * @param {string} [args.ledgerPath]  Override for tests / non-default layouts.
+ * @returns {{ ledgerPath: string, record: object }}
+ */
+export function appendLedgerEvent({
+  emitter,
+  schemaFile,
+  payload,
+  ticketId,
+  timestamp,
+  config,
+  ledgerPath: ledgerPathOverride,
+}) {
+  const validator = getValidator(schemaFile);
+  if (!validator(payload)) {
+    const detail = (validator.errors ?? [])
+      .map((e) => `${e.instancePath || '/'} ${e.message}`)
+      .join('; ');
+    throw new Error(`${emitter}: payload failed schema validation: ${detail}`);
+  }
+
+  const ledgerPath =
+    ledgerPathOverride ?? storyLedgerPath(null, ticketId, config);
+  mkdirSync(path.dirname(ledgerPath), { recursive: true });
+  const record = {
+    kind: 'emitted',
+    ts: timestamp,
+    event: payload.event,
+    payload,
+  };
+  appendFileSync(ledgerPath, `${JSON.stringify(record)}\n`, 'utf8');
+  return { ledgerPath, record };
+}

package/.agents/scripts/lib/orchestration/lifecycle/emit-loop-tick.js

@@ -9,14 +9,12 @@
  * appends an inspectable `emitted` line a reconciler can read for
  * forward-progress evidence.
  *
- * Distinct from `story.heartbeat` (emit-story-heartbeat.js): the
- * heartbeat carries Story-phase info for a single in-flight Story and is
- * always Epic-scoped (its ledger path is `epicLedgerPath(epicId)`). A
- * host loop is not bound to a Story tier, so `loop.tick` carries a
+ * A host loop is not bound to a Story tier, so `loop.tick` carries a
  * free-form `loopName`, a monotonic `round` counter, the loop's
- * configured `cadence` label, and a per-round `status` instead. Keeping
- * the two events separate means a loop tick never masquerades as Story
- * progress (and vice versa).
+ * configured `cadence` label, and a per-round `status`. It is now the only
+ * forward-progress beat: the Story-scoped `story.heartbeat` it was once
+ * contrasted against was Epic-scoped by construction, could never fire under
+ * v2 (which has no Epics), and was deleted (A22).
  *
  * Bus path (Story acceptance: "Emitting a loop.tick event THROUGH the
  * lifecycle bus appends a record to the per-run ledger"): this helper
@@ -39,15 +37,15 @@
  * Ledger path resolution: a caller supplies EITHER an explicit
  * `ledgerPath` (the host-loop case — the loop owns where its ledger
  * lives) OR an `epicId`, in which case the canonical
- * `epicLedgerPath(epicId)` is used so an Epic-scoped loop's ticks land
- * in the same `temp/epic-<id>/lifecycle.ndjson` the rest of the run
+ * `runLedgerPath(epicId)` is used so an Epic-scoped loop's ticks land
+ * in the same `temp/run-<id>/lifecycle.ndjson` the rest of the run
  * reads. Exactly one of the two MUST be supplied.
  */
 
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
-import { epicLedgerPath } from '../../config/temp-paths.js';
+import { runLedgerPath } from '../../config/temp-paths.js';
 import { createBus } from './bus.js';
 import { createLedgerWriter } from './ledger-writer.js';
 
@@ -65,8 +63,8 @@ const SCHEMA_DIR = path.resolve(
 const VALID_STATUSES = new Set(['running', 'done', 'blocked']);
 
 /**
- * Parse `temp/epic-<id>/lifecycle.ndjson` (or any
- * `<dir>/epic-<id>/lifecycle.ndjson`) back into `{ tempRoot, epicId }`
+ * Parse `temp/run-<id>/lifecycle.ndjson` (or any
+ * `<dir>/run-<id>/lifecycle.ndjson`) back into `{ tempRoot, epicId }`
  * so a LedgerWriter — which is constructed from `{ epicId, tempRoot }`
  * rather than a raw path — can be bound to the supplied ledger path.
  *
@@ -79,13 +77,13 @@ const VALID_STATUSES = new Set(['running', 'done', 'blocked']);
  * @returns {{ tempRoot: string, epicId: number }}
  */
 function decomposeLedgerPath(ledgerPath) {
-  const epicDir = path.dirname(ledgerPath);
-  const tempRoot = path.dirname(epicDir);
-  const epicDirName = path.basename(epicDir);
-  const m = /^epic-(\d+)$/.exec(epicDirName);
+  const runDir = path.dirname(ledgerPath);
+  const tempRoot = path.dirname(runDir);
+  const runDirName = path.basename(runDir);
+  const m = /^run-(\d+)$/.exec(runDirName);
   if (!m) {
     throw new Error(
-      `emitLoopTick: ledgerPath does not match <tempRoot>/epic-<id>/lifecycle.ndjson layout (got ${ledgerPath})`,
+      `emitLoopTick: ledgerPath does not match <tempRoot>/run-<id>/lifecycle.ndjson layout (got ${ledgerPath})`,
     );
   }
   const epicId = Number.parseInt(m[1], 10);
@@ -104,7 +102,7 @@ function decomposeLedgerPath(ledgerPath) {
  *                                   One of running|done|blocked.
  * @param {string} [opts.timestamp]  ISO-8601 wall clock. Defaults to now().
  * @param {number} [opts.epicId]     When supplied (and no `ledgerPath`),
- *                                   the canonical `epicLedgerPath(epicId)`
+ *                                   the canonical `runLedgerPath(epicId)`
  *                                   is used for the ledger.
  * @param {object} [opts.config]     Optional resolved config for tempRoot
  *                                   (only consulted on the `epicId` path).
@@ -158,7 +156,7 @@ export async function emitLoopTick(opts) {
     if (!Number.isInteger(epicId) || epicId < 1) {
       throw new Error('emitLoopTick: epicId must be a positive integer');
     }
-    ledgerPath = epicLedgerPath(epicId, config);
+    ledgerPath = runLedgerPath(epicId, config);
   }
 
   const payload = {

package/.agents/scripts/lib/orchestration/lifecycle/emit-merge-flip-failed.js

@@ -0,0 +1,86 @@
+/**
+ * emit-merge-flip-failed.js — Story #4539.
+ *
+ * Appends a single `merge.flip-failed` NDJSON record when a delivery run
+ * observed a **confirmed merge** but the `agent::closing → agent::done`
+ * label write itself failed.
+ *
+ * Why this is not `merge.unlanded`: the merge landed. Reporting it as
+ * unlanded points the operator at branch protection, required checks, and
+ * poll budgets — none of which are the fault — while the real remedy is a
+ * re-run of `single-story-confirm-merge.js`, which is idempotent and flips
+ * the label from the already-merged PR. The two events are deliberately
+ * distinct so the ledger attributes a label-write API failure differently
+ * from a merge that never happened.
+ *
+ * The Story is still transitioned to `agent::blocked` by the caller: a
+ * merged PR whose Story sits at `agent::closing` is exactly the silent
+ * strand the must-land contract exists to prevent, so it terminates
+ * explicitly — but it terminates with the truth.
+ */
+
+import {
+  appendLedgerEvent,
+  assertMergeTerminalFields,
+} from './emit-ledger-event.js';
+
+/**
+ * The only block class this event carries. Distinct from every
+ * `merge.unlanded` attribution (`MERGE_UNLANDED_BLOCK_CLASSES`) because the
+ * merge is not in question here — only the label write is.
+ */
+export const MERGED_FLIP_FAILED_BLOCK_CLASS = 'merged-flip-failed';
+
+/**
+ * Append exactly one `merge.flip-failed` record to the resolved ledger.
+ *
+ * @param {object} opts
+ * @param {'story'} opts.scope
+ * @param {number} opts.ticketId       The storyId.
+ * @param {number} opts.prNumber       The PR that merged.
+ * @param {string} opts.reason         What failed on the label write.
+ * @param {number} opts.elapsedSeconds Elapsed poll time when the flip failed.
+ * @param {string} [opts.timestamp]
+ * @param {object} [opts.config]
+ * @param {string} [opts.ledgerPath]
+ * @returns {{ ledgerPath: string, record: object }}
+ */
+export function emitMergeFlipFailed(opts) {
+  const {
+    scope,
+    ticketId,
+    prNumber,
+    reason,
+    elapsedSeconds,
+    timestamp = new Date().toISOString(),
+    config,
+    ledgerPath,
+  } = opts ?? {};
+
+  assertMergeTerminalFields('emitMergeFlipFailed', {
+    scope,
+    ticketId,
+    prNumber,
+    reason,
+    elapsedSeconds,
+  });
+
+  return appendLedgerEvent({
+    emitter: 'emitMergeFlipFailed',
+    schemaFile: 'merge.flip-failed.schema.json',
+    payload: {
+      event: 'merge.flip-failed',
+      scope,
+      ticketId,
+      prNumber,
+      blockClass: MERGED_FLIP_FAILED_BLOCK_CLASS,
+      reason,
+      elapsedSeconds,
+      timestamp,
+    },
+    ticketId,
+    timestamp,
+    config,
+    ledgerPath,
+  });
+}

package/.agents/scripts/lib/orchestration/lifecycle/emit-merge-unlanded.js

@@ -6,23 +6,16 @@
  * finishes its work without a confirmed merge. Pattern mirrors
  * `emit-story-heartbeat.js`: direct schema validation via Ajv followed by
  * a synchronous `appendFileSync` — this event is NOT routed through the
- * bus (unlike `emit-loop-tick.js`) because it can fire from either the
- * epic-path finalize flow (which already owns an Epic-scoped bus
- * instance for its own run) or the standalone `single-story-close` flow,
- * which has no bus at all. A bare append keeps both call sites simple
- * and dependency-free.
+ * bus (unlike `emit-loop-tick.js`) because it fires from the standalone
+ * `single-story-close` flow, which has no bus at all. A bare append keeps
+ * the call site simple and dependency-free.
  *
- * Ledger destination is scope-driven (Story #4426 AC4):
- *   - `scope: 'epic'`  → `epicLedgerPath(ticketId)` — the same
- *     `temp/epic-<id>/lifecycle.ndjson` every other Epic-scoped event
- *     lands in. `ticketId` is the epicId.
- *   - `scope: 'story'` → `storyLedgerPath(null, ticketId)` — the
- *     standalone story-scope destination
- *     `temp/standalone/stories/story-<id>/lifecycle.ndjson`. `ticketId`
- *     is the storyId. The standalone `single-story-close` path has no
- *     parent Epic to anchor a `temp/epic-<id>/` directory to, mirroring
- *     the `eid === null` standalone convention `signalsFile` already
- *     uses for Story-level signals.
+ * Ledger destination (Story #4426 AC4): `storyLedgerPath(null, ticketId)`
+ * — the standalone story-scope destination
+ * `temp/standalone/stories/story-<id>/lifecycle.ndjson`, where `ticketId`
+ * is the storyId. The `single-story-close` path has no parent Epic to
+ * anchor a run directory to, mirroring the `eid === null` standalone
+ * convention `signalsFile` already uses for Story-level signals.
  *
  * A caller may always override the destination via `ledgerPath` (tests,
  * or a future caller with a non-default temp layout).
@@ -57,50 +50,20 @@
  * `predicate-refused` / a classified arm failure directly.
  */
 
-import { appendFileSync, mkdirSync, readFileSync } from 'node:fs';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-import Ajv2020 from 'ajv/dist/2020.js';
-import addFormats from 'ajv-formats';
-
-import { epicLedgerPath, storyLedgerPath } from '../../config/temp-paths.js';
 import { isValidBlockClass } from '../merge-block-class.js';
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const SCHEMA_PATH = path.resolve(
-  __dirname,
-  '..',
-  '..',
-  '..',
-  '..',
-  'schemas',
-  'lifecycle',
-  'merge.unlanded.schema.json',
-);
-
-const VALID_SCOPES = new Set(['epic', 'story']);
-
-let _validator;
-
-function getValidator() {
-  if (_validator) return _validator;
-  const schema = JSON.parse(readFileSync(SCHEMA_PATH, 'utf8'));
-  const ajv = new Ajv2020({ allErrors: true, strict: false });
-  addFormats(ajv);
-  _validator = ajv.compile(schema);
-  return _validator;
-}
+import {
+  appendLedgerEvent,
+  assertMergeTerminalFields,
+} from './emit-ledger-event.js';
 
 /**
  * Append exactly one `merge.unlanded` NDJSON record to the resolved
  * lifecycle ledger.
  *
  * @param {object} opts
- * @param {'epic'|'story'} opts.scope  Which delivery path is reporting the
+ * @param {'story'} opts.scope         Which delivery path is reporting the
  *                                     unlanded merge.
- * @param {number} opts.ticketId       epicId when `scope === 'epic'`,
- *                                     storyId when `scope === 'story'`.
+ * @param {number} opts.ticketId       The storyId.
  * @param {number} opts.prNumber       The PR number that did not land.
  * @param {string} opts.blockClass     A valid `merge.unlanded` attribution
  *                                     (`MERGE_UNLANDED_BLOCK_CLASSES` in
@@ -130,64 +93,35 @@ export function emitMergeUnlanded(opts) {
     ledgerPath: ledgerPathOverride,
   } = opts ?? {};
 
-  if (!VALID_SCOPES.has(scope)) {
-    throw new Error(
-      `emitMergeUnlanded: scope "${scope}" must be one of: ${[...VALID_SCOPES].join(', ')}`,
-    );
-  }
-  if (!Number.isInteger(ticketId) || ticketId < 1) {
-    throw new Error('emitMergeUnlanded: ticketId must be a positive integer');
-  }
-  if (!Number.isInteger(prNumber) || prNumber < 1) {
-    throw new Error('emitMergeUnlanded: prNumber must be a positive integer');
-  }
-  if (!isValidBlockClass(blockClass)) {
-    throw new Error(
-      `emitMergeUnlanded: blockClass "${blockClass}" is not a recognised merge-block-class value`,
-    );
-  }
-  if (typeof reason !== 'string' || reason.length === 0) {
-    throw new Error('emitMergeUnlanded: reason must be a non-empty string');
-  }
-  if (typeof elapsedSeconds !== 'number' || elapsedSeconds < 0) {
-    throw new Error(
-      'emitMergeUnlanded: elapsedSeconds must be a non-negative number',
-    );
-  }
-
-  const payload = {
-    event: 'merge.unlanded',
+  assertMergeTerminalFields('emitMergeUnlanded', {
     scope,
     ticketId,
     prNumber,
-    blockClass,
     reason,
     elapsedSeconds,
-    timestamp,
-  };
-
-  const validator = getValidator();
-  if (!validator(payload)) {
-    const detail = (validator.errors ?? [])
-      .map((e) => `${e.instancePath || '/'} ${e.message}`)
-      .join('; ');
+  });
+  if (!isValidBlockClass(blockClass)) {
     throw new Error(
-      `emitMergeUnlanded: payload failed schema validation: ${detail}`,
+      `emitMergeUnlanded: blockClass "${blockClass}" is not a recognised merge-block-class value`,
     );
   }
 
-  const ledgerPath =
-    ledgerPathOverride ??
-    (scope === 'epic'
-      ? epicLedgerPath(ticketId, config)
-      : storyLedgerPath(null, ticketId, config));
-  mkdirSync(path.dirname(ledgerPath), { recursive: true });
-  const record = {
-    kind: 'emitted',
-    ts: timestamp,
-    event: 'merge.unlanded',
-    payload,
-  };
-  appendFileSync(ledgerPath, `${JSON.stringify(record)}\n`, 'utf8');
-  return { ledgerPath, record };
+  return appendLedgerEvent({
+    emitter: 'emitMergeUnlanded',
+    schemaFile: 'merge.unlanded.schema.json',
+    payload: {
+      event: 'merge.unlanded',
+      scope,
+      ticketId,
+      prNumber,
+      blockClass,
+      reason,
+      elapsedSeconds,
+      timestamp,
+    },
+    ticketId,
+    timestamp,
+    config,
+    ledgerPath: ledgerPathOverride,
+  });
 }

package/.agents/scripts/lib/orchestration/lifecycle/ledger-writer.js

@@ -25,6 +25,7 @@
 
 import { appendFileSync, mkdirSync } from 'node:fs';
 import path from 'node:path';
+import { runTempDir } from '../../config/temp-paths.js';
 
 /**
  * Static deny-list pulled from the Tech Spec § Security & Privacy. Keys
@@ -85,7 +86,7 @@ export class LedgerWriter {
    * @param {object} opts
    * @param {number} opts.epicId
    * @param {string} opts.tempRoot - absolute or repo-relative path; the
-   *   writer resolves `temp/epic-<id>/lifecycle.ndjson` underneath.
+   *   writer resolves `temp/run-<id>/lifecycle.ndjson` underneath.
    * @param {() => number} [opts.now] - injectable clock for tests.
    */
   constructor(opts) {
@@ -101,7 +102,9 @@ export class LedgerWriter {
     }
     this._epicId = opts.epicId;
     this._tempRoot = opts.tempRoot;
-    this._epicDir = path.join(this._tempRoot, `epic-${this._epicId}`);
+    this._epicDir = runTempDir(this._epicId, {
+      project: { paths: { tempRoot: this._tempRoot } },
+    });
     this._ledgerPath = path.join(this._epicDir, 'lifecycle.ndjson');
     this._now = typeof opts.now === 'function' ? opts.now : Date.now;
   }
@@ -127,7 +130,7 @@ export class LedgerWriter {
    * The naive optimization (cache "ensured" after the first call) is
    * unsound when a listener moves the ledger directory mid-handler —
    * which is exactly what the Cleaner does on Wave 8 (Story #2259):
-   * it renames `temp/epic-<id>/` under `archive/` between the listener
+   * it renames `temp/run-<id>/` under `archive/` between the listener
    * body and the bus's `onCompleted` hook fire-time, and the next
    * append (the `completed` record for the outer event) would land
    * in a vanished directory. `mkdirSync({recursive: true})` is

package/.agents/scripts/lib/orchestration/lifecycle/listeners/README.md

@@ -1,45 +1,27 @@
 # Lifecycle Listeners
 
 Each listener in this directory subscribes to one or more lifecycle bus
-events and performs a single side effect. The canonical close-tail roster
-— in registration order — is wired by
-[`index.js`](./index.js) (`buildDefaultListenerChain`), the production
-entrypoint the standalone `lifecycle-emit.js` CLI shells in for
-`/deliver`'s Phase 6 / 7.5 / 8 / 8.5 markdown invocations:
+events and performs a single side effect. The full close-tail roster and
+event taxonomy live in [`docs/LIFECYCLE.md`](../../../../../../docs/LIFECYCLE.md)
+— that document is the SSOT. This README only indexes the **files that still
+live in this folder**.
 
-- `ledger-writer.js` — privileged `onEmitted` hook that lands every
-  `emitted` record on disk before any listener body runs (MUST be first).
-- `acceptance-reconciler.js` — gates Finalize on close-time acceptance
-  coverage (`epic.close.end → acceptance.reconcile.*`).
-- `finalizer.js` — opens the PR on `acceptance.reconcile.{ok,waived}` and
-  emits `epic.merge.ready`.
-- `automerge-armer.js` — arms `gh pr merge --auto --squash --delete-branch`
-  on `epic.merge.ready`.
-- `automerge-predicate.js` — evaluates the clean-sprint predicate and
-  emits `epic.merge.{ready,blocked}`.
-- `branch-cleaner.js` — reaps story/epic branches on `epic.cleanup.start`.
-- `merge-watcher.js` — polls `gh pr view` after `epic.merge.armed` until
-  the PR's `mergeCommit` is observed, then emits `epic.merge.confirmed`.
-- `cleaner.js` — archives `temp/epic-<id>/` and emits the terminal
-  `epic.cleanup.* → epic.complete` sequence on `epic.merge.confirmed`.
-- `label-transitioner.js` — flips the Epic ticket to `agent::done` (and
-  closes it as completed, idempotently) on `epic.complete`. Skipped when
-  no provider is wired. Re-homed onto this chain after the 2026-07-11
-  incident (merged Epics stranding at `agent::executing`): the original
-  LabelTransitioner died with the in-process runner stratum (#3936) and
-  the flip had no owner.
-- `checkpoint-pointer-writer.js` — persists `{ lastCompletedSeqId, phase }`
-  on every `*.end` event.
+## Files here
 
-Two further listeners are activated outside the close-tail chain by their
-own CLI entrypoints rather than `buildDefaultListenerChain`:
+- [`watcher.js`](./watcher.js) — the CI-poll loop (`watchPrToTerminal`)
+  driven by `pr-watch-with-update.js`.
 
-- `notify-dispatcher.js` — fans out the curated webhook event subset
-  (driven by `notify.js`).
-- `intervention-recorder.js` — appends operator-intervention payloads to
-  the epic-run-state (driven by `epic-deliver-note-intervention.js`).
-- `watcher.js` — the CI-poll loop (`watchPrToTerminal`) driven by
-  `pr-watch-with-update.js`.
+`merge-watcher.js` was deleted in Story #4545: the Epic-era `MergeWatcher`
+listener had no production caller after the v2.0.0 Story-only cutover. The
+poll defaults and `deriveChecksStatus` the live close path did import from it
+now live in
+[`lib/orchestration/merge-poll.js`](../../merge-poll.js), a home the close
+path owns.
+
+Other close-tail side effects (ledger write, finalize/PR open, automerge
+arm, branch cleanup, label transition) are owned by the Story delivery
+path (`helpers/deliver-story` / `single-story-close.js`) rather than a
+`buildDefaultListenerChain` factory in this directory.
 
 ## Idempotency contract
 
@@ -50,10 +32,6 @@ canonical pattern is a per-instance `Set<seqId>` checked at the top of
 the listener body; the second invocation returns early without mutating
 external state.
 
-The seqId guard is the only correctness requirement we surface from the
-bus contract — downstream idempotency primitives (label-state diff,
-marker-keyed upsert, NDJSON dedupe by seqId) layer on top of it.
-
 ## Side-effect firewall
 
 Listeners MAY:
@@ -61,13 +39,13 @@ Listeners MAY:
 - read tickets via the injected `provider`,
 - write tickets via the injected `transitionTicketState`,
 - upsert structured comments via the injected `upsertStructuredComment`,
-- append to per-Epic ledger / signals files under `tempRoot`.
+- append to per-run ledger / signals files under `tempRoot`.
 
 Listeners MUST NOT:
 
 - `bus.emit()` from inside a listener body (sequential mediator
-  contract — the bus cannot re-entry safely),
-- import the runner state directly,
+  contract — the bus cannot re-enter safely),
+- import runner state directly,
 - mutate cross-cutting globals.
 
 Trace observers (`bus.on('*', fn)`) live under