mandrel 1.57.0

package/.agents/scripts/lib/orchestration/git-cleanup/phases/render.js

@@ -0,0 +1,214 @@
+/**
+ * render.js — pure rendering helpers for git-cleanup (Story #2466).
+ *
+ * Owns the text + JSON envelope renderers and the `computeExitCode`
+ * helper. Extracted verbatim from `git-cleanup.js` so every named export
+ * keeps its contract.
+ *
+ * @module lib/orchestration/git-cleanup/phases/render
+ */
+
+const TAG = '[git-cleanup]';
+
+/** Pure: render the dry-run plan as the operator-facing text block. */
+export function renderDryRun(plan, opts = {}) {
+  const { baseBranch = null } = opts;
+  const lines = [
+    `${TAG} DRY RUN (nothing deleted) — ${plan.candidates.length} candidate(s)`,
+  ];
+  if (plan.candidates.length === 0) {
+    lines.push('  (no merged branches to clean up)');
+  } else {
+    for (const c of plan.candidates) {
+      const pr = c.prNumber ? `PR #${c.prNumber}` : c.detectedBy;
+      const wt = c.hasWorktree ? ` (worktree: ${c.worktreePath})` : '';
+      const remoteOnly = c.localExists === false ? ' (remote-only)' : '';
+      lines.push(`  • ${c.branch} — ${pr}${wt}${remoteOnly}`);
+    }
+  }
+  const skipped = plan.skipped ?? [];
+  const currentHeadSkip = skipped.find((s) => s.reason === 'current-head');
+  if (currentHeadSkip) {
+    const hint = baseBranch
+      ? `checkout ${baseBranch} first to include this branch`
+      : 'checkout the base branch first to include this branch';
+    lines.push(
+      `${TAG} ⓘ ${currentHeadSkip.branch} skipped — current HEAD (${hint})`,
+    );
+  }
+  for (const skip of skipped) {
+    const line = renderLatestPrSkipLine(skip);
+    if (line) lines.push(line);
+  }
+  return lines;
+}
+
+/**
+ * Pure: render a single latest-PR-state skip line. Returns null when the
+ * skip reason is not one of the latest-PR family — `renderDryRun` filters
+ * by truthy return value so unrelated skip reasons (`protected`,
+ * `current-head`, `filtered`, `not-merged`) stay quiet.
+ *
+ * @param {{ branch: string, reason: string, prNumber?: number, tipSha?: string, mergedSha?: string }} skip
+ * @returns {string | null}
+ */
+export function renderLatestPrSkipLine(skip) {
+  if (!skip) return null;
+  const prRef = skip.prNumber ? `PR #${skip.prNumber}` : 'latest PR';
+  if (skip.reason === 'latest-pr-closed-not-merged') {
+    return `${TAG} ⏭️  ${skip.branch} skipped — ${prRef} was closed without merging`;
+  }
+  if (skip.reason === 'latest-pr-open') {
+    return `${TAG} ⏭️  ${skip.branch} skipped — ${prRef} is still open`;
+  }
+  if (skip.reason === 'tip-diverged-from-merge') {
+    const tip = skip.tipSha ? skip.tipSha.slice(0, 7) : '<unknown>';
+    const merged = skip.mergedSha ? skip.mergedSha.slice(0, 7) : '<unknown>';
+    return `${TAG} ⏭️  ${skip.branch} skipped — tip ${tip} diverges from ${prRef}'s merged ${merged} (post-merge force-push)`;
+  }
+  if (skip.reason === 'latest-pr-unknown-state') {
+    return `${TAG} ⏭️  ${skip.branch} skipped — ${prRef} has an unrecognized state`;
+  }
+  return null;
+}
+
+/** Pure: render a per-branch execution line. */
+export function renderExecutionLine(entry, scope) {
+  const icon = entry.ok ? '✅' : '❌';
+  const label = scope.padEnd(8);
+  const tag =
+    scope === 'local' || scope === 'remote' ? entry.branch : entry.path;
+  const note = entry.alreadyGone
+    ? ' (already gone)'
+    : entry.dirty
+      ? ' (forced — was dirty)'
+      : '';
+  return `${TAG} ${icon} ${label} ${tag}${note}`;
+}
+
+/** Pure: render the optional prune line. */
+export function renderPruneLine(prune) {
+  if (!prune?.attempted) return null;
+  if (!prune.ok) {
+    return `${TAG} ❌ prune    ${prune.remote} (${prune.stderr ?? 'failed'})`;
+  }
+  if (prune.pruned.length === 0) {
+    return `${TAG} ✅ prune    ${prune.remote} (no stale refs)`;
+  }
+  const list = prune.pruned.map((n) => `${prune.remote}/${n}`).join(', ');
+  return `${TAG} ✅ prune    ${prune.remote} (dropped ${prune.pruned.length} stale ref(s): ${list})`;
+}
+
+/**
+ * Pure: render a single deferred-worktree line. A lock-class
+ * worktree-removal failure (Windows file lock on an already-merged
+ * branch's directory) is non-fatal — the branch ref was still reaped and
+ * the directory is handed off to the pending-cleanup sweep. Returns the
+ * operator-facing warning so the deferred signal is visible even on a
+ * clean (`ok: true`) run.
+ *
+ * @param {{ branch?: string, path: string, pendingCleanup?: object|null }} entry
+ * @returns {string}
+ */
+export function renderDeferredLine(entry) {
+  const ref = entry.branch ? `${entry.branch} ` : '';
+  const handoff = entry.pendingCleanup
+    ? ' (deferred to pending-cleanup sweep)'
+    : ' (deferred)';
+  return `${TAG} ⚠️ deferred ${ref}${entry.path} — worktree locked; ref reaped${handoff}`;
+}
+
+/** Pure: render the trailing summary line. */
+export function renderExecutionSummary(result) {
+  if (!result.ok) {
+    return `${TAG} ❌ ${result.failures.length} failure(s) during cleanup.`;
+  }
+  const prunedCount = result.prune?.pruned?.length ?? 0;
+  const pruneNote =
+    prunedCount > 0 ? ` + ${prunedCount} stale tracking ref(s)` : '';
+  const deferredCount = result.deferred?.length ?? 0;
+  const deferredNote =
+    deferredCount > 0
+      ? ` (${deferredCount} worktree(s) deferred to sweep)`
+      : '';
+  return `${TAG} ✅ Reaped ${result.local.length} local + ${result.remote.length} remote + ${result.worktrees.length} worktree(s)${pruneNote}.${deferredNote}`;
+}
+
+const EMPTY_RESULT = Object.freeze({
+  worktrees: [],
+  local: [],
+  remote: [],
+  prune: null,
+  failures: [],
+  deferred: [],
+  ok: true,
+});
+
+/** Pure: build the JSON envelope emitted in `--json` mode. */
+export function buildJsonEnvelope({
+  dryRun,
+  baseBranch,
+  plan,
+  result,
+  fastForward = null,
+  prune = null,
+  stashes = null,
+}) {
+  const r = result ?? EMPTY_RESULT;
+  return {
+    dryRun,
+    baseBranch,
+    candidates: plan.candidates,
+    skipped: plan.skipped,
+    worktrees: r.worktrees,
+    local: r.local,
+    remote: r.remote,
+    prune: r.prune ?? prune ?? null,
+    fastForward,
+    stashes,
+    failures: r.failures,
+    deferred: r.deferred ?? [],
+    ok: r.ok,
+  };
+}
+
+function legacyExitCode(plan, result) {
+  if ((plan?.candidates?.length ?? 0) === 0) return 2;
+  if (result && !result.ok) return 1;
+  return 0;
+}
+
+/**
+ * Pure: derive the process exit code. Supports both the legacy
+ * `(plan, result)` signature and the new multi-phase context object.
+ *
+ * @param {{ candidates?: Array, branchesPlan?: object, branchesResult?: object, fastForward?: object, prune?: object, stashes?: object } | { candidates: Array }} ctx
+ * @param {{ ok: boolean } | null | undefined} [legacyResult]
+ * @returns {0 | 1 | 2}
+ */
+export function computeExitCode(ctx, legacyResult) {
+  if (legacyResult !== undefined || Array.isArray(ctx?.candidates)) {
+    return legacyExitCode(ctx, legacyResult);
+  }
+  const {
+    branchesPlan = null,
+    branchesResult = null,
+    fastForward = null,
+    prune = null,
+    stashes = null,
+  } = ctx ?? {};
+  const anyFailure =
+    (branchesResult && !branchesResult.ok) ||
+    (fastForward && !fastForward.ok) ||
+    (prune && !prune.ok) ||
+    (stashes && !stashes.ok);
+  if (anyFailure) return 1;
+  const anyWork =
+    (branchesPlan && branchesPlan.candidates.length > 0) ||
+    fastForward?.applied ||
+    (prune && (prune.pruned?.length ?? 0) > 0) ||
+    (stashes &&
+      (stashes.actions ?? []).some((a) => a.action === 'drop' && a.dropped));
+  if (!anyWork) return 2;
+  return 0;
+}

