agentxchain 2.107.0 → 2.109.0

package/src/lib/governed-state.js

@@ -39,7 +39,7 @@ import {
 import { getMaxConcurrentTurns } from './normalized-config.js';
 import { getTurnStagingResultPath, getTurnStagingDir, getDispatchTurnDir, getReviewArtifactPath } from './turn-paths.js';
 import { runHooks } from './hook-runner.js';
-import { emitNotifications } from './notification-runner.js';
+import { emitNotifications, clearSlaReminders } from './notification-runner.js';
 import { emitRunEvent } from './run-events.js';
 import { writeSessionCheckpoint } from './session-checkpoint.js';
 import { recordRunHistory } from './run-history.js';
@@ -54,6 +54,7 @@ import {
   replayVerificationMachineEvidence,
   summarizeVerificationReplay,
 } from './verification-replay.js';
+import { executeGateActions } from './gate-actions.js';
 
 // ── Constants ────────────────────────────────────────────────────────────────
 
@@ -1273,6 +1274,67 @@ function canApprovePendingGate(state) {
   return state?.status === 'paused' || state?.status === 'blocked';
 }
 
+function blockRunForGateActionFailure(root, state, gateFailure, config) {
+  const gateType = gateFailure.gate_type === 'run_completion' ? 'run_completion' : 'phase_transition';
+  const recoveryAction = gateType === 'run_completion'
+    ? 'agentxchain approve-completion'
+    : 'agentxchain approve-transition';
+  const actionLabel = gateFailure.action_label || gateFailure.command || gateFailure.gate_id || 'gate action';
+  const blockedAt = gateFailure.timestamp || new Date().toISOString();
+  const blockedState = {
+    ...state,
+    status: 'blocked',
+    blocked_on: `gate_action:${gateFailure.gate_id || 'unknown'}`,
+    blocked_reason: {
+      category: 'gate_action_failed',
+      blocked_at: blockedAt,
+      turn_id: gateFailure.requested_by_turn || null,
+      detail: `Gate action failed for "${gateFailure.gate_id || 'unknown'}": ${actionLabel}`,
+      recovery: {
+        typed_reason: 'gate_action_failed',
+        owner: 'human',
+        recovery_action: recoveryAction,
+        turn_retained: false,
+        detail: `${gateFailure.gate_id || 'unknown'} action ${gateFailure.action_index || '?'} (${actionLabel})`,
+      },
+      gate_action: {
+        attempt_id: gateFailure.attempt_id || null,
+        gate_id: gateFailure.gate_id || null,
+        gate_type: gateType,
+        action_index: gateFailure.action_index || null,
+        action_label: gateFailure.action_label || null,
+        command: gateFailure.command || null,
+        exit_code: gateFailure.exit_code ?? null,
+        stderr_tail: gateFailure.stderr_tail || null,
+      },
+    },
+  };
+
+  writeState(root, blockedState);
+  emitBlockedNotification(root, config, blockedState, {
+    category: 'gate_action_failed',
+    blockedOn: blockedState.blocked_on,
+    recovery: blockedState.blocked_reason.recovery,
+  });
+  emitRunEvent(root, 'run_blocked', {
+    run_id: blockedState.run_id,
+    phase: blockedState.phase,
+    status: blockedState.status,
+    turn: gateFailure.requested_by_turn
+      ? { turn_id: gateFailure.requested_by_turn, role_id: null }
+      : undefined,
+    payload: {
+      category: 'gate_action_failed',
+      gate_id: gateFailure.gate_id || null,
+      gate_type: gateType,
+      action_index: gateFailure.action_index || null,
+      exit_code: gateFailure.exit_code ?? null,
+    },
+  });
+
+  return blockedState;
+}
+
 function deriveHookRecovery(state, { phase, hookName, detail, errorCode, turnId, turnRetained }) {
   const isTamper = errorCode?.includes('_tamper');
   const pendingPhaseTransition = state?.pending_phase_transition;
@@ -2652,11 +2714,32 @@ function _acceptGovernedTurnLocked(root, config, opts) {
       },
     });
 
