mandrel 1.94.0 → 2.1.0

package/.agents/scripts/lib/orchestration/wave-marker.js

@@ -1,28 +0,0 @@
-/**
- * lib/orchestration/wave-marker.js — Wave-marker regex + parser.
- *
- * Centralizes the regex used to recognize `wave-N-start` / `wave-N-end`
- * structured-comment types so call sites (`ticketing.js`, tool-registry
- * descriptors, tests) all agree on the same bounded pattern.
- *
- * The wave index is bounded to 1-3 digits (0-999) so a malformed or
- * malicious marker cannot trigger pathological regex backtracking on
- * unbounded `\d+`.
- */
-
-export const WAVE_MARKER_RE = /^wave-([0-9]{1,3})-(start|end)$/;
-
-/**
- * Parse a wave-marker string into its components.
- *
- * @param {string} s
- * @returns {{ index: number, phase: 'start' | 'end' } | null}
- *   `null` for any input that is not a string or does not match
- *   {@link WAVE_MARKER_RE}.
- */
-export function parseWaveMarker(s) {
-  if (typeof s !== 'string') return null;
-  const m = WAVE_MARKER_RE.exec(s);
-  if (!m) return null;
-  return { index: Number(m[1]), phase: m[2] };
-}

package/.agents/scripts/lib/orchestration/wave-record-io.js

