mandrel 1.57.0

package/.agents/scripts/lib/orchestration/lifecycle/emit-story-dispatch-end.js

@@ -0,0 +1,147 @@
+/**
+ * emit-story-dispatch-end.js — Story #3900.
+ *
+ * Programmatic helper that appends a single `story.dispatch.end` NDJSON
+ * record to `temp/epic-<id>/lifecycle.ndjson` for one recorded Story.
+ *
+ * Why this exists:
+ *   The `wave-tick.js` in-flight reconciler (and the `--check-idle`
+ *   watchdog) compute "in-flight" Stories as those carrying a
+ *   `story.dispatch.start` record WITHOUT a matching `story.dispatch.end`.
+ *   Before this Story the only producer of `story.dispatch.end` was
+ *   `lib/orchestration/wave-session.js`, which nothing imports outside
+ *   tests — so every dispatched Story stayed "in-flight" forever and the
+ *   idle watchdog flagged completed Stories as stalled. The host-LLM driven
+ *   `/epic-deliver` path closes a wave through `epic-execute-record-wave.js`,
+ *   so that CLI is the correct place to emit the matching dispatch-end per
+ *   recorded Story.
+ *
+ * The emit mirrors the thin direct-append shape of
+ * `lifecycle-emit-story-dispatch.js` (start) and `emit-story-heartbeat.js`:
+ * one schema-validated `emitted`-kind record, no full listener chain. It is
+ * best-effort at the call site — a failed append must not block the wave
+ * loop, so callers wrap it and log.
+ *
+ * Schema contract (story.dispatch.end.schema.json):
+ *   { storyId, outcome: done|blocked|failed|skipped, durationMs }
+ */
+
+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 } from '../../config/temp-paths.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const SCHEMA_PATH = path.resolve(
+  __dirname,
+  '..',
+  '..',
+  '..',
+  '..',
+  'schemas',
+  'lifecycle',
+  'story.dispatch.end.schema.json',
+);
+
+const VALID_OUTCOMES = new Set(['done', 'blocked', 'failed', 'skipped']);
+
+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;
+}
+
+/**
+ * Append exactly one `story.dispatch.end` NDJSON record to the Epic ledger.
+ *
+ * @param {object} opts
+ * @param {number} opts.epicId       Parent Epic — required for the ledger path.
+ * @param {number} opts.storyId      Story whose dispatch settled.
+ * @param {string} opts.outcome      One of done|blocked|failed|skipped.
+ * @param {number} [opts.durationMs=0]  Wall-clock dispatch duration in ms.
+ *                                       Defaults to 0 when the host loop does
+ *                                       not track per-Story timing.
+ * @param {string} [opts.timestamp]  ISO-8601 wall clock. Defaults to now().
+ * @param {object} [opts.config]     Optional resolved config for tempRoot.
+ * @param {string} [opts.ledgerPath] Override for tests.
+ * @returns {{ ledgerPath: string, record: object }}
+ */
+export function emitStoryDispatchEnd(opts) {
+  const {
+    epicId,
+    storyId,
+    outcome,
+    durationMs = 0,
+    timestamp = new Date().toISOString(),
+    config,
+    ledgerPath: ledgerPathOverride,
+  } = opts ?? {};
+
+  if (!Number.isInteger(epicId) || epicId < 1) {
+    throw new Error('emitStoryDispatchEnd: epicId must be a positive integer');
+  }
+  if (!Number.isInteger(storyId) || storyId < 1) {
+    throw new Error('emitStoryDispatchEnd: storyId must be a positive integer');
+  }
+  if (!VALID_OUTCOMES.has(outcome)) {
+    throw new Error(
+      `emitStoryDispatchEnd: outcome "${outcome}" must be one of: ${[...VALID_OUTCOMES].join(', ')}`,
+    );
+  }
+  if (!Number.isInteger(durationMs) || durationMs < 0) {
+    throw new Error(
+      'emitStoryDispatchEnd: durationMs must be a non-negative integer',
+    );
+  }
+
+  const payload = { storyId, outcome, durationMs };
+
+  const validator = getValidator();
+  if (!validator(payload)) {
+    const detail = (validator.errors ?? [])
+      .map((e) => `${e.instancePath || '/'} ${e.message}`)
+      .join('; ');
+    throw new Error(
+      `emitStoryDispatchEnd: payload failed schema validation: ${detail}`,
+    );
+  }
+
+  const ledgerPath = ledgerPathOverride ?? epicLedgerPath(epicId, config);
+  mkdirSync(path.dirname(ledgerPath), { recursive: true });
+  const record = {
+    kind: 'emitted',
+    ts: timestamp,
+    event: 'story.dispatch.end',
+    payload,
+  };
+  appendFileSync(ledgerPath, `${JSON.stringify(record)}\n`, 'utf8');
+  return { ledgerPath, record };
+}
+
+/**
+ * Map a recorded Story status (`done`/`blocked`/`failed`) to the
+ * `story.dispatch.end` outcome enum. The status taxonomy is a strict subset
+ * of the outcome enum, so the mapping is identity for the three values the
+ * record-wave projection produces. Unknown values throw rather than emit a
+ * schema-invalid record.
+ *
+ * @param {string} status
+ * @returns {string}
+ */
+export function storyStatusToDispatchOutcome(status) {
+  if (!VALID_OUTCOMES.has(status)) {
+    throw new Error(
+      `storyStatusToDispatchOutcome: unknown story status "${status}"`,
+    );
+  }
+  return status;
+}

