agentxchain 2.104.0 → 2.105.0

package/src/lib/admission-control.js

@@ -14,6 +14,11 @@
  */
 
 import { getEffectiveGateArtifacts } from './gate-evaluator.js';
+import {
+  canRoleParticipateInRequiredFileProduction,
+  canRoleSatisfyWorkflowArtifactOwnership,
+  getRoleRuntimeCapabilityContract,
+} from './runtime-capabilities.js';
 
 /**
  * Run all admission control checks against a governed config.
@@ -68,17 +73,20 @@ export function runAdmissionControl(config, rawConfig) {
         .filter(({ role }) => role);
 
       const hasFileProducer = rolesWithAuthority.some(({ role, runtime }) =>
-        canRoleProduceFiles(role, runtime));
+        canRoleParticipateInRequiredFileProduction(role, runtime));
 
       // Only flag non-manual roles as review_only dead-ends
       const nonManualRoles = rolesWithAuthority.filter(({ runtime }) => runtime?.type !== 'manual');
       if (!hasFileProducer && nonManualRoles.length > 0) {
         const roleSummary = nonManualRoles
-          .map(({ id, role }) => `${id}:${role.write_authority}`)
+          .map(({ id, role, runtime }) => {
+            const contract = getRoleRuntimeCapabilityContract(id, role, runtime);
+            return `${id}:${role.write_authority}/${runtime?.type || 'unknown'}->${contract.effective_write_path}`;
+          })
           .join(', ');
         const fileSummary = requiredArtifacts.map(a => a.path).join(', ');
         errors.push(
-          `ADM-001: Phase "${phase}" gate "${exitGateId}" requires files (${fileSummary}) but all routed roles are review_only (${roleSummary}). No agent can produce the required artifacts.`
+          `ADM-001: Phase "${phase}" gate "${exitGateId}" requires files (${fileSummary}) but no routed role has a reachable file-production path (${roleSummary}).`
         );
       }
 
@@ -97,9 +105,10 @@ export function runAdmissionControl(config, rawConfig) {
         const ownerRuntimeKey = ownerRole.runtime_id || ownerRole.runtime;
         const ownerRuntime = runtimes?.[ownerRuntimeKey];
 
-        if (!canRoleProduceFiles(ownerRole, ownerRuntime)) {
+        if (!canRoleSatisfyWorkflowArtifactOwnership(ownerRole, ownerRuntime)) {
+          const contract = getRoleRuntimeCapabilityContract(artifact.owned_by, ownerRole, ownerRuntime);
           errors.push(
-            `ADM-004: Phase "${phase}" artifact "${artifact.path}" is owned_by "${artifact.owned_by}" but that role is ${ownerRole.write_authority} on runtime type "${ownerRuntime?.type || 'unknown'}". The owner can participate in the phase but cannot produce the required artifact.`
+            `ADM-004: Phase "${phase}" artifact "${artifact.path}" is owned_by "${artifact.owned_by}" but that role resolves to workflow ownership "${contract.workflow_artifact_ownership}" via ${ownerRole.write_authority}/${ownerRuntime?.type || 'unknown'} (${contract.effective_write_path}).`
           );
         }
       }
@@ -238,10 +247,3 @@ function matchesPhaseRule(rule, phase) {
   if (rule.from_phase && rule.from_phase !== phase) return false;
   return true;
 }
-
-function canRoleProduceFiles(role, runtime) {
-  if (!role) return false;
-  return runtime?.type === 'manual'
-    || role.write_authority === 'authoritative'
-    || role.write_authority === 'proposed';
-}

package/src/lib/blocked-state.js

@@ -8,6 +8,15 @@ import {
   derivePolicyEscalationRecoveryAction,
   getActiveTurnCount,
 } from './governed-state.js';
+import { getEffectiveGateArtifacts } from './gate-evaluator.js';
+import { getRoleRuntimeCapabilityContract } from './runtime-capabilities.js';
+
+const RUNTIME_GUIDANCE_PRIORITY = new Map([
+  ['invalid_binding', 1],
+  ['review_only_remote_dead_end', 2],
+  ['proposal_apply_required', 3],
+  ['tool_defined_proof_not_strong_enough', 4],
+]);
 
 function isLegacyEscalationRecoveryAction(action) {
   return action === 'Resolve the escalation, then run agentxchain step --resume'
@@ -69,6 +78,139 @@ function maybeRefreshRecoveryAction(state, config, persistedRecovery, turnRetain
   return null;
 }
 
+export function deriveRuntimeBlockedGuidance(state, config) {
+  if (!state || !config || typeof state !== 'object' || typeof config !== 'object') {
+    return [];
+  }
+
+  const failure = state.last_gate_failure;
+  if (!failure || typeof failure !== 'object') {
+    return [];
+  }
+
+  const phase = typeof failure.phase === 'string' && failure.phase
+    ? failure.phase
+    : state.phase;
+  const gateId = typeof failure.gate_id === 'string' && failure.gate_id
+    ? failure.gate_id
+    : config.routing?.[phase]?.exit_gate || null;
+  const missingFiles = Array.isArray(failure.missing_files)
+    ? failure.missing_files.filter((path) => typeof path === 'string' && path.length > 0)
+    : [];
+
+  if (!phase || !gateId || missingFiles.length === 0 || !config.gates?.[gateId]) {
+    return [];
+  }
+
+  const requiredArtifacts = getEffectiveGateArtifacts(config, config.gates[gateId], phase)
+    .filter((artifact) => artifact?.required !== false)
+    .filter((artifact) => missingFiles.includes(artifact.path));
+
+  if (requiredArtifacts.length === 0) {
+    return [];
+  }
+
+  const entryRole = config.routing?.[phase]?.entry_role || null;
+  const guidance = [];
+
+  for (const artifact of requiredArtifacts) {
+    const roleId = artifact.owned_by || entryRole;
+    if (!roleId) continue;
+
+    const role = config.roles?.[roleId];
+    if (!role) continue;
+
+    const runtimeId = role.runtime_id || role.runtime;
+    const runtime = config.runtimes?.[runtimeId];
+    if (!runtime) continue;
+
+    const contract = getRoleRuntimeCapabilityContract(roleId, role, runtime);
+    const invalidBinding = contract.effective_write_path.startsWith('invalid_')
+      || contract.workflow_artifact_ownership === 'invalid';
+
+    let code = null;
+    let command = null;
+    let reason = null;
+
+    if (invalidBinding) {
+      code = 'invalid_binding';
+      command = `Edit agentxchain.json for role "${roleId}", then run agentxchain validate`;
+      reason = `Artifact "${artifact.path}" is owned by "${roleId}", but ${role.write_authority}/${runtime.type} resolves to ${contract.effective_write_path}.`;
+    } else if (contract.workflow_artifact_ownership === 'no') {
+      code = 'review_only_remote_dead_end';
+      command = `Edit agentxchain.json for role "${roleId}", then run agentxchain validate`;
+      reason = `Artifact "${artifact.path}" is owned by "${roleId}", but ${role.write_authority}/${runtime.type} can only return review artifacts and cannot satisfy workflow ownership.`;
+    } else if (contract.workflow_artifact_ownership === 'proposal_apply_required') {
+      const turnId = failure.requested_by_turn || state.last_completed_turn_id || null;
+      code = 'proposal_apply_required';
+      command = turnId ? `agentxchain proposal apply ${turnId}` : 'agentxchain proposal list';
+      reason = `Artifact "${artifact.path}" is owned by "${roleId}", and ${role.write_authority}/${runtime.type} stages required files behind proposal apply.`;
+    } else if (contract.workflow_artifact_ownership === 'tool_defined') {
+      code = 'tool_defined_proof_not_strong_enough';
+      command = `agentxchain role show ${roleId}`;
+      reason = `Artifact "${artifact.path}" is owned by "${roleId}", but ${runtime.type} leaves the file-write contract tool-defined and not statically provable.`;
+    }
+
+    if (!code) continue;
+    guidance.push({
+      code,
+      phase,
+      gate_id: gateId,
+      role_id: roleId,
+      artifact_path: artifact.path,
+      command,
+      reason,
+    });
+  }
+
+  const seen = new Set();
+  return guidance
+    .sort((left, right) => {
+      const priority = (RUNTIME_GUIDANCE_PRIORITY.get(left.code) || 99)
+        - (RUNTIME_GUIDANCE_PRIORITY.get(right.code) || 99);
+      if (priority !== 0) return priority;
+      const commandCmp = left.command.localeCompare(right.command, 'en');
+      if (commandCmp !== 0) return commandCmp;
+      return left.artifact_path.localeCompare(right.artifact_path, 'en');
+    })
+    .filter((entry) => {
+      const key = `${entry.code}|${entry.role_id}|${entry.command}|${entry.artifact_path}`;
+      if (seen.has(key)) return false;
+      seen.add(key);
+      return true;
+    });
+}
+
+export function deriveGovernedRunNextActions(state, config = null) {
+  const recovery = deriveRecoveryDescriptor(state, config);
+  const runtimeGuidance = recovery?.runtime_guidance || deriveRuntimeBlockedGuidance(state, config);
+  const nextActions = [];
+  const seen = new Set();
+
+  const pushAction = (command, reason) => {
+    if (typeof command !== 'string' || !command.trim() || typeof reason !== 'string' || !reason.trim()) {
+      return;
+    }
+    const key = `${command}|${reason}`;
+    if (seen.has(key)) return;
+    seen.add(key);
+    nextActions.push({ command, reason });
+  };
+
+  for (const entry of runtimeGuidance) {
+    pushAction(entry.command, entry.reason);
+  }
+
+  if (recovery?.recovery_action) {
+    const reason = runtimeGuidance.length > 0
+      ? `After resolving the ${runtimeGuidance[0].code} blocker, continue the run.`
+      : `Run is blocked: ${recovery.typed_reason}.`;
+    pushAction(recovery.recovery_action, reason);
+  }
+
+  return nextActions;
+}
+
 export function deriveRecoveryDescriptor(state, config = null) {
   if (!state || typeof state !== 'object') {
     return null;
@@ -99,6 +241,7 @@ export function deriveRecoveryDescriptor(state, config = null) {
   const persistedRecovery = state.blocked_reason?.recovery;
   if (persistedRecovery && typeof persistedRecovery === 'object') {
     const refreshedRecoveryAction = maybeRefreshRecoveryAction(state, config, persistedRecovery, turnRetained);
+    const runtimeGuidance = deriveRuntimeBlockedGuidance(state, config);
     return {
       typed_reason: persistedRecovery.typed_reason || 'unknown_block',
       owner: persistedRecovery.owner || 'human',
@@ -109,6 +252,7 @@ export function deriveRecoveryDescriptor(state, config = null) {
         ? persistedRecovery.turn_retained
         : turnRetained,
       detail: persistedRecovery.detail ?? state.blocked_on ?? null,
+      runtime_guidance: runtimeGuidance,
     };
   }
 
@@ -126,6 +270,7 @@ export function deriveRecoveryDescriptor(state, config = null) {
       }),
       turn_retained: turnRetained,
       detail: state.blocked_on.slice('human:'.length) || null,
+      runtime_guidance: deriveRuntimeBlockedGuidance(state, config),
     };
   }
 
@@ -151,6 +296,7 @@ export function deriveRecoveryDescriptor(state, config = null) {
       recovery_action: recoveryAction,
       turn_retained: turnRetained,
       detail: state.escalation?.detail || state.escalation?.reason || state.blocked_on,
+      runtime_guidance: deriveRuntimeBlockedGuidance(state, config),
     };
   }
 
@@ -164,6 +310,7 @@ export function deriveRecoveryDescriptor(state, config = null) {
       }),
       turn_retained: turnRetained,
       detail: state.blocked_on.slice('dispatch:'.length) || state.blocked_on,
+      runtime_guidance: deriveRuntimeBlockedGuidance(state, config),
     };
   }
 
@@ -179,6 +326,7 @@ export function deriveRecoveryDescriptor(state, config = null) {
       }),
       turn_retained: turnRetained,
       detail: derivePolicyEscalationDetail(state, { policyId }),
+      runtime_guidance: deriveRuntimeBlockedGuidance(state, config),
     };
   }
 
@@ -190,6 +338,7 @@ export function deriveRecoveryDescriptor(state, config = null) {
       recovery_action: 'agentxchain resume',
       turn_retained: false,
       detail: `${scope} timeout exceeded`,
+      runtime_guidance: deriveRuntimeBlockedGuidance(state, config),
     };
   }
 
@@ -199,5 +348,6 @@ export function deriveRecoveryDescriptor(state, config = null) {
     recovery_action: 'Inspect state.json and resolve manually before rerunning agentxchain step',
     turn_retained: turnRetained,
     detail: state.blocked_on,
+    runtime_guidance: deriveRuntimeBlockedGuidance(state, config),
   };
 }

package/src/lib/conflict-actions.js

@@ -0,0 +1,17 @@
+export function deriveConflictedTurnResolutionActions(turnId) {
+  if (typeof turnId !== 'string' || !turnId.trim()) {
+    throw new Error('deriveConflictedTurnResolutionActions requires a non-empty turnId');
+  }
+
+  const normalizedTurnId = turnId.trim();
+  return [
+    {
+      command: `agentxchain reject-turn --turn ${normalizedTurnId} --reassign`,
+      description: 'reject and re-dispatch with conflict context',
+    },
+    {
+      command: `agentxchain accept-turn --turn ${normalizedTurnId} --resolution human_merge`,
+      description: 'manually merge and re-accept',
+    },
+  ];
+}

package/src/lib/context-section-parser.js

@@ -3,6 +3,7 @@ const CONTEXT_TITLE = '# Execution Context';
 const SECTION_DEFINITIONS = [
   { id: 'current_state', header: 'Current State', required: true },
   { id: 'budget', header: null, required: false },
+  { id: 'runtime_capability_contract', header: 'Runtime Capability Contract', required: false },
   { id: 'project_goal', header: 'Project Goal', required: true },
   { id: 'inherited_run_context', header: 'Inherited Run Context', required: true },
   { id: 'last_turn_header', header: 'Last Accepted Turn', required: true },
@@ -82,6 +83,7 @@ export function renderContextSections(sections) {
     sectionMap.get('budget')?.content,
   ]);
 
+  appendTopLevelSection(lines, 'Runtime Capability Contract', [sectionMap.get('runtime_capability_contract')?.content]);
   appendTopLevelSection(lines, 'Project Goal', [sectionMap.get('project_goal')?.content]);
   appendTopLevelSection(lines, 'Inherited Run Context', [sectionMap.get('inherited_run_context')?.content]);
   appendTopLevelSection(lines, 'Last Accepted Turn', [

package/src/lib/continuity-status.js

@@ -4,7 +4,7 @@ import { captureBaselineRef, readSessionCheckpoint } from './session-checkpoint.
 
 export const SESSION_RECOVERY_PATH = '.agentxchain/SESSION_RECOVERY.md';
 
-function deriveRecommendedContinuityAction(state) {
+export function deriveRecommendedContinuityAction(state) {
   if (!state) {
     return {
       recommended_command: null,

package/src/lib/coordinator-blocker-presentation.js

@@ -0,0 +1,127 @@
+import { pushDetail } from './coordinator-presentation-detail.js';
+import { getCoordinatorPendingGateDetails } from './coordinator-pending-gate-presentation.js';
+
+function isObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function normalizeMessage(value) {
+  if (typeof value === 'string') {
+    return value;
+  }
+  if (value == null) {
+    return null;
+  }
+  return JSON.stringify(value);
+}
+
+export function getCoordinatorBlockerDetails(blocker) {
+  if (!isObject(blocker)) {
+    return [];
+  }
+
+  const details = [];
+  switch (blocker.code) {
+    case 'repo_run_id_mismatch':
+      pushDetail(details, 'Repo', blocker.repo_id, { mono: true });
+      pushDetail(details, 'Expected', blocker.expected_run_id, { mono: true });
+      pushDetail(details, 'Actual', blocker.actual_run_id, { mono: true });
+      break;
+    case 'repo_not_ready':
+      pushDetail(details, 'Repo', blocker.repo_id, { mono: true });
+      pushDetail(details, 'Current Phase', blocker.current_phase);
+      pushDetail(details, 'Required Phase', blocker.required_phase);
+      break;
+    default:
+      break;
+  }
+
+  return details;
+}
+
+export function summarizeCoordinatorAttention(coordinatorBlockers) {
+  if (!isObject(coordinatorBlockers) || coordinatorBlockers.ok === false) {
+    return null;
+  }
+
+  const active = isObject(coordinatorBlockers.active) ? coordinatorBlockers.active : {};
+  const blockers = Array.isArray(active.blockers)
+    ? active.blockers.filter((blocker) => isObject(blocker) && blocker.code !== 'no_next_phase')
+    : [];
+  const nextActions = Array.isArray(coordinatorBlockers.next_actions)
+    ? coordinatorBlockers.next_actions.filter((action) => isObject(action))
+    : [];
+
+  return {
+    title: coordinatorBlockers.mode === 'pending_gate' ? 'Approval Snapshot' : 'Blocker Snapshot',
+    active,
+    blockers,
+    nextActions,
+    primaryBlocker: blockers[0] || null,
+    primaryAction: nextActions[0] || null,
+    additionalBlockerCount: Math.max(0, blockers.length - 1),
+    additionalActionCount: Math.max(0, nextActions.length - 1),
+  };
+}
+
+export function buildCoordinatorAttentionSnapshotPresentation(coordinatorBlockers) {
+  const summary = summarizeCoordinatorAttention(coordinatorBlockers);
+  if (!summary) {
+    return null;
+  }
+
+  const details = [];
+  pushDetail(details, 'Mode', coordinatorBlockers?.mode);
+  if (summary.title === 'Approval Snapshot') {
+    details.push(
+      ...getCoordinatorPendingGateDetails({
+        pendingGate: coordinatorBlockers?.pending_gate,
+        active: summary.active,
+      }),
+    );
+  } else {
+    pushDetail(details, 'Type', summary.active?.gate_type);
+    pushDetail(details, 'Gate', summary.active?.gate_id, { mono: true });
+    pushDetail(details, 'Current Phase', summary.active?.current_phase);
+    pushDetail(details, 'Target Phase', summary.active?.target_phase);
+  }
+  if (summary.blockers.length > 0) {
+    pushDetail(details, 'Blockers', summary.blockers.length);
+  }
+  pushDetail(details, 'Primary Blocker', summary.primaryBlocker?.code, { mono: true });
+
+  return {
+    title: summary.title,
+    subtitle: 'First-glance coordinator attention only. Full blocker diagnostics stay in the Blockers view.',
+    details,
+    summaryMessage: summary.primaryBlocker
+      ? null
+      : summary.title === 'Approval Snapshot'
+        ? 'All coordinator prerequisites are satisfied. Human approval is the remaining action.'
+        : normalizeMessage(coordinatorBlockers?.blocked_reason),
+    primaryBlocker: summary.primaryBlocker,
+    primaryBlockerDetails: getCoordinatorBlockerDetails(summary.primaryBlocker),
+    primaryAction: summary.primaryAction,
+    additionalBlockerCount: summary.additionalBlockerCount,
+    additionalActionCount: summary.additionalActionCount,
+  };
+}
+
+export function getCoordinatorAttentionStatusCard(coordinatorBlockers) {
+  const summary = summarizeCoordinatorAttention(coordinatorBlockers);
+  if (!summary || summary.blockers.length > 0) {
+    return null;
+  }
+
+  if (summary.title === 'Approval Snapshot') {
+    return {
+      title: 'Approval Snapshot',
+      message: 'All coordinator prerequisites are satisfied. Human approval is the remaining action.',
+    };
+  }
+
+  return {
+    title: 'Gate Clear',
+    message: 'The coordinator gate has no outstanding blockers.',
+  };
+}

package/src/lib/coordinator-event-narrative.js

@@ -0,0 +1,43 @@
+function countLabel(count, noun) {
+  return `${count} ${noun}${count === 1 ? '' : 's'}`;
+}
+
+export function summarizeCoordinatorEvent(entry) {
+  const type = entry?.type || 'unknown';
+  const ts = entry?.timestamp || '';
+
+  switch (type) {
+    case 'run_initialized': {
+      const repoCount = entry?.repo_runs ? Object.keys(entry.repo_runs).length : 0;
+      return `Coordinator run initialized with ${countLabel(repoCount, 'repo')}`;
+    }
+    case 'turn_dispatched':
+      return `Dispatched turn to ${entry?.repo_id || 'unknown'} (${entry?.role || '?'}) in workstream ${entry?.workstream_id || 'unknown'}`;
+    case 'acceptance_projection': {
+      const turnRef = entry?.repo_turn_id ? ` (turn ${entry.repo_turn_id})` : '';
+      const summaryText = entry?.summary ? ` — ${entry.summary}` : '';
+      return `Projected acceptance from ${entry?.repo_id || 'unknown'}${turnRef}${summaryText}`;
+    }
+    case 'context_generated': {
+      const upstreamCount = Array.isArray(entry?.upstream_repo_ids) ? entry.upstream_repo_ids.length : 0;
+      return `Generated cross-repo context for ${entry?.target_repo_id || 'unknown'} from ${countLabel(upstreamCount, 'upstream repo')}`;
+    }
+    case 'phase_transition_requested':
+      return `Requested phase transition: ${entry?.from || '?'} → ${entry?.to || '?'}`;
+    case 'phase_transition_approved':
+      return `Phase transition approved: ${entry?.from || '?'} → ${entry?.to || '?'}`;
+    case 'run_completion_requested':
+      return `Requested run completion (gate: ${entry?.gate || 'unknown'})`;
+    case 'run_completed':
+      return 'Coordinator run completed';
+    case 'state_resynced': {
+      const resyncedCount = Array.isArray(entry?.resynced_repos) ? entry.resynced_repos.length : 0;
+      const barrierChangeCount = Array.isArray(entry?.barrier_changes) ? entry.barrier_changes.length : 0;
+      return `Resynced state for ${countLabel(resyncedCount, 'repo')}, ${countLabel(barrierChangeCount, 'barrier change')}`;
+    }
+    case 'blocked_resolved':
+      return `Blocked state resolved: ${entry?.from || '?'} → ${entry?.to || '?'}`;
+    default:
+      return `${type} event${ts ? ` at ${ts}` : ''}`;
+  }
+}

package/src/lib/coordinator-gate-approval.js

@@ -0,0 +1,98 @@
+import { deriveCoordinatorNextActions } from './coordinator-next-actions.js';
+import { collectCoordinatorRepoSnapshots } from './coordinator-repo-snapshots.js';
+
+export function deriveCoordinatorGateNextActions(state, config) {
+  return deriveCoordinatorNextActions({
+    status: state?.status ?? null,
+    blockedReason: state?.blocked_reason ?? null,
+    pendingGate: state?.pending_gate ?? null,
+    repos: config ? collectCoordinatorRepoSnapshots(config) : [],
+    coordinatorRepoRuns: state?.repo_runs || {},
+  });
+}
+
+function deriveTypedReason(code) {
+  if (code === 'hook_blocked') {
+    return 'hook_block';
+  }
+  if (code === 'hook_failed') {
+    return 'hook_failure';
+  }
+  return 'approval_failed';
+}
+
+function deriveRecoveryDetail(code, gate, hookName) {
+  const gateLabel = gate ? `pending gate "${gate}"` : 'pending coordinator gate';
+  if (code === 'hook_blocked') {
+    return `Coordinator state is unchanged. Fix or reconfigure hook "${hookName || 'before_gate'}", then rerun approval for ${gateLabel}.`;
+  }
+  if (code === 'hook_failed') {
+    return `Coordinator state is unchanged. Fix hook "${hookName || 'before_gate'}" or its execution failure, then rerun approval for ${gateLabel}.`;
+  }
+  return `Coordinator state is unchanged. Resolve the approval failure, then follow the next coordinator action for ${gateLabel}.`;
+}
+
+export function normalizeCoordinatorGateApprovalFailure({
+  state,
+  config,
+  code,
+  error,
+  hookName = null,
+  hookPhase = null,
+}) {
+  const gate = state?.pending_gate?.gate ?? null;
+  const gateType = state?.pending_gate?.gate_type ?? null;
+  const nextActions = deriveCoordinatorGateNextActions(state, config);
+  const nextAction = nextActions[0]?.command ?? null;
+  const detail = deriveRecoveryDetail(code, gate, hookName);
+
+  return {
+    ok: false,
+    code: code || 'approval_failed',
+    error: error || 'Coordinator gate approval failed',
+    gate,
+    gate_type: gateType,
+    hook_phase: hookPhase || null,
+    hook_name: hookName || null,
+    next_action: nextAction,
+    next_actions: nextActions,
+    recovery_summary: {
+      typed_reason: deriveTypedReason(code),
+      owner: 'human',
+      recovery_action: nextAction,
+      detail,
+    },
+  };
+}
+
+export function normalizeCoordinatorGateApprovalSuccess({
+  result,
+  gateType,
+  phaseTransitionMessagePrefix = 'Coordinator phase transition approved',
+  completionMessage = 'Coordinator run completion approved. Run is now complete.',
+}) {
+  const nextActions = deriveCoordinatorGateNextActions(result?.state, result?.config);
+  const nextAction = nextActions[0]?.command ?? null;
+
+  if (gateType === 'phase_transition') {
+    return {
+      ok: true,
+      gate_type: 'phase_transition',
+      status: result?.state?.status || null,
+      phase: result?.state?.phase || null,
+      message: `${phaseTransitionMessagePrefix}: ${result?.transition?.from} -> ${result?.transition?.to}`,
+      next_action: nextAction,
+      next_actions: nextActions,
+    };
+  }
+
+  return {
+    ok: true,
+    gate_type: 'run_completion',
+    status: result?.state?.status || null,
+    phase: result?.state?.phase || null,
+    message: completionMessage,
+    next_action: nextAction,
+    next_actions: nextActions,
+  };
+}

package/src/lib/coordinator-gate-evaluation-presentation.js

@@ -0,0 +1,57 @@
+function formatList(values) {
+  return values.join(', ');
+}
+
+export function buildCoordinatorGateEvaluationPresentation({
+  gateType,
+  evaluation,
+  includeReady = false,
+  includeBlockerCount = true,
+} = {}) {
+  const normalizedGateType = gateType === 'run_completion' ? 'run_completion' : 'phase_transition';
+  const data = evaluation && typeof evaluation === 'object' ? evaluation : {};
+  const blockers = Array.isArray(data.blockers) ? data.blockers : [];
+  const details = [];
+
+  if (typeof data.gate_id === 'string' && data.gate_id.length > 0) {
+    details.push({ label: 'Gate', value: data.gate_id, mono: true });
+  }
+
+  if (typeof data.current_phase === 'string' && data.current_phase.length > 0) {
+    details.push({ label: 'Current Phase', value: data.current_phase });
+  }
+
+  if (typeof data.target_phase === 'string' && data.target_phase.length > 0) {
+    details.push({ label: 'Target Phase', value: data.target_phase });
+  }
+
+  if (Array.isArray(data.required_repos) && data.required_repos.length > 0) {
+    details.push({ label: 'Required Repos', value: formatList(data.required_repos) });
+  }
+
+  if (Array.isArray(data.human_barriers) && data.human_barriers.length > 0) {
+    details.push({ label: 'Human Barriers', value: formatList(data.human_barriers) });
+  }
+
+  if (normalizedGateType === 'run_completion' && typeof data.requires_human_approval === 'boolean') {
+    details.push({
+      label: 'Human Approval',
+      value: data.requires_human_approval ? 'Required' : 'Not required',
+    });
+  }
+
+  if (includeReady && typeof data.ready === 'boolean') {
+    details.push({ label: 'Ready', value: data.ready ? 'Yes' : 'No' });
+  }
+
+  if (includeBlockerCount) {
+    details.push({ label: 'Blockers', value: String(blockers.length) });
+  }
+
+  return {
+    title: normalizedGateType === 'run_completion' ? 'Run Completion' : 'Phase Transition',
+    statusLabel: data.ready ? 'ready' : 'not ready',
+    details,
+    blockers,
+  };
+}