package/.agents/scripts/lib/orchestration/git-cleanup/phases/stashes.js

@@ -0,0 +1,137 @@
+/**
+ * stashes.js — stash-triage phase of git-cleanup (Story #2466).
+ *
+ * Owns `parseStashList`, `planStashes`, `executeStashes`, `stashRefIndex`,
+ * and `buildAllowlistDecider`. Extracted verbatim from `git-cleanup.js`.
+ *
+ * @module lib/orchestration/git-cleanup/phases/stashes
+ */
+
+import { gitSpawn } from '../../../git-utils.js';
+import { Logger } from '../../../Logger.js';
+import { dropStash } from './git-probes.js';
+
+const TAG = '[git-cleanup]';
+
+/**
+ * Pure: parse `git stash list --format='%gd|%ci|%s'` output into
+ * structured stash entries.
+ */
+export function parseStashList(stdout) {
+  const out = [];
+  for (const raw of (stdout ?? '').split('\n')) {
+    const line = raw.trim();
+    if (!line) continue;
+    const idx = line.indexOf('|');
+    if (idx < 0) continue;
+    const ref = line.slice(0, idx).trim();
+    const rest = line.slice(idx + 1);
+    const idx2 = rest.indexOf('|');
+    if (idx2 < 0) continue;
+    const createdAt = rest.slice(0, idx2).trim();
+    const message = rest.slice(idx2 + 1).trim();
+    if (!ref) continue;
+    out.push({ ref, createdAt, message });
+  }
+  return out;
+}
+
+/* node:coverage ignore next */
+function listStashes(cwd) {
+  const res = gitSpawn(cwd, 'stash', 'list', '--format=%gd|%ci|%s');
+  if (res.status !== 0) return [];
+  return parseStashList(res.stdout);
+}
+
+/** Plan the stash phase: enumerate stashes, no mutation. */
+export function planStashes(ctx) {
+  const { cwd, stashListerFn = listStashes } = ctx;
+  return { stashes: stashListerFn(cwd) };
+}
+
+/**
+ * Pure: extract the numeric index from a stash ref like `stash@{3}`.
+ */
+export function stashRefIndex(ref) {
+  const m = /^stash@\{(\d+)\}$/.exec(ref ?? '');
+  return m ? Number(m[1]) : -1;
+}
+
+/**
+ * Build a non-interactive `decideFn` that drops stashes whose refs
+ * appear in `allowlist`, and keeps every other stash. Used in JSON /
+ * --yes mode.
+ */
+export function buildAllowlistDecider(allowlist) {
+  const set = new Set(allowlist ?? []);
+  return (entry) => (set.has(entry.ref) ? 'drop' : 'keep');
+}
+
+function applyDecision({
+  s,
+  decideFn,
+  dropFn,
+  cwd,
+  actions,
+  failures,
+  logger,
+}) {
+  const decision = decideFn(s);
+  if (decision === 'quit') {
+    actions.push({ ref: s.ref, action: 'quit' });
+    return { quit: true };
+  }
+  if (decision === 'keep') {
+    actions.push({ ref: s.ref, action: 'keep' });
+    return { quit: false };
+  }
+  const res = dropFn(s.ref, cwd);
+  if (res.ok) {
+    logger.info?.(`${TAG} ✅ dropped ${s.ref}: ${s.message}`);
+    actions.push({ ref: s.ref, action: 'drop', dropped: true });
+  } else {
+    logger.warn?.(`${TAG} ❌ drop ${s.ref} failed: ${res.stderr}`);
+    actions.push({
+      ref: s.ref,
+      action: 'drop',
+      dropped: false,
+      stderr: res.stderr,
+    });
+    failures.push({ ref: s.ref, stderr: res.stderr });
+  }
+  return { quit: false };
+}
+
+/**
+ * Execute the stash phase. Dispatches per-stash via the injected
+ * `decideFn` so interactive prompts (readline) and non-interactive
+ * allowlists (`--drop-stashes <ref>`) share the same engine.
+ */
+export function executeStashes(ctx) {
+  const { cwd, stashes, decideFn, dropFn = dropStash, logger = Logger } = ctx;
+  const actions = [];
+  const failures = [];
+  let quit = false;
+  // Drop stashes high-index-first so the indices of remaining stashes
+  // stay stable across calls — git renumbers from the top of the stack.
+  const ordered = [...stashes].sort(
+    (a, b) => stashRefIndex(b.ref) - stashRefIndex(a.ref),
+  );
+  for (const s of ordered) {
+    if (quit) {
+      actions.push({ ref: s.ref, action: 'quit' });
+      continue;
+    }
+    const out = applyDecision({
+      s,
+      decideFn,
+      dropFn,
+      cwd,
+      actions,
+      failures,
+      logger,
+    });
+    if (out.quit) quit = true;
+  }
+  return { ok: failures.length === 0, actions, failures };
+}

