mandrel 1.57.0

package/.agents/scripts/lib/orchestration/lifecycle/listeners/branch-cleaner.js

@@ -0,0 +1,259 @@
+// .agents/scripts/lib/orchestration/lifecycle/listeners/branch-cleaner.js
+/**
+ * BranchCleaner — lifecycle listener that owns post-merge **branch** reap
+ * for `/epic-deliver`. Story #2398 (companion to Cleaner, which owns the
+ * temp-tree archival half of end-of-Epic cleanup).
+ *
+ * Subscribes to:
+ *   - `epic.cleanup.start` → and ONLY this event.
+ *
+ * Why `epic.cleanup.start` and not `epic.merge.armed`:
+ *   Cleaner subscribes to `epic.merge.armed` and is the source of the
+ *   `epic.cleanup.start → epic.cleanup.end → epic.complete` terminal
+ *   sequence. The Bus runs listeners awaited and in registration order,
+ *   so a BranchCleaner registered on `epic.cleanup.start` BEFORE Cleaner
+ *   registers on `epic.merge.armed` will run synchronously inside
+ *   Cleaner's emit chain, between the start and end events, and crucially
+ *   BEFORE Cleaner's archive rename moves `temp/epic-<id>/` to
+ *   `temp/archive/epic-<id>-<ts>/`. The state checkpoint that we read to
+ *   enumerate Story branches lives on the Epic Issue (as the
+ *   `epic-run-state` structured comment), not under `temp/`, so the
+ *   ordering above is for symmetry with the existing Cleaner contract
+ *   — both halves of cleanup observe the same temp tree as it exists at
+ *   `epic.cleanup.start`.
+ *
+ * Side effects executed inside `handle()`:
+ *   1. Read the `epic-run-state` checkpoint via the injected
+ *      `checkpointer`. Skip with classification `no-state` when the
+ *      checkpoint is missing or carries no Stories (a brand-new run
+ *      that armed without ever finalising a wave should never reach
+ *      `epic.cleanup.start`, but the guard keeps this listener
+ *      idempotent under replay).
+ *   2. Call `reapEpicBranches()` from `lib/orchestration/epic-cleanup.js`,
+ *      which:
+ *      - switches the main checkout off `epic/<id>` to the baseBranch
+ *        when needed (so `git branch -D epic/<id>` isn't refused);
+ *      - removes attached worktrees with the Windows file-lock fallback
+ *        (worktree-remove → worktree-remove --force → fs.rm + prune);
+ *      - deletes every `story-<id>` branch listed in the checkpoint plus
+ *        the `epic/<id>` branch itself;
+ *      - runs `git remote prune` to drop stale `<remote>/...` tracking
+ *        refs left behind by `gh pr merge --delete-branch`;
+ *      - deletes the `wt-branch` scratch ref left by `story-close.js`'s
+ *        internal merge worktree when it is no longer checked out.
+ *   3. Record one classification entry per invocation (`reaped`,
+ *      `no-state`, `failed`, or `skipped-duplicate`) so failures surface
+ *      in the lifecycle ledger alongside Cleaner's archival outcome.
+ *
+ * Idempotency contract: per-instance `Set<string>` of `${event}:${seqId}`
+ * keys — repeat `(event, seqId)` invocation short-circuits and classifies
+ * `skipped-duplicate`. Mirrors Cleaner's bus-level replay defence.
+ *
+ * Side-effect firewall: the listener mutates **local git state** (branch
+ * refs, worktree paths, remote tracking refs) and nothing else. It does
+ * NOT touch the temp tree, the ticketing provider (the checkpointer
+ * `read()` is the only ticketing call and is read-only), or label state.
+ * Label transitions stay with LabelTransitioner on `epic.complete`.
+ *
+ * Production failure mode: `reapEpicBranches()` aggregates per-branch
+ * failures into the result envelope rather than throwing — a single
+ * branch that won't reap (e.g. because the operator stashed unmerged
+ * work onto it) must not block the rest of cleanup. The listener
+ * therefore records `failed` as a classification with the failure
+ * summary; orchestration callers that want hard-stop semantics can
+ * inspect the classifications. Programmer errors in the listener's own
+ * inputs (missing bus / non-numeric epicId / missing checkpointer)
+ * throw at construction time per
+ * `.agents/rules/orchestration-error-handling.md`.
+ */
+
+import { rmSync as defaultRmSync } from 'node:fs';
+
+import { gitSpawn as defaultGitSpawn } from '../../../git-utils.js';
+import { reapEpicBranches } from '../../epic-cleanup.js';
+
+/**
+ * BranchCleaner listener.
+ */
+export class BranchCleaner {
+  /**
+   * @param {object} opts
+   * @param {object} opts.bus
+   * @param {number} opts.epicId
+   * @param {{ read: () => Promise<object|null> }} opts.checkpointer
+   *   Object exposing `read()` returning the `epic-run-state` checkpoint
+   *   shape (epicId + waves[].stories[].id). Production passes the
+   *   stateless `epic-run-state-store` module bound to `{provider, epicId}`;
+   *   tests pass a fake.
+   * @param {string} opts.cwd - Absolute path to the **main** checkout
+   *   (not a worktree). `reapEpicBranches()` runs `git checkout`,
+   *   `git branch -D`, and `git remote prune` against this directory.
+   * @param {string} [opts.baseBranch='main'] - Branch to switch the main
+   *   checkout to before reaping `epic/<id>`.
+   * @param {string} [opts.remote='origin'] - Remote to prune.
+   * @param {Function} [opts.gitSpawn] - Injectable git spawner for tests.
+   * @param {Function} [opts.rmSyncFn] - Injectable filesystem remove for
+   *   the worktree Windows-lock fallback.
+   * @param {Function} [opts.spawnFn] - Injectable process spawner forwarded
+   *   to `reapEpicBranches` for the Story #3367 open-PR guard probe
+   *   (`gh pr list --head epic/<id> --state open`). Defaults to the real
+   *   `spawnSync` inside `epic-cleanup.js`; tests inject a stub.
+   * @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('BranchCleaner requires a bus with on() and emit()');
+    }
+    if (!Number.isInteger(opts.epicId) || opts.epicId < 1) {
+      throw new TypeError('BranchCleaner requires a numeric epicId');
+    }
+    if (!opts.checkpointer || typeof opts.checkpointer.read !== 'function') {
+      throw new TypeError(
+        'BranchCleaner requires a checkpointer exposing read()',
+      );
+    }
+    if (typeof opts.cwd !== 'string' || opts.cwd.length === 0) {
+      throw new TypeError('BranchCleaner requires a non-empty cwd string');
+    }
+    this.bus = opts.bus;
+    this.epicId = opts.epicId;
+    this.checkpointer = opts.checkpointer;
+    this.cwd = opts.cwd;
+    this.baseBranch = opts.baseBranch ?? 'main';
+    this.remote = opts.remote ?? 'origin';
+    this.gitSpawn = opts.gitSpawn ?? defaultGitSpawn;
+    this.rmSyncFn = opts.rmSyncFn ?? defaultRmSync;
+    // Story #3367 — forwarded to reapEpicBranches' open-PR guard probe.
+    // `undefined` lets epic-cleanup.js fall back to its real `spawnSync`.
+    this.spawnFn = opts.spawnFn;
+    this.logger = opts.logger ?? console;
+    /** @type {Set<string>} `${event}:${seqId}` idempotency cache. */
+    this._seen = new Set();
+    /**
+     * Classification log — every `epic.cleanup.start` observed lands
+     * here with the outcome (`reaped`, `no-state`, `failed`,
+     * `skipped-duplicate`). Mirrors Cleaner's "no silent skip" surface.
+     */
+    this.classifications = [];
+    // Frozen tuple — BranchCleaner subscribes to EXACTLY one event.
+    this.events = Object.freeze(['epic.cleanup.start']);
+  }
+
+  register() {
+    return this.events.map((event) =>
+      this.bus.on(event, async (ctx) => this.handle(ctx)),
+    );
+  }
+
+  async handle({ event, seqId }) {
+    const key = `${event}:${seqId}`;
+    if (this._seen.has(key)) {
+      this.classifications.push({
+        event,
+        seqId,
+        outcome: 'skipped-duplicate',
+      });
+      this.logger.debug?.(`[BranchCleaner] skip duplicate ${key} (idempotent)`);
+      return;
+    }
+    this._seen.add(key);
+
+    let state;
+    try {
+      state = await this.checkpointer.read();
+    } catch (err) {
+      this.classifications.push({
+        event,
+        seqId,
+        outcome: 'failed',
+        reason: `checkpoint-read-failed:${err?.message ?? err}`,
+      });
+      this.logger.warn?.(
+        `[BranchCleaner] checkpoint read failed: ${err?.message ?? err}`,
+      );
+      return;
+    }
+
+    if (!state || !Number.isInteger(state.epicId) || state.epicId < 1) {
+      this.classifications.push({
+        event,
+        seqId,
+        outcome: 'no-state',
+        reason: 'checkpoint-absent-or-empty',
+      });
+      this.logger.info?.(
+        '[BranchCleaner] no epic-run-state checkpoint; nothing to reap.',
+      );
+      return;
+    }
+
+    const result = reapEpicBranches({
+      state,
+      cwd: this.cwd,
+      gitSpawn: this.gitSpawn,
+      rmSyncFn: this.rmSyncFn,
+      baseBranch: this.baseBranch,
+      remote: this.remote,
+      spawnFn: this.spawnFn,
+      logger: this.logger,
+    });
+
+    const summary = summarizeReap(result);
+    if (result.ok) {
+      this.classifications.push({
+        event,
+        seqId,
+        outcome: 'reaped',
+        epicId: result.epicId,
+        ...summary,
+      });
+      this.logger.info?.(
+        `[BranchCleaner] reaped ${summary.branchesDeleted} branch(es) + ${summary.worktreesRemoved} worktree(s) for epic/${result.epicId}`,
+      );
+    } else {
+      this.classifications.push({
+        event,
+        seqId,
+        outcome: 'failed',
+        reason: 'reap-failures',
+        epicId: result.epicId,
+        ...summary,
+        failures: result.failures.map((f) => ({
+          branch: f.branch,
+          stderr: f.stderr ?? null,
+        })),
+      });
+      this.logger.warn?.(
+        `[BranchCleaner] ${result.failures.length} branch(es) failed to reap for epic/${result.epicId}`,
+      );
+    }
+  }
+
+  reset() {
+    this._seen.clear();
+    this.classifications = [];
+  }
+}
+
+/**
+ * Pure: condense a `reapEpicBranches()` result into the counts that the
+ * classification log carries. Exported for tests.
+ *
+ * @param {{ reaped: Array<object>, pruned: { pruned: string[] }|null, wtBranch: { deleted: boolean }|null }} result
+ * @returns {{ branchesDeleted: number, worktreesRemoved: number, tracksPruned: number, wtBranchDeleted: boolean }}
+ */
+export function summarizeReap(result) {
+  const reaped = Array.isArray(result?.reaped) ? result.reaped : [];
+  return {
+    branchesDeleted: reaped.filter((r) => r.branchDeleted).length,
+    worktreesRemoved: reaped.filter(
+      (r) => r.worktreeReaped && r.method !== 'no-worktree',
+    ).length,
+    tracksPruned: result?.pruned?.pruned?.length ?? 0,
+    wtBranchDeleted: result?.wtBranch?.deleted === true,
+  };
+}

