mandrel 2.65.0 → 2.67.0

package/.agents/scripts/lib/observability/close-telemetry.js

@@ -0,0 +1,330 @@
+/**
+ * What a Story cost, as close observes it: retries by cause, review halts and
+ * overrides by provider, acceptance rounds, worker tokens. Best-effort and
+ * local only — a failed write is a missing metric, never a failed close.
+ *
+ * @module lib/observability/close-telemetry
+ */
+
+import crypto from 'node:crypto';
+
+import { parseWorkerTokens } from '../cli-args.js';
+import { Logger } from '../Logger.js';
+import { EVENT_KINDS } from '../signals/schema.js';
+import {
+  emitRuntimeFriction,
+  emitTerminalFriction,
+  RUNTIME_FRICTION_CATEGORIES,
+} from './runtime-friction.js';
+import { appendSignal, forEachLine } from './signals-writer.js';
+
+const RETRY_CAUSES = Object.freeze({
+  CI_RED: 'ci-red',
+  REVIEW_BLOCK: 'review-block',
+  GATE_FAILED: 'gate-failed',
+  MERGE_WAIT: 'merge-wait',
+  OTHER: 'other',
+});
+
+const BLOCK_CLASS_CAUSES = Object.freeze({
+  'checks-failed': RETRY_CAUSES.CI_RED,
+  'advisory-gate-red': RETRY_CAUSES.CI_RED,
+  'checks-pending-timeout': RETRY_CAUSES.MERGE_WAIT,
+});
+
+const FAILED_PHASE_CAUSES = Object.freeze({
+  'code-review': RETRY_CAUSES.REVIEW_BLOCK,
+  'close-validation': RETRY_CAUSES.GATE_FAILED,
+  'confirm-merge': RETRY_CAUSES.MERGE_WAIT,
+});
+
+/**
+ * @param {object|null|undefined} envelope
+ * @returns {string|null} `null` for a landed or pending close.
+ */
+function retryCauseForTerminal(envelope) {
+  const status = envelope?.status;
+  if (status === 'blocked') {
+    return (
+      BLOCK_CLASS_CAUSES[envelope.blocked?.blockClass] ?? RETRY_CAUSES.OTHER
+    );
+  }
+  if (status === 'failed') {
+    return FAILED_PHASE_CAUSES[envelope.phase] ?? RETRY_CAUSES.OTHER;
+  }
+  return null;
+}
+
+/**
+ * @param {{ envelope: object, config?: object }} args
+ * @returns {Promise<boolean>}
+ */
+async function emitCloseRetrySignal({ envelope, config }) {
+  const cause = retryCauseForTerminal(envelope);
+  const storyId = Number(envelope?.storyId);
+  if (cause === null || !Number.isInteger(storyId) || storyId <= 0) {
+    return false;
+  }
+  const signal = {
+    kind: EVENT_KINDS.RETRY,
+    eventId: crypto.randomUUID(),
+    ts: new Date().toISOString(),
+    epicId: null,
+    storyId,
+    taskId: null,
+    phase: 'close',
+    emitter: { tool: 'single-story-close' },
+    details: {
+      cause,
+      status: envelope.status,
+      closePhase: envelope.phase ?? null,
+      blockClass: envelope.blocked?.blockClass ?? null,
+    },
+  };
+  return appendSignal({ epicId: null, storyId, signal, config });
+}
+
+/**
+ * @param {{ envelope: object, config?: object }} args
+ * @returns {Promise<void>}
+ */
+export async function emitCloseTerminalSignals({ envelope, config } = {}) {
+  await emitCloseRetrySignal({ envelope, config });
+  await emitTerminalFriction({ envelope, config });
+}
+
+/**
+ * @param {{ storyId: number, prNumber?: number|null, criticalCount: number,
+ *   criticalByProvider?: Record<string, number>, config?: object }} args
+ * @returns {Promise<boolean>} true when a record was appended.
+ */
+export function emitReviewBlockedFriction({
+  storyId,
+  prNumber = null,
+  criticalCount,
+  criticalByProvider = {},
+  config,
+}) {
+  return emitRuntimeFriction({
+    storyId,
+    category: RUNTIME_FRICTION_CATEGORIES.REVIEW_BLOCKED,
+    tool: 'single-story-close',
+    details: { prNumber, criticalCount, criticalByProvider },
+    config,
+  });
+}
+
+/**
+ * @param {Record<string, number>} into
+ * @param {Record<string, number>} from
+ * @returns {Record<string, number>} `into`, mutated.
+ */
+function addCounts(into, from) {
+  for (const [key, count] of Object.entries(from)) {
+    into[key] = (into[key] ?? 0) + count;
+  }
+  return into;
+}
+
+function emptyTelemetryTally() {
+  return {
+    acceptanceRounds: 0,
+    retries: { total: 0, byCause: {} },
+    review: { haltsByProvider: {}, overridesByProvider: {} },
+  };
+}
+
+/**
+ * One incident per provider that raised a critical finding, not per finding.
+ *
+ * @param {object} details
+ * @returns {Record<string, number>}
+ */
+function providerIncidents(details) {
+  const out = {};
+  const byProvider = details?.criticalByProvider;
+  for (const [name, count] of Object.entries(byProvider ?? {})) {
+    if (Number.isInteger(count) && count > 0) out[name] = 1;
+  }
+  return out;
+}
+
+const RECORD_TALLIERS = Object.freeze({
+  [EVENT_KINDS.RETRY]: (tally, record) => {
+    const cause =
+      typeof record.details?.cause === 'string'
+        ? record.details.cause
+        : RETRY_CAUSES.OTHER;
+    tally.retries.total += 1;
+    addCounts(tally.retries.byCause, { [cause]: 1 });
+  },
+  [EVENT_KINDS.ACCEPTANCE_EVAL]: (tally, record) => {
+    const round = Number(record.details?.round);
+    const seen = Number.isInteger(round) && round > 0 ? round : 1;
+    tally.acceptanceRounds = Math.max(tally.acceptanceRounds, seen);
+  },
+  [EVENT_KINDS.FRICTION]: (tally, record) => {
+    if (record.details?.recovered === true) return;
+    if (record.category === RUNTIME_FRICTION_CATEGORIES.REVIEW_BLOCKED) {
+      addCounts(
+        tally.review.haltsByProvider,
+        providerIncidents(record.details),
+      );
+    } else if (
+      record.category === RUNTIME_FRICTION_CATEGORIES.REVIEW_BLOCK_OVERRIDDEN
+    ) {
+      addCounts(
+        tally.review.overridesByProvider,
+        providerIncidents(record.details),
+      );
+    }
+  },
+});
+
+/**
+ * @param {Iterable<unknown>} records
+ * @returns {ReturnType<typeof emptyTelemetryTally>}
+ */
+function tallyStoryTelemetry(records) {
+  const tally = emptyTelemetryTally();
+  for (const record of records ?? []) {
+    if (!record || typeof record !== 'object') continue;
+    RECORD_TALLIERS[record.kind]?.(tally, record);
+  }
+  return tally;
+}
+
+/**
+ * @param {Array<ReturnType<typeof emptyTelemetryTally>>} tallies
+ * @returns {ReturnType<typeof emptyTelemetryTally>}
+ */
+function mergeTelemetryTallies(tallies) {
+  const total = emptyTelemetryTally();
+  for (const t of tallies ?? []) {
+    total.acceptanceRounds += t.acceptanceRounds;
+    total.retries.total += t.retries.total;
+    addCounts(total.retries.byCause, t.retries.byCause);
+    addCounts(total.review.haltsByProvider, t.review.haltsByProvider);
+    addCounts(total.review.overridesByProvider, t.review.overridesByProvider);
+  }
+  return total;
+}
+
+/**
+ * A halt no override rejected, on a Story that then landed.
+ *
+ * @param {ReturnType<typeof emptyTelemetryTally>} tally
+ * @param {boolean} landed
+ * @returns {Record<string, number>}
+ */
+function confirmedHalts(tally, landed) {
+  if (!landed) return {};
+  const out = {};
+  for (const [name, count] of Object.entries(tally.review.haltsByProvider)) {
+    if (!tally.review.overridesByProvider[name]) out[name] = count;
+  }
+  return out;
+}
+
+/**
+ * @param {{ storyId: number, config?: object, readFn?: typeof forEachLine }} args
+ * @returns {Promise<ReturnType<typeof emptyTelemetryTally>>}
+ */
+async function readStoryTally({ storyId, config, readFn = forEachLine }) {
+  const rows = [];
+  try {
+    await readFn(null, storyId, (parsed) => rows.push(parsed), config);
+  } catch (err) {
+    Logger.warn(
+      `[close-telemetry] signal read failed for Story #${storyId}: ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+    );
+  }
+  return tallyStoryTelemetry(rows);
+}
+
+/**
+ * @param {{ storyId: number, config?: object, workerTokens?: number|null,
+ *   landed?: boolean, readFn?: typeof forEachLine }} args
+ * @returns {Promise<object>}
+ */
+async function buildCloseTelemetry({
+  storyId,
+  config,
+  workerTokens = null,
+  landed = false,
+  readFn,
+}) {
+  const tally = await readStoryTally({ storyId, config, readFn });
+  return {
+    acceptanceRounds: tally.acceptanceRounds,
+    retries: tally.retries,
+    review: {
+      ...tally.review,
+      confirmedHaltsByProvider: confirmedHalts(tally, landed),
+    },
+    workerTokens: Number.isInteger(workerTokens) ? workerTokens : null,
+  };
+}
+
+/**
+ * Over the run's own Stories, not the friction recurrence window.
+ *
+ * @param {Array<string|number>} storyIds
+ * @param {object} [config]
+ * @param {{ readFn?: typeof forEachLine }} [opts]
+ * @returns {Promise<ReturnType<typeof emptyTelemetryTally> & { storyCount: number }>}
+ */
+export async function gatherRunTelemetry(storyIds, config, { readFn } = {}) {
+  const tallies = [];
+  for (const raw of Array.isArray(storyIds) ? storyIds : []) {
+    const storyId = Number(raw);
+    if (!Number.isInteger(storyId) || storyId <= 0) continue;
+    tallies.push(await readStoryTally({ storyId, config, readFn }));
+  }
+  return { ...mergeTelemetryTallies(tallies), storyCount: tallies.length };
+}
+
+/**
+ * @param {unknown} raw
+ * @returns {number|null}
+ */
+export function resolveWorkerTokens(raw) {
+  const { tokens, warning } = parseWorkerTokens(raw);
+  if (warning) Logger.warn(`[single-story-close] ${warning}`);
+  return tokens;
+}
+
+/**
+ * The retry goes first so the summary counts it; a failure leaves
+ * `telemetry: null` and the close's status untouched.
+ *
+ * @param {{ terminal: object, result?: object|null, config?: object,
+ *   workerTokens?: number|null, readFn?: typeof forEachLine }} args
+ * @returns {Promise<void>}
+ */
+export async function recordCloseTelemetry({
+  terminal,
+  result,
+  config,
+  workerTokens = null,
+  readFn,
+}) {
+  await emitCloseRetrySignal({ envelope: terminal, config });
+  if (!result) return;
+  try {
+    result.telemetry = await buildCloseTelemetry({
+      storyId: result.storyId,
+      config,
+      workerTokens,
+      landed: terminal?.status === 'landed',
+      readFn,
+    });
+  } catch (err) {
+    Logger.warn(
+      `[single-story-close] telemetry summary unavailable: ${err?.message ?? err}`,
+    );
+    result.telemetry = null;
+  }
+}

package/.agents/scripts/lib/observability/runtime-friction.js

@@ -23,6 +23,8 @@ export const RUNTIME_FRICTION_CATEGORIES = Object.freeze({
   /** A tool failed to execute — kept out of code-finding severity tiers. */
   TOOL_DEGRADED: 'tool-degraded',
   LIGHT_SCOPE_REJECTED: 'light-scope-rejected',
+  /** A critical code-review halt, attributed to the provider(s) that raised it. */
+  REVIEW_BLOCKED: 'review-blocked',
   /** A human shipped over a review blocker; a rising count means miscalibration. */
   REVIEW_BLOCK_OVERRIDDEN: 'review-block-overridden',
 });

package/.agents/scripts/lib/observability/signal-validator.js

@@ -2,6 +2,10 @@
  * signal-validator.js — write-time validation of signal records against the
  * on-disk `signal-event.schema.json`, compiled once so the writer and the
  * contract test validate against the same document. Never throws.
+ *
+ * The schema is compiled on the first `validateSignal` call, not at import:
+ * every CLI that imports the signals writer (including for `--help`) would
+ * otherwise pay the AJV compile at start-up.
  */
 
 import { readFileSync } from 'node:fs';
@@ -45,7 +49,14 @@ function buildValidator() {
   }
 }
 
-const _validate = buildValidator();
+/** `undefined` until the first `validateSignal` call builds it. */
+let _validate;
+
+/** @returns {import('ajv').ValidateFunction | null} */
+function getValidator() {
+  if (_validate === undefined) _validate = buildValidator();
+  return _validate;
+}
 
 /**
  * @param {import('ajv').ErrorObject[] | null | undefined} errors
@@ -74,7 +85,8 @@ function violatingFieldOf(errors) {
  * @returns {{ valid: boolean, violatingField: string|null, message: string|null }}
  */
 export function validateSignal(record) {
-  if (_validate === null) {
+  const validate = getValidator();
+  if (validate === null) {
     return { valid: true, violatingField: null, message: null };
   }
   if (record === null || typeof record !== 'object' || Array.isArray(record)) {
@@ -84,9 +96,9 @@ export function validateSignal(record) {
       message: 'signal record must be a plain object',
     };
   }
-  const valid = _validate(record);
+  const valid = validate(record);
   if (valid) return { valid: true, violatingField: null, message: null };
-  const field = violatingFieldOf(_validate.errors);
-  const message = _validate.errors?.[0]?.message ?? 'schema validation failed';
+  const field = violatingFieldOf(validate.errors);
+  const message = validate.errors?.[0]?.message ?? 'schema validation failed';
   return { valid: false, violatingField: field, message };
 }

package/.agents/scripts/lib/observability/source-classifier.js

@@ -37,6 +37,8 @@ const FRAMEWORK_SCRIPT_BASENAMES = Object.freeze([
   'check-test-temp-hygiene.js',
   'check-windows-git-perf.js',
   'ceremony-derive.js',
+  'clean-temp.js',
+  'clean-worktrees.js',
   'cleanup-repo-test-temp.js',
   'coverage-capture.js',
   'deliver-light.js',
@@ -51,7 +53,7 @@ const FRAMEWORK_SCRIPT_BASENAMES = Object.freeze([
   'generate-lens-checklists.js',
   'generate-skills-index.js',
   'generate-workflows-doc.js',
-  'git-cleanup.js',
+  'clean-git.js',
   'lint-issue-body.js',
   'mandrel-update-preflight.js',
   'merge-baseline.js',

package/.agents/scripts/lib/orchestration/code-review.js

@@ -112,6 +112,7 @@ function resolveScopeEnvelope(opts, config) {
  *   postedCommentId: number|null,
  *   commentTargetId: number,
  *   halted: boolean,
+ *   criticalByProvider?: Record<string, number>,
  *   degraded: boolean, degradations: Array<object>,
  *   blockerReason: string|null,
  * }>}
@@ -229,6 +230,21 @@ async function postReviewComment({
   }
 }
 
+/**
+ * Which review provider(s) raised the critical findings. A chain reports its
+ * own per-entry attribution; any other provider owns every critical.
+ *
+ * @param {{ reviewProvider: object, providerName: string,
+ *   severity: { critical: number } }} args
+ * @returns {Record<string, number>}
+ */
+function resolveCriticalByProvider({ reviewProvider, providerName, severity }) {
+  if (typeof reviewProvider?.getCriticalByProvider === 'function') {
+    return reviewProvider.getCriticalByProvider();
+  }
+  return severity.critical > 0 ? { [providerName]: severity.critical } : {};
+}
+
 async function executeReviewPipeline({ opts, config, envelope }) {
   const {
     provider,
@@ -277,6 +293,11 @@ async function executeReviewPipeline({ opts, config, envelope }) {
   );
   const severity = countBySeverity(findings);
   const halted = hasSurvivingCritical(severity);
+  const criticalByProvider = resolveCriticalByProvider({
+    reviewProvider,
+    providerName,
+    severity,
+  });
   const report = renderFindingsFn({
     scope,
     ticketId,
@@ -304,6 +325,7 @@ async function executeReviewPipeline({ opts, config, envelope }) {
     postedCommentId,
     commentTargetId,
     halted,
+    criticalByProvider,
     ...degradationEnvelope(degradations),
     blockerReason: halted
       ? `code-review reported ${severity.critical} critical blocker(s)`

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

@@ -1,5 +1,5 @@
 /**
- * git-cleanup `main()`: argv, base-branch resolution, the four phases, and
+ * `clean-git.js` `main()`: argv, base-branch resolution, the four phases, and
  * the optional JSON envelope.
  *
  * @module lib/orchestration/git-cleanup/phases/cli

package/.agents/scripts/lib/orchestration/plan-metrics.js

@@ -231,75 +231,88 @@ function recordTimestamp(entry) {
  * }|null}
  */
 export function summarizePlanMetrics(ledger, opts = {}) {
-  const all = ledger?.entries ?? [];
-  const since = typeof opts.since === 'string' ? opts.since : null;
-  // ISO-8601 UTC strings compare correctly as strings.
-  const entries =
-    since === null
-      ? all
-      : all.filter((e) => {
-          const stamp = recordTimestamp(e);
-          return stamp !== null && stamp >= since;
-        });
+  const entries = scopeEntries(ledger?.entries ?? [], opts.since);
   if (entries.length === 0) return null;
-  const byCli = {};
-  const byMode = {};
-  const criticSkipsByCritic = {};
-  let criticSkips = 0;
-  let failures = 0;
-  let totalDurationMs = 0;
-  let firstStartedAt = null;
-  let lastEndedAt = null;
-  const invocationEntries = [];
-  for (const e of entries) {
-    if (e.kind === PLAN_METRICS_KIND_CRITIC_SKIP) {
-      criticSkips += 1;
-      if (typeof e.critic === 'string') {
-        criticSkipsByCritic[e.critic] =
-          (criticSkipsByCritic[e.critic] ?? 0) + 1;
-      }
-      continue;
-    }
-    if (typeof e.kind === 'string') {
-      // Other kinded records (e.g. `findings-yield`) are not invocations.
-      continue;
-    }
-    invocationEntries.push(e);
-    byCli[e.cli] = (byCli[e.cli] ?? 0) + 1;
-    if (typeof e.mode === 'string') byMode[e.mode] = (byMode[e.mode] ?? 0) + 1;
-    if (e.ok !== true) failures += 1;
-    if (typeof e.durationMs === 'number') totalDurationMs += e.durationMs;
-    if (typeof e.startedAt === 'string') {
-      if (firstStartedAt === null || e.startedAt < firstStartedAt) {
-        firstStartedAt = e.startedAt;
-      }
-    }
-    if (typeof e.endedAt === 'string') {
-      if (lastEndedAt === null || e.endedAt > lastEndedAt) {
-        lastEndedAt = e.endedAt;
-      }
-    }
-  }
-  let spanMs = null;
-  if (firstStartedAt !== null && lastEndedAt !== null) {
-    const span = Date.parse(lastEndedAt) - Date.parse(firstStartedAt);
-    if (Number.isFinite(span)) spanMs = Math.max(0, span);
-  }
+  const skips = tallyCriticSkips(entries);
+  const invocations = tallyInvocations(
+    entries.filter((e) => typeof e.kind !== 'string'),
+  );
   return {
-    invocations: invocationEntries.length,
-    failures,
-    byCli,
-    byMode,
-    criticSkips,
-    criticSkipsByCritic,
-    firstStartedAt,
-    lastEndedAt,
-    spanMs,
-    totalDurationMs,
+    invocations: invocations.count,
+    failures: invocations.failures,
+    byCli: invocations.byCli,
+    byMode: invocations.byMode,
+    criticSkips: skips.count,
+    criticSkipsByCritic: skips.byCritic,
+    firstStartedAt: invocations.firstStartedAt,
+    lastEndedAt: invocations.lastEndedAt,
+    spanMs: spanBetween(invocations.firstStartedAt, invocations.lastEndedAt),
+    totalDurationMs: invocations.totalDurationMs,
     malformedLines: ledger?.malformedLines ?? 0,
   };
 }
 
+function scopeEntries(all, since) {
+  if (typeof since !== 'string') return all;
+  // ISO-8601 UTC strings compare correctly as strings.
+  return all.filter((e) => {
+    const stamp = recordTimestamp(e);
+    return stamp !== null && stamp >= since;
+  });
+}
+
+function increment(counts, key) {
+  counts[key] = (counts[key] ?? 0) + 1;
+}
+
+function tallyCriticSkips(entries) {
+  const byCritic = {};
+  let count = 0;
+  for (const e of entries) {
+    if (e.kind !== PLAN_METRICS_KIND_CRITIC_SKIP) continue;
+    count += 1;
+    if (typeof e.critic === 'string') increment(byCritic, e.critic);
+  }
+  return { count, byCritic };
+}
+
+function earlierStamp(current, candidate) {
+  if (typeof candidate !== 'string') return current;
+  return current === null || candidate < current ? candidate : current;
+}
+
+function laterStamp(current, candidate) {
+  if (typeof candidate !== 'string') return current;
+  return current === null || candidate > current ? candidate : current;
+}
+
+function tallyInvocations(entries) {
+  const tally = {
+    count: entries.length,
+    failures: 0,
+    byCli: {},
+    byMode: {},
+    totalDurationMs: 0,
+    firstStartedAt: null,
+    lastEndedAt: null,
+  };
+  for (const e of entries) {
+    increment(tally.byCli, e.cli);
+    if (typeof e.mode === 'string') increment(tally.byMode, e.mode);
+    if (e.ok !== true) tally.failures += 1;
+    if (typeof e.durationMs === 'number') tally.totalDurationMs += e.durationMs;
+    tally.firstStartedAt = earlierStamp(tally.firstStartedAt, e.startedAt);
+    tally.lastEndedAt = laterStamp(tally.lastEndedAt, e.endedAt);
+  }
+  return tally;
+}
+
+function spanBetween(first, last) {
+  if (first === null || last === null) return null;
+  const span = Date.parse(last) - Date.parse(first);
+  return Number.isFinite(span) ? Math.max(0, span) : null;
+}
+
 /**
  * @param {ReturnType<typeof summarizePlanMetrics>} summary
  * @returns {string}