package/.agents/scripts/lib/orchestration/lifecycle/emit-story-heartbeat.js

@@ -0,0 +1,155 @@
+/**
+ * emit-story-heartbeat.js — Story #3057.
+ *
+ * Programmatic helper that appends a single `story.heartbeat` NDJSON
+ * record to `temp/epic-<id>/lifecycle.ndjson` during a Story's
+ * implementation loop. Story-implementation phases can run for many
+ * minutes between dispatch and merge; `story.heartbeat` is the
+ * inspectable in-progress signal the host-loop reconciler reads to
+ * confirm forward progress.
+ *
+ * Distinct from:
+ *   - `story.dispatch.start` — one per Story per dispatch attempt
+ *     (lifecycle-emit-story-dispatch.js).
+ *   - `story.merged` — one per Story per close, post-merge.
+ *
+ * The emit is best-effort: a failure to append (missing schema,
+ * unreachable ledger path, validation error) MUST NOT block the phase
+ * transition itself. Callers should catch and log via the script's
+ * Logger; the heartbeat is observability, not state.
+ *
+ * Schema contract (story.heartbeat.schema.json):
+ *   { event, storyId, epicId, phase, timestamp, operator? }
+ *
+ * The schema declares `additionalProperties: false`, so this emitter's
+ * signature is deliberately narrow: only the schema-allowed fields are
+ * accepted. Earlier per-child counters (`taskId`, `tasksDone`,
+ * `tasksTotal`, `currentTaskId`) were dropped under Epic #3078's
+ * 3-tier hard cutover — they would fail strict validation and have no
+ * meaning now that the Story is the leaf execution unit with no child
+ * tickets. The optional `operator` field (Story #3480) records the handle
+ * holding the assignee-as-lease claim; it is included only when supplied so
+ * pre-lease callers continue to emit the unchanged shape.
+ */
+
+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 } from '../../config/temp-paths.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const SCHEMA_PATH = path.resolve(
+  __dirname,
+  '..',
+  '..',
+  '..',
+  '..',
+  'schemas',
+  'lifecycle',
+  'story.heartbeat.schema.json',
+);
+
+const VALID_PHASES = new Set([
+  'init',
+  'implementing',
+  'closing',
+  'blocked',
+  'done',
+]);
+
+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;
+}
+
+/**
+ * Append exactly one `story.heartbeat` NDJSON record to the Epic ledger.
+ *
+ * @param {object} opts
+ * @param {number} opts.storyId   Story whose implementation loop is firing.
+ * @param {number} opts.epicId    Parent Epic — required for the ledger path.
+ * @param {string} [opts.phase='implementing']
+ *                                One of init|implementing|closing|blocked|done.
+ * @param {string} [opts.timestamp]   ISO-8601 wall clock. Defaults to now().
+ * @param {string} [opts.operator]    Optional lease-owner handle (Story #3480).
+ *                                    When a non-empty string is supplied it is
+ *                                    recorded on the payload so the
+ *                                    assignee-as-lease primitive can decide a
+ *                                    claim's liveness from the latest heartbeat
+ *                                    for a given owner. Omitted when absent so
+ *                                    pre-lease callers emit the unchanged shape.
+ * @param {object} [opts.config]      Optional resolved config for tempRoot.
+ * @param {string} [opts.ledgerPath]  Override for tests.
+ * @returns {{ ledgerPath: string, record: object }}
+ */
+export function emitStoryHeartbeat(opts) {
+  const {
+    storyId,
+    epicId,
+    phase = 'implementing',
+    timestamp = new Date().toISOString(),
+    operator,
+    config,
+    ledgerPath: ledgerPathOverride,
+  } = opts ?? {};
+
+  if (!Number.isInteger(storyId) || storyId < 1) {
+    throw new Error('emitStoryHeartbeat: storyId must be a positive integer');
+  }
+  if (!Number.isInteger(epicId) || epicId < 1) {
+    throw new Error('emitStoryHeartbeat: epicId must be a positive integer');
+  }
+  if (!VALID_PHASES.has(phase)) {
+    throw new Error(
+      `emitStoryHeartbeat: phase "${phase}" must be one of: ${[...VALID_PHASES].join(', ')}`,
+    );
+  }
+  if (
+    operator !== undefined &&
+    (typeof operator !== 'string' || operator.length === 0)
+  ) {
+    throw new Error(
+      'emitStoryHeartbeat: operator, when supplied, must be a non-empty string',
+    );
+  }
+
+  const payload = {
+    event: 'story.heartbeat',
+    storyId,
+    epicId,
+    phase,
+    timestamp,
+    ...(operator !== undefined ? { operator } : {}),
+  };
+
+  const validator = getValidator();
+  if (!validator(payload)) {
+    const detail = (validator.errors ?? [])
+      .map((e) => `${e.instancePath || '/'} ${e.message}`)
+      .join('; ');
+    throw new Error(
+      `emitStoryHeartbeat: payload failed schema validation: ${detail}`,
+    );
+  }
+
+  const ledgerPath = ledgerPathOverride ?? epicLedgerPath(epicId, config);
+  mkdirSync(path.dirname(ledgerPath), { recursive: true });
+  const record = {
+    kind: 'emitted',
+    ts: timestamp,
+    event: 'story.heartbeat',
+    payload,
+  };
+  appendFileSync(ledgerPath, `${JSON.stringify(record)}\n`, 'utf8');
+  return { ledgerPath, record };
+}

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

@@ -0,0 +1,226 @@
+// .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';
+
+/**
+ * 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/epic-<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 = path.join(this._tempRoot, `epic-${this._epicId}`);
+    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/epic-<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

@@ -0,0 +1,69 @@
+# 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
+`/epic-deliver`'s Phase 6 / 7.5 / 8 / 8.5 markdown invocations:
+
+- `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`.
+- `checkpoint-pointer-writer.js` — persists `{ lastCompletedSeqId, phase }`
+  on every `*.end` event.
+
+Two further listeners are activated outside the close-tail chain by their
+own CLI entrypoints rather than `buildDefaultListenerChain`:
+
+- `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`.
+
+## 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.
+
+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:
+
+- 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`.
+
+Listeners MUST NOT:
+
+- `bus.emit()` from inside a listener body (sequential mediator
+  contract — the bus cannot re-entry safely),
+- import the 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.