+    // DEC-RUN-LOOP-CONFLICT-002: Persist turn_conflicted as a durable run event
+    emitRunEvent(root, 'turn_conflicted', {
+      run_id: state.run_id,
+      phase: state.phase,
+      status: updatedState.status,
+      turn: { turn_id: currentTurn.turn_id, role_id: currentTurn.assigned_role },
+      payload: {
+        error_code: 'conflict',
+        detection_count: detectionCount,
+        conflicting_files: conflict.conflicting_files,
+        accepted_since_turn_ids: conflict.accepted_since.map(entry => entry.turn_id),
+        overlap_ratio: conflict.overlap_ratio,
+      },
+    });
+
     writeState(root, updatedState);
 
     // DEC-RHTR-SPEC: Record conflict_loop blocked outcome in cross-run history (non-fatal)
     if (updatedState.status === 'blocked') {
       recordRunHistory(root, updatedState, config, 'blocked');
+      // DEC-CONFLICT-NOTIFY-001: Emit run_blocked notification for conflict-loop exhaustion
+      emitBlockedNotification(root, config, updatedState, {
+        category: 'conflict_loop',
+        blockedOn: updatedState.blocked_on,
+        recovery: updatedState.blocked_reason?.recovery || null,
+      }, currentTurn);
     }
 
     return {
@@ -3799,9 +3882,10 @@ export function rejectGovernedTurn(root, config, validationResult, reasonOrOptio
  *
  * @param {string} root - project root directory
  * @param {object} [config] - normalized config (optional; required for hook support)
+ * @param {object} [opts] - optional execution controls
  * @returns {{ ok: boolean, error?: string, error_code?: string, state?: object, transition?: object, hookResults?: object }}
  */
-export function approvePhaseTransition(root, config) {
+export function approvePhaseTransition(root, config, opts = {}) {
   const state = readState(root);
   if (!state) {
     return { ok: false, error: 'No governed state.json found' };
@@ -3815,6 +3899,23 @@ export function approvePhaseTransition(root, config) {
 
   const transition = state.pending_phase_transition;
 
+  if (opts.dryRun) {
+    const gateActions = executeGateActions(root, config, {
+      gateId: transition.gate,
+      gateType: 'phase_transition',
+      phase: state.phase,
+      requestedByTurn: transition.requested_by_turn || null,
+      triggerCommand: 'approve-transition',
+    }, { dryRun: true });
+    return {
+      ok: true,
+      dry_run: true,
+      state: attachLegacyCurrentTurnAlias(state),
+      transition,
+      gate_actions: gateActions.actions,
+    };
+  }
+
   // ── before_gate hooks ──────────────────────────────────────────────
   const hooksConfig = config?.hooks || {};
   if (hooksConfig.before_gate && hooksConfig.before_gate.length > 0) {
@@ -3856,6 +3957,32 @@ export function approvePhaseTransition(root, config) {
     }
   }
 
+  const gateActions = executeGateActions(root, config, {
+    gateId: transition.gate,
+    gateType: 'phase_transition',
+    phase: state.phase,
+    requestedByTurn: transition.requested_by_turn || null,
+    triggerCommand: 'approve-transition',
+  });
+
+  if (!gateActions.ok) {
+    for (const entry of gateActions.actions || []) {
+      appendJsonl(root, LEDGER_PATH, entry);
+    }
+    const blockedState = blockRunForGateActionFailure(root, state, gateActions.failed_action, config);
+    return {
+      ok: false,
+      error: gateActions.error,
+      error_code: 'gate_action_failed',
+      state: blockedState,
+      gateActionRun: gateActions,
+    };
+  }
+
+  for (const entry of gateActions.actions || []) {
+    appendJsonl(root, LEDGER_PATH, entry);
+  }
+
   const updatedState = {
     ...state,
     phase: transition.to,
@@ -3872,6 +3999,7 @@ export function approvePhaseTransition(root, config) {
   };
 
   writeState(root, updatedState);
+  clearSlaReminders(root, 'pending_phase_transition');
   emitRunEvent(root, 'gate_approved', {
     run_id: updatedState.run_id,
     phase: updatedState.phase,
@@ -3897,6 +4025,7 @@ export function approvePhaseTransition(root, config) {
     ok: true,
     state: attachLegacyCurrentTurnAlias(updatedState),
     transition,
+    gateActionRun: gateActions,
   };
 }
 
@@ -3912,9 +4041,10 @@ export function approvePhaseTransition(root, config) {
  *
  * @param {string} root - project root directory
  * @param {object} [config] - normalized config (optional; required for hook support)
+ * @param {object} [opts] - optional execution controls
  * @returns {{ ok: boolean, error?: string, error_code?: string, state?: object, completion?: object, hookResults?: object }}
  */
-export function approveRunCompletion(root, config) {
+export function approveRunCompletion(root, config, opts = {}) {
   const state = readState(root);
   if (!state) {
     return { ok: false, error: 'No governed state.json found' };
@@ -3928,6 +4058,23 @@ export function approveRunCompletion(root, config) {
 
   const completion = state.pending_run_completion;
 
+  if (opts.dryRun) {
+    const gateActions = executeGateActions(root, config, {
+      gateId: completion.gate,
+      gateType: 'run_completion',
+      phase: state.phase,
+      requestedByTurn: completion.requested_by_turn || null,
+      triggerCommand: 'approve-completion',
+    }, { dryRun: true });
+    return {
+      ok: true,
+      dry_run: true,
+      state: attachLegacyCurrentTurnAlias(state),
+      completion,
+      gate_actions: gateActions.actions,
+    };
+  }
+
   // ── before_gate hooks ──────────────────────────────────────────────
   const hooksConfig = config?.hooks || {};
   if (hooksConfig.before_gate && hooksConfig.before_gate.length > 0) {
@@ -3969,6 +4116,32 @@ export function approveRunCompletion(root, config) {
     }
   }
 
+  const gateActions = executeGateActions(root, config, {
+    gateId: completion.gate,
+    gateType: 'run_completion',
+    phase: state.phase,
+    requestedByTurn: completion.requested_by_turn || null,
+    triggerCommand: 'approve-completion',
+  });
+
+  if (!gateActions.ok) {
+    for (const entry of gateActions.actions || []) {
+      appendJsonl(root, LEDGER_PATH, entry);
+    }
+    const blockedState = blockRunForGateActionFailure(root, state, gateActions.failed_action, config);
+    return {
+      ok: false,
+      error: gateActions.error,
+      error_code: 'gate_action_failed',
+      state: blockedState,
+      gateActionRun: gateActions,
+    };
+  }
+
+  for (const entry of gateActions.actions || []) {
+    appendJsonl(root, LEDGER_PATH, entry);
+  }
+
   const updatedState = {
     ...state,
     status: 'completed',
@@ -3984,6 +4157,7 @@ export function approveRunCompletion(root, config) {
   };
 
   writeState(root, updatedState);
+  clearSlaReminders(root, 'pending_run_completion');
 
   emitPendingLifecycleNotification(root, config, updatedState, 'run_completed', {
     completed_at: updatedState.completed_at,
@@ -4014,6 +4188,7 @@ export function approveRunCompletion(root, config) {
     ok: true,
     state: attachLegacyCurrentTurnAlias(updatedState),
     completion,
+    gateActionRun: gateActions,
   };
 }
 

package/src/lib/normalized-config.js

@@ -28,6 +28,7 @@ import {
   isWorkflowKitPhaseTemplateId,
   VALID_WORKFLOW_KIT_PHASE_TEMPLATE_IDS,
 } from './workflow-kit-phase-templates.js';
+import { validateGateActionsConfig } from './gate-actions.js';
 
 const VALID_WRITE_AUTHORITIES = ['authoritative', 'proposed', 'review_only'];
 const VALID_RUNTIME_TYPES = ['manual', 'local_cli', 'api_proxy', 'mcp', 'remote_agent'];
@@ -501,7 +502,8 @@ export function validateV4Config(data, projectRoot) {
 
   // Gates (optional but validated if present)
   if (data.gates) {
-    if (data.routing) {
+    validateGateActionsConfig(data.gates, errors);
+    if (data.gates && typeof data.gates === 'object' && !Array.isArray(data.gates) && data.routing) {
       for (const [, route] of Object.entries(data.routing)) {
         if (route.exit_gate && !data.gates[route.exit_gate]) {
           errors.push(`Routing references unknown gate: "${route.exit_gate}"`);
@@ -520,6 +522,9 @@ export function validateV4Config(data, projectRoot) {
   if (data.notifications) {
     const notificationValidation = validateNotificationsConfig(data.notifications);
     errors.push(...notificationValidation.errors);
+    if (Array.isArray(notificationValidation.warnings)) {
+      warnings.push(...notificationValidation.warnings);
+    }
   }
 
   // Schedules (optional but validated if present)

package/src/lib/notification-runner.js

@@ -1,4 +1,4 @@
-import { appendFileSync, existsSync, mkdirSync } from 'node:fs';
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
 import { dirname, join } from 'node:path';
 import { randomBytes } from 'node:crypto';
@@ -13,6 +13,7 @@ export const VALID_NOTIFICATION_EVENTS = [
   'phase_transition_pending',
   'run_completion_pending',
   'run_completed',
+  'approval_sla_reminder',
 ];
 
 const NOTIFICATION_NAME_RE = /^[a-z0-9_-]+$/;
@@ -166,10 +167,10 @@ export function validateNotificationsConfig(notifications) {
 
   if (!notifications || typeof notifications !== 'object' || Array.isArray(notifications)) {
     errors.push('notifications must be an object');
-    return { ok: false, errors };
+    return { ok: false, errors, warnings: [] };
   }
 
-  const allowedKeys = new Set(['webhooks']);
+  const allowedKeys = new Set(['webhooks', 'approval_sla']);
   for (const key of Object.keys(notifications)) {
     if (!allowedKeys.has(key)) {
       errors.push(`notifications contains unknown field "${key}"`);
@@ -177,12 +178,12 @@ export function validateNotificationsConfig(notifications) {
   }
 
   if (!('webhooks' in notifications)) {
-    return { ok: errors.length === 0, errors };
+    return { ok: errors.length === 0, errors, warnings: [] };
   }
 
   if (!Array.isArray(notifications.webhooks)) {
     errors.push('notifications.webhooks must be an array');
-    return { ok: false, errors };
+    return { ok: false, errors, warnings: [] };
   }
 
   if (notifications.webhooks.length > MAX_NOTIFICATION_WEBHOOKS) {
@@ -261,7 +262,51 @@ export function validateNotificationsConfig(notifications) {
     }
   });
 
-  return { ok: errors.length === 0, errors };
+  // Validate approval_sla if present
+  const warnings = [];
+  if (notifications.approval_sla !== undefined) {
+    const sla = notifications.approval_sla;
+    if (!sla || typeof sla !== 'object' || Array.isArray(sla)) {
+      errors.push('notifications.approval_sla must be an object');
+    } else {
+      const slaAllowed = new Set(['enabled', 'reminder_after_seconds']);
+      for (const key of Object.keys(sla)) {
+        if (!slaAllowed.has(key)) {
+          errors.push(`notifications.approval_sla contains unknown field "${key}"`);
+        }
+      }
+      if ('enabled' in sla && typeof sla.enabled !== 'boolean') {
+        errors.push('notifications.approval_sla.enabled must be a boolean');
+      }
+      if (!Array.isArray(sla.reminder_after_seconds) || sla.reminder_after_seconds.length === 0) {
+        errors.push('notifications.approval_sla.reminder_after_seconds must be a non-empty array of positive integers');
+      } else {
+        if (sla.reminder_after_seconds.length > 10) {
+          errors.push('notifications.approval_sla.reminder_after_seconds: maximum 10 thresholds');
+        }
+        let prev = 0;
+        for (let i = 0; i < sla.reminder_after_seconds.length; i++) {
+          const v = sla.reminder_after_seconds[i];
+          if (!Number.isInteger(v) || v <= 0) {
+            errors.push(`notifications.approval_sla.reminder_after_seconds[${i}]: must be a positive integer`);
+          } else if (v < 300) {
+            errors.push(`notifications.approval_sla.reminder_after_seconds[${i}]: minimum value is 300 (5 minutes)`);
+          } else if (v <= prev) {
+            errors.push(`notifications.approval_sla.reminder_after_seconds[${i}]: values must be strictly ascending`);
+          }
+          prev = v;
+        }
+      }
+      // Warn if no webhook subscribes to approval_sla_reminder
+      const hasSubscriber = Array.isArray(notifications.webhooks) &&
+        notifications.webhooks.some(w => Array.isArray(w.events) && w.events.includes('approval_sla_reminder'));
+      if (!hasSubscriber) {
+        warnings.push('notifications.approval_sla is configured but no webhook subscribes to "approval_sla_reminder"');
+      }
+    }
+  }
+
+  return { ok: errors.length === 0, errors, warnings };
 }
 
 export function emitNotifications(root, config, state, eventType, payload = {}, turn = null) {
@@ -328,3 +373,114 @@ export function emitNotifications(root, config, state, eventType, payload = {},
 
   return { ok: true, event_id: eventId, results };
 }
+
+const SLA_REMINDERS_PATH = '.agentxchain/sla-reminders.json';
+
+function readSlaReminders(root) {
+  try {
+    const filePath = join(root, SLA_REMINDERS_PATH);
+    if (!existsSync(filePath)) return [];
+    const data = JSON.parse(readFileSync(filePath, 'utf8'));
+    return Array.isArray(data) ? data : [];
+  } catch { return []; }
+}
+
+function writeSlaReminders(root, sent) {
+  const filePath = join(root, SLA_REMINDERS_PATH);
+  mkdirSync(dirname(filePath), { recursive: true });
+  writeFileSync(filePath, JSON.stringify(sent, null, 2) + '\n');
+}
+
+/**
+ * Evaluate and emit approval SLA reminders for pending approvals.
+ * Uses `.agentxchain/sla-reminders.json` for dedup tracking (not governed state).
+ * Returns { reminders_sent: string[], notifications_emitted: number }.
+ */
+export function evaluateApprovalSlaReminders(root, config, state) {
+  const result = { reminders_sent: [], notifications_emitted: 0 };
+
+  const sla = config?.notifications?.approval_sla;
+  if (!sla || sla.enabled === false) return result;
+  if (!Array.isArray(sla.reminder_after_seconds) || sla.reminder_after_seconds.length === 0) return result;
+
+  const webhooks = config?.notifications?.webhooks;
+  if (!Array.isArray(webhooks) || !webhooks.some(w => Array.isArray(w.events) && w.events.includes('approval_sla_reminder'))) {
+    return result;
+  }
+
+  if (!state) return result;
+
+  const sent = readSlaReminders(root);
+  const now = Date.now();
+  const pendingApprovals = [];
+
+  if (state.pending_phase_transition && state.pending_phase_transition.requested_at) {
+    pendingApprovals.push({
+      approval_type: 'pending_phase_transition',
+      requested_at: state.pending_phase_transition.requested_at,
+      from_phase: state.pending_phase_transition.from || null,
+      to_phase: state.pending_phase_transition.to || null,
+      gate: state.pending_phase_transition.gate || null,
+    });
+  }
+
+  if (state.pending_run_completion && state.pending_run_completion.requested_at) {
+    pendingApprovals.push({
+      approval_type: 'pending_run_completion',
+      requested_at: state.pending_run_completion.requested_at,
+      from_phase: null,
+      to_phase: null,
+      gate: state.pending_run_completion.gate || null,
+    });
+  }
+
+  let changed = false;
+  for (const approval of pendingApprovals) {
+    const requestedMs = new Date(approval.requested_at).getTime();
+    if (isNaN(requestedMs)) continue;
+    const elapsedSeconds = Math.floor((now - requestedMs) / 1000);
+
+    for (let i = 0; i < sla.reminder_after_seconds.length; i++) {
+      const threshold = sla.reminder_after_seconds[i];
+      const reminderKey = `${approval.approval_type}:${threshold}`;
+
+      if (elapsedSeconds >= threshold && !sent.includes(reminderKey)) {
+        const payload = {
+          approval_type: approval.approval_type,
+          requested_at: approval.requested_at,
+          elapsed_seconds: elapsedSeconds,
+          threshold_seconds: threshold,
+          reminder_index: i + 1,
+          total_thresholds: sla.reminder_after_seconds.length,
+        };
+        if (approval.from_phase) payload.from_phase = approval.from_phase;
+        if (approval.to_phase) payload.to_phase = approval.to_phase;
+        if (approval.gate) payload.gate = approval.gate;
+
+        emitNotifications(root, config, state, 'approval_sla_reminder', payload);
+        sent.push(reminderKey);
+        result.reminders_sent.push(reminderKey);
+        result.notifications_emitted++;
+        changed = true;
+      }
+    }
+  }
+
+  if (changed) {
+    writeSlaReminders(root, sent);
+  }
+
+  return result;
+}
+
+/**
+ * Clear SLA reminder tracking for a resolved approval type.
+ * Called from approve-transition / approve-completion.
+ */
+export function clearSlaReminders(root, approvalType) {
+  const sent = readSlaReminders(root);
+  const filtered = sent.filter(k => !k.startsWith(`${approvalType}:`));
+  if (filtered.length !== sent.length) {
+    writeSlaReminders(root, filtered);
+  }
+}