mandrel 2.31.0 → 2.32.0

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

@@ -1,229 +0,0 @@
-// .agents/scripts/lib/orchestration/lifecycle/ledger-writer.js
-/**
- * LedgerWriter — append-only NDJSON persister for the lifecycle bus.
- *
- * Registered as the first named listener on every event by the runner
- * factory. Each successful emit produces exactly one `emitted` + one
- * `completed` line; a listener throw produces `emitted` + `failed`.
- *
- * The writer is a thin wrapper around `fs.appendFileSync` because:
- *   - the bus is strictly sequential, so a synchronous append cannot race;
- *   - resume semantics depend on the ledger being on disk before any
- *     downstream listener runs (`emitted` lands before listener `N`
- *     executes; a crash mid-listener leaves an `emitted`-without-
- *     `completed` line that resume detects);
- *   - synchronous I/O makes failure modes obvious (a thrown EACCES is
- *     observable immediately and propagates through the bus).
- *
- * Secret denylist: payload keys named in `SECRET_KEY_DENY_LIST` are
- * stripped before write. This is defense-in-depth: payloads should never
- * carry secrets to begin with, but the strip means a future contributor
- * who accidentally adds `{ token: ... }` to an event payload can't leak
- * it to the on-disk ledger (which we treat as an artifact safe to attach
- * to PR comments).
- */
-
-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
- * are matched case-insensitively against own enumerable keys of the
- * top-level payload AND of any nested object.
- */
-export const SECRET_KEY_DENY_LIST = Object.freeze([
-  'token',
-  'password',
-  'secret',
-  'apikey',
-  'webhookurl',
-]);
-
-const SECRET_DENY_SET = new Set(SECRET_KEY_DENY_LIST);
-
-/**
- * Recursively strip deny-listed keys from an arbitrary value. Arrays and
- * primitives are passed through; objects produce a new object with the
- * deny-listed keys omitted. The original input is not mutated.
- *
- * Cyclic structures aren't expected in event payloads (the schema layer
- * forbids them by construction), so we don't carry a `seen` set.
- */
-export function stripSecrets(value) {
-  if (Array.isArray(value)) {
-    return value.map(stripSecrets);
-  }
-  if (value && typeof value === 'object') {
-    const out = {};
-    for (const [k, v] of Object.entries(value)) {
-      if (SECRET_DENY_SET.has(k.toLowerCase())) continue;
-      out[k] = stripSecrets(v);
-    }
-    return out;
-  }
-  return value;
-}
-
-/**
- * Produce the canonical ISO-8601 wall-clock string for a ledger record.
- * Pulled out so tests can fake `Date.now()` without mocking the global.
- */
-function nowIso(now = Date.now) {
-  return new Date(now()).toISOString();
-}
-
-/**
- * LedgerWriter binds to a single Epic's temp directory. The runner
- * constructs one per Epic run (and reuses it across resume).
- *
- * Usage:
- *   const writer = new LedgerWriter({ epicId: 2172, tempRoot: 'temp' });
- *   writer.register(bus);
- */
-export class LedgerWriter {
-  /**
-   * @param {object} opts
-   * @param {number} opts.epicId
-   * @param {string} opts.tempRoot - absolute or repo-relative path; the
-   *   writer resolves `temp/run-<id>/lifecycle.ndjson` underneath.
-   * @param {() => number} [opts.now] - injectable clock for tests.
-   */
-  constructor(opts) {
-    if (!opts || !Number.isInteger(opts.epicId) || opts.epicId <= 0) {
-      throw new TypeError(
-        'LedgerWriter: opts.epicId must be a positive integer',
-      );
-    }
-    if (typeof opts.tempRoot !== 'string' || opts.tempRoot.length === 0) {
-      throw new TypeError(
-        'LedgerWriter: opts.tempRoot must be a non-empty string',
-      );
-    }
-    this._epicId = opts.epicId;
-    this._tempRoot = opts.tempRoot;
-    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;
-  }
-
-  /**
-   * Resolved on-disk path for the NDJSON ledger. Exposed for tests and
-   * for the TraceLogger which renders the companion markdown from it.
-   */
-  get ledgerPath() {
-    return this._ledgerPath;
-  }
-
-  /**
-   * Directory housing the ledger and (later) the companion markdown.
-   */
-  get epicDir() {
-    return this._epicDir;
-  }
-
-  /**
-   * Ensure the epic-scoped temp directory exists before every append.
-   *
-   * 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/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
-   * idempotent and cheap (microseconds), so we call it every time and
-   * keep the writer robust to its own directory being moved.
-   */
-  _ensureDir() {
-    mkdirSync(this._epicDir, { recursive: true });
-  }
-
-  /**
-   * Append one NDJSON record. Internal — callers should use the bus
-   * listener registered by `register()`.
-   */
-  _appendRecord(record) {
-    this._ensureDir();
-    appendFileSync(this._ledgerPath, `${JSON.stringify(record)}\n`, 'utf8');
-  }
-
-  /**
-   * Build the `emitted` record for a given context. Exposed for tests so
-   * the deny-list strip can be asserted directly.
-   */
-  buildEmitted({ event, seqId, payload }) {
-    return {
-      kind: 'emitted',
-      seqId,
-      ts: nowIso(this._now),
-      event,
-      payload: stripSecrets(payload ?? {}),
-    };
-  }
-
-  buildCompleted({ event, seqId }) {
-    return {
-      kind: 'completed',
-      seqId,
-      ts: nowIso(this._now),
-      event,
-    };
-  }
-
-  buildFailed({ event, seqId, listener, error }) {
-    const errorRecord = {
-      name: error?.name ? String(error.name) : 'Error',
-      message: error?.message ? String(error.message) : String(error),
-    };
-    if (typeof error?.stack === 'string' && error.stack.length > 0) {
-      errorRecord.stack = error.stack;
-    }
-    return {
-      kind: 'failed',
-      seqId,
-      ts: nowIso(this._now),
-      event,
-      listener,
-      error: errorRecord,
-    };
-  }
-
-  /**
-   * Register this writer against the supplied bus by installing the
-   * privileged `onEmitted` / `onCompleted` / `onFailed` hooks. The
-   * writer is NOT a regular listener — it uses the privileged seam so
-   * `emitted` lands BEFORE any listener side effect (resume contract)
-   * and `completed` / `failed` land AFTER the listener phase.
-   */
-  register(bus) {
-    if (
-      !bus ||
-      typeof bus.onEmitted !== 'function' ||
-      typeof bus.onCompleted !== 'function' ||
-      typeof bus.onFailed !== 'function'
-    ) {
-      throw new TypeError(
-        'LedgerWriter.register: bus must expose onEmitted/onCompleted/onFailed hooks',
-      );
-    }
-    bus.onEmitted(({ event, seqId, payload }) => {
-      this._appendRecord(this.buildEmitted({ event, seqId, payload }));
-    });
-    bus.onCompleted(({ event, seqId }) => {
-      this._appendRecord(this.buildCompleted({ event, seqId }));
-    });
-    bus.onFailed(({ event, seqId, listener, error }) => {
-      this._appendRecord(this.buildFailed({ event, seqId, listener, error }));
-    });
-  }
-}
-
-/**
- * Factory wrapper for symmetry with `createBus()`.
- */
-export function createLedgerWriter(opts) {
-  return new LedgerWriter(opts);
-}

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

