agentxchain 2.104.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/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`;
+  }
+}

package/src/lib/repo-decisions.js

@@ -66,38 +66,15 @@ export function summarizeRepoDecisions(decisions, config) {
   if (!Array.isArray(decisions) || decisions.length === 0) return null;
   const active = decisions.filter((d) => d.status === 'active');
   const overridden = decisions.filter((d) => d.status === 'overridden');
-  const addAuthority = (decision) => {
-    const authority = getDecisionAuthorityMetadata(decision.role, config);
-    return {
-      id: decision.id,
-      category: decision.category,
-      statement: decision.statement,
-      role: decision.role,
-      run_id: decision.run_id,
-      overrides: decision.overrides || null,
-      durability: decision.durability || 'repo',
-      authority_level: authority?.level ?? null,
-      authority_source: authority?.source || null,
-    };
-  };
+  const activeEntries = active.map((decision) => addActiveAuthority(decision, config));
+  const overriddenEntries = overridden.map((decision) => addOverriddenAuthority(decision, config));
   return {
     total: decisions.length,
     active_count: active.length,
     overridden_count: overridden.length,
-    active: active.map(addAuthority),
-    overridden: overridden.map((d) => {
-      const authority = getDecisionAuthorityMetadata(d.role, config);
-      return {
-        id: d.id,
-        overridden_by: d.overridden_by,
-        statement: d.statement,
-        overrides: d.overrides || null,
-        durability: d.durability || 'repo',
-        role: d.role || null,
-        authority_level: authority?.level ?? null,
-        authority_source: authority?.source || null,
-      };
-    }),
+    active: activeEntries,
+    overridden: overriddenEntries,
+    operator_summary: buildRepoDecisionOperatorSummaryFromEntries(activeEntries, overriddenEntries),
   };
 }
 
@@ -105,6 +82,17 @@ export function buildRepoDecisionsSummary(decisions) {
   return summarizeRepoDecisions(decisions, null);
 }
 
+export function buildRepoDecisionOperatorSummary(decisions, config) {
+  if (!Array.isArray(decisions) || decisions.length === 0) return null;
+  const activeEntries = decisions
+    .filter((decision) => decision.status === 'active')
+    .map((decision) => addActiveAuthority(decision, config));
+  const overriddenEntries = decisions
+    .filter((decision) => decision.status === 'overridden')
+    .map((decision) => addOverriddenAuthority(decision, config));
+  return buildRepoDecisionOperatorSummaryFromEntries(activeEntries, overriddenEntries);
+}
+
 // ── Write ───────────────────────────────────────────────────────────────────
 
 export function appendRepoDecision(root, entry) {
@@ -255,6 +243,59 @@ export function renderRepoDecisionsMarkdown(activeDecisions, config) {
   return lines.join('\n');
 }
 
+function addActiveAuthority(decision, config) {
+  const authority = getDecisionAuthorityMetadata(decision.role, config);
+  return {
+    id: decision.id,
+    category: decision.category,
+    statement: decision.statement,
+    role: decision.role,
+    run_id: decision.run_id,
+    overrides: decision.overrides || null,
+    durability: decision.durability || 'repo',
+    authority_level: authority?.level ?? null,
+    authority_source: authority?.source || null,
+  };
+}
+
+function addOverriddenAuthority(decision, config) {
+  const authority = getDecisionAuthorityMetadata(decision.role, config);
+  return {
+    id: decision.id,
+    overridden_by: decision.overridden_by,
+    statement: decision.statement,
+    overrides: decision.overrides || null,
+    durability: decision.durability || 'repo',
+    role: decision.role || null,
+    authority_level: authority?.level ?? null,
+    authority_source: authority?.source || null,
+  };
+}
+
+function buildRepoDecisionOperatorSummaryFromEntries(activeEntries, overriddenEntries) {
+  const activeCategories = [...new Set(
+    activeEntries
+      .map((decision) => decision.category)
+      .filter(Boolean),
+  )].sort();
+
+  const highestAuthority = activeEntries
+    .filter((decision) => typeof decision.authority_level === 'number')
+    .reduce((current, decision) => {
+      if (!current || decision.authority_level > current.authority_level) return decision;
+      return current;
+    }, null);
+
+  return {
+    active_categories: activeCategories,
+    highest_active_authority_level: highestAuthority?.authority_level ?? null,
+    highest_active_authority_role: highestAuthority?.role ?? null,
+    highest_active_authority_source: highestAuthority?.authority_source ?? null,
+    superseding_active_count: activeEntries.filter((decision) => decision.overrides).length,
+    overridden_with_successor_count: overriddenEntries.filter((decision) => decision.overridden_by).length,
+  };
+}
+
 // ── Constants ───────────────────────────────────────────────────────────────
 
 export { REPO_DECISIONS_PATH };