package/.agents/scripts/lib/orchestration/label-transitions.js

@@ -0,0 +1,43 @@
+/**
+ * label-transitions.js — readability wrappers over `transitionTicketState`.
+ *
+ * These are deliberately thin: each helper names the *target* state and
+ * forwards to the underlying SDK call. They exist so that init / close /
+ * deliver-tail call sites read as prose ("toExecuting(provider, taskId)")
+ * instead of forcing readers to parse the `STATE_LABELS.X` constant at
+ * every call site.
+ *
+ * Not an abstraction — the underlying `transitionTicketState` remains the
+ * authoritative single-ticket transition path. Opts are forwarded verbatim.
+ */
+
+import { STATE_LABELS, transitionTicketState } from './ticketing.js';
+
+/** Transition a ticket to `agent::executing`. */
+export function toExecuting(provider, ticketId, opts) {
+  return transitionTicketState(
+    provider,
+    ticketId,
+    STATE_LABELS.EXECUTING,
+    opts,
+  );
+}
+
+/**
+ * Transition an array of tickets to `agent::done`, in order. Each call
+ * triggers its own cascade (via `transitionTicketState`). Failures for
+ * individual tickets propagate — callers that need per-ticket tolerance
+ * should use `batchTransitionTickets` instead.
+ *
+ * @param {object} provider
+ * @param {number[]} ticketIds
+ * @param {object} [opts]
+ */
+export async function toDone(provider, ticketIds, opts) {
+  if (!Array.isArray(ticketIds)) {
+    throw new TypeError('toDone: ticketIds must be an array');
+  }
+  for (const id of ticketIds) {
+    await transitionTicketState(provider, id, STATE_LABELS.DONE, opts);
+  }
+}