@@ -1,218 +0,0 @@
-/**
- * wave-record-io.js — impure helpers for the per-Story status recorder CLI
- * (`epic-execute-record-wave.js`): ticket verification, manifest title
- * lookup, and returns reconciliation.
- *
- * These functions all hit the provider and are intentionally kept out of
- * `wave-record-projection.js`, which is the pure helper layer. The parent
- * CLI imports both modules and threads the I/O results through the
- * projection.
- *
- * Story #4155 (Epic #4151) — the wave-batch livelock-recovery path
- * (`planStoryIdsForWave` + the empty-mode-B reconcile) was deleted along
- * with the wave checkpoint it keyed off. Under the ready-set runtime a
- * Story's terminal state is always re-derivable from its live label on the
- * next `tick`, so there is no falsely-`complete` empty wave to recover from
- * — the recorder records exactly the Stories it was handed.
- *
- * Story #3909 — the per-wave dispatch-manifest refresh hop was deleted; the
- * manifest is written once at `epic-deliver-prepare` time and left frozen.
- * `loadManifestTitleMap` reads it for rollup-row titles.
- */
-
-import { Logger } from '../Logger.js';
-import { concurrentMap } from '../util/concurrent-map.js';
-import {
-  reconcileStoryFromGitHub,
-  renderMalformedReturnsFriction,
-} from './epic-runner/sub-agent-return.js';
-import { parseFencedJsonComment } from './structured-comment-parser.js';
-import { findStructuredComment, postStructuredComment } from './ticketing.js';
-import { normalizeReturnsPure } from './wave-record-projection.js';
-
-/**
- * Default cap for {@link verifyWaveResults}. Mirrors the default for
- * `delivery.deliverRunner.verifyConcurrencyCap` in `.agentrc.json`
- * (Epic #3019 Tech Spec §1.4 / Story #3024).
- */
-const DEFAULT_VERIFY_CONCURRENCY_CAP = 4;
-
-/**
- * Normalize raw `--returns` payload (per-Story sub-agent return texts) into
- * the same shape `validateResults` produces. Entries that fail to parse are
- * reconciled from GitHub and recorded as parse failures; the caller posts a
- * single rolled-up friction comment listing every failure.
- *
- * @param {{ provider: object, returns: Array<{ storyId: number, returnText: string }> }} args
- */
-export async function normalizeReturns({ provider, returns } = {}) {
-  return normalizeReturnsPure({
-    returns,
-    reconcile: ({ storyId }) => reconcileStoryFromGitHub({ provider, storyId }),
-  });
-}
-
-/**
- * Verify a single result row: pass-through when the row is not claiming
- * `done`, otherwise re-fetch the ticket and emit either the verified row
- * (label/state agrees) or a `{ verified, discrepancy }` pair when the
- * claim disagrees with GitHub. Network failures surface as
- * `verify-error` discrepancies — they cannot prove the claim either way
- * so the row is downgraded to `failed`.
- *
- * Extracted as a per-row mapper so {@link verifyWaveResults} can run the
- * verifications through {@link concurrentMap} under a bounded cap.
- *
- * @param {object} r
- * @param {{ getTicket: Function }} provider
- * @returns {Promise<{ verified: object, discrepancy: object|null }>}
- */
-async function verifySingleResult(r, provider) {
-  if (r.status !== 'done') {
-    return { verified: r, discrepancy: null };
-  }
-  let ticket;
-  try {
-    ticket = await provider.getTicket(r.storyId, { fresh: true });
-  } catch (err) {
-    const message = err?.message ?? String(err);
-    return {
-      verified: { ...r, status: 'failed', verifyError: message },
-      discrepancy: {
-        storyId: r.storyId,
-        claimed: 'done',
-        actual: 'verify-error',
-        verifyError: message,
-      },
-    };
-  }
-  const labels = ticket?.labels ?? [];
-  const isDone = labels.includes('agent::done') || ticket?.state === 'closed';
-  if (isDone) {
-    return { verified: r, discrepancy: null };
-  }
-  const actualLabel =
-    labels.find((l) => typeof l === 'string' && l.startsWith('agent::')) ??
-    'unknown';
-  return {
-    verified: { ...r, status: 'failed' },
-    discrepancy: { storyId: r.storyId, claimed: 'done', actual: actualLabel },
-  };
-}
-
-/**
- * Re-fetch each Story's actual ticket state and downgrade any
- * `status: 'done'` claim whose ticket has not actually reached
- * `agent::done` (or `state: 'closed'`). Returns the verified rows plus
- * a list of discrepancies for friction reporting.
- *
- * Verification reads each Story ticket fresh (`{ fresh: true }`) so a
- * stale cache cannot mask the discrepancy. A network failure during
- * verification cannot prove the claim either way, so the row is
- * downgraded to `failed` and a `verify-error` discrepancy is recorded —
- * an unverifiable `done` must not be recorded as `done`, which is what the
- * auto-merge predicate reads as "GitHub agrees everything is done."
- *
- * Story #3024 — verification runs through {@link concurrentMap} under a
- * bounded cap (default 4, override via
- * `delivery.deliverRunner.verifyConcurrencyCap`). Per-row failures are
- * captured inside the mapper so one Story's `getTicket` throw cannot
- * abort the whole batch — the per-row try/catch lives in
- * {@link verifySingleResult} and turns into a `verify-error`
- * discrepancy rather than a rejected mapper. Input order is preserved
- * (mapper-index → output-index), matching the previous serial behaviour.
- *
- * @param {{
- *   provider: { getTicket?: Function },
- *   results: Array<object>,
- *   concurrencyCap?: number,
- * }} args
- */
-export async function verifyWaveResults({
-  provider,
-  results,
-  concurrencyCap,
-} = {}) {
-  if (!provider || typeof provider.getTicket !== 'function') {
-    return { verified: results ?? [], discrepancies: [] };
-  }
-  const cap =
-    Number.isInteger(concurrencyCap) && concurrencyCap >= 1
-      ? concurrencyCap
-      : DEFAULT_VERIFY_CONCURRENCY_CAP;
-  const rows = results ?? [];
-  const outcomes = await concurrentMap(
-    rows,
-    (r) => verifySingleResult(r, provider),
-    { concurrency: cap },
-  );
-  const verified = [];
-  const discrepancies = [];
-  for (const out of outcomes) {
-    verified.push(out.verified);
-    if (out.discrepancy) discrepancies.push(out.discrepancy);
-  }
-  return { verified, discrepancies };
-}
-
-/**
- * Best-effort cross-look of the dispatch-manifest titles. Failure to read
- * or parse the manifest is non-fatal — empty title is acceptable.
- *
- * @param {{ provider: object, epicId: number }} args
- */
-export async function loadManifestTitleMap({ provider, epicId }) {
-  try {
-    const comment = await findStructuredComment(
-      provider,
-      epicId,
-      'dispatch-manifest',
-    );
-    if (!comment) return new Map();
-    const payload = parseFencedJsonComment(comment);
-    if (!payload || !Array.isArray(payload.stories)) return new Map();
-    return new Map(
-      payload.stories
-        .map((s) => [Number(s.storyId ?? s.id), String(s.title ?? '')])
-        .filter(([id]) => Number.isFinite(id)),
-    );
-  } catch {
-    return new Map();
-  }
-}
-
-/**
- * Parse / reconcile the per-Story returns (or pass `results` through). Posts
- * a single rolled-up friction comment listing every malformed return on
- * failure — non-fatal if the post itself fails.
- *
- * @returns {Promise<{ resolvedResults: Array, parseFailures: Array }>}
- */
-export async function resolveResolvedResults({
-  provider,
-  epicId,
-  results,
-  returns,
-}) {
-  if (returns == null) {
-    return { resolvedResults: results, parseFailures: [] };
-  }
-  const normalized = await normalizeReturns({ provider, returns });
-  if (normalized.parseFailures.length > 0) {
-    try {
-      const body = renderMalformedReturnsFriction({
-        epicId,
-        failures: normalized.parseFailures,
-      });
-      await postStructuredComment(provider, epicId, 'friction', body);
-    } catch (err) {
-      Logger.error(
-        `[epic-execute-record-wave] Failed to post malformed-return friction on Epic #${epicId}: ${err?.message ?? err}`,
-      );
-    }
-  }
-  return {
-    resolvedResults: normalized.results,
-    parseFailures: normalized.parseFailures,
-  };
-}

