agentxchain 2.103.0 → 2.105.0

package/src/lib/history-diff-summary.js

@@ -0,0 +1,249 @@
+function normalizeSingleLine(value) {
+  if (typeof value !== 'string') return null;
+  const normalized = value.replace(/\s+/g, ' ').trim();
+  return normalized.length > 0 ? normalized : null;
+}
+
+export function buildRunOutcomeSummary(entry) {
+  const status = typeof entry?.status === 'string' ? entry.status : 'unknown';
+  const nextAction = normalizeSingleLine(
+    entry?.retrospective?.next_operator_action
+    || entry?.retrospective?.follow_on_hint
+    || null,
+  );
+
+  if (status === 'blocked' && nextAction) {
+    return { label: 'operator', status, next_action: nextAction };
+  }
+  if (status === 'blocked') {
+    return { label: 'blocked', status, next_action: null };
+  }
+  if (status === 'completed' && nextAction) {
+    return { label: 'follow-on', status, next_action: nextAction };
+  }
+  if (status === 'completed') {
+    return { label: 'clean', status, next_action: null };
+  }
+  return { label: 'unknown', status, next_action: nextAction };
+}
+
+export function buildRunDiffSummary(diff) {
+  if (!diff?.changed) {
+    return {
+      outcome: 'unchanged',
+      risk_level: 'none',
+      highlights: [],
+      changed_field_count: 0,
+    };
+  }
+
+  const regressionSignals = [];
+  const improvementSignals = [];
+  const changeSignals = [];
+
+  const statusChange = diff.scalar_changes?.status;
+  if (statusChange?.changed) {
+    const leftRank = getRunStatusRank(statusChange.left);
+    const rightRank = getRunStatusRank(statusChange.right);
+    if (rightRank < leftRank) {
+      regressionSignals.push(`status worsened to ${statusChange.right}`);
+    } else if (rightRank > leftRank) {
+      improvementSignals.push(`status improved to ${statusChange.right}`);
+    } else {
+      changeSignals.push(`status changed to ${statusChange.right}`);
+    }
+  }
+
+  const blockedReason = diff.scalar_changes?.blocked_reason;
+  if (blockedReason?.changed && blockedReason.right) {
+    regressionSignals.push(`blocked reason: ${blockedReason.right}`);
+  }
+
+  const nextAction = diff.scalar_changes?.next_action;
+  if (nextAction?.changed) {
+    if (nextAction.right) {
+      changeSignals.push(`next action: ${nextAction.right}`);
+    } else {
+      improvementSignals.push('operator follow-up cleared');
+    }
+  }
+
+  for (const gateChange of diff.gate_changes || []) {
+    if (!gateChange.changed) continue;
+    if (isBlockingGateState(gateChange.right) && !isBlockingGateState(gateChange.left)) {
+      regressionSignals.push(`gate ${gateChange.gate_id} is ${gateChange.right}`);
+    } else if (isPassingGateState(gateChange.right) && isBlockingGateState(gateChange.left)) {
+      improvementSignals.push(`gate ${gateChange.gate_id} recovered to ${gateChange.right}`);
+    } else {
+      changeSignals.push(`gate ${gateChange.gate_id}: ${gateChange.left ?? '—'} -> ${gateChange.right ?? '—'}`);
+    }
+  }
+
+  const phases = diff.list_changes?.phases_completed;
+  if (phases?.changed) {
+    if (phases.added.length > 0) {
+      changeSignals.push(`phases added: ${phases.added.join(', ')}`);
+    }
+    if (phases.removed.length > 0) {
+      regressionSignals.push(`phases removed: ${phases.removed.join(', ')}`);
+    }
+  }
+
+  const roles = diff.list_changes?.roles_used;
+  if (roles?.changed) {
+    if (roles.added.length > 0) {
+      changeSignals.push(`roles added: ${roles.added.join(', ')}`);
+    }
+    if (roles.removed.length > 0) {
+      changeSignals.push(`roles removed: ${roles.removed.join(', ')}`);
+    }
+  }
+
+  const cost = diff.numeric_changes?.total_cost_usd;
+  if (cost?.changed) {
+    changeSignals.push(`cost ${formatSignedNumber(cost.delta, 4, '$')}`);
+  }
+
+  const duration = diff.numeric_changes?.duration_ms;
+  if (duration?.changed) {
+    changeSignals.push(`duration ${formatDurationDelta(duration.delta)}`);
+  }
+
+  let outcome = 'changed';
+  let riskLevel = 'low';
+  if (regressionSignals.length > 0 && improvementSignals.length > 0) {
+    outcome = 'mixed';
+    riskLevel = regressionSignals.some((signal) => signal.startsWith('status worsened') || signal.startsWith('gate '))
+      ? 'high'
+      : 'medium';
+  } else if (regressionSignals.length > 0) {
+    outcome = 'regressed';
+    riskLevel = regressionSignals.some((signal) => signal.startsWith('status worsened') || signal.startsWith('gate '))
+      ? 'high'
+      : 'medium';
+  } else if (improvementSignals.length > 0) {
+    outcome = 'improved';
+    riskLevel = changeSignals.length > 0 ? 'low' : 'none';
+  }
+
+  return {
+    outcome,
+    risk_level: riskLevel,
+    highlights: [...regressionSignals, ...improvementSignals, ...changeSignals].slice(0, 3),
+    changed_field_count: countChangedFields(diff),
+  };
+}
+
+export function buildExportDiffSummary(diff) {
+  if (!diff?.changed) {
+    return {
+      outcome: 'unchanged',
+      risk_level: 'none',
+      highlights: [],
+      changed_field_count: 0,
+    };
+  }
+
+  const regressions = Array.isArray(diff.regressions) ? diff.regressions : [];
+  const highlights = [];
+
+  if (regressions.length > 0) {
+    for (const reg of regressions.slice(0, 3)) {
+      highlights.push(`${reg.id}: ${reg.message}`);
+    }
+    return {
+      outcome: 'regressed',
+      risk_level: regressions.some((reg) => reg.severity === 'error') ? 'high' : 'medium',
+      highlights,
+      changed_field_count: countChangedFields(diff),
+    };
+  }
+
+  pushFirstChangeHighlights(diff, highlights);
+
+  return {
+    outcome: 'changed',
+    risk_level: 'low',
+    highlights: highlights.slice(0, 3),
+    changed_field_count: countChangedFields(diff),
+  };
+}
+
+function pushFirstChangeHighlights(diff, highlights) {
+  const scalarChanges = Object.values(diff.scalar_changes || {}).filter((entry) => entry.changed);
+  for (const entry of scalarChanges) {
+    if (highlights.length >= 3) return;
+    highlights.push(`${entry.label}: ${entry.left ?? '—'} -> ${entry.right ?? '—'}`);
+  }
+
+  const numericChanges = Object.values(diff.numeric_changes || {}).filter((entry) => entry.changed);
+  for (const entry of numericChanges) {
+    if (highlights.length >= 3) return;
+    highlights.push(`${entry.label}: ${entry.left ?? '—'} -> ${entry.right ?? '—'}`);
+  }
+
+  const listChanges = Object.values(diff.list_changes || {}).filter((entry) => entry.changed);
+  for (const entry of listChanges) {
+    if (highlights.length >= 3) return;
+    if (entry.added?.length > 0) {
+      highlights.push(`${entry.label} added: ${entry.added.join(', ')}`);
+    } else if (entry.removed?.length > 0) {
+      highlights.push(`${entry.label} removed: ${entry.removed.join(', ')}`);
+    }
+  }
+}
+
+function countChangedFields(diff) {
+  const scalar = Object.values(diff.scalar_changes || {}).filter((entry) => entry.changed).length;
+  const numeric = Object.values(diff.numeric_changes || {}).filter((entry) => entry.changed).length;
+  const lists = Object.values(diff.list_changes || {}).filter((entry) => entry.changed).length;
+  const gates = Array.isArray(diff.gate_changes)
+    ? diff.gate_changes.filter((entry) => entry.changed).length
+    : 0;
+  const repoStatuses = Array.isArray(diff.repo_status_changes)
+    ? diff.repo_status_changes.filter((entry) => entry.changed).length
+    : 0;
+  const repoExports = Array.isArray(diff.repo_export_changes)
+    ? diff.repo_export_changes.filter((entry) => entry.changed).length
+    : 0;
+  const eventTypes = Array.isArray(diff.event_type_changes)
+    ? diff.event_type_changes.filter((entry) => entry.changed).length
+    : 0;
+  return scalar + numeric + lists + gates + repoStatuses + repoExports + eventTypes;
+}
+
+function getRunStatusRank(status) {
+  if (status === 'completed') return 3;
+  if (status === 'blocked') return 2;
+  if (status === 'failed') return 1;
+  return 0;
+}
+
+function isBlockingGateState(value) {
+  return value === 'failed' || value === 'blocked' || value === 'pending';
+}
+
+function isPassingGateState(value) {
+  return value === 'passed' || value === 'approved';
+}
+
+function formatSignedNumber(value, digits, prefix = '') {
+  if (typeof value !== 'number' || Number.isNaN(value) || value === 0) return 'unchanged';
+  const sign = value > 0 ? '+' : '';
+  return `${sign}${prefix}${Math.abs(value).toFixed(digits)}`;
+}
+
+function formatDurationDelta(ms) {
+  if (typeof ms !== 'number' || Number.isNaN(ms) || ms === 0) return 'unchanged';
+  const sign = ms > 0 ? '+' : '-';
+  const absolute = Math.abs(ms);
+  if (absolute < 1000) return `${sign}${absolute}ms`;
+  const secs = Math.floor(absolute / 1000);
+  if (secs < 60) return `${sign}${secs}s`;
+  const mins = Math.floor(secs / 60);
+  const remainSecs = secs % 60;
+  if (mins < 60) return `${sign}${mins}m ${remainSecs}s`;
+  const hrs = Math.floor(mins / 60);
+  const remainMins = mins % 60;
+  return `${sign}${hrs}h ${remainMins}m`;
+}