package/.agents/scripts/lib/orchestration/lifecycle/listeners/checkpoint-pointer-writer.js

@@ -0,0 +1,278 @@
+// .agents/scripts/lib/orchestration/lifecycle/listeners/checkpoint-pointer-writer.js
+/**
+ * CheckpointPointerWriter — lifecycle listener that maintains a
+ * minimal pointer file at `temp/epic-<id>/checkpoint.json` after every
+ * `*.end` lifecycle event (Story #2266 / Task #2268, Epic #2172).
+ *
+ * The writer replaces the legacy `epic-runner/checkpointer.js`
+ * structured-comment checkpointer with a ledger-driven pointer: the
+ * NDJSON ledger (`lifecycle.ndjson`) is the canonical run history, and
+ * the pointer file is a tiny `{ lastCompletedSeqId, phase }` snapshot
+ * the runner reads at resume time to seek the right offset into the
+ * ledger.
+ *
+ * Subscription set: **every event whose name ends in `.end`**. The
+ * frozen `EVENTS` tuple is computed from the lifecycle schema directory
+ * via the helper export so the registration cannot drift from the
+ * taxonomy without updating the schema set.
+ *
+ * Self-emit contract: after the pointer write succeeds the listener
+ * emits `checkpoint.written` exactly once per observed `*.end`. The
+ * self-emit is guarded by the per-instance `(event, seqId)` idempotency
+ * set so the bus's resume window (re-emitting an event whose `emitted`
+ * line landed but whose `completed` did not) cannot produce a duplicate
+ * `checkpoint.written`. The seqId set persists for the lifetime of the
+ * listener; cross-process restart relies on the on-disk pointer's
+ * monotonicity (the second invocation observes `lastCompletedSeqId >=
+ * payload.seqId` and short-circuits).
+ *
+ * Side-effect firewall: filesystem write + exactly one `bus.emit`. No
+ * provider calls, no GitHub IO, no runner-state mutation.
+ *
+ * Registration order: the runner factory registers this listener
+ * EARLY — before downstream listeners that may fail — so the pointer
+ * file always advances even if a later listener throws on the SAME
+ * `*.end`. The throw still flows through the bus's `onFailed` hook
+ * (LedgerWriter records a `failed` line) but the pointer reflects the
+ * last `*.end` that reached this listener, which is what the resume
+ * coordinator needs to skip past completed events on the next start.
+ */
+
+import { mkdirSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+
+/**
+ * The pointer file name under `temp/epic-<id>/`. Stable and grep-able
+ * so future tooling can locate the file without re-deriving the path.
+ */
+export const POINTER_FILENAME = 'checkpoint.json';
+
+/**
+ * The self-emitted lifecycle event name. Matches the schema id at
+ * `.agents/schemas/lifecycle/checkpoint.written.schema.json`.
+ */
+export const CHECKPOINT_WRITTEN_EVENT = 'checkpoint.written';
+
+/**
+ * The frozen list of `*.end` events the writer subscribes to. Sourced
+ * from the lifecycle taxonomy (`.agents/schemas/lifecycle/*.end.schema.json`).
+ *
+ * Listed explicitly rather than discovered at runtime so:
+ *   (a) the registration set is a code-visible contract — adding a new
+ *       `*.end` event to the schema set forces a code change here,
+ *       which is the seam reviewers grep for;
+ *   (b) construction stays synchronous (no readdir + parse) and the
+ *       constructor remains safe to call inside the runner factory.
+ *
+ * If a new `*.end` event is added to the schema directory, append it
+ * here. The `checkpoint.written` event itself is intentionally NOT in
+ * this list — the writer's own self-emit must not retrigger the writer
+ * (that would loop), and `checkpoint.written` is not an `*.end` event
+ * by naming convention.
+ */
+export const SUBSCRIBED_END_EVENTS = Object.freeze([
+  'close-validate.end',
+  'code-review.end',
+  'epic.automerge.end',
+  'epic.cleanup.end',
+  'epic.close.end',
+  'epic.finalize.end',
+  'epic.plan.end',
+  'epic.snapshot.end',
+  'epic.watch.end',
+  'retro.end',
+  'story.dispatch.end',
+]);
+
+/**
+ * Resolve the pointer-file path for a given Epic. Exported so tests
+ * can target the same file without re-deriving the layout.
+ */
+export function resolvePointerPath({ tempRoot, epicId }) {
+  if (typeof tempRoot !== 'string' || tempRoot.length === 0) {
+    throw new TypeError(
+      'resolvePointerPath: tempRoot must be a non-empty string',
+    );
+  }
+  if (!Number.isInteger(epicId) || epicId < 1) {
+    throw new TypeError(
+      'resolvePointerPath: epicId must be a positive integer',
+    );
+  }
+  return path.join(tempRoot, `epic-${epicId}`, POINTER_FILENAME);
+}
+
+/**
+ * Build the pointer payload. Pulled out so tests can assert the exact
+ * on-disk shape without parsing JSON every time.
+ */
+export function buildPointerPayload({ lastCompletedSeqId, phase }) {
+  return {
+    lastCompletedSeqId,
+    phase,
+  };
+}
+
+/**
+ * CheckpointPointerWriter listener.
+ */
+export class CheckpointPointerWriter {
+  /**
+   * @param {object} opts
+   * @param {object} opts.bus Lifecycle bus exposing `on()` + `emit()`.
+   * @param {number} opts.epicId Epic ticket id.
+   * @param {string} opts.tempRoot Absolute or repo-relative path; the
+   *   listener resolves `<tempRoot>/epic-<id>/checkpoint.json`.
+   * @param {typeof writeFileSync} [opts.writeFn] Injectable writer for
+   *   tests.
+   * @param {typeof mkdirSync} [opts.mkdirFn] Injectable directory
+   *   creator for tests.
+   * @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(
+        'CheckpointPointerWriter requires a bus with on() and emit()',
+      );
+    }
+    if (!Number.isInteger(opts.epicId) || opts.epicId < 1) {
+      throw new TypeError('CheckpointPointerWriter requires a numeric epicId');
+    }
+    if (typeof opts.tempRoot !== 'string' || opts.tempRoot.length === 0) {
+      throw new TypeError(
+        'CheckpointPointerWriter requires a non-empty tempRoot string',
+      );
+    }
+    this.bus = opts.bus;
+    this.epicId = opts.epicId;
+    this.tempRoot = opts.tempRoot;
+    this._writeFn = opts.writeFn ?? writeFileSync;
+    this._mkdirFn = opts.mkdirFn ?? mkdirSync;
+    this.logger = opts.logger ?? console;
+    this._pointerPath = resolvePointerPath({
+      tempRoot: this.tempRoot,
+      epicId: this.epicId,
+    });
+    this._epicDir = path.dirname(this._pointerPath);
+    /** @type {Set<string>} `${event}:${seqId}` idempotency cache. */
+    this._seen = new Set();
+    /**
+     * Monotonic seqId guard. The pointer's `lastCompletedSeqId` MUST
+     * be non-decreasing — observing a lower seqId after a higher one
+     * means we are replaying an out-of-order event (resume window or
+     * test misuse). The listener short-circuits on the regression and
+     * logs a debug line; it does NOT throw, because a resume cycle
+     * can legitimately replay older `emitted` lines before catching
+     * up.
+     */
+    this._lastSeqId = 0;
+    this.events = SUBSCRIBED_END_EVENTS;
+  }
+
+  /**
+   * Resolved on-disk path for the pointer file. Exposed for tests.
+   */
+  get pointerPath() {
+    return this._pointerPath;
+  }
+
+  /**
+   * Register the listener on every subscribed `*.end` event. Returns
+   * the array of unsubscribe callbacks the bus produced (parity with
+   * `signals-appender.register()`).
+   */
+  register() {
+    return this.events.map((event) =>
+      this.bus.on(event, async (ctx) => this.handle(ctx)),
+    );
+  }
+
+  /**
+   * Bus listener body. Idempotent on `(event, seqId)`; emits
+   * `checkpoint.written` exactly once after the pointer write
+   * succeeds.
+   */
+  async handle({ event, seqId, payload: _payload }) {
+    const key = `${event}:${seqId}`;
+    if (this._seen.has(key)) {
+      this.logger.debug?.(
+        `[CheckpointPointerWriter] skip duplicate ${key} (idempotent)`,
+      );
+      return;
+    }
+    this._seen.add(key);
+
+    // Resume / out-of-order guard. The on-disk pointer is the
+    // canonical "highest seqId observed so far" — when a replay
+    // delivers a seqId lower than what we already wrote, we keep the
+    // pointer untouched and do NOT re-emit `checkpoint.written` for
+    // the stale event. This makes the listener safe to register
+    // BEFORE the resume coordinator has fully consumed the prior
+    // ledger.
+    if (seqId <= this._lastSeqId) {
+      this.logger.debug?.(
+        `[CheckpointPointerWriter] skip non-advancing seqId=${seqId} (lastCompletedSeqId=${this._lastSeqId})`,
+      );
+      return;
+    }
+
+    // The `phase` carried in the pointer is the event name itself —
+    // every `*.end` event is by convention a phase boundary, so the
+    // event name is the human-readable phase label the resume
+    // coordinator displays ("we crashed after wave.end seqId=42").
+    // Embedding the event name keeps the pointer self-describing
+    // without requiring an extra `payload.phase` field on every
+    // schema.
+    const phase = event;
+    const pointerPayload = buildPointerPayload({
+      lastCompletedSeqId: seqId,
+      phase,
+    });
+
+    try {
+      this._mkdirFn(this._epicDir, { recursive: true });
+      // `writeFileSync` with the default flag truncates — exactly
+      // what we want: the pointer is a single-line atomic snapshot,
+      // not an append log. The ledger is the append log; this file
+      // is the cursor.
+      this._writeFn(
+        this._pointerPath,
+        `${JSON.stringify(pointerPayload)}\n`,
+        'utf8',
+      );
+    } catch (err) {
+      // A failed pointer write is recoverable — the ledger still has
+      // the full history, and the next `*.end` will retry the
+      // pointer. Surface as a warning and bail before the self-emit
+      // so we don't claim progress we didn't persist.
+      this.logger.warn?.(
+        `[CheckpointPointerWriter] pointer write failed for ${key}: ${err?.message ?? err}`,
+      );
+      // Leave the seqId guard advanced for this `(event, seqId)` so
+      // the in-process retry path doesn't loop on the same failure,
+      // but DO NOT bump `_lastSeqId` — the next event may still want
+      // to advance past `seqId`.
+      return;
+    }
+    this._lastSeqId = seqId;
+
+    // Self-emit AFTER the pointer write succeeds. Per the listener
+    // README, listeners MAY emit follow-up events; the seqId guard
+    // above ensures `checkpoint.written` fires exactly once per
+    // observed `*.end`.
+    await this.bus.emit(CHECKPOINT_WRITTEN_EVENT, pointerPayload);
+  }
+
+  /**
+   * Test-only — clear the seqId cache so a single instance can
+   * exercise resume scenarios without re-constructing the listener.
+   */
+  resetSeen() {
+    this._seen.clear();
+    this._lastSeqId = 0;
+  }
+}