package/.agents/scripts/lib/orchestration/wave-record-notifications.js

@@ -1,145 +0,0 @@
-/**
- * wave-record-notifications.js — webhook-emit helpers for the per-Story
- * status recorder CLI (`epic-execute-record-wave.js`).
- *
- * Story #4155 (Epic #4151) — the Epic `/deliver` runtime cut over from the
- * wave-batch scheduler to the continuous ready-set core, so these emits are
- * no longer keyed to a wave boundary. The recorder fires curated webhook
- * events per recorder beat: `epic-started` once (on the first recorded
- * Story), `epic-progress` with the run's done/total counts (re-derived from
- * the checkpoint's flat per-Story `stories` map), and `epic-blocked` when a
- * Story in this beat blocked or failed. Each helper is fire-and-forget —
- * webhook misconfig or a transient Slack outage must not block the loop.
- *
- * These helpers stay in their own module to keep the parent CLI a thin
- * runner shell. They are not part of the pure projection layer; they
- * intentionally call `notify` (or the test-injected stand-in) and Logger.
- */
-
-import { Logger } from '../Logger.js';
-import {
-  emitEpicBlocked,
-  emitEpicProgress,
-  emitEpicStarted,
-} from './epic-runner/progress-reporter/transport.js';
-
-/**
- * Build the notify-bound closure used by the curated webhook emitters. When
- * a test passes `injectedNotify`, we route through it verbatim; otherwise
- * thread `orchestration` + `provider` into the default `notify` so the
- * downstream hook layer has everything it needs.
- */
-export function buildNotifyFn(injectedNotify, config, provider, defaultNotify) {
-  if (injectedNotify) return injectedNotify;
-  return (ticketId, payload, opts = {}) =>
-    defaultNotify(ticketId, payload, {
-      orchestration: config.orchestration,
-      provider,
-      ...opts,
-    });
-}
-
-/**
- * Count Stories in a terminal `done` state across the checkpoint's flat
- * per-Story `stories` status map. Pure helper.
- *
- * @param {Record<string, { status?: string }>|undefined} stories
- * @returns {number}
- */
-export function countDoneStories(stories) {
-  const map = stories && typeof stories === 'object' ? stories : {};
-  let done = 0;
-  for (const rec of Object.values(map)) {
-    if (rec?.status === 'done') done += 1;
-  }
-  return done;
-}
-
-/**
- * Fire the curated webhook events for a recorder beat. Each emit is
- * fire-and-forget (the emit helpers swallow webhook misconfiguration), but
- * we still serialise them so the order is deterministic.
- *
- * - `epic-started` fires exactly once: on the very first recorded Story
- *   (signalled by `firstRecord === true`), before any Story has been
- *   recorded on a prior beat.
- * - `epic-progress` always fires with the run's done/total counts.
- * - `epic-blocked` fires when this beat recorded at least one blocked or
- *   failed Story.
- *
- * @param {{
- *   injectedNotify?: Function,
- *   defaultNotify: Function,
- *   config: object,
- *   provider: object,
- *   epicId: number,
- *   firstRecord: boolean,
- *   stories: Record<string, { status?: string }>,
- *   verified: Array<{ storyId: number, status: string }>,
- *   blockedStoryIds: number[],
- * }} args
- */
-export async function emitRecordNotifications({
-  injectedNotify,
-  defaultNotify,
-  config,
-  provider,
-  epicId,
-  firstRecord,
-  stories,
-  verified,
-  blockedStoryIds,
-}) {
-  const notifyFn = buildNotifyFn(
-    injectedNotify,
-    config,
-    provider,
-    defaultNotify,
-  );
-  const map = stories && typeof stories === 'object' ? stories : {};
-  const totalStories = Object.keys(map).length;
-  const doneStories = countDoneStories(map);
-
-  if (firstRecord) {
-    await emitEpicStarted({
-      notify: notifyFn,
-      epicId,
-      totalStories,
-      logger: Logger,
-    });
-  }
-
-  const blockedIds = Array.isArray(blockedStoryIds) ? blockedStoryIds : [];
-  const failedStoryId = (verified ?? []).find(
-    (r) => r.status === 'failed',
-  )?.storyId;
-  const failingStoryId = blockedIds[0] ?? failedStoryId;
-  const hasFailure = blockedIds.length > 0 || failedStoryId != null;
-
-  if (hasFailure) {
-    await emitEpicBlocked({
-      notify: notifyFn,
-      epicId,
-      reason: blockedIds.length > 0 ? 'story_blocked' : 'story_failed',
-      storyId: failingStoryId,
-      logger: Logger,
-    });
-  }
-
-  await emitEpicProgress({
-    notify: notifyFn,
-    epicId,
-    done: doneStories,
-    total: totalStories,
-    phase: 'wave-loop',
-    openBlockers: hasFailure
-      ? [
-          {
-            reason: blockedIds.length > 0 ? 'story_blocked' : 'story_failed',
-            storyId: failingStoryId,
-          },
-        ]
-      : [],
-    logger: Logger,
-  });
-}