package/src/lib/manual-qa-fallback.js

@@ -0,0 +1,18 @@
+/**
+ * Narrow recovery hint for the built-in manual QA fallback path.
+ *
+ * The check must use normalized config so operator-facing guidance stays
+ * consistent across commands and does not depend on raw config exceptions.
+ */
+export function shouldSuggestManualQaFallback({
+  roleId,
+  runtimeId,
+  classified,
+  config,
+}) {
+  return classified?.error_class === 'missing_credentials'
+    && roleId === 'qa'
+    && runtimeId === 'api-qa'
+    && config?.roles?.qa?.runtime_id === 'api-qa'
+    && config?.runtimes?.['manual-qa']?.type === 'manual';
+}

package/src/lib/normalized-config.js

@@ -15,6 +15,11 @@
 import { validateHooksConfig } from './hook-runner.js';
 import { validateNotificationsConfig } from './notification-runner.js';
 import { validatePolicies, normalizePolicies } from './policy-evaluator.js';
+import {
+  canRoleParticipateInRequiredFileProduction,
+  canRoleSatisfyWorkflowArtifactOwnership,
+  getRoleRuntimeCapabilityContract,
+} from './runtime-capabilities.js';
 import { validateTimeoutsConfig } from './timeout-evaluator.js';
 import { SUPPORTED_TOKEN_COUNTER_PROVIDERS } from './token-counter.js';
 import {
@@ -455,21 +460,12 @@ export function validateV4Config(data, projectRoot) {
   // Cross-reference: review_only roles should not use authoritative runtimes
   if (data.roles && data.runtimes) {
     for (const [id, role] of Object.entries(data.roles)) {
-      if (role.write_authority === 'review_only' && role.runtime && data.runtimes[role.runtime]) {
-        const rt = data.runtimes[role.runtime];
-        if (rt.type === 'local_cli') {
-          errors.push(`Role "${id}" is review_only but uses local_cli runtime "${role.runtime}" — review_only roles should not have authoritative write access`);
-        }
-      }
-      // api_proxy and remote_agent restriction: only review_only and proposed roles may bind.
-      // These adapters do not have a proven local workspace mutation path in v1.
       if (role.runtime && data.runtimes[role.runtime]) {
         const rt = data.runtimes[role.runtime];
-        if (
-          (rt.type === 'api_proxy' || rt.type === 'remote_agent')
-          && role.write_authority !== 'review_only'
-          && role.write_authority !== 'proposed'
-        ) {
+        const contract = getRoleRuntimeCapabilityContract(id, role, rt);
+        if (contract.effective_write_path === 'invalid_review_only_binding') {
+          errors.push(`Role "${id}" is review_only but uses local_cli runtime "${role.runtime}" — review_only roles should not have authoritative write access`);
+        } else if (contract.effective_write_path === 'invalid_authoritative_binding') {
           errors.push(
             `Role "${id}" has write_authority "${role.write_authority}" but uses ${rt.type} runtime "${role.runtime}" — ${rt.type} only supports review_only and proposed roles`
           );
@@ -534,7 +530,7 @@ export function validateV4Config(data, projectRoot) {
 
   // Workflow Kit (optional but validated if present)
   if (data.workflow_kit !== undefined) {
-    const wkValidation = validateWorkflowKitConfig(data.workflow_kit, data.routing, data.roles);
+    const wkValidation = validateWorkflowKitConfig(data.workflow_kit, data.routing, data.roles, data.runtimes);
     errors.push(...wkValidation.errors);
   }
 
@@ -697,7 +693,7 @@ export function validateSchedulesConfig(schedules, roles) {
  * Validate the workflow_kit config section.
  * Returns { ok, errors, warnings }.
  */
-export function validateWorkflowKitConfig(wk, routing, roles) {
+export function validateWorkflowKitConfig(wk, routing, roles, runtimes = {}) {
   const errors = [];
   const warnings = [];
 
@@ -837,20 +833,25 @@ export function validateWorkflowKitConfig(wk, routing, roles) {
           } else if (
             artifact.required !== false &&
             roles && typeof roles === 'object' &&
-            roles[artifact.owned_by]?.write_authority === 'review_only'
+            roles[artifact.owned_by]
           ) {
-            // Check if any authoritative/proposed role exists in this phase's routing
+            const ownerRole = roles[artifact.owned_by];
+            const ownerRuntimeKey = ownerRole.runtime_id || ownerRole.runtime;
+            const ownerRuntime = runtimes?.[ownerRuntimeKey];
             const phaseRouting = routing?.[phase];
             const phaseRoles = new Set([
               ...(phaseRouting?.allowed_next_roles || []),
               ...(phaseRouting?.entry_role ? [phaseRouting.entry_role] : []),
             ]);
-            const hasWriter = [...phaseRoles].some(rid =>
-              roles[rid]?.write_authority === 'authoritative' || roles[rid]?.write_authority === 'proposed',
-            );
-            if (!hasWriter) {
+            const hasReachableProducer = [...phaseRoles].some((rid) => {
+              const phaseRole = roles[rid];
+              if (!phaseRole) return false;
+              const phaseRuntimeKey = phaseRole.runtime_id || phaseRole.runtime;
+              return canRoleParticipateInRequiredFileProduction(phaseRole, runtimes?.[phaseRuntimeKey]);
+            });
+            if (!canRoleSatisfyWorkflowArtifactOwnership(ownerRole, ownerRuntime) && !hasReachableProducer) {
               warnings.push(
-                `${prefix} owned_by "${artifact.owned_by}" is a review_only role in phase "${phase}" with no authoritative or proposed role — nobody can write this required artifact`,
+                `${prefix} owned_by "${artifact.owned_by}" has no reachable workflow ownership path in phase "${phase}", and no routed role can satisfy the required artifact`,
               );
             }
           }
@@ -1053,6 +1054,9 @@ export function normalizeV4(raw) {
         title: role.title,
         mandate: role.mandate,
         write_authority: role.write_authority,
+        ...(typeof role.decision_authority === 'number'
+          ? { decision_authority: role.decision_authority }
+          : {}),
         runtime_class: raw.runtimes?.[role.runtime]?.type || 'manual',
         runtime_id: role.runtime,
       };
@@ -1205,6 +1209,7 @@ export function normalizeWorkflowKit(raw, routingPhases) {
   if (raw.phases) {
     for (const [phase, phaseConfig] of Object.entries(raw.phases)) {
       phases[phase] = {
+        ...(typeof phaseConfig?.template === 'string' ? { template: phaseConfig.template } : {}),
         artifacts: expandWorkflowKitPhaseArtifacts(phaseConfig).map(a => ({
           path: a.path,
           semantics: a.semantics || null,

package/src/lib/planning-artifacts.js

@@ -0,0 +1,131 @@
+import { basename } from 'node:path';
+import { buildSystemSpecContent } from './governed-templates.js';
+
+export const GOVERNED_BASELINE_PLANNING_PATHS = Object.freeze([
+  '.planning/PM_SIGNOFF.md',
+  '.planning/ROADMAP.md',
+  '.planning/SYSTEM_SPEC.md',
+  '.planning/IMPLEMENTATION_NOTES.md',
+  '.planning/acceptance-matrix.md',
+  '.planning/ship-verdict.md',
+  '.planning/RELEASE_NOTES.md',
+]);
+
+const PHASE_DISPLAY_NAMES = Object.freeze({
+  qa: 'QA',
+});
+
+function formatPhaseDisplayName(phaseKey) {
+  if (PHASE_DISPLAY_NAMES[phaseKey]) {
+    return PHASE_DISPLAY_NAMES[phaseKey];
+  }
+  return phaseKey.replace(/_/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase());
+}
+
+function buildRoadmapPhaseTable(routing, roles) {
+  const rows = Object.entries(routing).map(([phaseKey, phaseConfig]) => {
+    const phaseName = formatPhaseDisplayName(phaseKey);
+    const entryRole = phaseConfig.entry_role;
+    const role = roles[entryRole];
+    const goal = role?.mandate || phaseName;
+    const status = phaseKey === Object.keys(routing)[0] ? 'In progress' : 'Pending';
+    return `| ${phaseName} | ${goal} | ${status} |`;
+  });
+  return `| Phase | Goal | Status |\n|-------|------|--------|\n${rows.join('\n')}\n`;
+}
+
+export function interpolateTemplateContent(contentTemplate, projectName) {
+  return contentTemplate.replaceAll('{{project_name}}', projectName);
+}
+
+export function appendAcceptanceHints(baseMatrix, acceptanceHints) {
+  if (!Array.isArray(acceptanceHints) || acceptanceHints.length === 0) {
+    return baseMatrix;
+  }
+
+  const hintLines = acceptanceHints.map((hint) => `- [ ] ${hint}`).join('\n');
+  return `${baseMatrix}\n\n## Template Guidance\n${hintLines}\n`;
+}
+
+export function generateWorkflowKitPlaceholder(artifact, projectName) {
+  const filename = basename(artifact.path);
+  const title = filename.replace(/\.[^.]+$/, '').replace(/[-_]/g, ' ');
+
+  if (artifact.semantics === 'section_check' && artifact.semantics_config?.required_sections?.length) {
+    const sections = artifact.semantics_config.required_sections
+      .map((section) => `${section}\n\n(Content here.)\n`)
+      .join('\n');
+    return `# ${title} — ${projectName}\n\n${sections}`;
+  }
+
+  return `# ${title} — ${projectName}\n\n(Operator fills this in.)\n`;
+}
+
+export function buildGovernedPlanningArtifacts({ projectName, routing, roles, template, workflowKitConfig }) {
+  const artifacts = [
+    {
+      path: '.planning/PM_SIGNOFF.md',
+      source: 'core',
+      content: `# PM Signoff — ${projectName}\n\nApproved: NO\n\n> This scaffold starts blocked on purpose. Change this to \`Approved: YES\` only after a human reviews the planning artifacts and is ready to open the planning gate.\n\n## Discovery Checklist\n- [ ] Target user defined\n- [ ] Core pain point defined\n- [ ] Core workflow defined\n- [ ] MVP scope defined\n- [ ] Out-of-scope list defined\n- [ ] Success metric defined\n\n## Notes for team\n(PM and human add final kickoff notes here.)\n`,
+    },
+    {
+      path: '.planning/ROADMAP.md',
+      source: 'core',
+      content: `# Roadmap — ${projectName}\n\n## Phases\n\n${buildRoadmapPhaseTable(routing, roles)}`,
+    },
+    {
+      path: '.planning/SYSTEM_SPEC.md',
+      source: 'core',
+      content: buildSystemSpecContent(projectName, template?.system_spec_overlay),
+    },
+    {
+      path: '.planning/IMPLEMENTATION_NOTES.md',
+      source: 'core',
+      content: `# Implementation Notes — ${projectName}\n\n## Changes\n\n(Dev fills this during implementation)\n\n## Verification\n\n(Dev fills this during implementation)\n\n## Unresolved Follow-ups\n\n(Dev lists any known gaps, tech debt, or follow-up items here.)\n`,
+    },
+    {
+      path: '.planning/acceptance-matrix.md',
+      source: 'core',
+      content: appendAcceptanceHints(
+        `# Acceptance Matrix — ${projectName}\n\n| Req # | Requirement | Acceptance criteria | Test status | Last tested | Status |\n|-------|-------------|-------------------|-------------|-------------|--------|\n| (QA fills this from ROADMAP.md) | | | | | |\n`,
+        template?.acceptance_hints,
+      ),
+    },
+    {
+      path: '.planning/ship-verdict.md',
+      source: 'core',
+      content: `# Ship Verdict — ${projectName}\n\n## Verdict: PENDING\n\n## QA Summary\n\n(QA writes the final ship/no-ship assessment here.)\n\n## Open Blockers\n\n(List any blocking issues.)\n\n## Conditions\n\n(List any conditions for shipping.)\n`,
+    },
+    {
+      path: '.planning/RELEASE_NOTES.md',
+      source: 'core',
+      content: `# Release Notes — ${projectName}\n\n## User Impact\n\n(QA fills this during the QA phase)\n\n## Verification Summary\n\n(QA fills this during the QA phase)\n\n## Upgrade Notes\n\n(QA fills this during the QA phase)\n\n## Known Issues\n\n(QA fills this during the QA phase)\n`,
+    },
+  ];
+
+  for (const artifact of template?.planning_artifacts || []) {
+    artifacts.push({
+      path: `.planning/${artifact.filename}`,
+      source: 'template',
+      content: interpolateTemplateContent(artifact.content_template, projectName),
+    });
+  }
+
+  const seenPaths = new Set(GOVERNED_BASELINE_PLANNING_PATHS);
+  if (workflowKitConfig?.phases && typeof workflowKitConfig.phases === 'object') {
+    for (const phaseConfig of Object.values(workflowKitConfig.phases)) {
+      if (!Array.isArray(phaseConfig.artifacts)) continue;
+      for (const artifact of phaseConfig.artifacts) {
+        if (!artifact.path || seenPaths.has(artifact.path)) continue;
+        seenPaths.add(artifact.path);
+        artifacts.push({
+          path: artifact.path,
+          source: 'workflow_kit',
+          content: generateWorkflowKitPlaceholder(artifact, projectName),
+        });
+      }
+    }
+  }
+
+  return artifacts;
+}

package/src/lib/recent-event-summary.js

@@ -0,0 +1,132 @@
+import { readRunEvents } from './run-events.js';
+
+export const RECENT_EVENT_WINDOW_MINUTES = 15;
+export const RECENT_EVENT_WINDOW_MS = RECENT_EVENT_WINDOW_MINUTES * 60 * 1000;
+
+function isObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function isValidTimestamp(timestamp) {
+  return typeof timestamp === 'string' && timestamp.trim().length > 0 && !Number.isNaN(new Date(timestamp).getTime());
+}
+
+function trimToNull(value) {
+  return typeof value === 'string' && value.trim().length > 0 ? value.trim() : null;
+}
+
+function describeEvent(eventType, entry) {
+  const repoId = trimToNull(entry.repo_id);
+  const roleId = trimToNull(entry.role_id);
+  const gateId = trimToNull(entry.payload?.gate_id) || trimToNull(entry.gate);
+  const prefix = repoId ? `[${repoId}] ` : '';
+
+  switch (eventType) {
+    case 'turn_dispatched':
+    case 'turn_accepted':
+    case 'turn_rejected':
+      return `${prefix}${eventType}${roleId ? ` [${roleId}]` : ''}`;
+    case 'phase_entered': {
+      const fromPhase = trimToNull(entry.payload?.from);
+      const toPhase = trimToNull(entry.payload?.to) || trimToNull(entry.phase);
+      if (fromPhase && toPhase) return `${prefix}${eventType} ${fromPhase} -> ${toPhase}`;
+      return `${prefix}${eventType}`;
+    }
+    case 'gate_pending':
+    case 'gate_approved':
+    case 'gate_failed':
+      return `${prefix}${eventType}${gateId ? ` (${gateId})` : ''}`;
+    case 'run_blocked':
+    case 'run_completed':
+    case 'run_started':
+    case 'escalation_raised':
+    case 'escalation_resolved':
+    case 'budget_exceeded_warn':
+      return `${prefix}${eventType}`;
+    default:
+      if (trimToNull(entry.summary)) return entry.summary.trim();
+      return `${prefix}${eventType || 'unknown_event'}`;
+  }
+}
+
+export function normalizeRecentEventEntry(entry) {
+  if (!isObject(entry)) return null;
+  const turn = isObject(entry.turn) ? entry.turn : null;
+  const eventType = trimToNull(entry.event_type) || trimToNull(entry.type) || 'unknown_event';
+  const phase = trimToNull(entry.phase);
+  const status = trimToNull(entry.status);
+  const turnId = trimToNull(turn?.turn_id) || trimToNull(entry.turn_id) || null;
+  const roleId = trimToNull(turn?.role_id)
+    || trimToNull(turn?.assigned_role)
+    || trimToNull(entry.role_id)
+    || trimToNull(entry.role)
+    || null;
+  const repoId = trimToNull(entry.repo_id);
+  const timestamp = trimToNull(entry.timestamp);
+
+  return {
+    event_type: eventType,
+    timestamp,
+    phase,
+    status,
+    turn_id: turnId,
+    role_id: roleId,
+    repo_id: repoId,
+    summary: describeEvent(eventType, { ...entry, role_id: roleId, repo_id: repoId, turn }),
+  };
+}
+
+export function buildRecentEventSummary(entries, { now = Date.now(), windowMs = RECENT_EVENT_WINDOW_MS } = {}) {
+  const normalized = Array.isArray(entries)
+    ? entries.map(normalizeRecentEventEntry).filter(Boolean)
+    : [];
+
+  if (normalized.length === 0) {
+    return {
+      window_minutes: Math.round(windowMs / 60000),
+      freshness: 'no_events',
+      recent_count: 0,
+      latest_event: null,
+    };
+  }
+
+  const latestEvent = normalized[normalized.length - 1];
+  const recentCount = normalized.filter((event) => {
+    if (!isValidTimestamp(event.timestamp)) return false;
+    return (now - new Date(event.timestamp).getTime()) <= windowMs;
+  }).length;
+
+  let freshness = 'unknown';
+  if (isValidTimestamp(latestEvent.timestamp)) {
+    freshness = (now - new Date(latestEvent.timestamp).getTime()) <= windowMs ? 'recent' : 'quiet';
+  }
+
+  return {
+    window_minutes: Math.round(windowMs / 60000),
+    freshness,
+    recent_count: recentCount,
+    latest_event: latestEvent,
+  };
+}
+
+export function readRecentRunEventSummary(root, opts = {}) {
+  const events = readRunEvents(root);
+  return buildRecentEventSummary(events, opts);
+}
+
+export function formatRecentEventSummaryLine(summary, scopeLabel = null) {
+  const prefix = scopeLabel ? `${scopeLabel}: ` : '';
+  if (!summary || typeof summary !== 'object') return `${prefix}unknown`;
+  const countLabel = `${summary.recent_count || 0} in last ${summary.window_minutes || RECENT_EVENT_WINDOW_MINUTES}m`;
+  switch (summary.freshness) {
+    case 'recent':
+      return `${prefix}recent (${countLabel})`;
+    case 'quiet':
+      return `${prefix}quiet (${countLabel})`;
+    case 'unknown':
+      return `${prefix}unknown timing`;
+    case 'no_events':
+    default:
+      return `${prefix}none recorded`;
+  }
+}