@@ -1,54 +0,0 @@
-# Lifecycle Listeners
-
-Each listener in this directory subscribes to one or more lifecycle bus
-events and performs a single side effect. The full close-tail roster and
-event taxonomy live in
-[`docs/LIFECYCLE.md`](https://github.com/dsj1984/mandrel/blob/main/docs/LIFECYCLE.md)
-— that document is the SSOT. This README only indexes the **files that still
-live in this folder**.
-
-## Files here
-
-- [`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
-`buildDefaultListenerChain` factory in this directory.
-
-## Idempotency contract
-
-Listeners MUST be idempotent on `(event, seqId)`. The bus may invoke a
-listener twice for the same seqId during the resume window (when an
-`emitted` ledger line landed but the matching `completed` did not). The
-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.
-
-## Side-effect firewall
-
-Listeners MAY:
-
-- read tickets via the injected `provider`,
-- write tickets via the injected `transitionTicketState`,
-- upsert structured comments via the injected `upsertStructuredComment`,
-- 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-enter safely),
-- import runner state directly,
-- mutate cross-cutting globals.
-
-Trace observers (`bus.on('*', fn)`) live under
-`lib/orchestration/lifecycle/trace-logger.js` and are subject to the
-same firewall, plus a stricter no-IO rule.

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

@@ -1,344 +0,0 @@
-// .agents/scripts/lib/orchestration/lifecycle/trace-logger.js
-/**
- * TraceLogger — renders the human-readable `lifecycle.md` companion
- * from the canonical NDJSON ledger.
- *
- * The companion is a strict projection of the ledger: re-rendering the
- * same ledger produces byte-identical Markdown (modulo wall-clock `ts`
- * formatting). Editing the companion does NOT affect resume; only the
- * NDJSON ledger is canonical. This is repeatability AC #12.
- *
- * `render(ledger)` is the pure function consumers should call.
- * `TraceLogger.register(bus, writerLedgerPath)` installs the wildcard
- * observer + the on-write side that keeps the companion in sync after
- * every emit, but it does so by re-reading the NDJSON file and calling
- * `render()` — there is no in-memory drift.
- */
-
-import { readFileSync, writeFileSync } from 'node:fs';
-import path from 'node:path';
-
-/**
- * Format an ISO-8601 timestamp as HH:MM:SS for the per-event line. The
- * `(durationMs)` chunk is computed from the gap between `emitted` and
- * `completed` (or `failed`) of the same seqId.
- */
-function formatClock(iso) {
-  // The ledger record schema requires ISO date-time strings (validated
-  // up-stream); a defensive `Date` parse here is just for resilience.
-  const d = new Date(iso);
-  if (Number.isNaN(d.getTime())) return '??:??:??';
-  const hh = String(d.getUTCHours()).padStart(2, '0');
-  const mm = String(d.getUTCMinutes()).padStart(2, '0');
-  const ss = String(d.getUTCSeconds()).padStart(2, '0');
-  return `${hh}:${mm}:${ss}`;
-}
-
-/**
- * Phase header derived from event name. The companion is grouped by
- * phase so operators can scan to the section that interests them. The
- * mapping is stable across runs.
- */
-const PHASE_BY_PREFIX = Object.freeze({
-  'story.dispatch': 'Waves',
-  'story.merged': 'Waves',
-  'story.blocked': 'Waves',
-  'pr.created': 'Finalize',
-  'notification.emitted': 'Notifications',
-  'checkpoint.written': 'Checkpoint',
-});
-
-function phaseFor(eventName) {
-  // 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}.`)) {
-      return PHASE_BY_PREFIX[k];
-    }
-  }
-  return 'Other';
-}
-
-/**
- * Render the payload summary chunk for a per-event line. We keep it
- * short: keys + scalar values, no nested object dumps (the canonical
- * NDJSON ledger is the place to recover full payloads). This matches
- * the Tech Spec spec: "payload-summary".
- */
-function summarizePayload(payload) {
-  if (!payload || typeof payload !== 'object') return '';
-  const parts = [];
-  for (const [k, v] of Object.entries(payload)) {
-    if (v == null) continue;
-    if (
-      typeof v === 'string' ||
-      typeof v === 'number' ||
-      typeof v === 'boolean'
-    ) {
-      parts.push(`${k}=${v}`);
-    } else if (Array.isArray(v)) {
-      parts.push(`${k}=[${v.length}]`);
-    } else if (typeof v === 'object') {
-      const keys = Object.keys(v);
-      parts.push(`${k}={${keys.length}}`);
-    }
-  }
-  return parts.join(' ');
-}
-
-/**
- * Parse an NDJSON ledger string into an array of records. Blank lines
- * and trailing whitespace are tolerated; malformed lines throw with
- * line number so the operator can locate the corruption.
- */
-export function parseLedger(text) {
-  const out = [];
-  const lines = String(text || '').split('\n');
-  for (let i = 0; i < lines.length; i += 1) {
-    const line = lines[i].trim();
-    if (line.length === 0) continue;
-    try {
-      out.push(JSON.parse(line));
-    } catch (_err) {
-      throw new Error(
-        `lifecycle ledger: malformed JSON on line ${i + 1}: ${line.slice(0, 80)}`,
-      );
-    }
-  }
-  return out;
-}
-
-/**
- * Pure render of a parsed ledger to Markdown. Same input → byte-identical
- * output (modulo `ts` field formatting, which is wall-clock by design).
- *
- * Layout (mirroring Tech Spec § Human-readable companion):
- *   # Lifecycle — epic <id>
- *
- *   ## <Phase>
- *   HH:MM:SS  event.name  (durationMs)  payload-summary
- *   ...
- *
- *   ## Summary
- *   - Events: N
- *   - Failed: N
- *   - …
- */
-/**
- * Index the ledger records into the two maps `render` needs: the `emitted`
- * record per seqId and the terminal (`completed`/`failed`) record per seqId.
- * Story #4075 — extracted from `render` so the orchestrating body stays flat.
- */
-function indexLedgerRecords(records) {
-  const emittedBySeq = new Map();
-  const terminalBySeq = new Map();
-  for (const rec of records) {
-    if (!rec || typeof rec !== 'object') continue;
-    if (rec.kind === 'emitted') emittedBySeq.set(rec.seqId, rec);
-    else if (rec.kind === 'completed' || rec.kind === 'failed')
-      terminalBySeq.set(rec.seqId, rec);
-  }
-  return { emittedBySeq, terminalBySeq };
-}
-
-/**
- * Compute the `(durationMs)` / `(pending)` chunk for one emitted event,
- * given its terminal record (or undefined when still in flight).
- */
-export function formatDurationChunk(emit, terminal) {
-  if (!terminal) return '(pending)';
-  const start = new Date(emit.ts).getTime();
-  const end = new Date(terminal.ts).getTime();
-  if (Number.isFinite(start) && Number.isFinite(end) && end >= start) {
-    return `(${end - start}ms)`;
-  }
-  return '';
-}
-
-/**
- * Render a single per-event line for the phase section.
- */
-function formatEventLine(emit, terminal) {
-  const failedMarker =
-    terminal && terminal.kind === 'failed' ? ' ⚠️ FAILED' : '';
-  const parts = [
-    formatClock(emit.ts),
-    emit.event,
-    formatDurationChunk(emit, terminal),
-    summarizePayload(emit.payload),
-  ].filter(Boolean);
-  return parts.join('  ') + failedMarker;
-}
-
-/**
- * Group emitted events into ordered phase buckets, each carrying its
- * rendered per-event lines. Phase order is first-seen by ascending seqId.
- */
-function buildPhaseLines(emittedBySeq, terminalBySeq) {
-  const phaseOrder = [];
-  const phaseLines = new Map();
-  for (const emit of [...emittedBySeq.values()].sort(
-    (a, b) => a.seqId - b.seqId,
-  )) {
-    const phase = phaseFor(emit.event);
-    if (!phaseLines.has(phase)) {
-      phaseLines.set(phase, []);
-      phaseOrder.push(phase);
-    }
-    phaseLines
-      .get(phase)
-      .push(formatEventLine(emit, terminalBySeq.get(emit.seqId)));
-  }
-  return { phaseOrder, phaseLines };
-}
-
-/**
- * Compute the wall-clock span (`maxEnd - minStart`) of a single phase, or
- * `null` when no finite span can be derived.
- */
-function computePhaseSpanMs(phase, emittedBySeq, terminalBySeq) {
-  let minStart = Infinity;
-  let maxEnd = -Infinity;
-  for (const emit of emittedBySeq.values()) {
-    if (phaseFor(emit.event) !== phase) continue;
-    const start = new Date(emit.ts).getTime();
-    if (Number.isFinite(start) && start < minStart) minStart = start;
-    const terminal = terminalBySeq.get(emit.seqId);
-    if (terminal) {
-      const end = new Date(terminal.ts).getTime();
-      if (Number.isFinite(end) && end > maxEnd) maxEnd = end;
-    }
-  }
-  return Number.isFinite(minStart) && Number.isFinite(maxEnd)
-    ? maxEnd - minStart
-    : null;
-}
-
-/**
- * Build the trailing `## Summary` block lines.
- */
-function buildSummaryLines(phaseOrder, emittedBySeq, terminalBySeq) {
-  const totalEvents = emittedBySeq.size;
-  const failedCount = [...terminalBySeq.values()].filter(
-    (r) => r.kind === 'failed',
-  ).length;
-  const phaseDurations = [];
-  for (const phase of phaseOrder) {
-    const spanMs = computePhaseSpanMs(phase, emittedBySeq, terminalBySeq);
-    if (spanMs !== null) phaseDurations.push(`  - ${phase}: ${spanMs}ms`);
-  }
-  const lines = [
-    '## Summary',
-    '',
-    `- Events: ${totalEvents}`,
-    `- Completed: ${totalEvents - failedCount}`,
-    `- Failed: ${failedCount}`,
-  ];
-  if (phaseDurations.length > 0) {
-    lines.push('- Phase durations:', ...phaseDurations);
-  }
-  lines.push('');
-  return lines;
-}
-
-export function render(ledger, opts = {}) {
-  const records = Array.isArray(ledger) ? ledger : parseLedger(ledger);
-  const { emittedBySeq, terminalBySeq } = indexLedgerRecords(records);
-  const { phaseOrder, phaseLines } = buildPhaseLines(
-    emittedBySeq,
-    terminalBySeq,
-  );
-
-  const epicId = opts.epicId ? `epic ${opts.epicId}` : 'epic';
-  const lines = [`# Lifecycle — ${epicId}`, ''];
-  for (const phase of phaseOrder) {
-    lines.push(`## ${phase}`, '', ...phaseLines.get(phase), '');
-  }
-  lines.push(...buildSummaryLines(phaseOrder, emittedBySeq, terminalBySeq));
-  return lines.join('\n');
-}
-
-/**
- * TraceLogger wires `render()` against a live bus + ledger file. It is
- * a wildcard observer: it does not mutate state under orchestration, it
- * only re-renders the companion markdown on every event.
- *
- * 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/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.
- */
-export class TraceLogger {
-  /**
-   * @param {object} opts
-   * @param {string} opts.ledgerPath - absolute path to the NDJSON ledger
-   *   the bus is writing (matches `LedgerWriter.ledgerPath`).
-   * @param {number} [opts.epicId] - included in the companion header.
-   */
-  constructor(opts) {
-    if (
-      !opts ||
-      typeof opts.ledgerPath !== 'string' ||
-      opts.ledgerPath.length === 0
-    ) {
-      throw new TypeError('TraceLogger: opts.ledgerPath is required');
-    }
-    this._ledgerPath = opts.ledgerPath;
-    this._companionPath = path.join(
-      path.dirname(this._ledgerPath),
-      'lifecycle.md',
-    );
-    this._epicId = opts.epicId ?? null;
-  }
-
-  get companionPath() {
-    return this._companionPath;
-  }
-
-  /**
-   * Re-render the companion from the on-disk ledger. Idempotent.
-   */
-  rerender() {
-    let text;
-    try {
-      text = readFileSync(this._ledgerPath, 'utf8');
-    } catch (err) {
-      if (err && err.code === 'ENOENT') return; // ledger not yet written
-      throw err;
-    }
-    const markdown = render(text, { epicId: this._epicId });
-    writeFileSync(this._companionPath, markdown, 'utf8');
-  }
-
-  /**
-   * Register as a wildcard observer. After every emit, re-read the
-   * ledger and re-render the companion.
-   *
-   * The companion render is a best-effort projection: a failed render
-   * (malformed ledger, transient write error, full disk) MUST NOT abort
-   * the in-flight bus emit. Because wildcard listeners run inside the
-   * `emit()` try/catch (see `bus.js`), an unguarded throw here would
-   * short-circuit the emit and propagate to the orchestration caller.
-   * We instead log the failure to stderr and swallow it, degrading to a
-   * stale `lifecycle.md` companion — the canonical NDJSON ledger is
-   * unaffected, so resume and downstream consumers are not broken.
-   */
-  register(bus) {
-    if (!bus || typeof bus.on !== 'function') {
-      throw new TypeError('TraceLogger.register: bus must expose .on()');
-    }
-    bus.on('*', () => {
-      try {
-        this.rerender();
-      } catch (err) {
-        const message = err && err.message ? err.message : String(err);
-        process.stderr.write(
-          `[TraceLogger] companion rerender failed (degrading to stale lifecycle.md): ${message}\n`,
-        );
-      }
-    });
-  }
-}