mandrel 2.0.0 → 2.2.0

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/listeners/README.md

@@ -8,12 +8,16 @@ live in this folder**.
 
 ## Files here
 
-- [`merge-watcher.js`](./merge-watcher.js) — polls `gh pr view` after
-  auto-merge is armed until the PR's `mergeCommit` is observed, then emits
-  the merge-confirmed event.
 - [`watcher.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

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

@@ -5,10 +5,9 @@
  *
  * Subscribes to:
  *   - `pr.created` → resolve the required-check names from GitHub at
- *     runtime via `gh pr checks <pr> --required`, emit
- *     `epic.watch.start` carrying that list, poll until every check
- *     reaches a terminal state (or a per-listener wall-clock deadline
- *     expires), then emit `epic.watch.end` with the outcome map.
+ *     runtime via `gh pr checks <pr> --required`, then poll until every
+ *     check reaches a terminal state (or a per-listener wall-clock
+ *     deadline expires), recording the outcome in `classifications`.
  *
  * Critical contract:
  *   - Required-check **names** are resolved from `gh pr checks` at
@@ -28,11 +27,13 @@
  * re-runs the poll loop (which is itself idempotent: the outcome map
  * always reflects the live GitHub state).
  *
- * Side-effect firewall: the listener emits on the bus and shells out
- * to `gh`. It does NOT mutate ticket labels, post comments, or call
- * `notify` — those listeners receive `epic.watch.end` (via the
- * downstream AutomergePredicate → epic.merge.ready/blocked chain) and
- * own their own side effects.
+ * Side-effect firewall: the listener shells out to `gh` and records
+ * its outcome in the in-memory `classifications` log. It does NOT
+ * mutate ticket labels, post comments, call `notify`, or emit on the
+ * bus — the production consumer (`pr-watch-with-update.js`) drives
+ * `watchPrToTerminal` directly without a bus, and the retired
+ * `epic.watch.start` / `epic.watch.end` bus events went with the
+ * Epic-orchestration stratum.
  */
 
 import { spawnSync } from 'node:child_process';
@@ -40,20 +41,20 @@ import { spawnSync } from 'node:child_process';
 import { parsePrNumberFromUrl } from '../../../github-url.js';
 
 /**
- * Map `gh pr checks` `state` values to the canonical outcome enum on
- * the `epic.watch.end` schema, with a fourth `'pending'` sentinel for
- * in-flight checks. Pure — exported for tests so the pin is explicit
- * and reviewable.
+ * Map `gh pr checks` `state` values to the canonical lowercase outcome
+ * vocabulary (`success` | `failure` | `timed_out` | `skipped`), with a
+ * fourth `'pending'` sentinel for in-flight checks. Pure — exported for
+ * tests so the pin is explicit and reviewable.
  *
  * `gh` returns capitalized SCREAMING_SNAKE values (`SUCCESS`,
- * `FAILURE`, `TIMED_OUT`, etc.); the schema enum is lowercase. An
- * empty / queued / in_progress state collapses to `'pending'` so the
- * poll loop can distinguish "still running" from terminal outcomes.
- * `'pending'` is intentionally NOT in the schema enum — `reduceOutcomes`
- * is called only on the live state, and the final emit gates on
- * `allTerminal()` so no `'pending'` ever leaks into `epic.watch.end`.
- * Unknown / non-pending unrecognized values collapse to `'skipped'`
- * so any future GitHub state we haven't enumerated still validates.
+ * `FAILURE`, `TIMED_OUT`, etc.). An empty / queued / in_progress state
+ * collapses to `'pending'` so the poll loop can distinguish "still
+ * running" from terminal outcomes. `'pending'` is intentionally NOT a
+ * terminal outcome — `reduceOutcomes` is called only on the live state,
+ * and the final outcome map gates on `allTerminal()` so no `'pending'`
+ * ever leaks into a finished watch. Unknown / non-pending unrecognized
+ * values collapse to `'skipped'` so any future GitHub state we haven't
+ * enumerated still maps into the vocabulary.
  */
 /**
  * The raw check-state tokens `normalizeCheckState` recognizes (lowercased).
@@ -264,8 +265,8 @@ export function parseGhPrChecks(stdout) {
 }
 
 /**
- * Reduce a list of check entries to the `{ checkName: outcome }` map
- * the `epic.watch.end` schema expects. Pure — exported for tests.
+ * Reduce a list of check entries to the canonical `{ checkName: outcome }`
+ * map. Pure — exported for tests.
  *
  * When `gh` returns the same `name` more than once (parallel matrix
  * builds, retries), the LAST entry wins. The poll loop calls this on
@@ -431,9 +432,9 @@ export async function pollUntilTerminal({
  * @param {{status:number,stdout:string,stderr:string}} [opts.firstProbe]
  *   Optional already-issued `gh pr checks` result. When the caller (the
  *   `Watcher` listener) has already probed once to resolve the required
- *   names for `epic.watch.start`, it threads that result here so the
- *   loop does not double-spend the first `gh pr checks` call. Omit it
- *   (the CLI path) and the loop issues the first probe itself.
+ *   check names, it threads that result here so the loop does not
+ *   double-spend the first `gh pr checks` call. Omit it (the CLI path)
+ *   and the loop issues the first probe itself.
  * @returns {Promise<{
  *   outcomes: object,
  *   requiredChecks: string[],
@@ -466,8 +467,8 @@ export async function watchPrToTerminal({
   firstProbe,
 }) {
   // First probe: resolve the required-check name set at runtime. Reuse a
-  // caller-supplied probe (the listener already issued one for
-  // `epic.watch.start`) so we never double-spend the first `gh` call.
+  // caller-supplied probe (the listener already issued one to resolve the
+  // required check names) so we never double-spend the first `gh` call.
   const first = firstProbe ?? ghPrChecksFn({ prUrl, cwd });
   // `gh` exits 8 when checks are still pending; this is expected and
   // does not indicate failure. Any other non-zero status with no
@@ -619,12 +620,8 @@ export class Watcher {
    * @param {{ info?: Function, warn?: Function, debug?: Function }} [opts.logger]
    */
   constructor(opts = {}) {
-    if (
-      !opts.bus ||
-      typeof opts.bus.on !== 'function' ||
-      typeof opts.bus.emit !== 'function'
-    ) {
-      throw new TypeError('Watcher requires a bus with on() and emit()');
+    if (!opts.bus || typeof opts.bus.on !== 'function') {
+      throw new TypeError('Watcher requires a bus with on()');
     }
     this.bus = opts.bus;
     this.cwd = opts.cwd ?? process.cwd();
@@ -688,11 +685,10 @@ export class Watcher {
       return;
     }
 
-    // First probe: resolve the required-check name set at runtime, so we
-    // can carry the list on `epic.watch.start` BEFORE the (potentially
-    // long) poll loop runs. We thread this probe into `watchPrToTerminal`
-    // (via `firstProbe`) so the shared loop reuses it instead of
-    // double-spending the first `gh pr checks` call.
+    // First probe: resolve the required-check name set at runtime BEFORE
+    // the (potentially long) poll loop runs. We thread this probe into
+    // `watchPrToTerminal` (via `firstProbe`) so the shared loop reuses it
+    // instead of double-spending the first `gh pr checks` call.
     const first = this.ghPrChecksFn({ prUrl, cwd: this.cwd });
     const firstEntries = parseGhPrChecks(first.stdout);
     if (firstEntries.length === 0 && first.status !== 0 && first.status !== 8) {
@@ -710,45 +706,24 @@ export class Watcher {
 
     const requiredChecks = firstEntries.map((e) => e.name);
 
-    try {
-      await this.bus.emit('epic.watch.start', { prUrl, requiredChecks });
-    } catch (err) {
-      this.classifications.push({
-        event,
-        seqId,
-        outcome: 'failed',
-        reason: `start-emit-failed:${err?.message ?? err}`,
-      });
-      this.logger.warn?.(
-        `[Watcher] epic.watch.start emit failed: ${err?.message ?? err}`,
-      );
-      return;
-    }
-
     // Delegate the poll + BEHIND-recovery loop to the shared plain
     // primitive so the CLI (`pr-watch-with-update.js`) and this listener
     // run identical logic.
-    const {
-      outcomes: emitOutcomes,
-      polls,
-      updatesApplied,
-      resumesApplied,
-      terminal,
-      stillRunning,
-    } = await watchPrToTerminal({
-      prUrl,
-      cwd: this.cwd,
-      maxPolls: this.maxPolls,
-      maxUpdates: this.maxUpdates,
-      maxResumes: this.maxResumes,
-      pollIntervalMs: this.pollIntervalMs,
-      ghPrChecksFn: this.ghPrChecksFn,
-      ghPrViewFn: this.ghPrViewFn,
-      ghPrUpdateBranchFn: this.ghPrUpdateBranchFn,
-      sleepFn: this.sleepFn,
-      logger: this.logger,
-      firstProbe: first,
-    });
+    const { polls, updatesApplied, resumesApplied, terminal, stillRunning } =
+      await watchPrToTerminal({
+        prUrl,
+        cwd: this.cwd,
+        maxPolls: this.maxPolls,
+        maxUpdates: this.maxUpdates,
+        maxResumes: this.maxResumes,
+        pollIntervalMs: this.pollIntervalMs,
+        ghPrChecksFn: this.ghPrChecksFn,
+        ghPrViewFn: this.ghPrViewFn,
+        ghPrUpdateBranchFn: this.ghPrUpdateBranchFn,
+        sleepFn: this.sleepFn,
+        logger: this.logger,
+        firstProbe: first,
+      });
 
     // `still-running` (slow CI, not red) is a distinct classification from
     // a genuine `timed-out` — reserved for a check that never went
@@ -768,16 +743,6 @@ export class Watcher {
       resumesApplied,
       requiredChecks: requiredChecks.length,
     });
-    try {
-      await this.bus.emit('epic.watch.end', {
-        prUrl,
-        checkOutcomes: emitOutcomes,
-      });
-    } catch (err) {
-      this.logger.warn?.(
-        `[Watcher] epic.watch.end emit failed (swallowed): ${err?.message ?? err}`,
-      );
-    }
   }
 
   reset() {

package/.agents/scripts/lib/orchestration/lifecycle/trace-logger.js

@@ -40,28 +40,17 @@ function formatClock(iso) {
  * mapping is stable across runs.
  */
 const PHASE_BY_PREFIX = Object.freeze({
-  'epic.snapshot': 'Snapshot',
-  'epic.plan': 'Plan',
   'story.dispatch': 'Waves',
   'story.merged': 'Waves',
   'story.blocked': 'Waves',
-  'epic.blocked': 'Waves',
-  'epic.close': 'Close-tail',
-  'acceptance.reconcile': 'Acceptance Reconciliation',
-  'epic.finalize': 'Finalize',
   'pr.created': 'Finalize',
-  'epic.watch': 'Watch',
-  'epic.automerge': 'Automerge',
-  'epic.merge': 'Automerge',
-  'epic.cleanup': 'Cleanup',
-  'epic.complete': 'Complete',
   'notification.emitted': 'Notifications',
   'checkpoint.written': 'Checkpoint',
 });
 
 function phaseFor(eventName) {
-  // Match longest prefix first so `epic.snapshot.start` resolves before
-  // `epic.snapshot` would match an unrelated `epic.*` block.
+  // Match longest prefix first so `story.dispatch.start` resolves before
+  // `story.dispatch` would match an unrelated `story.*` block.
   const keys = Object.keys(PHASE_BY_PREFIX).sort((a, b) => b.length - a.length);
   for (const k of keys) {
     if (eventName === k || eventName.startsWith(`${k}.`)) {
@@ -277,7 +266,7 @@ export function render(ledger, opts = {}) {
  *
  * The wildcard-firewall rule (Tech Spec § Bus contract) requires that
  * trace observers do NOT import any module that mutates GitHub state,
- * the worktree, or the filesystem outside `temp/epic-<id>/`. This
+ * the worktree, or the filesystem outside `temp/run-<id>/`. This
  * module satisfies that constraint: the only filesystem writes are to
  * the companion path under the same temp directory the ledger lives
  * in.