package/.agents/scripts/lib/orchestration/lifecycle/bus.js

@@ -0,0 +1,309 @@
+// .agents/scripts/lib/orchestration/lifecycle/bus.js
+/**
+ * Lifecycle event bus — sequential awaited mediator.
+ *
+ * The bus is the only authorized emitter of typed lifecycle events. It is a
+ * mediator (not pub/sub): listeners run in registration order, awaited,
+ * and a throw in any listener short-circuits the remaining listeners and
+ * propagates to the caller. There is no Promise.all over listener arrays
+ * — that pattern breaks repeatability and is forbidden by the lint rule in
+ * `biome.json`.
+ *
+ * Wildcard subscriptions (`bus.on('*', fn)`) are permitted for trace /
+ * heartbeat observers. They MUST NOT perform side effects on the system
+ * under orchestration; the firewall against state-mutating imports in
+ * wildcard listeners is documented in
+ * `.agents/scripts/lib/orchestration/lifecycle/listeners/README.md`.
+ *
+ * Schema validation: `emit()` validates the payload against the schema at
+ * `.agents/schemas/lifecycle/<event>.schema.json` BEFORE invoking any
+ * listener. Validation failures throw immediately; no `emitted` ledger
+ * record is written, no listener runs. This guarantees that every record
+ * in the ledger carries a payload conformant to its event schema.
+ *
+ * The bus does NOT write the ledger directly. `LedgerWriter` registers as
+ * the first listener on every event and handles persistence. This keeps
+ * the bus a pure mediator and makes the ledger boundary easy to fake in
+ * tests.
+ */
+
+import { 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';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const DEFAULT_SCHEMA_DIR = path.resolve(
+  __dirname,
+  '..',
+  '..',
+  '..',
+  '..',
+  'schemas',
+  'lifecycle',
+);
+
+/**
+ * Compile a validator for a single event by loading its schema lazily. The
+ * result is cached per Bus instance so repeated emits of the same event
+ * don't re-parse JSON.
+ */
+function buildValidator(ajv, schemaDir, event) {
+  const schemaPath = path.join(schemaDir, `${event}.schema.json`);
+  const schema = JSON.parse(readFileSync(schemaPath, 'utf8'));
+  return ajv.compile(schema);
+}
+
+/**
+ * Format AJV error array into a single-line message suitable for a thrown
+ * Error. Reviewers prefer a compact summary over a stringified blob.
+ */
+function formatAjvErrors(errors) {
+  if (!Array.isArray(errors) || errors.length === 0) return 'invalid payload';
+  return errors
+    .map((e) => `${e.instancePath || '/'} ${e.message}`.trim())
+    .join('; ');
+}
+
+export class Bus {
+  /**
+   * @param {object} [opts]
+   * @param {string} [opts.schemaDir] absolute path to the lifecycle schema
+   *   directory. Defaults to `.agents/schemas/lifecycle/` resolved against
+   *   this module's location. Tests pass a fixture directory.
+   */
+  constructor(opts = {}) {
+    this._schemaDir = opts.schemaDir ?? DEFAULT_SCHEMA_DIR;
+    this._ajv = new Ajv2020({ allErrors: true });
+    addFormats(this._ajv);
+    /** @type {Map<string, Array<{ fn: Function, wildcard: boolean }>>} */
+    this._listeners = new Map();
+    /** @type {Array<{ fn: Function, wildcard: boolean }>} */
+    this._wildcards = [];
+    /** @type {Map<string, Function>} cached AJV validators. */
+    this._validators = new Map();
+    this._nextSeqId = 1;
+    /**
+     * Hooks that run AFTER schema validation + seqId assignment but
+     * BEFORE any listener. LedgerWriter installs an `onEmitted` hook
+     * here so its `emitted` ledger line lands on disk before downstream
+     * listeners execute (the resume contract depends on this).
+     *
+     * Hooks are NOT regular listeners and intentionally not exposed via
+     * `bus.on()` — they are a privileged seam used by the ledger writer
+     * and (later) the resume coordinator. Each hook receives the same
+     * `{ event, seqId, payload }` context shape a listener sees.
+     *
+     * Hooks run sequentially with await, in registration order. A throw
+     * from a hook is treated like a thrown listener — it propagates to
+     * the caller and short-circuits everything after it.
+     *
+     * @type {Array<(ctx: {event: string, seqId: number, payload: object}) => unknown | Promise<unknown>>}
+     */
+    this._onEmittedHooks = [];
+    /**
+     * Hooks that run AFTER every listener resolves successfully — the
+     * `completed` boundary. LedgerWriter installs an `onCompleted` hook
+     * to write its `completed` ledger line. Same execution contract as
+     * `_onEmittedHooks` (sequential, awaited, registration order).
+     *
+     * @type {Array<(ctx: {event: string, seqId: number, payload: object}) => unknown | Promise<unknown>>}
+     */
+    this._onCompletedHooks = [];
+    /**
+     * Hooks that run when a listener throws — the `failed` boundary.
+     * They receive the same context PLUS the error and the inferred
+     * listener name (best-effort; `bus` does not currently annotate
+     * which listener threw, but the LedgerWriter hook tags `unknown`
+     * when no annotation is present).
+     *
+     * @type {Array<(ctx: {event: string, seqId: number, payload: object, listener: string, error: Error}) => unknown | Promise<unknown>>}
+     */
+    this._onFailedHooks = [];
+  }
+
+  /**
+   * Privileged seam — install a hook that runs after schema validation
+   * and seqId assignment but BEFORE any listener for the event. Used by
+   * LedgerWriter to land the `emitted` ledger record on disk before any
+   * downstream side effect runs (resume contract).
+   */
+  onEmitted(fn) {
+    if (typeof fn !== 'function') {
+      throw new TypeError('Bus.onEmitted: hook must be a function');
+    }
+    this._onEmittedHooks.push(fn);
+  }
+
+  /**
+   * Privileged seam — install a hook that runs AFTER every listener for
+   * the event resolves. Used by LedgerWriter to land the `completed`
+   * ledger record.
+   */
+  onCompleted(fn) {
+    if (typeof fn !== 'function') {
+      throw new TypeError('Bus.onCompleted: hook must be a function');
+    }
+    this._onCompletedHooks.push(fn);
+  }
+
+  /**
+   * Privileged seam — install a hook that runs when a listener throws.
+   * Used by LedgerWriter to land the `failed` ledger record before
+   * re-propagating.
+   */
+  onFailed(fn) {
+    if (typeof fn !== 'function') {
+      throw new TypeError('Bus.onFailed: hook must be a function');
+    }
+    this._onFailedHooks.push(fn);
+  }
+
+  /**
+   * Register a listener. Use `event === '*'` for a wildcard observer; the
+   * `wildcard: true` flag is set on the listener record so the lint rule
+   * (and downstream reviewers) can identify observer-only listeners.
+   *
+   * Returns an unsubscribe function for symmetry with conventional emitter
+   * APIs; the runner doesn't currently use it, but tests do.
+   */
+  on(event, fn) {
+    if (typeof fn !== 'function') {
+      throw new TypeError('Bus.on: listener must be a function');
+    }
+    if (typeof event !== 'string' || event.length === 0) {
+      throw new TypeError('Bus.on: event must be a non-empty string');
+    }
+    const record = { fn, wildcard: event === '*' };
+    if (event === '*') {
+      this._wildcards.push(record);
+      return () => {
+        this._wildcards = this._wildcards.filter((r) => r !== record);
+      };
+    }
+    const list = this._listeners.get(event) ?? [];
+    list.push(record);
+    this._listeners.set(event, list);
+    return () => {
+      const next = (this._listeners.get(event) ?? []).filter(
+        (r) => r !== record,
+      );
+      if (next.length === 0) this._listeners.delete(event);
+      else this._listeners.set(event, next);
+    };
+  }
+
+  /**
+   * Get (and cache) the compiled AJV validator for a given event.
+   */
+  _getValidator(event) {
+    let validator = this._validators.get(event);
+    if (!validator) {
+      validator = buildValidator(this._ajv, this._schemaDir, event);
+      this._validators.set(event, validator);
+    }
+    return validator;
+  }
+
+  /**
+   * Emit a typed event.
+   *
+   * Contract (Tech Spec § Bus contract):
+   *   1. validate payload (throw before any listener runs on mismatch);
+   *   2. assign monotonic per-run seqId;
+   *   3. invoke registered named listeners sequentially with await;
+   *   4. invoke wildcard listeners sequentially with await AFTER named
+   *      listeners (observer order);
+   *   5. propagate the first thrown error.
+   *
+   * The bus does NOT write the ledger directly; LedgerWriter is wired in
+   * by the runner as the first registered named listener for every event.
+   *
+   * @param {string} event
+   * @param {object} payload
+   * @returns {Promise<{ seqId: number }>}
+   */
+  async emit(event, payload) {
+    if (typeof event !== 'string' || event.length === 0) {
+      throw new TypeError('Bus.emit: event must be a non-empty string');
+    }
+    const validator = this._getValidator(event);
+    const ok = validator(payload);
+    if (!ok) {
+      const err = new Error(
+        `Bus.emit: schema validation failed for "${event}": ${formatAjvErrors(validator.errors)}`,
+      );
+      err.code = 'BUS_SCHEMA_VALIDATION';
+      err.event = event;
+      err.ajvErrors = validator.errors;
+      throw err;
+    }
+    const seqId = this._nextSeqId;
+    this._nextSeqId += 1;
+    const context = { event, seqId, payload };
+    // Privileged onEmitted hooks run BEFORE any listener — gives
+    // LedgerWriter the seam to land the `emitted` line on disk before
+    // any downstream side effect (resume contract).
+    for (const hook of this._onEmittedHooks) {
+      await hook(context);
+    }
+    const named = this._listeners.get(event) ?? [];
+    try {
+      for (const record of named) {
+        await record.fn(context);
+      }
+      for (const record of this._wildcards) {
+        await record.fn(context);
+      }
+    } catch (err) {
+      // Failed boundary — let writers/observers persist before we
+      // propagate. Listener name annotation is best-effort: when the
+      // error carries `.listener`, we honor it; otherwise we tag
+      // 'unknown' so the ledger record still validates against
+      // `ledger-record.schema.json` (which requires a `listener` field
+      // on failed records).
+      const listener =
+        (err && typeof err.listener === 'string' && err.listener) || 'unknown';
+      const failedCtx = { ...context, listener, error: err };
+      for (const hook of this._onFailedHooks) {
+        // Hook errors are intentionally swallowed here so we don't
+        // mask the originating listener error. The runner only sees the
+        // original throw.
+        try {
+          await hook(failedCtx);
+        } catch (hookErr) {
+          // Surface to stderr so a misbehaving writer doesn't go silent,
+          // but do not propagate — original error wins.
+          process.stderr.write(
+            `[Bus.onFailed] hook threw while recording failure for "${event}" (seqId=${seqId}): ${hookErr.message}\n`,
+          );
+        }
+      }
+      throw err;
+    }
+    // Completed boundary — writers persist `completed` after every
+    // listener resolves.
+    for (const hook of this._onCompletedHooks) {
+      await hook(context);
+    }
+    return { seqId };
+  }
+
+  /**
+   * Inspect the next seqId without emitting. Useful for tests asserting
+   * monotonicity across multiple bus instances or after replay.
+   */
+  peekNextSeqId() {
+    return this._nextSeqId;
+  }
+}
+
+/**
+ * Convenience factory. Lets the runner own bus construction without
+ * importing the class name directly.
+ */
+export function createBus(opts = {}) {
+  return new Bus(opts);
+}