package/.agents/scripts/lib/orchestration/wave-record-projection.js

@@ -1,212 +0,0 @@
-/**
- * wave-record-projection.js — pure helpers for the per-Story status
- * recorder CLI (`epic-execute-record-wave.js`).
- *
- * Story #4155 (Epic #4151) — the Epic `/deliver` runtime cut over from the
- * wave-batch scheduler to the continuous ready-set core. The post-dispatch
- * persistence shrank with it: there is no longer a wave-level aggregation
- * (`aggregateWaveStatus`), a `currentWave` advance (`nextCurrentWave`), a
- * next-action classifier (`classifyWaveOutcome`), or a `projectWaveRecord`
- * splice into a `waves[]` history. The recorder now writes each returned
- * Story's **terminal status** into the checkpoint's flat per-Story `stories`
- * map and re-renders the operator rollup from that map.
- *
- * Every export here is pure: no network I/O, no filesystem reads, no
- * spawning. The parent CLI handles the impure work (provider calls,
- * checkpoint reads/writes, webhook emits) and threads the resolved inputs
- * through these helpers.
- *
- * Group the exports by responsibility:
- *
- *   - Input validation: `validateResults`, `validateReturnsEntry`,
- *     `classifyParsedReturn`, `validateEpic`, `selectInputFlag`.
- *   - Normalization: `normalizeReturnsPure`.
- *   - Projection: `toRollupRow`.
- */
-
-import { parseStoryAgentReturn } from './epic-runner/sub-agent-return.js';
-
-/** Per-Story return statuses we accept off `/deliver` sub-agents. */
-export const VALID_STORY_STATUSES = new Set(['done', 'blocked', 'failed']);
-
-/**
- * Story status → rollup-row state. Post-fan-out every Story is in a
- * terminal state, so we only emit the three terminal forms here.
- */
-export const STORY_STATUS_TO_ROW_STATE = {
-  done: 'done',
-  blocked: 'blocked',
-  failed: 'failed',
-};
-
-/**
- * Validate and normalize an inbound `--results` array into the per-Story
- * shape the rest of the pipeline consumes.
- *
- * @param {unknown} raw
- */
-export function validateResults(raw) {
-  if (!Array.isArray(raw)) {
-    throw new TypeError(
-      'epic-execute-record-wave: --results must be a JSON array of per-Story result objects',
-    );
-  }
-  return raw.map((entry, idx) => {
-    if (!entry || typeof entry !== 'object') {
-      throw new TypeError(
-        `epic-execute-record-wave: results[${idx}] must be an object; got ${typeof entry}`,
-      );
-    }
-    const storyId = Number(entry.storyId ?? entry.id);
-    if (!Number.isInteger(storyId) || storyId <= 0) {
-      throw new TypeError(
-        `epic-execute-record-wave: results[${idx}].storyId must be a positive integer; got ${JSON.stringify(entry.storyId)}`,
-      );
-    }
-    const status = String(entry.status ?? '');
-    if (!VALID_STORY_STATUSES.has(status)) {
-      throw new RangeError(
-        `epic-execute-record-wave: results[${idx}].status "${status}" must be one of: ${[...VALID_STORY_STATUSES].join(', ')}`,
-      );
-    }
-    const out = { storyId, status };
-    if (typeof entry.phase === 'string') out.phase = entry.phase;
-    if (entry.blockerCommentId != null) {
-      out.blockerCommentId = String(entry.blockerCommentId);
-    }
-    return out;
-  });
-}
-
-/**
- * Pure validator for a single `--returns[]` entry. Throws the same
- * `TypeError`s the outer loop used to throw inline, returning a
- * `{ storyId, returnText }` pair on success. Extracted so `normalizeReturns`
- * can route each entry through the same validate → parse → reconcile path
- * without nesting four conditionals deep.
- */
-export function validateReturnsEntry(entry, idx) {
-  if (!entry || typeof entry !== 'object') {
-    throw new TypeError(
-      `epic-execute-record-wave: returns[${idx}] must be an object; got ${typeof entry}`,
-    );
-  }
-  const storyId = Number(entry.storyId ?? entry.id);
-  if (!Number.isInteger(storyId) || storyId <= 0) {
-    throw new TypeError(
-      `epic-execute-record-wave: returns[${idx}].storyId must be a positive integer; got ${JSON.stringify(entry.storyId)}`,
-    );
-  }
-  let returnText;
-  if (typeof entry.returnText === 'string') {
-    returnText = entry.returnText;
-  } else if (entry.returnText == null) {
-    returnText = '';
-  } else {
-    returnText = JSON.stringify(entry.returnText);
-  }
-  return { storyId, returnText };
-}
-
-/**
- * Pure helper: classify a parsed sub-agent return for a known `storyId`.
- * Returns either `{ ok: true, value }` (use the parsed envelope as-is) or
- * `{ ok: false, error }` (caller must reconcile from GitHub and record a
- * parse failure with the message).
- */
-export function classifyParsedReturn(parsed, storyId) {
-  if (parsed.ok && Number(parsed.value.storyId) === storyId) {
-    return { ok: true, value: parsed.value };
-  }
-  const error = parsed.ok
-    ? `parsed envelope storyId ${parsed.value.storyId} disagrees with expected ${storyId}`
-    : parsed.error;
-  return { ok: false, error };
-}
-
-/**
- * Build the rollup-row shape the unified `epic-run-progress` writer
- * consumes. Returns `{ id, title, state, blockerCommentId? }`.
- */
-export function toRollupRow(verified, titleById) {
-  const row = {
-    id: verified.storyId,
-    title: titleById.get(verified.storyId) ?? '',
-    state: STORY_STATUS_TO_ROW_STATE[verified.status] ?? 'unknown',
-  };
-  if (verified.status === 'blocked' && verified.blockerCommentId != null) {
-    row.blockerCommentId = String(verified.blockerCommentId);
-  }
-  return row;
-}
-
-/** Validate the core `{ epicId }` invariant. Throws on bad input. */
-export function validateEpic(epicId) {
-  if (!Number.isInteger(epicId) || epicId <= 0) {
-    throw new TypeError(
-      'runEpicExecuteRecordWave: --epic must be a positive integer',
-    );
-  }
-}
-
-/**
- * Pure helper: enforce the XOR contract between `--results` and `--returns`.
- * Throws on "neither" / "both"; otherwise returns the chosen flag name so
- * the CLI can route to `parseInputArg` with a single branch.
- */
-export function selectInputFlag(hasResults, hasReturns) {
-  if (hasResults && hasReturns) {
-    throw new TypeError(
-      'epic-execute-record-wave: pass --results OR --returns, not both',
-    );
-  }
-  if (!hasResults && !hasReturns) {
-    throw new TypeError(
-      'epic-execute-record-wave: --results or --returns is required',
-    );
-  }
-  return hasResults ? 'results' : 'returns';
-}
-
-/**
- * Normalize a return-text array into the parsed-results shape, returning the
- * envelopes that parsed cleanly and a list of failures for entries that
- * disagreed with their expected `storyId` or were not envelope-shaped. This
- * is the pure half of `normalizeReturns` in the CLI; the impure half
- * (`reconcileStoryFromGitHub` on each failure) is bound by the caller via
- * the `reconcile` dependency.
- *
- * Tests pin the success path without binding `reconcile`; the CLI binds it
- * to the network helper.
- *
- * @param {object} args
- * @param {Array<{ storyId: number, returnText: string }>} args.returns
- * @param {(args: { storyId: number }) => Promise<object> | object} [args.reconcile]
- *   Optional async hook used to fetch a fallback row when parsing fails. If
- *   omitted, parse failures push a placeholder `{ storyId, status: 'failed' }`
- *   row so the caller can still record without I/O.
- */
-export async function normalizeReturnsPure({ returns, reconcile } = {}) {
-  if (!Array.isArray(returns)) {
-    throw new TypeError(
-      'epic-execute-record-wave: --returns must be a JSON array of { storyId, returnText } objects',
-    );
-  }
-  const results = [];
-  const parseFailures = [];
-  for (const [idx, entry] of returns.entries()) {
-    const { storyId, returnText } = validateReturnsEntry(entry, idx);
-    const parsed = parseStoryAgentReturn(returnText);
-    const classified = classifyParsedReturn(parsed, storyId);
-    if (classified.ok) {
-      results.push(classified.value);
-      continue;
-    }
-    const fallback = reconcile
-      ? await reconcile({ storyId })
-      : { storyId, status: 'failed' };
-    results.push(fallback);
-    parseFailures.push({ storyId, error: classified.error, returnText });
-  }
-  return { results, parseFailures };
-}