agentxchain 2.107.0 → 2.109.0

package/src/commands/status.js

@@ -14,9 +14,11 @@ import { getConnectorHealth } from '../lib/connector-health.js';
 import { readRepoDecisions, summarizeRepoDecisions } from '../lib/repo-decisions.js';
 import { deriveWorkflowKitArtifacts } from '../lib/workflow-kit-artifacts.js';
 import { evaluateTimeouts } from '../lib/timeout-evaluator.js';
+import { evaluateApprovalSlaReminders } from '../lib/notification-runner.js';
 import { summarizeRunProvenance } from '../lib/run-provenance.js';
 import { readRecentRunEventSummary } from '../lib/recent-event-summary.js';
 import { deriveConflictedTurnResolutionActions } from '../lib/conflict-actions.js';
+import { summarizeLatestGateActionAttempt } from '../lib/gate-actions.js';
 import { getDashboardPid, getDashboardSession } from './dashboard.js';
 
 export async function statusCommand(opts) {
@@ -125,6 +127,14 @@ function renderGovernedStatus(context, opts) {
   const repoDecisionSummary = summarizeRepoDecisions(readRepoDecisions(root), config);
 
   const workflowKitArtifacts = deriveWorkflowKitArtifacts(root, config, state);
+  const gateActionAttempt = state?.pending_phase_transition
+    ? summarizeLatestGateActionAttempt(root, 'phase_transition', state.pending_phase_transition.gate)
+    : state?.pending_run_completion
+      ? summarizeLatestGateActionAttempt(root, 'run_completion', state.pending_run_completion.gate)
+      : null;
+
+  // Fire approval SLA reminders as a side effect (webhook-only, no CLI output)
+  evaluateApprovalSlaReminders(root, config, state);
 
   if (opts.json) {
     const dashPid = getDashboardPid(root);
@@ -152,6 +162,7 @@ function renderGovernedStatus(context, opts) {
       next_actions: nextActions,
       connector_health: connectorHealth,
       recent_event_summary: recentEventSummary,
+      gate_action_attempt: gateActionAttempt,
       workflow_kit_artifacts: workflowKitArtifacts,
       dashboard_session: dashboardSessionObj,
     }, null, 2));
@@ -197,6 +208,7 @@ function renderGovernedStatus(context, opts) {
   const activeTurnCount = getActiveTurnCount(state);
   const activeTurns = getActiveTurns(state);
   const singleActiveTurn = getActiveTurn(state);
+  const approvalPending = Boolean(state?.pending_phase_transition || state?.pending_run_completion);
   if (activeTurnCount > 1) {
     console.log(`  ${chalk.dim('Turns:')}    ${activeTurnCount} active`);
     for (const turn of Object.values(activeTurns)) {
@@ -249,8 +261,14 @@ function renderGovernedStatus(context, opts) {
     if (singleActiveTurn.status === 'conflicted' && singleActiveTurn.conflict_state) {
       const cs = singleActiveTurn.conflict_state;
       const files = cs.conflict_error?.conflicting_files || [];
+      const count = cs.detection_count || 1;
       const [reassignAction, mergeAction] = deriveConflictedTurnResolutionActions(singleActiveTurn.turn_id);
-      console.log(`  ${chalk.dim('Conflict:')} ${chalk.red(`${files.length} file(s) conflicting`)} — detection #${cs.detection_count || 1}`);
+      console.log(`  ${chalk.dim('Conflict:')} ${chalk.red(`${files.length} file(s) conflicting`)} — detection #${count}`);
+      if (cs.conflict_error?.overlap_ratio != null) {
+        console.log(`  ${chalk.dim('Overlap:')}  ${(cs.conflict_error.overlap_ratio * 100).toFixed(0)}%`);
+      }
+      const suggestion = cs.conflict_error?.suggested_resolution || 'reject_and_reassign';
+      console.log(`  ${chalk.dim('Suggest:')}  ${suggestion}`);
       console.log(`  ${chalk.dim('Resolve:')}  ${chalk.cyan(reassignAction.command)}`);
       console.log(`  ${chalk.dim('     or:')}  ${chalk.cyan(mergeAction.command)}`);
     }
@@ -321,12 +339,33 @@ function renderGovernedStatus(context, opts) {
     const pt = state.pending_phase_transition;
     console.log(`  ${chalk.dim('Pending:')}  ${formatGovernedPhase(pt.from)} → ${formatGovernedPhase(pt.to)}`);
     console.log(`  ${chalk.dim('Gate:')}     ${pt.gate} (requires human approval)`);
+    if (pt.requested_at) {
+      console.log(`  ${chalk.dim('Requested:')} ${pt.requested_at} (${timeSince(pt.requested_at)} ago)`);
+    }
   }
 
   if (state?.pending_run_completion) {
     const pc = state.pending_run_completion;
     console.log(`  ${chalk.dim('Pending:')}  ${chalk.bold('Run Completion')}`);
     console.log(`  ${chalk.dim('Gate:')}     ${pc.gate} (requires human approval)`);
+    if (pc.requested_at) {
+      console.log(`  ${chalk.dim('Requested:')} ${pc.requested_at} (${timeSince(pc.requested_at)} ago)`);
+    }
+  }
+
+  if (gateActionAttempt) {
+    console.log(`  ${chalk.dim('Gate actions:')} ${gateActionAttempt.status} at ${gateActionAttempt.attempted_at || 'unknown time'}`);
+    for (const action of gateActionAttempt.actions) {
+      const label = action.action_label || action.command || `action ${action.action_index || '?'}`;
+      const outcome = action.status === 'failed'
+        ? chalk.red('failed')
+        : chalk.green('succeeded');
+      const exit = action.exit_code == null ? '' : ` (exit ${action.exit_code})`;
+      console.log(`    ${action.action_index || '?'}. ${label} — ${outcome}${exit}`);
+      if (action.status === 'failed' && action.stderr_tail) {
+        console.log(`      ${chalk.dim(action.stderr_tail)}`);
+      }
+    }
   }
 
   if (state?.status === 'completed') {
@@ -368,14 +407,20 @@ function renderGovernedStatus(context, opts) {
 
   renderWorkflowKitArtifactsSection(workflowKitArtifacts);
 
-  if (config.timeouts && state?.status === 'active') {
-    const activeTurn = getActiveTurn(state);
+  if (config.timeouts && (state?.status === 'active' || approvalPending)) {
+    const activeTurn = state?.status === 'active' ? getActiveTurn(state) : null;
     const turnResult = activeTurn ? { role: activeTurn.assigned_role } : undefined;
     const timeoutEval = evaluateTimeouts({ config, state, turn: activeTurn, turnResult, now: new Date().toISOString() });
     const allItems = [...timeoutEval.exceeded, ...timeoutEval.warnings];
-    if (allItems.length > 0) {
+    if (allItems.length > 0 || approvalPending) {
       console.log('');
       console.log(`  ${chalk.dim('Timeouts:')}`);
+      if (approvalPending) {
+        console.log(`    ${chalk.yellow('◷')} approval wait does not mutate timeout state; phase/run clocks keep ticking until the next accepted turn`);
+      }
+      if (approvalPending && allItems.length === 0) {
+        console.log(`    ${chalk.dim('No current phase/run timeout pressure.')}`);
+      }
       for (const item of allItems) {
         const isExceeded = timeoutEval.exceeded.includes(item);
         const elapsed = item.elapsed_minutes != null ? `${item.elapsed_minutes}m` : '?';
@@ -637,6 +682,7 @@ function formatRunStatus(status) {
 
 function timeSince(iso) {
   const ms = Date.now() - new Date(iso).getTime();
+  if (!Number.isFinite(ms) || ms < 0) return '0s';
   const sec = Math.floor(ms / 1000);
   if (sec < 60) return `${sec}s`;
   const min = Math.floor(sec / 60);

package/src/commands/step.js

@@ -67,6 +67,7 @@ import { runHooks } from '../lib/hook-runner.js';
 import { finalizeDispatchManifest, verifyDispatchManifest } from '../lib/dispatch-manifest.js';
 import { resolveGovernedRole } from '../lib/role-resolution.js';
 import { shouldSuggestManualQaFallback } from '../lib/manual-qa-fallback.js';
+import { evaluateApprovalSlaReminders } from '../lib/notification-runner.js';
 
 export async function stepCommand(opts) {
   const context = loadProjectContext();
@@ -169,6 +170,7 @@ export async function stepCommand(opts) {
 
   if (!skipAssignment) {
     if (state.pending_phase_transition || state.pending_run_completion) {
+      evaluateApprovalSlaReminders(root, config, state);
       printRecoverySummary(state, 'This run is awaiting approval.', config);
       process.exit(1);
     }

package/src/lib/dashboard/bridge-server.js

@@ -26,6 +26,9 @@ import { readWorkflowKitArtifacts } from './workflow-kit-artifacts.js';
 import { readConnectorHealthSnapshot } from './connectors.js';
 import { readTimeoutStatus } from './timeout-status.js';
 import { queryRunHistory } from '../run-history.js';
+import { loadProjectContext, loadProjectState } from '../config.js';
+import { evaluateApprovalSlaReminders } from '../notification-runner.js';
+import { readGateActionSnapshot } from './gate-action-reader.js';
 
 const MIME_TYPES = {
   '.html': 'text/html; charset=utf-8',
@@ -214,6 +217,40 @@ function resolveDashboardAssetPath(dashboardDir, pathname) {
   return { blocked: false, filePath };
 }
 
+function readDashboardPollStatus(workspacePath, replayMode) {
+  const body = {
+    ok: true,
+    polled_at: new Date().toISOString(),
+    replay_mode: replayMode,
+    governed_project_detected: false,
+    state_available: false,
+    reminder_evaluation: {
+      reminders_sent: [],
+      notifications_emitted: 0,
+    },
+  };
+
+  if (replayMode) {
+    return { ok: true, status: 200, body };
+  }
+
+  const context = loadProjectContext(workspacePath);
+  if (!context || context.config?.protocol_mode !== 'governed') {
+    return { ok: true, status: 200, body };
+  }
+
+  body.governed_project_detected = true;
+
+  const state = loadProjectState(context.root, context.config);
+  if (!state) {
+    return { ok: true, status: 200, body };
+  }
+
+  body.state_available = true;
+  body.reminder_evaluation = evaluateApprovalSlaReminders(context.root, context.config, state);
+  return { ok: true, status: 200, body };
+}
+
 // ── Bridge Server ───────────────────────────────────────────────────────────
 
 export function createBridgeServer({ agentxchainDir, dashboardDir, port = 3847, replayMode = false }) {
@@ -315,6 +352,12 @@ export function createBridgeServer({ agentxchainDir, dashboardDir, port = 3847,
       return;
     }
 
+    if (pathname === '/api/poll') {
+      const result = readDashboardPollStatus(workspacePath, replayMode);
+      writeJson(res, result.status, result.body);
+      return;
+    }
+
     if (pathname === '/api/actions/approve-gate') {
       if (replayMode) {
         writeJson(res, 403, { ok: false, code: 'replay_mode', error: 'Replay mode: gate approval is not available on exported snapshots.' });
@@ -419,6 +462,12 @@ export function createBridgeServer({ agentxchainDir, dashboardDir, port = 3847,
       return;
     }
 
+    if (pathname === '/api/gate-actions') {
+      const result = readGateActionSnapshot(workspacePath);
+      writeJson(res, result.status, result.body);
+      return;
+    }
+
     // API routes
     if (pathname.startsWith('/api/')) {
       const result = readResource(agentxchainDir, pathname);

package/src/lib/dashboard/gate-action-reader.js

@@ -0,0 +1,58 @@
+/**
+ * Gate-action reader — reads gate-action config and latest attempt for the dashboard.
+ *
+ * Follows the same pattern as other dashboard readers (connectors.js, timeout-status.js):
+ * returns { status, body } for the bridge server to serialize.
+ *
+ * Per DEC-DASHBOARD-GATE-ACTIONS-001: repo-local only, read-only.
+ */
+
+import { loadProjectContext, loadProjectState } from '../config.js';
+import { getGateActions, summarizeLatestGateActionAttempt } from '../gate-actions.js';
+
+/**
+ * Read gate-action snapshot for the current pending gate (if any).
+ *
+ * @param {string} workspacePath — project root
+ * @returns {{ status: number, body: object }}
+ */
+export function readGateActionSnapshot(workspacePath) {
+  const context = loadProjectContext(workspacePath);
+  if (!context || context.config?.protocol_mode !== 'governed') {
+    return { status: 200, body: { configured: [], latest_attempt: null } };
+  }
+
+  const state = loadProjectState(context.root, context.config);
+  if (!state) {
+    return { status: 200, body: { configured: [], latest_attempt: null } };
+  }
+
+  const pendingTransition = state.pending_phase_transition || null;
+  const pendingCompletion = state.pending_run_completion || null;
+
+  let gateType = null;
+  let gateId = null;
+
+  if (pendingTransition?.gate) {
+    gateType = 'phase_transition';
+    gateId = pendingTransition.gate;
+  } else if (pendingCompletion?.gate) {
+    gateType = 'run_completion';
+    gateId = pendingCompletion.gate;
+  }
+
+  if (!gateId) {
+    return { status: 200, body: { configured: [], latest_attempt: null } };
+  }
+
+  const configured = getGateActions(context.config, gateId);
+  const latestAttempt = summarizeLatestGateActionAttempt(context.root, gateType, gateId);
+
+  return {
+    status: 200,
+    body: {
+      configured,
+      latest_attempt: latestAttempt,
+    },
+  };
+}

package/src/lib/dashboard/timeout-status.js

@@ -73,6 +73,30 @@ function emptyLiveTimeouts() {
   return { exceeded: [], warnings: [] };
 }
 
+function buildLiveContext(state) {
+  const pendingPhase = state?.pending_phase_transition;
+  const pendingCompletion = state?.pending_run_completion;
+  if (pendingPhase) {
+    return {
+      awaiting_approval: true,
+      pending_gate_type: 'phase_transition',
+      requested_at: typeof pendingPhase.requested_at === 'string' ? pendingPhase.requested_at : null,
+    };
+  }
+  if (pendingCompletion) {
+    return {
+      awaiting_approval: true,
+      pending_gate_type: 'run_completion',
+      requested_at: typeof pendingCompletion.requested_at === 'string' ? pendingCompletion.requested_at : null,
+    };
+  }
+  return {
+    awaiting_approval: false,
+    pending_gate_type: null,
+    requested_at: null,
+  };
+}
+
 function getActiveTurns(state) {
   if (!state?.active_turns || typeof state.active_turns !== 'object' || Array.isArray(state.active_turns)) {
     return [];
@@ -90,7 +114,8 @@ function annotateTurnTimeout(result, state, turn) {
 }
 
 export function evaluateDashboardTimeoutPressure(config, state, now = new Date()) {
-  if (!config?.timeouts || state?.status !== 'active') {
+  const approvalPending = Boolean(state?.pending_phase_transition || state?.pending_run_completion);
+  if (!config?.timeouts || (state?.status !== 'active' && !approvalPending)) {
     return emptyLiveTimeouts();
   }
 
@@ -100,16 +125,18 @@ export function evaluateDashboardTimeoutPressure(config, state, now = new Date()
     warnings: [...base.warnings],
   };
 
-  for (const turn of getActiveTurns(state)) {
-    const turnEval = evaluateTimeouts({ config, state, turn, now });
-    for (const item of turnEval.exceeded) {
-      if (item.scope === 'turn') {
-        live.exceeded.push(annotateTurnTimeout(item, state, turn));
+  if (state?.status === 'active') {
+    for (const turn of getActiveTurns(state)) {
+      const turnEval = evaluateTimeouts({ config, state, turn, now });
+      for (const item of turnEval.exceeded) {
+        if (item.scope === 'turn') {
+          live.exceeded.push(annotateTurnTimeout(item, state, turn));
+        }
       }
-    }
-    for (const item of turnEval.warnings) {
-      if (item.scope === 'turn') {
-        live.warnings.push(annotateTurnTimeout(item, state, turn));
+      for (const item of turnEval.warnings) {
+        if (item.scope === 'turn') {
+          live.warnings.push(annotateTurnTimeout(item, state, turn));
+        }
       }
     }
   }
@@ -172,6 +199,7 @@ export function readTimeoutStatus(workspacePath) {
         configured: false,
         config: null,
         live: null,
+        live_context: null,
         events: [],
       },
     };
@@ -190,12 +218,13 @@ export function readTimeoutStatus(workspacePath) {
   return {
     ok: true,
     status: 200,
-    body: {
-      ok: true,
-      configured: true,
-      config: configSummary,
-      live,
-      events,
-    },
-  };
+      body: {
+        ok: true,
+        configured: true,
+        config: configSummary,
+        live,
+        live_context: buildLiveContext(state),
+        events,
+      },
+    };
 }

package/src/lib/gate-actions.js

@@ -0,0 +1,232 @@
+import { randomBytes } from 'crypto';
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { spawnSync } from 'child_process';
+
+const LEDGER_PATH = '.agentxchain/decision-ledger.jsonl';
+const MAX_OUTPUT_TAIL_CHARS = 1200;
+
+export function validateGateActionsConfig(gates, errors) {
+  if (!gates || typeof gates !== 'object' || Array.isArray(gates)) {
+    errors.push('gates must be an object');
+    return;
+  }
+
+  for (const [gateId, gate] of Object.entries(gates)) {
+    if (!gate || typeof gate !== 'object' || Array.isArray(gate)) {
+      errors.push(`Gate "${gateId}" must be an object`);
+      continue;
+    }
+
+    if (!('gate_actions' in gate)) {
+      continue;
+    }
+
+    if (!Array.isArray(gate.gate_actions) || gate.gate_actions.length === 0) {
+      errors.push(`Gate "${gateId}": gate_actions must be a non-empty array when provided`);
+      continue;
+    }
+
+    if (gate.requires_human_approval !== true) {
+      errors.push(`Gate "${gateId}": gate_actions require requires_human_approval: true`);
+    }
+
+    for (let i = 0; i < gate.gate_actions.length; i++) {
+      const action = gate.gate_actions[i];
+      const prefix = `gates.${gateId}.gate_actions[${i}]`;
+      if (!action || typeof action !== 'object' || Array.isArray(action)) {
+        errors.push(`${prefix} must be an object`);
+        continue;
+      }
+      if (typeof action.run !== 'string' || !action.run.trim()) {
+        errors.push(`${prefix}.run must be a non-empty string`);
+      }
+      if ('label' in action && (typeof action.label !== 'string' || !action.label.trim())) {
+        errors.push(`${prefix}.label must be a non-empty string when provided`);
+      }
+    }
+  }
+}
+
+export function getGateActions(config, gateId) {
+  const actions = config?.gates?.[gateId]?.gate_actions;
+  if (!Array.isArray(actions) || actions.length === 0) {
+    return [];
+  }
+
+  return actions
+    .filter((action) => action && typeof action === 'object' && typeof action.run === 'string' && action.run.trim())
+    .map((action, index) => ({
+      index: index + 1,
+      label: typeof action.label === 'string' && action.label.trim() ? action.label.trim() : null,
+      run: action.run.trim(),
+    }));
+}
+
+function trimOutputTail(value) {
+  if (typeof value !== 'string') {
+    return null;
+  }
+  const trimmed = value.trim();
+  if (!trimmed) {
+    return null;
+  }
+  if (trimmed.length <= MAX_OUTPUT_TAIL_CHARS) {
+    return trimmed;
+  }
+  return trimmed.slice(-MAX_OUTPUT_TAIL_CHARS);
+}
+
+function buildGateActionEntry(action, meta, runtimeResult, status) {
+  return {
+    type: 'gate_action',
+    timestamp: new Date().toISOString(),
+    attempt_id: meta.attemptId,
+    gate_id: meta.gateId,
+    gate_type: meta.gateType,
+    phase: meta.phase || null,
+    requested_by_turn: meta.requestedByTurn || null,
+    trigger_command: meta.triggerCommand || null,
+    action_index: action.index,
+    action_label: action.label,
+    command: action.run,
+    status,
+    exit_code: Number.isInteger(runtimeResult?.status) ? runtimeResult.status : null,
+    signal: runtimeResult?.signal || null,
+    stdout_tail: trimOutputTail(runtimeResult?.stdout),
+    stderr_tail: trimOutputTail(runtimeResult?.stderr),
+    spawn_error: runtimeResult?.error?.message || null,
+  };
+}
+
+export function executeGateActions(root, config, meta, opts = {}) {
+  const actions = getGateActions(config, meta.gateId);
+  if (actions.length === 0) {
+    return { ok: true, dry_run: Boolean(opts.dryRun), actions: [] };
+  }
+
+  if (opts.dryRun) {
+    return { ok: true, dry_run: true, actions };
+  }
+
+  const attemptId = `ga_${Date.now()}_${randomBytes(4).toString('hex')}`;
+  const results = [];
+
+  for (const action of actions) {
+    const runtimeResult = spawnSync('/bin/sh', ['-lc', action.run], {
+      cwd: root,
+      env: {
+        ...process.env,
+        AGENTXCHAIN_GATE_ID: meta.gateId,
+        AGENTXCHAIN_GATE_TYPE: meta.gateType,
+        AGENTXCHAIN_PHASE: meta.phase || '',
+        AGENTXCHAIN_REQUESTED_BY_TURN: meta.requestedByTurn || '',
+        AGENTXCHAIN_TRIGGER_COMMAND: meta.triggerCommand || '',
+      },
+      encoding: 'utf8',
+      maxBuffer: 10 * 1024 * 1024,
+    });
+
+    const status = runtimeResult.error || runtimeResult.status !== 0 ? 'failed' : 'succeeded';
+    const entry = buildGateActionEntry(action, { ...meta, attemptId }, runtimeResult, status);
+    results.push(entry);
+
+    if (status === 'failed') {
+      return {
+        ok: false,
+        attempt_id: attemptId,
+        actions: results,
+        failed_action: entry,
+        error: `Gate action failed for "${meta.gateId}": ${action.label || action.run}`,
+      };
+    }
+  }
+
+  return {
+    ok: true,
+    attempt_id: attemptId,
+    actions: results,
+  };
+}
+
+export function normalizeGateActionEntry(entry) {
+  if (!entry || entry.type !== 'gate_action') {
+    return null;
+  }
+
+  return {
+    attempt_id: entry.attempt_id || null,
+    gate_id: entry.gate_id || null,
+    gate_type: entry.gate_type || null,
+    phase: entry.phase || null,
+    requested_by_turn: entry.requested_by_turn || null,
+    trigger_command: entry.trigger_command || null,
+    action_index: Number.isInteger(entry.action_index) ? entry.action_index : null,
+    action_label: entry.action_label || null,
+    command: entry.command || null,
+    status: entry.status || 'unknown',
+    exit_code: Number.isInteger(entry.exit_code) ? entry.exit_code : null,
+    signal: entry.signal || null,
+    stdout_tail: entry.stdout_tail || null,
+    stderr_tail: entry.stderr_tail || null,
+    spawn_error: entry.spawn_error || null,
+    timestamp: entry.timestamp || null,
+  };
+}
+
+export function extractGateActionDigest(entries) {
+  if (!Array.isArray(entries) || entries.length === 0) {
+    return [];
+  }
+
+  return entries
+    .map(normalizeGateActionEntry)
+    .filter(Boolean)
+    .sort((a, b) => (a.timestamp || '').localeCompare(b.timestamp || ''));
+}
+
+export function readGateActionEntries(root) {
+  const filePath = join(root, LEDGER_PATH);
+  if (!existsSync(filePath)) {
+    return [];
+  }
+
+  const raw = readFileSync(filePath, 'utf8').trim();
+  if (!raw) {
+    return [];
+  }
+
+  const entries = raw
+    .split('\n')
+    .filter(Boolean)
+    .map((line) => {
+      try {
+        return JSON.parse(line);
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean);
+
+  return extractGateActionDigest(entries);
+}
+
+export function summarizeLatestGateActionAttempt(root, gateType, gateId) {
+  const entries = readGateActionEntries(root)
+    .filter((entry) => entry.gate_type === gateType && entry.gate_id === gateId);
+
+  if (entries.length === 0) {
+    return null;
+  }
+
+  const latest = entries[entries.length - 1];
+  const attemptEntries = entries.filter((entry) => entry.attempt_id === latest.attempt_id);
+  return {
+    attempt_id: latest.attempt_id,
+    gate_id: gateId,
+    gate_type: gateType,
+    status: attemptEntries.some((entry) => entry.status === 'failed') ? 'failed' : 'succeeded',
+    attempted_at: latest.timestamp || null,
+    actions: attemptEntries,
+  };
+}